Gradle Configuration

Overview

The Makers BTG Tests project uses Gradle as its build tool. The build.gradle file defines project dependencies, Java version, test configuration, and Serenity BDD integration.

Project Configuration

build.gradle

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

group = 'org.btg.practual'
version = '1.0.0-SNAPSHOT'

Plugins

java

plugin

Provides Java compilation, testing, and packaging capabilities.

net.serenity-bdd.serenity-gradle-plugin

plugin

Version: 4.0.46Integrates Serenity BDD into the Gradle build lifecycle:

Aggregates test results
Generates HTML reports
Manages Serenity dependencies
Provides aggregate task for report generation

Project Identity

group

string

Value: org.btg.practualMaven group ID for the project.

version

string

Value: 1.0.0-SNAPSHOTCurrent project version. SNAPSHOT indicates this is a development version.

Java Toolchain

build.gradle

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

java.toolchain.languageVersion

JavaLanguageVersion

Value: Java 21Configures the Java version for compilation and execution.Benefits of toolchains:

Gradle automatically downloads Java 21 if not installed
Ensures consistent Java version across all developers
Prevents “works on my machine” issues
CI/CD uses the exact same Java version

Java 21 is a Long-Term Support (LTS) release with modern language features including:

Virtual Threads (Project Loom)
Pattern Matching for switch
Record Patterns
Sequenced Collections

Dependency Versions

build.gradle

ext {
    serenityVersion = '4.0.46'
    junitVersion = '5.10.1'
}

Centralized version management using Gradle’s extra properties (ext block):

serenityVersion

string

default:"4.0.46"

Serenity BDD framework version used across all Serenity dependencies.

junitVersion

string

default:"5.10.1"

JUnit 5 (Jupiter) version for test execution.

Using ext properties ensures all related dependencies use the same version, preventing compatibility issues.

Dependencies

build.gradle

repositories {
    mavenCentral()
}

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

    // 2. Patrón Screenplay (Core y Webdriver para UI)
    implementation "net.serenity-bdd:serenity-screenplay:${serenityVersion}"
    implementation "net.serenity-bdd:serenity-screenplay-webdriver:${serenityVersion}"

    // 3. Motor de Pruebas: JUnit 5 (Jupiter)
    testImplementation "org.junit.jupiter:junit-jupiter-api:${junitVersion}"
    testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:${junitVersion}"
    testImplementation "org.junit.platform:junit-platform-suite:1.10.1"

    // 4. AssertJ para validaciones
    testImplementation "org.assertj:assertj-core:3.24.2"

    // 5. Logging
    testImplementation "ch.qos.logback:logback-classic:1.4.14"

    // 6. Cucumber JUnit Platform Engine
    testImplementation "io.cucumber:cucumber-junit-platform-engine:7.14.0"

    // 7. JUnit 4 (Required by Serenity Reporter)
    testImplementation "junit:junit:4.13.2"
}

Dependency Categories

1. Serenity BDD Core & Cucumber

serenity-core

implementation

Version: 4.0.46Core Serenity BDD framework providing:

Test orchestration
Report generation
Screenshot capture
WebDriver management

serenity-cucumber

implementation

Version: 4.0.46Integration between Serenity BDD and Cucumber for BDD-style testing:

Gherkin feature file support
Step definition integration
BDD report generation

2. Screenplay Pattern

serenity-screenplay

implementation

Version: 4.0.46Core Screenplay pattern implementation:

Actor-based test design
Task and Question abstractions
Interaction modeling
High-level test readability

serenity-screenplay-webdriver

implementation

Version: 4.0.46Web UI interactions for Screenplay:

Browser actions (Click, Enter, Open)
Element queries (Text, Value, Visibility)
Navigation and frame switching
WebDriver integration

3. JUnit 5 Test Engine

junit-jupiter-api

testImplementation

Version: 5.10.1JUnit 5 API for writing tests:

@Test annotations
Lifecycle hooks (@BeforeEach, @AfterEach)
Assertions

junit-jupiter-engine

testRuntimeOnly

Version: 5.10.1JUnit 5 test execution engine. Runtime-only dependency as tests don’t directly import engine classes.

junit-platform-suite

testImplementation

Version: 1.10.1Enables test suite configuration with @Suite and @IncludeEngines annotations for running Cucumber tests.

4. AssertJ

assertj-core

testImplementation

Version: 3.24.2Fluent assertion library providing readable and powerful assertions:

assertThat(username).isEqualTo("expected");
assertThat(errors).isEmpty();
assertThat(response.status()).isEqualTo(200);

More expressive than standard JUnit assertions.

5. Logging

logback-classic

testImplementation

Version: 1.4.14Logging framework (SLF4J implementation) for test execution logging:

Configurable log levels
File and console output
Pattern-based formatting

Configuration file: src/test/resources/logback-test.xml

6. Cucumber JUnit Platform Engine

cucumber-junit-platform-engine

testImplementation

Version: 7.14.0Enables Cucumber to run as a JUnit Platform test engine. Required for @IncludeEngines("cucumber") annotation in test runners.Bridges Cucumber feature execution with JUnit Platform.

7. JUnit 4 (Compatibility)

junit:junit

testImplementation

Version: 4.13.2JUnit 4 dependency required by Serenity’s reporting mechanism. Even though tests use JUnit 5, Serenity’s internal reporter needs JUnit 4.

This is a compatibility requirement and doesn’t affect your test code.

Build Configuration

Encoding

build.gradle

tasks.withType(JavaCompile).configureEach {
    options.encoding = 'UTF-8'
}

options.encoding

string

default:"UTF-8"

Ensures all Java source files are compiled using UTF-8 encoding.Why important: Prevents encoding issues with special characters in code, comments, or test data across different operating systems.

Test Task Configuration

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"
}

Test Platform

useJUnitPlatform()

method

Configures Gradle to use JUnit Platform (JUnit 5) for test execution.Required for running JUnit 5 and Cucumber tests via JUnit Platform.

Test Logging

testLogging.events

array

Values: ["passed", "skipped", "failed"]Logs test events to the console:

✅ passed: Successful tests
⏭️ skipped: Skipped tests
❌ failed: Failed tests with stack traces

testLogging.showStandardStreams

boolean

default:"true"

Displays System.out and System.err output in the console during test execution.Useful for debugging but can create verbose output.

System Properties

systemProperties System.getProperties()

method

Passes all JVM system properties from the command line to test execution.Enables runtime configuration:

./gradlew test -Denvironment=qa -Dheadless=true

systemProperty 'serenity.test.root'

string

Value: org.btg.practualRoot package for scanning test classes and step definitions.

systemProperty 'serenity.project.name'

string

Value: Makers BTG TestsProject name displayed in Serenity HTML reports.

Gradle Start Parameters

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.Benefits:

Complete test coverage in one run
Full test report generation
Better CI/CD feedback

Build still fails if any test fails, but all tests are executed first.

Essential for CI/CD pipelines to get complete test results rather than stopping at the first failure.

Serenity Plugin Configuration

build.gradle

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

serenity.testRoot

string

Value: org.btg.practualRoot package for test scanning (matches systemProperty).

serenity.requirementsBaseDir

string

Value: src/test/resources/featuresDirectory containing Cucumber feature files for requirements traceability in reports.

serenity.reports

array

Value: ["html"]Report formats to generate. HTML provides rich visual reports with screenshots and step details.

Report Generation

build.gradle

test.finalizedBy(aggregate)

test.finalizedBy(aggregate)

task

Automatically runs the aggregate task after tests complete.The aggregate task:

Collects test results from all test executions
Generates consolidated Serenity HTML reports
Creates requirements traceability documentation

Reports are generated in target/site/serenity/

View reports by opening target/site/serenity/index.html in a browser.

Common Gradle Commands

./gradlew clean

Dependency Management Best Practices

Keep Versions Aligned

All Serenity dependencies should use the same version

Use Version Variables

Centralize versions in ext block for easy updates

Regular Updates

Check for newer stable versions periodically

Test After Upgrades

Run full test suite after dependency updates

Troubleshooting

Build Failures

Java Version Mismatch

Error: Unsupported class file major versionSolution: Ensure Java 21 is installed or let Gradle download it:

# Check Java version
./gradlew -version

# Gradle will auto-download Java 21 if toolchain is configured
./gradlew clean test

Dependency Resolution Failures

Error: Could not resolve net.serenity-bdd:serenity-core:4.0.46Solution: Check internet connection and Maven Central access:

./gradlew clean build --refresh-dependencies

Test Task Not Found

Error: Task 'test' not foundSolution: Ensure you’re in the project root directory with build.gradle

Reports Not Generated

Check that test.finalizedBy(aggregate) is present in build.gradleManually generate reports:

./gradlew aggregate

Dependency Conflicts

View dependency tree to identify conflicts:

./gradlew dependencies --configuration testRuntimeClasspath

Upgrading Dependencies

Check for Updates

# Using Gradle versions plugin (if installed)
./gradlew dependencyUpdates

Update Serenity Version

Update version in build.gradle:

ext {
    serenityVersion = '4.1.0'  // New version
}

Update plugin version:

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

Refresh dependencies:

./gradlew clean build --refresh-dependencies

Always test thoroughly after version upgrades. Check Serenity BDD release notes for breaking changes.

CI/CD Integration

GitHub Actions Example

.github/workflows/test.yml

name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '21'
      - name: Run tests
        run: ./gradlew clean test
      - name: Publish reports
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: serenity-reports
          path: target/site/serenity/

Gradle toolchain will ensure Java 21 is used even if the system has a different version installed.

Get Started

Framework Guide

Writing Tests

Configuration

Running Tests

Best Practices

Overview

Project Configuration

Plugins

Project Identity

Java Toolchain

Dependency Versions

Dependencies

Dependency Categories

Build Configuration

Encoding

Test Task Configuration

Test Platform

Test Logging

System Properties

Gradle Start Parameters

Serenity Plugin Configuration

Report Generation

Common Gradle Commands

Dependency Management Best Practices

Keep Versions Aligned

Use Version Variables

Regular Updates

Test After Upgrades

Troubleshooting

Build Failures

Dependency Conflicts

Upgrading Dependencies

Check for Updates

Update Serenity Version

CI/CD Integration

GitHub Actions Example

Build docs developers (and LLMs) love

Get Started

Framework Guide

Writing Tests

Configuration

Running Tests

Best Practices

​Overview

​Project Configuration

​Plugins

​Project Identity

​Java Toolchain

​Dependency Versions

​Dependencies

​Dependency Categories

​Build Configuration

​Encoding

​Test Task Configuration

​Test Platform

​Test Logging

​System Properties

​Gradle Start Parameters

​Serenity Plugin Configuration

​Report Generation

​Common Gradle Commands

​Dependency Management Best Practices

Keep Versions Aligned

Use Version Variables

Regular Updates

Test After Upgrades

​Troubleshooting

​Build Failures

​Dependency Conflicts

​Upgrading Dependencies

​Check for Updates

​Update Serenity Version

​CI/CD Integration

​GitHub Actions Example

Build docs developers (and LLMs) love

Overview

Project Configuration

Plugins

Project Identity

Java Toolchain

Dependency Versions

Dependencies

Dependency Categories

Build Configuration

Encoding

Test Task Configuration

Test Platform

Test Logging

System Properties

Gradle Start Parameters

Serenity Plugin Configuration

Report Generation

Common Gradle Commands

Dependency Management Best Practices

Troubleshooting

Build Failures

Dependency Conflicts

Upgrading Dependencies

Check for Updates

Update Serenity Version

CI/CD Integration

GitHub Actions Example