CucumberJS

The official Flakiness.io reporter for CucumberJS. The open source implementation is available at github.com/flakiness/cucumberjs.

A custom CucumberJS formatter that generates Flakiness Reports from your Cucumber test runs. The formatter automatically converts CucumberJS test results into the standardized Flakiness JSON format, preserving complete Gherkin structure, test outcomes, and environment information.

Quick Start

1. Install the Flakiness.io CucumberJS formatter:

   npm install -D @flakiness/cucumberjs

2. Add the formatter to your cucumber.mjs configuration file:

   cucumber.mjs

   export default {
     format: [
       'progress',
       ['@flakiness/cucumberjs', '.flakiness/cucumber-formatter.log'],
     ],
     formatOptions: {
       flakinessProject: 'my-org/my-project',
     },
   };

3. Run your tests. The report will be automatically generated in the ./flakiness-report folder:

   npx cucumber-js

4. View the interactive report:

   npx flakiness show ./flakiness-report

Tip

Make sure to add flakiness-report folder to your .gitignore. You can also use the Flakiness CLI to view reports locally.

Supported Gherkin Features

• Scenarios & Scenario Outlines (with multiple Examples blocks)
• Rules
• Tags & tag inheritance (Feature → Rule → Scenario → Examples)
• Steps (Given/When/Then with keyword prefix)
• Data Tables
• Before & After Hooks (named and unnamed)
• Feature, Rule, and Scenario descriptions
• Attachments (this.attach() and this.log())
• Retries (--retry)
• Parallel execution (--parallel)
• All statuses: passed, failed, pending, undefined, ambiguous, skipped

CI/CD Integration

Reports are automatically uploaded to Flakiness.io at the end of each test run when authentication is configured. If no credentials are present, the report is still generated locally and can be uploaded manually later.

When uploading succeeds, you’ll see a confirmation in your terminal:

[flakiness.io] ✓ Uploaded as https://flakiness.io/my-org/my-project/run/42

Upload Method	Status	Guide
GitHub OIDC	Supported	GitHub Actions
Access Token	Supported	GitHub Actions
Other CI	Supported	Other CI Providers

Tip

GitHub OIDC is the recommended method — no secrets to manage. It requires the flakinessProject config option. See the GitHub Actions guide for setup instructions.

Configuration

All options are passed via CucumberJS’s formatOptions in your configuration file.

flakinessProject?: string

The Flakiness.io project identifier in org/project format. Required for GitHub OIDC authentication. Defaults to the FLAKINESS_PROJECT environment variable.

formatOptions: {
  flakinessProject: 'my-org/my-project',
}

endpoint?: string

Custom Flakiness.io endpoint URL for uploading reports. Defaults to the FLAKINESS_ENDPOINT environment variable, or https://flakiness.io if not set.

Use this option to point to a custom or self-hosted Flakiness.io instance.

formatOptions: {
  endpoint: 'https://custom.flakiness.io',
}

token?: string

Access token for authenticating with Flakiness.io when uploading reports. Defaults to the FLAKINESS_ACCESS_TOKEN environment variable.

If no token is provided, the formatter will attempt GitHub OIDC when flakinessProject is set. If neither is available, the report is generated locally without uploading.

formatOptions: {
  token: 'your-access-token',
}

outputFolder?: string

Directory path where the Flakiness report will be written. Defaults to flakiness-report in the current working directory, or the FLAKINESS_OUTPUT_DIR environment variable if set.

formatOptions: {
  outputFolder: './test-results/flakiness',
}

disableUpload?: boolean

When set to true, prevents uploading the report to Flakiness.io. The report is still generated locally. Can also be controlled via the FLAKINESS_DISABLE_UPLOAD environment variable.

formatOptions: {
  disableUpload: true,
}

Environment Variables

The formatter respects the following environment variables:

• FLAKINESS_ACCESS_TOKEN: Access token for Flakiness.io uploads (equivalent to token option)
• FLAKINESS_PROJECT: Flakiness.io project in orgSlug/projectSlug format (equivalent to flakinessProject option)
• FLAKINESS_ENDPOINT: Custom Flakiness.io endpoint URL (equivalent to endpoint option)
• FLAKINESS_OUTPUT_DIR: Output directory for reports (equivalent to outputFolder option)
• FLAKINESS_DISABLE_UPLOAD: Disable automatic upload (equivalent to disableUpload option)
• FK_ENV_*: Custom environment variables prefixed with FK_ENV_ are automatically included in the environment’s metadata. The prefix is stripped and the key is converted to lowercase.

Example:

export FK_ENV_DEPLOYMENT=staging
export FK_ENV_REGION=us-east-1

This will result in the environment containing:

{
  "metadata": {
    "deployment": "staging",
    "region": "us-east-1"
  }
}

Flakiness.io platform will create a dedicated history for tests executed in each unique environment. This means tests run with FK_ENV_DEPLOYMENT=staging will have a separate timeline from tests run with FK_ENV_DEPLOYMENT=production, allowing you to track flakiness patterns specific to each deployment environment.

Example Configuration

Here’s a complete example with all options:

export default {
  format: [
    'progress',
    ['@flakiness/cucumberjs', '.flakiness/cucumber-formatter.log'],
  ],
  formatOptions: {
    flakinessProject: 'my-org/my-project',
    endpoint: process.env.FLAKINESS_ENDPOINT,
    token: process.env.FLAKINESS_ACCESS_TOKEN,
    outputFolder: './flakiness-report',
    disableUpload: false,
  },
};

Requirements

• @cucumber/cucumber 12.0 or higher
• Node.js project with a git repository (for commit information)

License & Source Code

The source code is available under MIT license at https://github.com/flakiness/cucumberjs