Principle:Webdriverio Webdriverio Cucumber Configuration

Metadata

Field	Value
Page ID	Cucumber_Configuration
Page Type	Principle
Repository	webdriverio/webdriverio
Knowledge Sources	Repo (webdriverio/webdriverio), Doc (WDIO Cucumber Docs), Doc (Cucumber API Docs)
Domains	Testing, BDD, Configuration
Related Pages	implemented_by Implementation:Webdriverio_Webdriverio_CucumberOptions_Interface

Overview

A mechanism for configuring the Cucumber BDD test framework within the WDIO testrunner environment.

Description

Cucumber Configuration defines how Gherkin feature files and step definitions are resolved, executed, and filtered within a WDIO test run. It bridges the WDIO configuration system with Cucumber's native options, allowing control over timeouts, tag expressions, formatters, language settings, and step definition file resolution. This configuration is specific to projects using framework: 'cucumber' in their wdio.conf.ts.

The configuration is provided as the cucumberOpts property within the standard WDIO configuration object. At runtime, the CucumberAdapter merges user-supplied values with a set of default options defined in DEFAULT_OPTS, ensuring that unconfigured properties receive sensible fallback values. This merge uses Object.assign, meaning user values override defaults at the top level.

The configuration controls several critical aspects of the test run:

• Step Definition Resolution: The require array specifies glob patterns or file paths that point to step definition files. The adapter resolves these patterns, loads the modules, and registers the step definitions with the Cucumber runtime.
• Tag Filtering: The tags property accepts a Cucumber tag expression (e.g., @smoke and not @wip) that filters which scenarios are executed. The adapter also supports dynamic skip-tag generation based on capabilities.
• Timeout Management: The timeout property (default: 60000ms) sets the maximum time a step definition may run before being considered failed.
• Formatter Configuration: The format array allows specifying Cucumber formatters for additional output. The adapter always appends its own internal CucumberFormatter to this list.
• Language Support: The language property (default: 'en') determines which spoken language the Gherkin parser uses for keywords.

Usage

Use Cucumber Configuration when setting up BDD-style testing with Cucumber and WDIO. Configure it via the cucumberOpts object in wdio.conf.ts. Essential settings include require (step definition paths), tags (tag expression filters), and timeout (step timeout in milliseconds).

// wdio.conf.ts
export const config: WebdriverIO.Config = {
    framework: 'cucumber',
    specs: ['./features/**/*.feature'],
    cucumberOpts: {
        require: ['./step-definitions/**/*.ts'],
        tags: '@smoke and not @wip',
        timeout: 60000,
        language: 'en',
        retry: 1,
        scenarioLevelReporter: false,
        tagsInTitle: false,
        ignoreUndefinedDefinitions: false,
    }
}

Common Configuration Scenarios

• Running a subset of scenarios: Set tags: '@smoke' to execute only scenarios tagged with @smoke.
• Increasing step timeout: Set timeout: 120000 for long-running steps (e.g., file uploads, complex UI workflows).
• Adding Cucumber formatters: Set format: 'json', './reports/cucumber.json' to produce a JSON report.
• Retrying failed scenarios: Set retry: 2 to retry failing scenarios up to 2 times.
• Internationalized features: Set language: 'fr' for French Gherkin keywords.

Theoretical Basis

Cucumber Configuration follows the convention-over-configuration principle. Step definitions are located by glob patterns. Tag expressions use boolean logic (@tag1 and not @tag2) to filter scenarios. The timeout ensures tests do not hang indefinitely. The configuration merges user settings with sensible defaults (60-second timeout, English language, zero retries).

The design applies several key principles:

• Separation of Concerns: Configuration is isolated in cucumberOpts rather than scattered across the WDIO config, making it clear which settings pertain to the Cucumber framework.
• Defaults with Override: The DEFAULT_OPTS constant in constants.ts provides safe defaults for every property. User-supplied values override these via Object.assign({}, DEFAULT_OPTS, userOpts).
• Tag Expression Algebra: Tag filtering uses Cucumber's boolean tag expression language, which supports and, or, not, and parenthetical grouping. The adapter can also dynamically generate skip tags from capability metadata.
• Backward Compatibility: The deprecated tagExpression property is still accepted and merged into tags with a deprecation warning logged at runtime.

Related Pages

Implementation:Webdriverio_Webdriverio_CucumberOptions_Interface

• implemented_by: Implementation:Webdriverio_Webdriverio_CucumberOptions_Interface