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-js/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.