Implementation:Webdriverio Webdriverio CucumberOptions Interface

Metadata

Field	Value
Page ID	CucumberOptions_Interface
Page Type	Implementation
Implementation Type	API Doc
Repository	webdriverio/webdriverio
Package	@wdio/cucumber-framework
Source	packages/wdio-cucumber-framework/src/types.ts (L6-152), packages/wdio-cucumber-framework/src/constants.ts (L5-32)
Related Pages	implements Principle:Webdriverio_Webdriverio_Cucumber_Configuration

Overview

Concrete configuration interface for Cucumber framework options provided by the @wdio/cucumber-framework package.

Description

The CucumberOptions interface defines all configuration properties for the Cucumber framework adapter. It is specified as the cucumberOpts property in wdio.conf.ts when framework: 'cucumber' is set. The adapter merges user-provided options with DEFAULT_OPTS constants using Object.assign({}, DEFAULT_OPTS, userCucumberOpts).

The interface is declared in packages/wdio-cucumber-framework/src/types.ts and the default values are defined in packages/wdio-cucumber-framework/src/constants.ts. The global WebdriverIO.CucumberOpts interface extends CucumberOptions, making these types available throughout the WDIO type system.

Source

Interface definition: packages/wdio-cucumber-framework/src/types.ts lines 6-152

Default values: packages/wdio-cucumber-framework/src/constants.ts lines 5-32

Key Properties

Property	Type	Default	Description
paths	string[]	[]	Paths to where feature files are located
require	string[]	[]	Step definition file patterns (glob or path)
import	string[]	[]	Paths to support code for ESM
tags	string		Tag expression filter (e.g., '@smoke and not @wip')
timeout	number	60000	Step timeout in milliseconds
retry	number	0	Number of times to retry failing test cases
retryTagFilter	string	(undefined)	Only retry scenarios matching this tag expression
language	string	'en'	Gherkin spoken language for keywords
format	[string, string?]>	[]	Output formatters
formatOptions	object	{}	Options to be provided to formatters
name	string[]	[]	Only execute scenarios with name matching the expression
order	'random' | `random:${string}`	'defined'	Feature execution order
backtrace	boolean	false	Show full backtrace for errors
dryRun	boolean	false	Prepare a test run but don't run it
failFast	boolean	false	Abort the run on first failure
strict	boolean	false	Fail if there are any undefined or pending steps
scenarioLevelReporter	boolean	false	Report at scenario level instead of step level
tagsInTitle	boolean	false	Add cucumber tags to feature or scenario name
ignoreUndefinedDefinitions	boolean	false	Treat undefined definitions as warnings
failAmbiguousDefinitions	boolean	false	Treat ambiguous definitions as errors
requireModule	string[]	[]	Require modules prior to requiring support files
publish	boolean	false	Publish a report to reports.cucumber.io
profiles	string[]	[]	Profiles from which to include configuration
tagExpression	string		(deprecated) Use tags instead
file	false | undefined	undefined	Path to load configuration file from, or false to skip

Import

The types are available from the @wdio/cucumber-framework package. Configuration is done in wdio.conf.ts:

import type { CucumberOptions } from '@wdio/cucumber-framework'

Default Values (constants.ts)

export const DEFAULT_TIMEOUT = 60000

export const DEFAULT_OPTS: CucumberOptions = {
    paths: [],
    backtrace: false,
    dryRun: false,
    forceExit: false,
    failFast: false,
    format: [],
    formatOptions: {},
    import: [],
    language: 'en',
    name: [],
    order: 'defined',
    publish: false,
    require: [],
    requireModule: [],
    retry: 0,
    strict: false,
    tags: '',
    worldParameters: {},
    timeout: DEFAULT_TIMEOUT,
    scenarioLevelReporter: false,
    tagsInTitle: false,
    ignoreUndefinedDefinitions: false,
    failAmbiguousDefinitions: false,
    tagExpression: '',
    profiles: [],
    file: undefined
}

Usage Example

// wdio.conf.ts
import url from 'node:url'
import path from 'node:path'

const __dirname = url.fileURLToPath(new URL('.', import.meta.url))

export const config: WebdriverIO.Config = {
    specs: [
        [path.resolve(__dirname, 'features', 'my-feature.feature')]
    ],
    capabilities: [{
        browserName: 'chrome'
    }],
    logLevel: 'error',
    framework: 'cucumber',
    reporters: ['spec'],
    cucumberOpts: {
        require: [path.resolve(__dirname, 'step-definitions.ts')],
        tags: '@smoke and not @wip',
        timeout: 60000,
        retry: 1,
        language: 'en',
        scenarioLevelReporter: false,
        tagsInTitle: true,
        ignoreUndefinedDefinitions: false,
        format: [['json', './reports/cucumber-report.json']],
    }
}

Internal Merge Behavior

At adapter construction time, user options are merged with defaults:

// packages/wdio-cucumber-framework/src/index.ts (constructor)
this._cucumberOpts = Object.assign(
    {},
    DEFAULT_OPTS,
    this._config.cucumberOpts as Required<CucumberOptions>
)

The adapter also always appends its internal CucumberFormatter to the format array and injects internal formatter options (reporter, cid, specs, event emitter, and WDIO-specific flags) into formatOptions.

Related Pages

• implements: Principle:Webdriverio_Webdriverio_Cucumber_Configuration