Serenity BDD Integration

What is Serenity BDD?

Serenity BDD (formerly Thucydides) is an open-source reporting library that provides:

Living Documentation - Automatic generation of illustrated, narrative reports
Screenplay Pattern Support - Built-in support for maintainable test design
WebDriver Management - Automatic browser driver management via Selenium Manager
Rich Reporting - Detailed test execution reports with screenshots and evidence
Requirements Traceability - Links tests to business requirements

This project uses Serenity BDD version 4.0.46, which includes the latest Selenium Manager integration and parallel reporting capabilities.

Gradle Configuration

Plugin Setup

The Serenity Gradle plugin is configured at the top of build.gradle:

plugins {
    id 'java'
    id 'net.serenity-bdd.serenity-gradle-plugin' version '4.0.46'
}

This plugin provides essential tasks:

test - Runs tests and captures Serenity data
aggregate - Generates HTML reports from test results
checkOutcomes - Verifies test results and fails the build if tests failed

Dependencies

The framework includes four core Serenity dependencies:

ext {
    serenityVersion = '4.0.46'
}

dependencies {
    // 1. Serenity BDD Core & Cucumber
    implementation "net.serenity-bdd:serenity-core:${serenityVersion}"
    implementation "net.serenity-bdd:serenity-cucumber:${serenityVersion}"

    // 2. Screenplay Pattern (Core and WebDriver for UI)
    implementation "net.serenity-bdd:serenity-screenplay:${serenityVersion}"
    implementation "net.serenity-bdd:serenity-screenplay-webdriver:${serenityVersion}"
}

Dependency Breakdown

serenity-core

Core Serenity BDD functionality
Report generation engine
Screenshot capture
Test lifecycle management

serenity-cucumber

Cucumber integration
Gherkin step reporting
Scenario outcome tracking
Feature file requirements mapping

serenity-screenplay

Screenplay pattern implementation
Actor, Task, and Question abstractions
Ability management
Consequence validation

serenity-screenplay-webdriver

WebDriver-based Interactions
Browser abilities (BrowseTheWeb)
UI element interactions
Page object utilities

Serenity Configuration

Build-level Configuration

In build.gradle, the Serenity block configures report generation:

serenity {
    testRoot = "org.btg.practual"
    requirementsBaseDir = "src/test/resources/features"
    reports = ["html"]
}

test.finalizedBy(aggregate)

testRoot - Base package for test scanning
requirementsBaseDir - Location of feature files for requirements tracing
reports - Report formats to generate (HTML in this case)
finalizedBy(aggregate) - Automatically generates reports after tests run

Runtime Configuration (serenity.conf)

The src/test/resources/serenity.conf file uses HOCON format for runtime settings:

serenity {
    take.screenshots = FOR_FAILURES
    test.root = "org.btg.practual"
    logging = QUIET
    console.colors = true
}

take.screenshots

FOR_FAILURES - Only captures screenshots when tests fail, reducing report sizeOther options: FOR_EACH_ACTION, BEFORE_AND_AFTER_EACH_STEP, DISABLED

test.root

org.btg.practual - Root package for test discoveryEnsures Serenity correctly scans and reports all test classes

logging

QUIET - Minimal console output during test executionOther options: VERBOSE, NORMAL

console.colors

true - Enables colored console output for better readabilityUseful for distinguishing pass/fail in terminal output

WebDriver Management

Selenium Manager Integration

Serenity 4.0.46 includes automatic WebDriver management:

webdriver {
  driver = chrome
  autodownload = true  # Enables Selenium Manager

  capabilities {
    browserName = "chrome"
    acceptInsecureCerts = true

    "goog:chromeOptions" {
      args = [
        "remote-allow-origins=*",
        "start-maximized",
        "incognito",
        "disable-infobars",
        "disable-gpu",
        "disable-default-apps",
        "disable-popup-blocking",
        "disable-dev-shm-usage",
        "no-sandbox"
      ]
    }
  }
}

autodownload = true enables Selenium Manager, which automatically downloads and manages the correct ChromeDriver version for your installed Chrome browser. No manual driver management required!

Chrome Options Explained

remote-allow-origins=* - Allows remote connections (required for newer Chrome versions)
start-maximized - Opens browser in full-screen mode
incognito - Runs in private browsing mode (clean state)
disable-infobars - Removes “Chrome is being controlled” banner
disable-gpu - Prevents GPU-related crashes in headless mode
disable-dev-shm-usage - Fixes shared memory issues in Docker/CI environments
no-sandbox - Required for running in containerized environments

Environment Management

Serenity supports multiple test environments through the environments block:

environments {
  qa {
    webdriver.base.url = "https://qa.btgpactual.com"
    api.endpoint = "https://api-qa.btgpactual.com/v1"
  }
  stg {
    webdriver.base.url = "https://stg.btgpactual.com"
    api.endpoint = "https://api-stg.btgpactual.com/v1"
  }
}

Switch environments at runtime using the environment system property:

./gradlew test -Denvironment=qa
./gradlew test -Denvironment=stg

Report Generation

Automatic Report Creation

Reports are generated automatically after test execution:

./gradlew test  # Runs tests and generates reports

The test.finalizedBy(aggregate) configuration ensures reports are created even if some tests fail.

Report Location

Serenity reports are generated in:

target/site/serenity/
├── index.html           # Main report entry point
├── requirements.html    # Requirements coverage
├── capabilities.html    # Test capabilities overview
└── css/                 # Report styling

Open target/site/serenity/index.html in your browser to view the interactive test report.

Report Features

Test Results Overview

High-level summary of test execution:

Total scenarios executed
Pass/fail/pending counts
Execution time
Success rate

Requirements Traceability

Maps tests to business requirements:

Feature file linkage
Coverage metrics
Scenario grouping
Tag-based filtering

Detailed Step Execution

Step-by-step test execution details:

Each Gherkin step
Execution duration
Screenshots (on failure)
Stack traces

Visual Evidence

Screenshots and artifacts:

Failure screenshots
Browser state capture
Console logs
Network activity

Serenity Reporter Integration

The Cucumber runner uses Serenity’s parallel reporter:

@ConfigurationParameter(
    key = PLUGIN_PROPERTY_NAME,
    value = "io.cucumber.core.plugin.SerenityReporterParallel,pretty,html:target/cucumber-report.html"
)

SerenityReporterParallel - Thread-safe reporter for parallel execution
pretty - Formatted console output
html:target/cucumber-report.html - Additional Cucumber HTML report

The Serenity reporter runs alongside Cucumber’s built-in reporters, capturing additional context for enhanced reporting.

Screenshot Capture

Screenshots are automatically captured based on configuration:

serenity {
    take.screenshots = FOR_FAILURES
}

Screenshot Strategies

Strategy	Description	Use Case
`FOR_FAILURES`	Only on test failures	Production (reduces report size)
`FOR_EACH_ACTION`	After every interaction	Debugging complex scenarios
`BEFORE_AND_AFTER_EACH_STEP`	Before/after each step	Detailed step verification
`DISABLED`	No screenshots	Performance testing

For debugging, temporarily change to FOR_EACH_ACTION to capture every interaction:

./gradlew test -Dserenity.take.screenshots=FOR_EACH_ACTION

Test Execution Options

The test task is configured with Serenity-specific properties:

test {
    useJUnitPlatform()
    
    systemProperties System.getProperties()
    systemProperty "serenity.test.root", "org.btg.practual"
    systemProperty "serenity.project.name", "Makers BTG Tests"
    
    testLogging {
        events "passed", "skipped", "failed"
        showStandardStreams = true
    }
}

useJUnitPlatform() - Enables JUnit 5 test execution
systemProperties - Passes all system properties to tests
serenity.project.name - Sets the project name in reports
showStandardStreams - Displays console output during tests

Best Practices

Use Environment-Specific Configs

Define QA, STG, and PROD environments in serenity.conf to avoid hardcoding URLs in test code

Optimize Screenshot Capture

Use FOR_FAILURES in CI/CD to reduce report size and execution time

Tag Your Scenarios

Use Cucumber tags (@smoke, @regression, @test) to control which scenarios run

Review Reports Regularly

Check Serenity reports for flaky tests, slow scenarios, and failure patterns

Learn more about implementing tests using the Screenplay Pattern or explore the Project Structure.

Get Started

Framework Guide

Writing Tests

Configuration

Running Tests

Best Practices

What is Serenity BDD?

Gradle Configuration

Plugin Setup

Dependencies

Serenity Configuration

Build-level Configuration

Runtime Configuration (serenity.conf)

take.screenshots

test.root

logging

console.colors

WebDriver Management

Selenium Manager Integration

Chrome Options Explained

Environment Management

Report Generation

Automatic Report Creation

Report Location

Report Features

Test Results Overview

Requirements Traceability

Detailed Step Execution

Visual Evidence

Serenity Reporter Integration

Screenshot Capture

Screenshot Strategies

Test Execution Options

Best Practices

Use Environment-Specific Configs

Optimize Screenshot Capture

Tag Your Scenarios

Review Reports Regularly

Build docs developers (and LLMs) love

Get Started

Framework Guide

Writing Tests

Configuration

Running Tests

Best Practices

​What is Serenity BDD?

​Gradle Configuration

​Plugin Setup

​Dependencies

​Serenity Configuration

​Build-level Configuration

​Runtime Configuration (serenity.conf)

take.screenshots

test.root

logging

console.colors

​WebDriver Management

​Selenium Manager Integration

​Chrome Options Explained

​Environment Management

​Report Generation

​Automatic Report Creation

​Report Location

​Report Features

Test Results Overview

Requirements Traceability

Detailed Step Execution

Visual Evidence

​Serenity Reporter Integration

​Screenshot Capture

​Screenshot Strategies

​Test Execution Options

​Best Practices

Use Environment-Specific Configs

Optimize Screenshot Capture

Tag Your Scenarios

Review Reports Regularly

Build docs developers (and LLMs) love

What is Serenity BDD?

Gradle Configuration

Plugin Setup

Dependencies

Serenity Configuration

Build-level Configuration

Runtime Configuration (serenity.conf)

WebDriver Management

Selenium Manager Integration

Chrome Options Explained

Environment Management

Report Generation

Automatic Report Creation

Report Location

Report Features

Serenity Reporter Integration

Screenshot Capture

Screenshot Strategies

Test Execution Options

Best Practices