Allure Cucumber.js

Generate beautiful HTML reports using Allure Report and your Cucumber.js tests.

Allure Report Cucumber.js Example

Check out the example project at github.com/epszaw/allure-cucumberjs-demo to see Allure Cucumber.js in action.

How to start

1. Prepare your project

These instructions depend on whether you have some Cucumber.js tests already or you're just starting a project.

Adding Allure Cucumber.js to an existing project

If you have some Cucumber.js tests, and you want to be able to use Allure Report with them:

Open a terminal and go to the project directory. For example:
```
Bash
cd /home/user/myproject
```
Install the Allure Report command-line tool, if it is not yet installed in your operating system. Note that Allure Report requires Java, see the installation instructions.
```
Bash
npm install --save-dev allure-commandline
```
```
Bash
yarn add --dev allure-commandline
```
```
Bash
pnpm install --dev allure-commandline
```

Install the Allure Cucumber.js adapter.

Bash
npm install --save-dev allure-cucumberjs

Bash
yarn add --dev allure-cucumberjs

Bash
pnpm install --dev allure-cucumberjs

Create the reporter.js file defining the Reporter class like shown below.

The resultsDir option here points to the allure-results directory in the project's root. This is the directory where Allure Cucumber.js will accumulate test results that will later be used by the Allure Report command-line utility.

The third argument for the CucumberJSAllureFormatter constructor is for providing configuration options for Allure Cucumber.js. To use the default options, pass the empty object {}, as shown in the example.
```
JavaScript
const { CucumberJSAllureFormatter, AllureRuntime } = require("allure-cucumberjs");
const path = require("path");

class Reporter extends CucumberJSAllureFormatter {
  constructor(options) {
    super(
      options,
      new AllureRuntime({
        resultsDir: path.resolve(__dirname, "allure-results"),
      }),
      {},
    );
  }
}

module.exports = Reporter;
```

In the Cucumber.js configuration file (e.g., cucumber.js), specify path to the reporter.js file in the format setting. For example:

JavaScript
const path = require("path");

module.exports = {
  default: {
    format: [path.resolve(__dirname, "reporter.js")],
  },
};

Starting a new project with Allure Cucumber.js

If you are starting a new project which will contain Cucumber.js tests:

Create a directory for the project.
Open a terminal and go to the project directory. For example:
```
Bash
cd /home/user/myproject
```
Install the Allure Report command-line tool, if it is not yet installed in your operating system. Note that Allure Report requires Java, see the installation instructions.
```
Bash
npm install --save-dev allure-commandline
```
```
Bash
yarn add --dev allure-commandline
```
```
Bash
pnpm install --dev allure-commandline
```

Install both the Cucumber.js test framework and the Allure Cucumber.js adapter.

Bash
npm install --save-dev @cucumber/cucumber allure-cucumberjs

Bash
yarn add --dev @cucumber/cucumber allure-cucumberjs

Bash
pnpm install --dev @cucumber/cucumber allure-cucumberjs

Create the reporter.js file defining the Reporter class like shown below.

The resultsDir option here points to the allure-results directory in the project's root. This is the directory where Allure Cucumber.js will accumulate test results that will later be used by the Allure Report command-line utility.

The third argument for the CucumberJSAllureFormatter constructor is for providing configuration options for Allure Cucumber.js. To use the default options, pass the empty object {}, as shown in the example.
```
JavaScript
const { CucumberJSAllureFormatter, AllureRuntime } = require("allure-cucumberjs");
const path = require("path");

class Reporter extends CucumberJSAllureFormatter {
  constructor(options) {
    super(
      options,
      new AllureRuntime({
        resultsDir: path.resolve(__dirname, "allure-results"),
      }),
      {},
    );
  }
}

module.exports = Reporter;
```

In the Cucumber.js configuration file (e.g., cucumber.js), specify path to the reporter.js file in the format setting. For example:

JavaScript
const path = require("path");

module.exports = {
  default: {
    format: [path.resolve(__dirname, "reporter.js")],
  },
};

Write your tests, following the official Cucumber.js documentation and, optionally, using some extended features provided by Allure Cucumber.js, see Writing tests.

2. Run tests

Run your Cucumber.js tests the same way as you would run them usually. For example:

Bash
npx cucumber-js

Bash
yarn dlx cucumber-js

Bash
pnpx cucumber-js

This will save necessary data into allure-results or other directory, according to the options in the Formatter class (see Prepare your project). If the directory already exists, the new files will be added to the existing ones, so that a future report will be based on them all.

3. Generate a report

Finally, run Allure to convert the test results into an HTML report. This will automatically open your browser to view the report.

Bash
npx allure serve allure-results

Bash
yarn dlx allure serve allure-results

Bash
pnpx allure serve allure-results

Replace allure-results with the path to the directory specified in the options in the Formatter class (see Prepare your project).

There are some options that can affect how the report is generated, see Allure command-line options.

Writing tests

The Allure Cucumber.js adapter not only collects the data provided by Cucumber.js's standard features, but also provides additional features for writing even better tests. This section lists the most notable ways to improve your tests, using both Cucumber.js's and Allure Cucumber.js's features.

With Allure Cucumber.js, you can:

provide description, links and other metadata,
organize tests into hierarchies,
divide the test into smaller, easier-to-read test steps,
describe parameters used when running parametrized tests,
make the test save screenshots and other files during execution,
select which tests to run via a test plan file,
provide arbitrary environment information for the whole test report.

Specify description, links and other metadata

There is a lot of metadata you can add to each test so that it would appear in the report. See the reference for more details.

To assign a metadata field, call a corresponding method at any point inside a test method's body. Note, however, that it is highly recommended to assign all metadata as early as possible. Otherwise, there is a risk of the test failing before having all metadata set, which is bad for the test report's readability.

JavaScript
const { Then } = require("@cucumber/cucumber");

Then("do something", async function () {
  this.tag("NewUI");
  this.tag("Authorization");
  this.severity("critical");
  this.description(
    "This test attempts to log into the website using a login and a password. Fails if any error happens.\n\nNote that this test _does not_ test 2-Factor Authentication.",
  );
  this.owner("John Doe");
  this.parameter("App Version", "2.0");
  this.parameter("Interface Language", "English");
  this.parameter("Test User", "admin");
  this.link("https://example.com/docs", "Related Documentation");
  this.issue("https://example.com/issues/AUTH-123", "AUTH-123");
  this.tms("https://example.com/tms/TMS-456", "TMS-456");
  // ...
});

Organize tests

As described in Improving navigation in your test report, Allure supports multiple ways to organize tests into hierarchical structures.

To specify a test's location in the behavior-based hierarchy:

JavaScript
const { Then } = require("@cucumber/cucumber");

Then("do something", async function () {
  this.epic("Web interface");
  this.feature("Essential features");
  this.story("Authentication");
  // ...
});

To specify a test's location in the suite-based hierarchy:

JavaScript
const { Then } = require("@cucumber/cucumber");

Then("do something", async function () {
  this.parentSuite("Web interface");
  this.suite("Essential features");
  this.subSuite("Authentication");
  // ...
});

To specify a test's location in the package-based hierarchy:

JavaScript
const { Then } = require("@cucumber/cucumber");

Then("do something", async function () {
  this.label("package", "com.example.web.essentials.authentication");
  // ...
});

Divide a test into steps

Allure Cucumber.js allows you to create sub-steps within a Gherkin test step. To do so, use the this.step() function.

Sub-steps are convenient for situations when you have a sequence of actions which is:

monolithic enough to be presented as a single step in a Gherkin file;
complex enough to have multiple potential points of failure.

JavaScript
const { Then } = require("@cucumber/cucumber");

Then("do something", async function () {
  await this.step("Step 1", async function () {
    // ...
  });
  await this.step("Step 2", async function () {
    await this.step("Step 2.1", async function () {
      // ...
    });
    await this.step("Step 2.2", async function () {
      // ...
    });
  });
});

Describe parametrized tests

With Cucumber.js, you can implement the parametrized tests pattern using the Scenario Outline and Examples keywords.

For indicating which parameters were used in a test, there are two approaches:

Use the angle brackets syntax to insert the parameter values directly into a step title.
Use this.parameter() to display the values in the test report.

In the example below:

The Examples block defines two values for the login variable: “johndoe” and “[email protected]”.
For each value, Cucumber.js uses it instead of the placeholder in the scenario title and step titles, e.g., “authorize as "johndoe"”.
Cucumber.js then uses the title to select and run the JavaScript function. The value (e.g., “johndoe”) is passed to it as an argument of type string.
The function calls this.parameter() to display the values in the test report.

Gherkin
Scenario Outline: test authorization as "<login>"
  Then authorize as "<login>"

  Examples:
    | login               |
    | johndoe             |
    | [email protected] |

JavaScript
const { Then } = require("@cucumber/cucumber");

Then(`authorize as {string}`, async function (login) {
  this.parameter("auth_method", "password");
  this.parameter("login", login);
  // ...
});

Note that for the matching to work properly in the step titles, it is necessary to use both the angular brackets and the quotes around the parameter name.

Attach screenshots and other files

Reports generated by Allure are able to include any sorts of files, attached to the test using the this.attach() method. For example, a popular way to make a report easier to understand is to attach a screenshot of the opened web page to it. See Attachments.

JavaScript
const { Then } = require("@cucumber/cucumber");

Then("do something", async function () {
  let browser = await chromium.launch();
  let page = await browser.newPage();
  await page.goto("https://example.com/");

  let screenshot = await page.screenshot();
  this.attach(screenshot, "image/png");

  await page.close();
  await browser.close();
});

Select tests via a test plan file

Test plan is currently not supported by the Allure Cucumber.js adapter.

Environment information

For the main page of the report, you can collect various information about the environment in which the tests were executed.

For example, it is a good idea to use this to remember the OS version and Node.js version. This may help the future reader investigate bugs that are reproducible only in some environments.

Allure Report Environments Widget

To provide such information, put a file named environment.properties into the allure-results directory after running the tests. The file must use the .properties file format.


os_platform = linux
os_release = 5.15.0-60-generic
os_version = #66-Ubuntu SMP Fri Jan 20 14:29:49 UTC 2023
node_version = v18.13.0

Note that this feature should be used for properties that do not change for the whole test run. If you have properties that can be different for different tests, consider using Parametrized tests.