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.

Installation

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

• @serenity-js/core
• @serenity-js/cucumber
• @cucumber/cucumber

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

Configuration

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';

configure({
    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');

configure({
    crew: [
        // ... reporting services
    ],
});

Learn more about Serenity/JS reporting services.

Reporting

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.