Skip to main content

Serenity BDD Reporter

Serenity reports are a powerful feature enabled by Serenity BDD. They aim not only to report test results, but also to document how features are tested, and what your application does. @serenity-js/serenity-bdd module enables integration between Serenity/JS and the Serenity BDD reporting CLI.

You will learn:

  • How to install Serenity BDD
  • How to configure Serenity BDD reporter
  • How to produce Serenity BDD reports
Example reports produced by Serenity BDD

Examples and Project Templates

If you'd like to dive straight into the code, Serenity/JS GitHub repository provides:

Example Serenity BDD reports

All the Serenity/JS project templates are configured to produce Serenity BDD reports and publish them to their GitHub Pages. Each Serenity/JS project template links to its respective Serenity BDD report from its readme file.

For example, here's where Serenity/JS + Cucumber + Playwright project template publishes its Serenity BDD reports.

Installation and usage

Serenity BDD reports are generated by Serenity BDD CLI, a Java program downloaded and managed by the @serenity-js/serenity-bdd module.

SerenityBDDReporter is also available as part of the @serenity-js/serenity-bdd module. It listens to domain events emitted by actors, test runner adapters, and other stage crew members, to produce Serenity BDD-compatible JSON reports, which can be then stored as files to disk by ArtifactArchiver.

Resulting JSON files can be processed by Serenity BDD CLI to produce a HTML report and rich living documentation containing screenshots, details of HTTP traffic for any REST API interactions, details of any activities performed by Serenity/JS actors and more.

Installation

To install the @serenity-js/serenity-bdd module, run the following command in your computer terminal:

npm install --save-dev @serenity-js/{core,serenity-bdd}

To learn more about the installation process, follow the API documentation.

Configuration

To use the Serenity BDD Reporter, you need to register it together with the Artifact Archiver so that the reports are stored to disk:

import { configure } from '@serenity-js/core'

configure({
crew: [
'@serenity-js/serenity-bdd',
[ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
]
})

To learn how to configure Serenity BDD Reporter with your test runner, follow the API documentation.

Reporting

To produce Serenity BDD reports, your test suite must:

  • download the Serenity BDD CLI, by calling serenity-bdd update, which will cache the CLI jar locally
  • produce intermediate Serenity BDD .json reports, by registering SerenityBDDReporter
  • invoke the Serenity BDD CLI when you want to produce the report, by calling serenity-bdd run

The pattern used by all the Serenity/JS Project Templates relies on using:

  • a postinstall NPM script to download the Serenity BDD CLI
  • npm-failsafe to run the reporting process even if the test suite itself has failed (which is precisely when you need test reports the most...).
  • rimraf as a convenience method to remove any test reports left over from the previous run
package.json
{
"scripts": {
"postinstall": "serenity-bdd update",
"clean": "rimraf target",
"test": "failsafe clean test:execute test:report",
"test:execute": "cucumber-js",
"test:report": "serenity-bdd run --features ./features ",
}
}

Note that in the above code sample, you should configure test:execute to invoke your test runner of choice.

To learn more about the SerenityBDDReporter, please consult:

You might also want to explore Serenity/JS example projects on GitHub.

Integration

SerenityBDDReporter emits ArtifactGenerated containing Serenity BDD-standard JSON reports, which can be stored to disk by ArtifactArchiver, and then turned into Serenity BDD HTML reports by Serenity BDD Reporting CLI.