---
title: Cucumber.js configuration
description: Configuration for Allure Cucumber.js integration | How to add labels and links from tags | Change allure-results directory | Configure link patterns
---

# Allure Cucumber.js configuration

When setting up a project using Allure Cucumber.js (see [How to start](/docs/cucumberjs/#how-to-start)), you can pass some configuration
options to Cucumber.js in the command line or in the configuration file, e.g., `cucumber.js`.

Info:
This section describes the configuration parameters for Allure Cucumber.js 3.0 and newer. For an older version, you may check this [readme](https://github.com/allure-framework/allure-js/tree/v2.15.1/packages/allure-cucumberjs).

An example of a command-line call with additional options:

**npm:**
```bash
npx cucumber-js --format allure-cucumberjs/reporter \
  --format-options '{ "resultsDir": "results" }'
```

**yarn:**
```bash
yarn run cucumber-js --format allure-cucumberjs/reporter \
  --format-options '{ "resultsDir": "results" }'
```

**pnpm:**
```bash
pnpx cucumber-js --format allure-cucumberjs/reporter \
  --format-options '{ "resultsDir": "results" }'
```

Warning:
In Yarn PnP, the command will not work with the default settings. See [a note for Yarn PnP users](#a-note-for-yarn-pnp-users) below.

An example of a larger configuration in a `cucumber.js` file:

```js
import { Status } from "allure-js-commons";
import * as os from "node:os";
import * as process from "node:process";

export default {
  format: ["allure-cucumberjs/reporter"],
  formatOptions: {
    resultsDir: "allure-results",
    labels: [
      {
        pattern: [/@epic:(.*)/],
        name: "epic",
      },
      {
        pattern: [/@severity:(.*)/],
        name: "severity",
      },
    ],
    links: {
      issue: {
        pattern: [/@issue:(.*)/],
        urlTemplate: "https://issues.example.com/%s",
        nameTemplate: "ISSUE %s",
      },
      tms: {
        pattern: [/@tms:(.*)/],
        urlTemplate: "https://tms.example.com/%s",
      },
      jira: {
        pattern: [/@jira:(.*)/],
        urlTemplate: (v) => `https://jira.example.com/browse/${v}`,
      },
    },
    categories: [
      {
        name: "foo",
        messageRegex: "bar",
        traceRegex: "baz",
        matchedStatuses: [Status.FAILED, Status.BROKEN],
      },
    ],
    environmentInfo: {
      os_platform: os.platform(),
      os_release: os.release(),
      os_version: os.version(),
      node_version: process.version,
    },
  },
};
```

## A note for Yarn PnP users

By default, [Yarn PnP](https://yarnpkg.com/features/pnp) does not let Cucumber.js use third-party formatters (like Allure Cucumber.js). Using the command or the configuration file from the example above will lead to the “Failed to import formatter” error message.

There are two options to fix this.

- **Option 1: register Allure Cucumber.js as a peer dependency for Cucumber.js.**

  In the project's [`.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc) file, write the following section:

  ```yml
  packageExtensions:
    "@cucumber/cucumber@*":
      peerDependencies:
        allure-cucumberjs: "*"
      peerDependenciesMeta:
        allure-cucumberjs:
          optional: true
  ```

- **Option 2: re-export the Allure Cucumber.js module.**

  1. Create a file called `reporter.js` with the following line:

     ```js
     export { default } from "allure-cucumberjs/reporter";
     ```

  1. In the command line or in the configuration file, replace `allure-cucumberjs/reporter` with the path to your file. For example:

     ```bash
     yarn run cucumber-js --format ./reporter.js \
       --format-options '{ "resultsDir": "results" }'
     ```

## Supported options

### resultsDir

Path to the directory where Allure Cucumber.js will save the test results, see [How it works](/docs/how-it-works/). If the directory does not exist, it will be created. Defaults to `allure-results`.

### labels

List of rules for automatically adding labels based on [Gherkin tags](https://cucumber.io/docs/cucumber/api/?lang=javascript#tags).

To define a rule, add an object with two properties to the list:

- `pattern`: a list of regular expressions to match Gherkin tags. Each regular expression must include exactly one capture group.
- `name`: the name of the [labels](/docs/cucumberjs-reference/#label) that must be created when tags match the pattern. This label will be assigned the value captured by a regular expression.

For example, with the configuration above, the `@severity:minor` tag will produce a [Severity](/docs/cucumberjs-reference/#severity) label with the value “minor”.

### links

A mapping of templates that can be used to construct full URLs from short identifiers.

For each type of link (see [`allure.link()`](/docs/cucumberjs-reference/#link)), you can specify the following:

- `nameTemplate` — a template or a function for generating the link name when it is not provided.
- `urlTemplate` — a template or a function for generating the link address when it is not provided.

The templates can be strings (with `%s` where the identifier should be placed) or functions (accepting the identifier and returning the URL).

For example, with the configuration above, `await allure.issue("123")` will produce a link with the name `Issue #123` and the address `https://issues.example.com/`. Allure will display the link with the appropriate icon for the `issue` type.

### categories

Define custom categories that will be used to distinguish test results by their errors; see [Categories](/docs/categories/).

This setting is an array, each item being an object representing one custom category. The objects may have the following properties:

- `name` — a category name.
- `messageRegex` — a regular expression that the test result's message should match.
- `traceRegex` — a regular expression that the test result's trace should match.
- `matchedStatuses` — an array of statuses that the test result should be one of.
- `flaky` — whether the test result should be marked as [flaky](/docs/test-stability/#flaky-tests).

### environmentInfo

Key-value pairs that will be displayed on the report's main page, see [Environment information](/docs/v2/readability/#environment-information).