@serenity-js/serenity-bdd

Serenity/JS

Serenity/JS is a Node.js library designed to make acceptance and regression testing of modern full-stack applications faster, more collaborative and easier to scale.

Serenity BDD

The @serenity-js/serenity-bdd module integrates Serenity/JS and the Serenity BDD reporting CLI.

This integration enables your Serenity/JS tests to produce interim JSON reports, which the Serenity BDD reporting CLI can then turn into world-class, illustrated test reports and living documentation.

Installation

npm install --save-dev @serenity-js/core @serenity-js/assertions @serenity-js/rest @serenity-js/serenity-bdd

SerenityBDDReporter

To allow Serenity/JS to produce Serenity BDD-standard JSON reports, assign the SerenityBDDReporter to the Stage and configure the ArtifactArchiver to store the reports at the location where Serenity BDD expects to find them.

This can be done in your protractor.conf.js file if you're using Protractor, or programmatically.

Programmatic configuration

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

serenity.setTheStage(
    ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
    new SerenityBDDReporter(),
);

Protractor

// protractor.conf.js

const
    { ArtifactArchiver }    = require('@serenity-js/core'),
    { SerenityBDDReporter } = require('@serenity-js/serenity-bdd'),

exports.config = {

    framework:      'custom',
    frameworkPath:  require.resolve('@serenity-js/protractor/adapter'),

    serenity: {
        crew: [
            ArtifactArchiver.storingArtifactsAt('./target/site/serenity'),
            new SerenityBDDReporter(),
        ]
    },

    // ...
}

Serenity BDD Living Documentation

To turn the Serenity BDD-standard JSON reports produced by the SerenityBDDReporter into Serenity BDD test reports, you need the Serenity BDD reporting CLI.

The Serenity BDD reporting CLI is a Java program, distributed as an executable .jar file and available on Bintray.

This module ships with a serenity-bdd CLI wrapper that makes downloading and running the Serenity BDD reporting CLI easy.

To learn more about the usage of the serenity-bdd wrapper, run:

npx serenity-bdd --help

Downloading the Serenity BDD reporting CLI

To download the Serenity BDD reporting CLI or update it, use the update command:

npx serenity-bdd update

Please note that the update command will try to download the jar only if you don't have one cached already, or when the one you have is not up to date. Otherwise no outbound network calls are made.

If you're behind a corporate proxy server that causes certificate errors you can tell the wrapper to ignore the SSL certificate check:

npx serenity-bdd update --ignoreSSL

You can also tell it to download the Serenity BDD reporting CLI jar from your company's artifact repository if you can't use the official Bintray one:

npx serenity-bdd update --repository https://artifactory.example.org/

To learn more about the update command, run:

npx serenity-bdd --help update

Producing the Serenity BDD test report

To produce the Serenity BDD test report and living documentation using default settings, run:

npx serenity-bdd run

To learn more about the run command and how to change the default settings, run:

npx serenity-bdd --help run

Using NPM scripts

The easiest way to ensure that the Serenity BDD reporting CLI is up to date and that the Serenity BDD test report is produced after each test run is to add the following entries to the scripts section of the package.json file:

{
  "scripts": {
    "test:update-serenity": "serenity-bdd update",
    "test:acceptance": "/* invoke the test runner */",
    "test:report": "serenity-bdd run",
    "test": "failsafe test:acceptance test:update-serenity test:report",
    // ... other scripts
  },
  // ... other config
}

In the above example, the npm-failsafe module is used to invoke each of the test:update-serenity, test:acceptance and test:report scripts when npm test is executed. This is to ensure that the Serenity BDD report is produced even when there is a test failure.