Skip to main content

@serenity-js/serenity-bdd

Follow Serenity/JS on LinkedIn Watch Serenity/JS on YouTube Join Serenity/JS Community Chat Support Serenity/JS on GitHub

Serenity/JS is an innovative open-source framework designed to make acceptance and regression testing of complex software systems faster, more collaborative and easier to scale.

⭐️ Get started with Serenity/JS!

👋 Join the Serenity/JS Community!

Serenity BDD​

@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. Learn more about Serenity/JS reporting.

Installation​

To install this module, run the following command in your computer terminal:

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

To learn more about Serenity/JS and how to use it on your project, follow the Serenity/JS Getting Started guide.

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:

  • via playwright.config.ts, if you're using Serenity/JS with Playwright Test
  • via wdio.conf.ts, if you're using Serenity/JS with WebdriverIO
  • via protractor.conf.js, if you're using Serenity/JS with Protractor
  • or programmatically.

Usage with Playwright Test​

Learn more about using Serenity/JS with Playwright Test.

// playwright.config.ts
import type { PlaywrightTestConfig } from '@serenity-js/playwright-test'

const config: PlaywrightTestConfig = {
    reporter: [
        [ '@serenity-js/playwright-test', {
            crew: [
                '@serenity-js/serenity-bdd',
                [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],
            ]
        }]
    ],

    // Other configuration omitted for brevity
    // For details, see https://playwright.dev/docs/test-configuration    
}

export default config

Usage with WebdriverIO​

Learn more about using Serenity/JS with WebdriverIO.

// wdio.conf.ts

import { WebdriverIOConfig } from '@serenity-js/webdriverio'

export const config: WebdriverIOConfig = {

    framework: '@serenity-js/webdriverio',

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

    // Other configuration omitted for brevity
    // For details, see https://webdriver.io/docs/options
}

Usage with Protractor​

Learn more about using Serenity/JS with Protractor.

// protractor.conf.js

exports.config = {

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

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

    // ...
}

Programmatic configuration​

Learn more about configuring Serenity/JS programmatically.

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

configure({
    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

Configuring Serenity BDD reporting CLI​

To configure the Serenity BDD reporting CLI, place a file called serenity.properties in your project root directory.

For example:

# serenity.properties
serenity.project.name=My awesome project

Please note that the reporting CLI considers only those properties that are related to producing test reports. Learn more about configuring serenity.properties.

Downloading the Serenity BDD reporting CLI​

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

npx serenity-bdd update

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

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

Downloading through a proxy​

The update command will pick up your proxy configuration automatically from your NPM config, .npmrc file, or environment variables.

Please note that you only need to use one of those configuration mechanisms.

Use NPM config (Linux, macOS, Windows)​

To use NPM-level configuration, run the following commands in your terminal:

npm config set proxy http://[user:pwd]@domain.tld:port
npm config set https-proxy http://[user:pwd]@domain.tld:port

If your proxy requires a certificate file, you can provide a path to it as follows:

npm config set cafile /path/to/root-ca.pem

The above can also be accomplished by placing an .npmrc file with following contents in your home directory or your project root:

# ~/.npmrc
proxy = http://[user:pwd]@domain.tld:port
https-proxy = http://[user:pwd]@domain.tld:port

cafile = /path/to/root-ca.pem          # optional
noproxy = localhost,mycompany.com      # optional
Environment variables on Linux or macOS​

To set your proxy on Linux or macOS, run the following commands in your terminal:

export HTTP_PROXY=http://[user:pwd]@domain.tld:port
export HTTPS_PROXY=http://[user:pwd]@domain.tld:port

If needed, you can also set a NO_PROXY variable to a comma-separated list of domains that don't require a proxy, for example:

export NO_PROXY=localhost,mycompany.com

Please note that you can add the above commands to your shell's ~/.profile, so that they're executed whenever you open a new terminal.

Environment variables on Windows​

To configure a proxy on Windows, run the following commands in Command Prompt:

set HTTP_PROXY=http://[user:pwd]@domain.tld:port
set HTTPS_PROXY=http://[user:pwd]@domain.tld:port

If you're using Powershell, run the following commands instead:

$env:HTTP_PROXY = http://[user:pwd]@domain.tld:port
$env:HTTPS_PROXY = http://[user:pwd]@domain.tld:port
Use a specific User-Agent​

If your artifact registry requires you to use a specific user agent, you can configure it using NPM config:

npm config set user-agent "Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Firefox/52.0"
Ignore SSL checks​

You can instruct the update command to ignore any SSL certificate errors by providing an --ignoreSSL flag when running the command: 

npx serenity-bdd update --ignoreSSL

You can also disable certificate checks at the NPM config level by running: 

npm config set strict-ssl false

Alternative, you can accomplish the same with an .npmrc file:

# ~/.npmrc
npm_config_strict-ssl = false

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​

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

In general, to produce Serenity BDD reports, your test suite must:

  • download the Serenity BDD CLI, by calling serenity-bdd update
  • 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:

  • an NPM postinstall 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.

📣 Stay up to date​

New features, tutorials, and demos are coming soon! Follow Serenity/JS on LinkedIn, subscribe to Serenity/JS channel on YouTube and join the Serenity/JS Community Chat to stay up to date! Please also make sure to star ⭐️ Serenity/JS on GitHub to help others discover the framework!

Follow Serenity/JS on LinkedIn Watch Serenity/JS on YouTube Join Serenity/JS Community Chat GitHub stars

💛 Support Serenity/JS​

If you appreciate all the effort that goes into making sophisticated tools easy to work with, please support our work and become a Serenity/JS GitHub Sponsor today!

GitHub Sponsors

Index

Functions

Stage