Serenity BDD review: tutorial, pros and cons

Serenity instruments your test code so that it can record what happens inside a test, not just whether it passed. Methods annotated with @Step in action classes, Screenplay tasks and interactions, and Cucumber steps all become entries in the test’s outcome, with their parameters, timing, screenshots and any REST requests and responses. During the run Serenity writes these outcomes as JSON files under target/site/serenity. That separation matters: the run itself only produces data, and the readable report is built afterwards from the data, which is why the same results can be rendered as a full site or a single-page summary.

After the tests finish, the aggregate goal of the serenity-maven-plugin, or the aggregate task in Gradle, reads every JSON outcome and generates the HTML report at target/site/serenity/index.html. The Requirements tab is the heart of it. Serenity derives a requirements hierarchy from the folder structure of feature files for Cucumber, or the package structure for JUnit, so a folder per capability containing a feature file per feature becomes a tree of capabilities and features with their scenarios and status. Pending scenarios, written but not yet automated, appear too, which is what lets the report describe what the product should do as well as what passed.

Screenplay models a test as actors who have abilities, such as browsing the web or calling an API, and who perform tasks made of smaller interactions, then ask questions about the state of the system. An actor attemptsTo open a page, enter a value or add an item, and the report renders those calls almost word for word. Because tasks are small objects composed from interactions rather than methods on a page class, they combine freely and are reused across features without inheritance hierarchies. The cost is more classes and a vocabulary that new team members must learn before they are productive.

Serenity is not a test runner. For JUnit tests it plugs in through SerenityJUnit5Extension; for Cucumber it plugs in as a Cucumber plugin, SerenityReporterParallel, configured on a JUnit Platform suite class. Execution, discovery, tags and parallelism therefore follow the underlying framework. Serenity adds the WebDriver lifecycle through @Managed fields or cast members, configuration through serenity.conf, and its reporting. Version alignment follows too: Serenity 5.4.0, released on 13 October 2026, moves its dependency management to Cucumber-JVM 8.0.4, JUnit 6.1.3 and Selenium 4.51.0.

Design the folder structure first, because it becomes the report. For Cucumber, put feature files under src/test/resources/features in a folder per capability, for example features/checkout and features/loyalty, with one feature file per feature; Serenity turns that tree into the Requirements tab. For JUnit, the package structure plays the same role, rooted at the package named by serenity.test.root. Keep the depth consistent across branches, since the documentation notes that uneven depths confuse the hierarchy. Keep Screenplay classes, tasks, questions and targets in their own package, separate from tests, because they are reused across many features. Hold browser and environment settings in serenity.conf rather than in code.

With Cucumber, the pattern is a thin step definition that hands work to an actor. A custom parameter type turns a name in the step text into an actor from the stage, so a step such as {actor} adds {string} to the list receives Toby or Rama directly. A @Before hook sets the stage with an OnlineCast, which gives each actor a browser. Tasks are built with Task.where, which takes a description that appears in the report and the interactions it performs. Keep tasks small and named in business terms; a task that needs a long description is usually two tasks.

The pipeline is a Maven build with one difference from a plain JUnit project: the job must run verify so the aggregate goal builds the report, and the report folder should be uploaded even when tests fail, because a failing run is exactly when the report is needed. Run headless in CI through headless.mode in serenity.conf or a system property. The Serenity documentation also shows publishing the report to GitHub Pages for a browsable history of the latest run on main.

Parallel execution comes from Cucumber on the JUnit Platform, not from Serenity, so it is configured in junit-platform.properties. The suite class must register Serenity’s SerenityReporterParallel plugin so that outcomes from concurrent scenarios are recorded correctly. Each actor in an OnlineCast gets its own browser, so scenarios are isolated as long as test data is unique per scenario. Start with a fixed parallelism that matches the cores and memory of the CI runner, since each thread runs a browser.

Serenity 5.0.0, published in December 2025, raised the Java baseline from 11 to 17 and moved to JUnit 6. Serenity 5.4.0, released on 13 October 2026, aligns with Cucumber-JVM 8, so read the Cucumber 8 notes too: Java 17, the JUnit Platform engine instead of the deprecated JUnit 4 and TestNG runners, and an explicit Jackson dependency for some Cucumber report plugins. Projects coming from Serenity 3 also need the 4.0 package changes, such as @Step and @Managed moving to net.serenitybdd.annotations. Day to day, pick one style, Screenplay or action classes, and keep to it; set screenshots to FOR_FAILURES unless an audit needs more; and review the Requirements tab with product owners, which is the point of the tool.