serenity-core: reports that turn test runs into living documentation

Two jobs: record the steps, then aggregate them into a report

Serenity BDD is described as a library designed to make writing automated acceptance tests easier, and more fun. The project README puts the value as a feeling: that you get when you know you can trust your tests.

The mechanism is described as working in two ways, and the split explains the whole design. First, it instruments your test code and reports on the steps that your tests execute to achieve their goals, and stores the test results in a standardized format. Second, it aggregates those test results into clear and meaningful reports that reflect not only the outcomes of your tests but also the status of your project. The example given is reporting on what requirements, features or stories you have implemented, and how well, or not, they were tested.

That second half is the differentiating part. A standard JUnit report tells you which test methods passed. A Serenity report tells you which requirements have passing tests, which requirements have no tests at all, and where a feature's steps diverge from the acceptance criteria it claims to cover. That is a different question, and it is the one a project lead actually asks.

The library provides tight integration with Selenium WebDriver and with RestAssured, so both web and API testing are covered, and it sits on top of tools like Cucumber and JUnit rather than replacing them. The test framework you already have stays; Serenity adds the reporting and the structure on top.

The documentation lives at serenity-bdd.info, and the repository is under the serenity-bdd organisation with a Continuous Integration badge and javadoc published on javadoc.io.

Page objects, action classes and the Screenplay pattern

The README's section on making tests cleaner lists the patterns Serenity supports: tight integration with Selenium WebDriver, and modern testing patterns such as Lean Page Objects, Action Classes, and the Screenplay Pattern.

These are three different levels of abstraction over the same problem, and choosing between them is the main design decision a new user makes.

Page objects wrap the page, so a test reads as a sequence of page interactions. Action classes sit between the test and the page objects, grouping a business intention into a named method, which is what stops a test class turning into a wall of one-line steps. The Screenplay pattern goes further and introduces actors with abilities and tasks, so the test is written as an actor performing a task, and the ability decides whether that is a web interaction or an API call.

That last point is why the Screenplay pattern is worth the extra structure in a library that also does API testing. The same task can be performed through a different ability without the test changing, which is the mechanism for testing a system at the API level and the UI level against the same requirement.

The repository layout shows how many of these variants are supported as separate modules. There are `serenity-screenplay/`, `serenity-screenplay-webdriver/`, `serenity-screenplay-rest/`, `serenity-screenplay-playwright/`, `serenity-rest-assured/`, `serenity-playwright/`, `serenity-webdriver`-style integrations and a set of cloud and cross browser providers including `serenity-browserstack/`, `serenity-saucelabs/`, `serenity-lambdatest/`, `serenity-bitbar/` and `serenity-crossbrowsertesting/`. There is also `serenity-appium/` with an Appium Screenplay proof of concept, and `serenity-mobile-screenplay-example/`.

A `serenity-bom/` module is present, which is the standard Maven mechanism for keeping a family of modules on aligned versions, and there is a `serenity-model/` module alongside `serenity-core/` and `serenity-reports/`.

The report types and the modules behind them

The reporting side is where most of the module count goes, and the top level directory listing shows the full set of artefacts this project produces.

The reports are grouped into `serenity-reports/`, `serenity-report-resources/`, `serenity-reports-configuration/`, `serenity-navigator-report/` and `serenity-json-summary-report/`. The navigator report is the one that drives the drill-down experience the README describes: you start from a test summary, move to a requirements summary, then into feature details, and finally into a test details view that includes the interactions and screenshots from the run. The screenshots are what make a failure explainable to someone who did not write the test.

Beyond the HTML reports there are integration modules that push results elsewhere. `serenity-json-summary-report/` produces a machine-readable summary, which is what a CI job would consume, and the `serenity-junit/` and `serenity-junit5/` modules exist for the JUnit 4 and JUnit 5 runners, while `serenity-cucumber/` and `serenity-jbehave/` are the BDD runner integrations. `serenity-cli/` is there for running from the command line, and `serenity-maven-plugin/` and `serenity-ant-task/` hook the build into Maven and Ant.

The `serenity-assertions/` module is the assertion library, and `serenity-ensure/` provides the soft assertion style, where a test records several failures rather than stopping at the first one. That matters for report quality, because a test that stops at the first failed assertion produces one symptom where it could have produced five.

The `serenity-asciidoc/` module is worth noting for teams that keep their documentation in AsciiDoc, since it lets a report feed into that documentation rather than living beside it.

There is also `serenity-playwright-demo/` and `serenity-browsermob-plugin/`, the latter for capturing network traffic during a browser test, and `serenity-model/` which holds the shared model used across modules.

Getting the project into your build

The README does not contain an install command, so there is nothing here to copy. The project points to the official Serenity BDD website for tutorials and documentation, and the repository itself is where you look for the build and the module set.

What the repository layout does tell you about the build is enough to orient yourself. There is a `pom.xml` at the root, a `mvnw` and `mvnw.cmd` wrapper pair, a `.mvn/` directory, a `gradle/` directory, and a `release.sh` script, so the project builds with Maven and also supports a Gradle path. A `Jenkinsfile` is present, which is the older CI system the project still carries alongside the GitHub Actions workflow indicated by the Continuous Integration badge.

The `docs/` directory and the `design/` directory sit at the root, and there is a `serenity-sample-alternative-resources/` module, which suggests the sample projects double as a source of alternative resource bundles.

Two build helpers are worth pointing out. `install-phantomjs.sh` sits at the root, a leftover from the era when headless browser testing on Linux needed a PhantomJS binary installed separately, and `infinitest.filters` is a configuration file for the Infinitest continuous test runner, which is a JVM library that reruns tests when the classes they depend on change. Neither is central to using Serenity, but both explain parts of the project's history.

The `GITHUB_RELEASE_SETUP.md` file and the `release.sh` script describe how tagged releases are cut, and the `CHANGELOG.md` at the root is the version history.

The Jira modules are deprecated and their tests are disabled

One section of the README is unambiguous, and it changes the picture for anyone planning to use the Jira integration.

The Jira integration modules, `serenity-jira-plugin` and `serenity-jira-requirements-provider`, are deprecated and no longer actively maintained. The stated reason is that Atlassian's API token restrictions, mandatory expiration, limited scopes and permission changes, make it impractical to reliably test and maintain these integrations. The modules remain in the codebase for existing users, but the tests are disabled and no further development is planned.

The reason is instructive rather than a complaint. A test-driven project cannot keep a module whose upstream API can change underneath it in ways the test suite cannot exercise, and token expiry and scope restrictions are exactly the kind of change that would break a test run for reasons unrelated to the code under test. Disabling the tests is the honest response to that.

The README does suggest a route if Jira integration matters to your project or organisation: the decision could be revisited via a commercial support package, and there is a separate Academy site offering support packages and one-on-one troubleshooting sessions.

The same section carries the project's funding model, which is worth understanding before you adopt it. The README states that pretty much all current development on the Serenity code base is driven by commercial support contracts, and that as with any open source project, support is never free, it is paid for from a volunteer's spare time, through a sponsoring organisation or via a commercial support package. Bug fixes or change requests coming from sponsors are generally prioritised over other requests, and the README asks for as much context as possible in a bug report, naming the Serenity version, the browser and driver versions, and the operating system.

The licence is a custom one, in a `licence.txt` file at the repository root, which GitHub's classifier cannot categorise. That is a detail to read before you build on it.

Against a plain JUnit report and against a commercial test tool

The comparison worth making is with what you would otherwise do.

The first alternative is to keep the JUnit XML report that your build already produces and add a report viewer on top. That is cheaper, since the XML is already there, and it is the right answer when the audience is engineers who already read test output. What it cannot do is the second half of what Serenity does, which is reporting on the requirements hierarchy and the state of the acceptance criteria associated with those requirements. A JUnit report tells you about test methods; Serenity's reports tell you about coverage of stated requirements, including the requirement that has no test at all. If your team's conversation is about features and acceptance criteria rather than about methods, that difference is the whole value.

The second alternative is a commercial test management tool. Such a tool typically adds requirements tracking, dashboards, issue integration and manual test management on top of the automated run, and it does so with a per-user licence and a server to run. Serenity's advantage is that it derives the requirement view from artefacts you already have, the Gherkin feature files and the test annotations, rather than asking someone to maintain a second copy of the requirements in a separate system. Its disadvantage is the same in reverse: because it derives from the tests, a requirement that exists only in a tracker and not in a feature file is invisible to it.

The pragmatic reading is that Serenity earns its place when your team has already committed to BDD and the feature files are the source of truth. It is a reporting layer over a structure you have, not a substitute for deciding how requirements are expressed.

Editorial conclusion

Adopt serenity-core if your team already writes Cucumber, JBehave or JUnit tests and wants reports that a product owner can read, with the requirement hierarchy and acceptance criteria visible. Do not adopt it if you need the Jira integration, since those modules are deprecated with tests disabled, and check first that you are prepared for a library where the open source release line is older than the code, because the last push was on 2026-10-14 while the latest listed release is v4.0.1 from 2024-01-10.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. serenity-bdd/serenity-core on GitHub