Serenity BDD Reporter

SerenityBDDReporter is available as part of the @serenity-js/serenity-bdd module.

This reporter emits Artifacts 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.

The resulting report contains screenshots, details of HTTP traffic for any REST API interactions, details of any activities performed by Serenity/JS Actors and more.

Serenity BDD report
Example Serenity BDD report


To use the SerenityBDDReporter, install the @serenity-js/serenity-bdd module:

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

To generate Serenity BDD HTML reports, you'll need the Serenity BDD Reporting CLI. You can download it using the serenity-bdd command available as part of this module:

npx @serenity-js/serenity-bdd update

The best way to ensure you always have the latest version of the CLI available is to run serenity-bdd update whenever you run npm install. To automate this process, add the below entry to your package.json:

  "scripts": {
    "postinstall": "serenity-bdd update"

Please note: Serenity BDD Reporting CLI is a Java library, so make sure you have installed the Java Runtime Environment.


SerenityBDDReporter listens to DomainEvents emitted by Actors and Serenity/JS test runner adapters.

When a test scenario finishes (see SceneFinishes event), the reporter emits an Artifact containing a Serenity BDD-standard JSON report.

This artifact is then stored to disk by the ArtifactArchiver, where it can be parsed by the Serenity BDD Reporting CLI and used to generate a HTML report.

graph TB A(["fas:fa-users Actors"]) TRA(["fas:fa-plug Serenity/JS test runner adapter"]) DEV(["fas:fa-laptop-code Developer"]) S["Serenity"] AA["ArtifactArchiver"] SBDDR["SerenityBDDReporter"] SBDDW["fas:fa-terminal serenity-bdd run"] TA["fas:fa-file json, png, etc."] SBDDCLI(["fab:fa-java serenity-bdd-cli.jar"]) HTML["fas:fa-chart-pie Serenity BDD HTML reports"] A -- notify --> S TRA -- notifies --> S DEV -- invokes -----> SBDDW S -- notifies ---> SBDDR S -- "notifies
[ArtifactGenerated]" ---> AA AA -- "stores
[Artifact]" ----> TA SBDDR -- "notifies
[ArtifactGenerated]" --> S SBDDW -- manages --> SBDDCLI SBDDCLI -- reads --> TA SBDDCLI -- produces --> HTML subgraph "serenity-bdd" SBDDR SBDDCLI SBDDW end subgraph "core" S AA end subgraph "file system" TA HTML end class A socket class TRA socket class R socket click A "/handbook/design/actors.html" click S "/modules/core/class/src/Serenity.ts~Serenity.html" click AA "handbook/reporting/artifact-archiver.html" click SBDDR "/modules/serenity-bdd/class/src/stage/crew/serenity-bdd-reporter/SerenityBDDReporter.ts~SerenityBDDReporter.html" click SBDDW "/modules/serenity-bdd"


To use the SerenityBDDReporter, register it as one of the StageCrewMembers, together with the ArtifactArchiver:

import { configure, ArtifactArchiver } from '@serenity-js/core';
import { SerenityBDDReporter } from '@serenity-js/serenity-bdd';

    crew: [
        new SerenityBDDReporter(),

When your test suite has finished running, generate the Serenity BDD reports by executing the following command in your terminal:

npx @serenity-js/serenity-bdd run

To automate this process, install the following additional modules:

npm install --save-dev rimraf npm-failsafe

Next, add the below scripts to your package.json:

  "scripts": {
    "postinstall": "serenity-bdd update",
    "test": "failsafe test:clean test:run test:report",
    "test:clean": "rimraf target/site/serenity",
    "test:run": "/* invoke your test runner of choice, i.e. cucumber-js */",
    "test:report": "serenity-bdd run"    

Now to run your test suite, execute:

npm test

The above command invokes:

  • test:clean, which removes any artifacts left over from the previous run,
  • test:run, which invokes your test runner of choice, configured with an appropriate Serenity/JS test runner adapter (learn how to configure Serenity/JS with Cucumber, Mocha, or Jasmine),
  • test:report, which instructs the Serenity BDD Reporting CLI to generate the HTML report.

To learn more about the available configuration options of the SerenityBDDReporter and the serenity-bdd command, consult the documentation of the @serenity-js/serenity-bdd module.

You might also want to explore the example projects.

Love Serenity/JS? Spread the word on Twitter and LinkedIn!

Found a typo? You can fix it yourself or raise a ticket on GitHub.

If you'd like to help us bring more great tools and content to the Open-Source Community, become a GitHub Sponsor of Serenity/JS for as little as the cost of a cup of coffee.