Integrating with Cucumber

Cucumber is a popular collaboration tool and a test runner capable of executing test scenarios written in plain language.

When you integrate Cucumber.js with Serenity/JS, the framework gathers and reports additional data about your Cucumber scenarios, even if they don't follow the Screenplay Pattern yet! Information reported includes scenario details, details of executed Cucumber steps, their arguments, provide code snippets for steps with missing implementation, and much more.

If you prefer to dive straight into the code, several reference implementations are available in the Serenity/JS GitHub repository. Those implementations demonstrate using Cucumber and Serenity/JS to run both REST API- and Web-based acceptance tests.

Integration architecture

@serenity-js/cucumber module provides a set of test runner adapters, or "formatters" in Cucumber-speak, for any version of Cucumber.js. The module picks the most appropriate adapter automatically, depending on the version of Cucumber.js you're using.

Serenity/JS test runner adapters translate the events that occur in the test runner to Serenity/JS DomainEvents; those can be then turned into test reports by Serenity/JS reporting services.

graph TB DEV(["fas:fa-laptop-code Developer"]) TR(["@cucumber/cucumber"]) SC(["@serenity-js/core"]) TRA(["@serenity-js/cucumber"]) CF["fas:fa-file config.ts"] R(["fas:fa-chart-pie Serenity/JS reporting services"]) DEV -- invokes --> TR TR -- loads --> CF TR -- notifies --> TRA TRA -- notifies --> SC CF -- configures --> SC SC -- notifies --> R class R socket click R "/handbook/reporting/index.html" click SC "/modules/core" click TRA "/modules/cucumber"

PRO TIP: Integration architecture described in this chapter is applicable when you want to invoke cucumber-js command line interface directly, for example for domain-level or REST/HTTP API-level testing.

If you want your Cucumber scenarios to interact with Web interfaces, check out Integrating with Protractor instead.


Assuming you already have a Node.js project set up, add the following dev dependencies:

To do that, run the following command in your terminal:

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

If you'd like to implement your test suite in TypeScript, also run:

npm install --save-dev typescript ts-node @types/node


In a TypeScript project, create a configuration file at features/support/config.ts to inform Serenity/JS what reporting services you wish to use:

// features/support/config.ts
import { configure } from '@serenity-js/core';

    crew: [
        // ... reporting services

In a JavaScript project, create a configuration file at features/support/config.js instead:

// features/support/config.js
const { configure } = require('@serenity-js/core');

    crew: [
        // ... reporting services

Learn more about Serenity/JS reporting services.


To register @serenity-js/cucumber test runner adapter with Cucumber, use the --format option when invoking the runner.

For example, when running Cucumber in a JavaScript project:

npx cucumber-js --format '@serenity-js/cucumber' \
    --require 'features/support/config.js' \
    [... any other options]

To make Cucumber support step definitions and configuration written in TypeScript, you'll need to add a dev dependency on ts-node and register it via --require-module:

npx cucumber-js --format '@serenity-js/cucumber' \
    --require-module 'ts-node/register' \
    --require 'features/support/config.ts' \ 
    [... any other options]

The above configuration works with the latest version of the cucumber.Cli available as part of the @cucumber/cucumber module. Consult the @serenity-js/cucumber documentation to learn how to configure the adapter with older versions of the runner.

To install and configure Serenity/JS reporting services appropriate for your project - follow the Serenity/JS reporting guide.

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.