Skip to main content Home Creators pramoddutta qaskills serenity-bdd-testing
serenity-bdd-testing Java BDD testing with Serenity BDD framework using the Screenplay pattern, Cucumber integration, step libraries, comprehensive reporting, and living documentation generation.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/PramodDutta/qaskills --skill serenity-bdd-testingThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository Use when publishing SEO blog articles to qaskills.sh, e.g. "publish today's articles", "daily SEO batch", "write 10 articles from keyword research", "add a blog post", or any request that creates files under packages/web/src/app/blog/posts.
secure-test-data-engineer Generate test data from the schemas you already have. Read OpenAPI, JSON Schema, SQL DDL, or TypeScript models and produce deterministic factories, boundary and negative cases, relational datasets with valid foreign keys, cleanup scripts, and PII-safe synthetic data. Production records never leave the machine.
Analyze a git diff, map affected risks, select the tests that matter, detect coverage gaps on changed lines, run configurable quality gates, and produce a go/no-go release report with cited evidence. Recommends only; never merges or deploys.
Related occupations SOC
Based on SOC occupation classification
name Serenity BDD Testing description Java BDD testing with Serenity BDD framework using the Screenplay pattern, Cucumber integration, step libraries, comprehensive reporting, and living documentation generation. version 1.0.0 author thetestingacademy license MIT tags ["serenity","bdd","java","screenplay","cucumber","reporting","living-documentation","step-libraries"] testingTypes ["bdd","acceptance","e2e","integration"] frameworks ["serenity-bdd"] languages ["java"] domains ["web","api","backend"] agents ["claude-code","cursor","github-copilot","windsurf","codex","aider","continue","cline","zed","bolt"]
Serenity BDD Testing
You are an expert QA engineer specializing in Serenity BDD, the Java testing framework that produces rich living documentation. When the user asks you to write, review, debug, or set up Serenity BDD tests, follow these detailed instructions. You understand the Serenity ecosystem deeply including the Screenplay pattern, Step Libraries, Cucumber integration, REST API testing with Serenity REST Assured, comprehensive HTML reporting, and living documentation.
Core Principles
Living Documentation — Serenity generates rich HTML reports that serve as living documentation. Write tests that produce meaningful, stakeholder-readable reports.Screenplay Pattern — Prefer the Screenplay pattern (Actors, Tasks, Questions, Interactions) over Page Objects for new projects. It scales better and produces clearer reports.Step Libraries — Use @Step annotated methods in dedicated step classes. Serenity records each step in reports with automatic screenshots.Layered Architecture — Separate test logic into layers: business rules (features/tests), tasks/workflows, page interactions, and technical infrastructure.Cucumber Integration — Use Cucumber for BDD scenarios when stakeholder collaboration is important. Serenity enriches Cucumber reports with screenshots and step details.REST API Testing — Use Serenity REST Assured for API testing with the same reporting and pattern benefits as UI tests.Parallel Execution — Configure parallel execution through Maven Surefire/Failsafe plugins. Design tests for isolation and independence.
Project Structure
project-root/
├── pom.xml # Maven configuration with Serenity dependencies
├── serenity.conf # Serenity configuration (HOCON format)
├── src/
│ └── test/
│ ├── java/
│ │ ├── features/
│ │ │ ├── auth/
│ │ │ │ └── LoginTest.java
│ │ │ ├── shopping/
│ │ │ │ └── CartTest.java
│ │ │ └── CucumberTestRunner.java
│ │ ├── screenplay/
│ │ │ ├── tasks/
│ │ │ │ ├── Login.java
│ │ │ │ ├── NavigateTo.java
│ │ │ │ └── AddToCart.java
│ │ │ ├── questions/
│ │ │ │ ├── DashboardInfo.java
│ │ │ │ └── CartDetails.java
│ │ │ ├── interactions/
│ │ │ │ └── EnterCredentials.java
│ │ │ └── ui/
│ │ │ ├── LoginPage.java
│ │ │ ├── DashboardPage.java
│ │ │ └── CartPage.java
│ │ ├── steps/
│ │ │ ├── AuthSteps.java
│ │ │ ├── NavigationSteps.java
│ │ │ └── ShoppingSteps.java
│ │ ├── stepdefinitions/
│ │ │ ├── LoginStepDefs.java
│ │ │ └── CartStepDefs.java
│ │ └── config/
│ │ └── TestConfig.java
│ └── resources/
│ ├── features/
│ │ ├── auth/
│ │ │ └── login.feature
│ │ └── shopping/
│ │ └── cart.feature
│ └── serenity.conf
├── target/
│ └── site/
│ └── serenity/ # Generated HTML reports
└── .github/
└── workflows/
└── serenity.yml
Detailed Code Examples
Screenplay Pattern - Tasks
package screenplay.tasks;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.actions.Click;
import net.serenitybdd.screenplay.actions.Enter;
import net.thucydides.core.annotations.Step;
import screenplay.ui.LoginPage;
import static net.serenitybdd.screenplay.Tasks.instrumented;
public class Login implements Task {
private final String email;
private final String password;
public Login (String email, String password) {
this .email = email;
this .password = password;
}
public static Login withCredentials (String email, String password) {
return instrumented(Login.class, email, password);
}
public static Login asAdmin () {
return instrumented(Login.class, "admin@example.com" , "AdminPass123" );
}
public static Login asUser () {
return instrumented(Login.class, "user@example.com" , "UserPass123" );
}
@Override
@Step("{0} logs in with email #email")
public <T extends Actor > void performAs (T actor) {
actor.attemptsTo(
Enter.theValue(email).into(LoginPage.EMAIL_INPUT),
Enter.theValue(password).into(LoginPage.PASSWORD_INPUT),
Click.on(LoginPage.LOGIN_BUTTON)
);
}
}
package screenplay.tasks;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Task;
import net.serenitybdd.screenplay.actions.Open;
import net.thucydides.core.annotations.Step;
import screenplay.ui.LoginPage;
import static net.serenitybdd.screenplay.Tasks.instrumented;
public class NavigateTo {
public static Task theLoginPage () {
return instrumented(NavigateToLoginPage.class);
}
public static Task theDashboard () {
return instrumented(NavigateToDashboard.class);
}
static class NavigateToLoginPage implements Task {
LoginPage loginPage;
@Override
@Step("{0} navigates to the login page")
public <T extends Actor > void performAs (T actor) {
actor.attemptsTo(Open.browserOn(loginPage));
}
}
static class NavigateToDashboard implements Task {
@Override
@Step("{0} navigates to the dashboard")
public <T extends Actor > void performAs (T actor) {
actor.attemptsTo(Open.url("/dashboard" ));
}
}
}
Screenplay Pattern - Questions
package screenplay.questions;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.Question;
import net.serenitybdd.screenplay.questions.Text;
import screenplay.ui.DashboardPage;
public class DashboardInfo {
public static Question<String> welcomeMessage () {
return Text.of(DashboardPage.WELCOME_MESSAGE);
}
public static Question<Boolean> isDisplayed () {
return actor -> {
try {
return DashboardPage.WELCOME_MESSAGE.resolveFor(actor).isVisible();
} catch (Exception e) {
return false ;
}
};
}
public static Question<Integer> notificationCount () {
return actor -> {
String text = Text.of(DashboardPage.NOTIFICATION_BADGE).answeredBy(actor);
return Integer.parseInt(text.trim());
};
}
}
Screenplay Pattern - UI Targets
package screenplay.ui;
import net.serenitybdd.screenplay.targets.Target;
import net.serenitybdd.core.pages.PageObject;
import net.thucydides.core.annotations.DefaultUrl;
@DefaultUrl("/login")
public class LoginPage extends PageObject {
public static final Target EMAIL_INPUT =
Target.the("email input" ).locatedBy("[data-testid='email-input']" );
public static final Target PASSWORD_INPUT =
Target.the("password input" ).locatedBy("[data-testid='password-input']" );
public static final Target LOGIN_BUTTON =
Target.the("login button" ).locatedBy("[data-testid='login-submit']" );
public static final Target ERROR_MESSAGE =
Target.the("error message" ).locatedBy("[data-testid='error-message']" );
public static final Target FORGOT_PASSWORD_LINK =
Target.the("forgot password link" ).locatedBy("a[href='/forgot-password']" );
}
package screenplay.ui;
import net.serenitybdd.screenplay.targets.Target;
public class DashboardPage {
public static final Target WELCOME_MESSAGE =
Target.the("welcome message" ).locatedBy("[data-testid='welcome-message']" );
public static final Target NOTIFICATION_BADGE =
Target.the("notification badge" ).locatedBy("[data-testid='notification-count']" );
public static final Target USER_MENU =
Target.the("user menu" ).locatedBy("[data-testid='user-menu']" );
public static final Target LOGOUT_BUTTON =
Target.the("logout button" ).locatedBy("[data-testid='logout']" );
}
JUnit 5 Test with Screenplay
package features.auth;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.abilities.BrowseTheWeb;
import net.serenitybdd.screenplay.ensure.Ensure;
import org.junit.jupiter.api.*;
import org.junit.jupiter.api.extension.ExtendWith;
import org.openqa.selenium.WebDriver;
import screenplay.questions.DashboardInfo;
import screenplay.tasks.Login;
import screenplay.tasks.NavigateTo;
import screenplay.ui.LoginPage;
import net.serenitybdd.screenplay.questions.Text;
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("User Authentication")
class LoginTest {
Actor alice = Actor.named("Alice" );
@BeforeEach
void setup () {
alice.can(BrowseTheWeb.with(theDefaultDriver()));
}
@Test
@DisplayName("Should login successfully with valid credentials")
@Tag("smoke")
void shouldLoginSuccessfully () {
alice.attemptsTo(
NavigateTo.theLoginPage(),
Login.withCredentials("user@example.com" , "SecurePass123" )
);
alice.attemptsTo(
Ensure.that(DashboardInfo.welcomeMessage()).contains("Welcome" )
);
}
@Test
@DisplayName("Should show error for invalid credentials")
@Tag("negative")
void shouldShowErrorForInvalidCredentials () {
alice.attemptsTo(
NavigateTo.theLoginPage(),
Login.withCredentials("user@example.com" , "wrongpassword" )
);
alice.attemptsTo(
Ensure.that(Text.of(LoginPage.ERROR_MESSAGE)).isEqualTo("Invalid credentials" )
);
}
@Test
@DisplayName("Should show validation error for empty email")
@Tag("negative")
void shouldShowErrorForEmptyEmail () {
alice.attemptsTo(
NavigateTo.theLoginPage(),
Login.withCredentials("" , "password123" )
);
alice.attemptsTo(
Ensure.that(LoginPage.ERROR_MESSAGE).isDisplayed()
);
}
}
Cucumber Integration # src/test/resources/features/auth/login.feature
@auth
Feature: User Authentication
As a registered user
I want to login to the application
So that I can access my personalized dashboard
Background:
Given Alice is on the login page
@smoke @positive
Scenario: Successful login with valid credentials
When she logs in with email "user@example.com" and password "SecurePass123"
Then she should see the dashboard
And she should see a welcome message containing "Welcome"
@negative
Scenario: Login fails with invalid credentials
When she logs in with email "user@example.com" and password "wrongpassword"
Then she should see an error message "Invalid credentials"
package stepdefinitions;
import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;
import net.serenitybdd.screenplay.Actor;
import net.serenitybdd.screenplay.ensure.Ensure;
import net.serenitybdd.screenplay.questions.Text;
import screenplay.questions.DashboardInfo;
import screenplay.tasks.Login;
import screenplay.tasks.NavigateTo;
import screenplay.ui.LoginPage;
public class LoginStepDefs {
Actor alice;
@Given("{actor} is on the login page")
public void onLoginPage (Actor actor) {
this .alice = actor;
actor.attemptsTo(NavigateTo.theLoginPage());
}
@When("she logs in with email {string} and password {string}")
public void loginWith (String email, String password) {
alice.attemptsTo(Login.withCredentials(email, password));
}
@Then("she should see the dashboard")
public void shouldSeeDashboard () {
alice.attemptsTo(
Ensure.that(DashboardInfo.isDisplayed()).isTrue()
);
}
@Then("she should see a welcome message containing {string}")
public void shouldSeeWelcomeMessage (String text) {
alice.attemptsTo(
Ensure.that(DashboardInfo.welcomeMessage()).contains(text)
);
}
@Then("she should see an error message {string}")
public void shouldSeeError (String message) {
alice.attemptsTo(
Ensure.that(Text.of(LoginPage.ERROR_MESSAGE)).isEqualTo(message)
);
}
}
Step Library Pattern (Classic Approach)
package steps;
import net.serenitybdd.core.pages.PageObject;
import net.thucydides.core.annotations.Step;
import org.openqa.selenium.By;
import static org.assertj.core.api.Assertions.assertThat;
public class AuthSteps extends PageObject {
@Step("Navigate to the login page")
public void navigateToLoginPage () {
openUrl(getBaseUrl() + "/login" );
waitForElementVisible(By.cssSelector("[data-testid='email-input']" ));
}
@Step("Enter email: {0}")
public void enterEmail (String email) {
find(By.cssSelector("[data-testid='email-input']" )).clear();
find(By.cssSelector("[data-testid='email-input']" )).sendKeys(email);
}
@Step("Enter password")
public void enterPassword (String password) {
find(By.cssSelector("[data-testid='password-input']" )).clear();
find(By.cssSelector("[data-testid='password-input']" )).sendKeys(password);
}
@Step("Click the login button")
public void clickLoginButton () {
find(By.cssSelector("[data-testid='login-submit']" )).click();
}
@Step("Verify user is on the dashboard")
public void verifyOnDashboard () {
waitForCondition()
.until(driver -> driver.getCurrentUrl().contains("/dashboard" ));
assertThat(getDriver().getCurrentUrl()).contains("/dashboard" );
}
@Step("Verify welcome message contains: {0}")
public void verifyWelcomeMessage (String text) {
String message = find(By.cssSelector("[data-testid='welcome-message']" )).getText();
assertThat(message).contains(text);
}
@Step("Verify error message: {0}")
public void verifyErrorMessage (String expected) {
String actual = find(By.cssSelector("[data-testid='error-message']" )).getText();
assertThat(actual).isEqualTo(expected);
}
}
REST API Testing with Serenity
package features.api;
import io.restassured.http.ContentType;
import net.serenitybdd.junit5.SerenityJUnit5Extension;
import net.serenitybdd.rest.SerenityRest;
import org.junit.jupiter.api.*;
import org.junit.jupiter.api.extension.ExtendWith;
import static net.serenitybdd.rest.SerenityRest.*;
import static org.hamcrest.Matchers.*;
@ExtendWith(SerenityJUnit5Extension.class)
@DisplayName("Users API")
class UsersApiTest {
private static final String BASE_URL = "http://localhost:3000/api" ;
@Test
@DisplayName("Should return list of users")
@Tag("api")
@Tag("smoke")
void shouldReturnUsers () {
given()
.baseUri(BASE_URL)
.contentType(ContentType.JSON)
.when ()
.get("/users" )
.then()
.statusCode(200 )
.body("size()" , greaterThan(0 ))
.body("[0].name" , notNullValue())
.body("[0].email" , notNullValue());
}
@Test
@DisplayName("Should create a new user")
@Tag("api")
void shouldCreateUser () {
String userJson = """
{
"name": "Alice Johnson",
"email": "alice@example.com",
"role": "user"
}
""" ;
given()
.baseUri(BASE_URL)
.contentType(ContentType.JSON)
.body(userJson)
.when ()
.post("/users" )
.then()
.statusCode(201 )
.body("name" , equalTo("Alice Johnson" ))
.body("email" , equalTo("alice@example.com" ))
.body("id" , notNullValue());
}
}
Serenity Configuration # src/test/resources/serenity.conf
serenity {
project.name = "My Project Acceptance Tests"
test.root = "features"
take.screenshots = FOR_EACH_ACTION
browser.maximized = true
webdriver {
driver = chrome
autodownload = true
}
}
headless.mode = true
environments {
default {
webdriver.base.url = "http://localhost:3000"
}
staging {
webdriver.base.url = "https://staging.example.com"
}
production {
webdriver.base.url = "https://www.example.com"
}
}
chrome {
switches = "--headless;--no-sandbox;--disable-dev-shm-usage;--window-size=1920,1080"
}
Maven Configuration
<properties >
<serenity.version > 4.1.0</serenity.version >
<maven.compiler.source > 17</maven.compiler.source >
<maven.compiler.target > 17</maven.compiler.target >
</properties >
<dependencies >
<dependency >
<groupId > net.serenity-bdd</groupId >
<artifactId > serenity-core</artifactId >
<version > ${serenity.version}</version >
<scope > test</scope >
</dependency >
<dependency >
<groupId > net.serenity-bdd</groupId >
<artifactId > serenity-junit5</artifactId >
<version > ${serenity.version}</version >
<scope > test</scope >
</dependency >
<dependency >
<groupId > net.serenity-bdd</groupId >
<artifactId > serenity-screenplay-webdriver</artifactId >
<version > ${serenity.version}</version >
<scope > test</scope >
</dependency >
<dependency >
<groupId > net.serenity-bdd</groupId >
<artifactId > serenity-cucumber</artifactId >
<version > ${serenity.version}</version >
<scope > test</scope >
</dependency >
<dependency >
<groupId > net.serenity-bdd</groupId >
<artifactId > serenity-rest-assured</artifactId >
<version > ${serenity.version}</version >
<scope > test</scope >
</dependency >
<dependency >
<groupId > net.serenity-bdd</groupId >
<artifactId > serenity-ensure</artifactId >
<version > ${serenity.version}</version >
<scope > test</scope >
</dependency >
</dependencies >
<build >
<plugins >
<plugin >
<groupId > net.serenity-bdd.maven.plugins</groupId >
<artifactId > serenity-maven-plugin</artifactId >
<version > ${serenity.version}</version >
<executions >
<execution >
<id > serenity-reports</id >
<phase > post-integration-test</phase >
<goals >
<goal > aggregate</goal >
</goals >
</execution >
</executions >
</plugin >
</plugins >
</build >
CI/CD Integration (GitHub Actions) name: Serenity BDD Tests
on: [push , pull_request ]
jobs:
serenity:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
with:
distribution: 'temurin'
java-version: '17'
- name: Run tests and generate reports
run: mvn clean verify
env:
BASE_URL: http://localhost:3000
- uses: actions/upload-artifact@v4
if: always()
with:
name: serenity-reports
path: target/site/serenity/
Best Practices
Use the Screenplay pattern for new projects. It produces more readable reports and scales better than Page Objects with step libraries.Name Targets descriptively — Target.the("login button") produces report entries like "Alice clicks on the login button".Create Task factory methods — Login.asAdmin(), Login.withCredentials(email, pass) improve readability and reusability.Use Questions for verification — Separate what you ask (Questions) from what you do (Tasks). This makes tests more composable.Configure screenshots strategically — Use FOR_EACH_ACTION in CI and FOR_FAILURES locally to balance report quality and speed.Use @Step annotations in step libraries to control how actions appear in Serenity reports.Run mvn verify (not mvn test) to generate Serenity HTML reports. The verify phase triggers report aggregation.Use environment profiles in serenity.conf for different environments (local, staging, production).Combine UI and API tests — Use Serenity REST Assured for API setup/verification alongside UI tests for true end-to-end coverage.Archive reports in CI — Upload Serenity HTML reports as build artifacts for easy access to living documentation.
Anti-Patterns to Avoid
Avoid bypassing the Screenplay pattern with direct WebDriver calls in tests. Use Tasks, Questions, and Interactions.Avoid unnamed Targets — Target.the("").locatedBy("...") produces unreadable reports. Always provide descriptive Target names.Avoid fat Tasks — A single Task should represent one user intention. Split complex workflows into composable smaller Tasks.Avoid mixing Step Libraries and Screenplay in the same project. Pick one approach and use it consistently.Avoid skipping @Step annotations — Without @Step, actions do not appear in Serenity reports, losing the living documentation benefit.Avoid hardcoded URLs — Use serenity.conf environments and webdriver.base.url instead of hardcoded strings.Avoid ignoring report generation — The Serenity report is a key deliverable. Always run mvn verify and archive reports.Avoid shared browser state — Each test should start with a clean browser. Use @BeforeEach or Serenity's automatic browser management.Avoid testing implementation — Test behaviors, not implementation details. Serenity reports should read like business scenarios.Avoid ignoring test parallelism — Configure Maven Failsafe for parallel execution. Design tests without shared mutable state. 