You are reading the documentation in the main development branch, which might contain some unreleased features. See documentation for older versions if you need it.

---

Configuration

Files

You can keep your configuration in a file. Cucumber will look for one of these files in the root of your project, and use the first one it finds:

• cucumber.json
• cucumber.yaml
• cucumber.yml
• cucumber.js
• cucumber.cjs
• cucumber.mjs

You can also put your file somewhere else and tell Cucumber via the --config CLI option:

cucumber-js --config config/cucumber.json

Here's a concise example of a configuration file in JSON format:

{
  "default": {
    "parallel": 2,
    "format": ["html:cucumber-report.html"]
  }
}

And the same in YAML format:

default:
  parallel: 2
  format:
    - "html:cucumber-report.html"

And the same in JavaScript (ESM) format:

export default {
  parallel: 2,
  format: ['html:cucumber-report.html']
}

And the same in JavaScript (CommonJS) format:

module.exports = {
  default: {
    parallel: 2,
    format: ['html:cucumber-report.html']
  }
}

Cucumber also supports the configuration being a string of options in the style of the CLI, though this isn't recommended:

module.exports = {
  default: '--parallel 2 --format html:cucumber-report.html'
}

(If you're wondering why the configuration sits within a "default" property, that's to allow for Profiles.)

TypeScript

You can also write your configuration file in TypeScript, with a .ts, .mts or .cts extension. These files are loaded with Node.js built-in TypeScript support, which has several caveats and limitations, mostly that your tsconfig.json won't be honoured and that you need to be explicit about type imports. Here's an example:

import type { IConfiguration } from '@cucumber/cucumber'

export default {
  parallel: 2,
  format: ['html:cucumber-report.html']
} satisfies Partial<IConfiguration>

Options

These options can be used in a configuration file (see above) or on the CLI, or both.

• Where options are repeatable, they are appended/merged if provided more than once.
• Where options aren't repeatable, the CLI takes precedence over a configuration file.

Name	Type	Repeatable	CLI Option	Description	Default
paths	string[]	Yes	(as arguments)	Paths to where your feature files are - see below	[]
backtrace	boolean	No	--backtrace, -b	Show the full backtrace for errors	false
dryRun	boolean	No	--dry-run, -d	Prepare a test run but don't run it - see Dry Run	false
forceExit	boolean	No	--exit, --force-exit	Explicitly call process.exit() after the test run (when run via CLI) - see CLI	false
failFast	boolean	No	--fail-fast	Stop running tests when a test fails - see Fail Fast	false
format	string[]	Yes	--format, -f	Name/path and (optionally) output file path of each formatter to use - see Formatters	[]
formatOptions	object	Yes	--format-options	Options to be provided to formatters - see Formatters	{}
import	string[]	Yes	--import, -i	Paths to where your support code is	[]
language	string	No	--language	Default language for your feature files	en
loader	string[]	Yes	--loader, -l	Module specifiers for loaders to be registered ahead of loading support code - see Transpiling	[]
name	string	No	--name	Regular expressions of which scenario names should match one of to be run - see Filtering	[]
order	string	No	--order	Run in the order defined, or in a random order - see Filtering and Ordering	defined
parallel	number	No	--parallel	Run tests in parallel with the given number of worker processes - see Parallel	0
plugin	string[]	Yes	--plugin	Paths or package names of plugins to load - see Plugins	[]
pluginOptions	object	Yes	--plugin-options	Options to be provided to plugins - see Plugins	{}
publish	boolean	No	--publish	Publish a report of your test run to https://reports.cucumber.io/	false
require	string[]	Yes	--require, -r	Paths to where your support code is, for CommonJS - see below	[]
requireModule	string[]	Yes	--require-module	Names of transpilation modules to load, loaded via require() - see Transpiling	[]
retry	number	No	--retry	Retry failing tests up to the given number of times - see Retry	0
retryTagFilter	string	Yes	--retry-tag-filter	Tag expression to filter which scenarios can be retried - see Retry
shard	string	No	--shard	Run a subset of scenarios across multiple test runs - see Sharding
strict	boolean	No	--strict, --no-strict	Fail the test run if there are pending steps	true
tags	string	Yes	--tags, -t	Tag expression to filter which scenarios should be run - see Filtering
worldParameters	object	Yes	--world-parameters	Parameters to be passed to your World - see World	{}

Finding your features

By default, Cucumber finds features that match this glob (relative to your project's root directory):

features/**/*.{feature,feature.md}

If your features are somewhere else, you can override this by proving your own glob or directory:

• In a configuration file { paths: ['somewhere-else/**/*.feature'] }
• On the CLI cucumber-js 'somewhere-else/**/*.feature' (note that the argument is quoted - this is to avoid your shell expanding the glob itself which might lead to different behaviour than what's documented here)

This option is repeatable, so you can provide several values and they'll be combined, whilst maintaining the order you provided them in.

For more granular options to control which scenarios from your features should be run, see Filtering.

Finding your code

By default, Cucumber finds support code files with this logic:

• If the features live in a features directory (at any level)
  • features/**/*.@(js|cjs|mjs)
• Otherwise
  • <DIR>/**/*.@(js|cjs|mjs) for each directory containing the selected features

If your files are somewhere else, you can override this by proving your own glob, directory or file path to the import configuration option:

• In a configuration file { import: ['somewhere-else/support/*.js'] }
• On the CLI cucumber-js --import somewhere-else/support/*.js

Once you specify any import options, the defaults described above are no longer applied. The option is repeatable, so you can provide several values and they'll be combined, meaning you can load files from multiple locations.

The default behaviour and the import option both use the new ES modules API to load your files. This should work fine for the majority of cases, but sometimes (e.g. when transpiling with the require-module option), you'll need to use the require option instead in the same way, and they'll be loaded with the legacy CommonJS modules API.