Skip to main content

​
Overview

Serenity-specific settings control test execution behavior, reporting, logging, and test organization. These settings are configured in both serenity.conf and build.gradle.

​
Serenity Configuration Block

The main Serenity settings in serenity.conf:
serenity.conf
serenity {
    take.screenshots = FOR_FAILURES
    test.root = "org.btg.practual"
    logging = QUIET
    console.colors = true
}

​
Screenshot Configuration

​
serenity.take.screenshots
enum
default:"FOR_FAILURES"
Controls when Serenity captures screenshots during test execution.Options:
  • FOR_FAILURES: Only capture screenshots when tests fail (default)
  • BEFORE_AND_AFTER_EACH_STEP: Capture before and after every step
  • AFTER_EACH_STEP: Capture after every step
  • FOR_EACH_ACTION: Capture for every user action
  • DISABLED: No screenshots

​
Screenshot Strategy Comparison

serenity {
    take.screenshots = FOR_FAILURES
}
FOR_FAILURES is recommended for most projects as it:
  • Minimizes test execution time
  • Reduces report size
  • Still provides debugging information when tests fail
Using BEFORE_AND_AFTER_EACH_STEP or AFTER_EACH_STEP significantly increases test execution time and report size. Only use during active debugging.

​
Test Root Package

​
serenity.test.root
string
default:"org.btg.practual"
Specifies the root package for test classes. Serenity uses this to scan for:
  • Cucumber step definitions
  • Screenplay tasks and questions
  • Page objects and interactions
  • Custom actions
This setting is defined in two places: 
serenity {
    test.root = "org.btg.practual"
}
Both configurations should match to ensure consistent scanning behavior. The build.gradle setting takes precedence during test execution.

​
Logging Configuration

​
serenity.logging
enum
default:"QUIET"
Controls the verbosity of Serenity’s console logging during test execution.Options:
  • QUIET: Minimal logging, only errors and critical information
  • NORMAL: Standard logging with test progress
  • VERBOSE: Detailed logging including step execution
serenity.conf
serenity {
    logging = QUIET
}
QUIET mode reduces console noise, making it easier to spot actual test failures. Test details are still captured in the HTML reports.

​
Console Colors

​
serenity.console.colors
boolean
default:"true"
Enables colored console output for better readability of test results.When enabled:
  • ✅ Passed tests appear in green
  • ❌ Failed tests appear in red
  • ⚠️ Skipped tests appear in yellow
serenity.conf
serenity {
    console.colors = true
}
Some CI/CD systems may not support colored output. If you see color codes instead of colored text, set this to false.

​
Gradle Test Configuration

Additional Serenity settings in build.gradle:
build.gradle
test {
    useJUnitPlatform()

    testLogging {
        events "passed", "skipped", "failed"
        showStandardStreams = true
    }

    systemProperties System.getProperties()
    systemProperty "serenity.test.root", "org.btg.practual"
    systemProperty "serenity.project.name", "Makers BTG Tests"
}

​
System Properties

​
serenity.test.root
string
Value: org.btg.practualRoot package for scanning test classes and step definitions.
​
serenity.project.name
string
Value: Makers BTG TestsProject name displayed in the Serenity HTML reports header.
​
systemProperties System.getProperties()
system
Passes all JVM system properties to the test execution.This enables runtime configuration overrides:
./gradlew test -Denvironment=qa -Dwebdriver.driver=chrome

​
Test Logging Configuration

build.gradle
testLogging {
    events "passed", "skipped", "failed"
    showStandardStreams = true
}
​
events
array
Specifies which test events to log to the console.
  • passed: Log successful test completion
  • skipped: Log skipped tests
  • failed: Log test failures with stack traces
​
showStandardStreams
boolean
default:"true"
When enabled, displays standard output (System.out) and error streams (System.err) in the console during test execution.Useful for debugging but can create verbose output.

​
Serenity Plugin Configuration

build.gradle
serenity {
    testRoot = "org.btg.practual"
    requirementsBaseDir = "src/test/resources/features"
    reports = ["html"]
}
​
testRoot
string
Value: org.btg.practualRoot package for test scanning (same as systemProperty).
​
requirementsBaseDir
string
Value: src/test/resources/featuresDirectory containing Cucumber feature files. Serenity uses this to:
  • Generate requirements documentation
  • Link test results to feature files
  • Create traceability reports
​
reports
array
Value: ["html"]Report formats to generate after test execution.Available formats:
  • html: Rich HTML reports with screenshots (default)
  • json: JSON output for integration with other tools
  • xml: JUnit XML format
The HTML report is the primary Serenity report format, providing:
  • Visual test results with screenshots
  • Step-by-step execution details
  • Requirements traceability
  • Test execution statistics

​
Report Customization

​
Project Name and Branding

build.gradle
test {
    systemProperty "serenity.project.name", "Makers BTG Tests"
    systemProperty "serenity.report.title", "Test Execution Report"
}

​
Custom Report Output Directory

build.gradle
serenity {
    outputDirectory = file("${project.buildDir}/custom-reports")
}

​
Additional Report Formats

build.gradle
serenity {
    reports = ["html", "json", "xml"]
}

​
Gradle Continue on Failure

build.gradle
gradle.startParameter.continueOnFailure = true
​
gradle.startParameter.continueOnFailure
boolean
default:"true"
Ensures Gradle continues executing all tests even if some fail, instead of stopping at the first failure.Impact:
  • All tests run to completion
  • Complete test report is generated
  • Build still fails if any test fails, but you see all results
This is crucial for CI/CD pipelines to get complete test coverage feedback rather than partial results.

​
Common Configuration Patterns

​
Development Mode (Verbose)

serenity.conf
serenity {
    take.screenshots = AFTER_EACH_STEP
    logging = VERBOSE
    console.colors = true
}

​
CI/CD Mode (Optimized)

serenity.conf
serenity {
    take.screenshots = FOR_FAILURES
    logging = QUIET
    console.colors = false
}

​
Performance Testing Mode

serenity.conf
serenity {
    take.screenshots = DISABLED
    logging = QUIET
}

​
Troubleshooting

​
Reports Not Generated

Check that build.gradle includes:
plugins {
    id 'net.serenity-bdd.serenity-gradle-plugin' version '4.0.46'
}
Ensure report generation is triggered:
test.finalizedBy(aggregate)
Reports are generated in target/site/serenity/ by default.

​
Step Definitions Not Found

Verify test.root matches your package structure: 
# If your tests are in src/test/java/org/btg/practual/
serenity.test.root = "org.btg.practual"

​
Large Report Files

Reduce screenshot frequency: 
serenity {
    take.screenshots = FOR_FAILURES
}

​
Best Practices

Use FOR_FAILURES Screenshots

Balances debugging capability with performance

Keep Logging QUIET

Reduces console noise, details still in reports

Enable continueOnFailure

Get complete test results in CI/CD

Set Project Name

Makes reports easily identifiable

Build docs developers (and LLMs) love

Get started for freeTalk to us