Principle:Webdriverio Webdriverio Cucumber Execution

Metadata

Field	Value
Page ID	Cucumber_Execution
Page Type	Principle
Repository	webdriverio/webdriverio
Knowledge Sources	Repo (webdriverio/webdriverio)
Domains	Testing, BDD, Execution
Related Pages	implemented_by Implementation:Webdriverio_Webdriverio_CucumberAdapter_Class

Overview

A mechanism for executing Cucumber BDD test scenarios within the WDIO testrunner lifecycle.

Description

Cucumber Execution bridges the WDIO testrunner with the Cucumber runtime. It adapts Cucumber's execution model to work within WDIO's worker process architecture, translating Cucumber events to WDIO reporter events, managing the Cucumber runtime lifecycle, and supporting WDIO-specific features like tag-based capability filtering and custom formatters.

The execution pipeline proceeds through several phases:

Phase 1: Initialization

The adapter is constructed with the worker's context (CID, config, spec files, capabilities, reporter). During construction it:

• Merges user cucumberOpts with DEFAULT_OPTS
• Initializes the Gherkin parser (Gherkin.Parser, Gherkin.AstBuilder, Gherkin.GherkinClassicTokenMatcher)
• Normalizes spec file paths (strips file:// protocol)
• Appends the internal CucumberFormatter to the format list
• Injects WDIO reporter and event emitter references into format options

The init() method then:

• Generates dynamic skip tags from capabilities (for capability-based scenario filtering)
• Uses loadSources() from @cucumber/cucumber/api to filter specs against tag expressions
• Deduplicates the final spec list

Phase 2: Runtime Setup

The run() method orchestrates the actual execution:

• Registers required modules (cucumberOpts.requireModule) for transpilation support
• Resets the Cucumber supportCodeLibraryBuilder with the appropriate paths
• Adds WDIO lifecycle hooks (beforeFeature, beforeScenario, beforeStep, afterStep, afterScenario, afterFeature) to the Cucumber support code
• Loads step definition files from require and import paths
• Wraps step definitions with WDIO's before/after hook integration
• Sets the default step timeout
• Finalizes the support code library

Phase 3: Execution

The adapter calls runCucumber() from @cucumber/cucumber/api with the prepared configuration and support code library. During execution:

• The CucumberFormatter listens to Cucumber envelope events and translates them to WDIO reporter events (suite:start, test:start, test:pass, test:fail, suite:end, etc.)
• Step results (pass, fail, undefined, ambiguous, pending, skipped) are translated to WDIO states
• Feature, scenario, and step metadata (titles, tags, URIs, durations) are propagated to reporters

Phase 4: Result Collection

After execution completes:

• The CucumberFormatter emits the failed count via the event emitter
• If ignoreUndefinedDefinitions is enabled, the adapter uses the formatter's failed count instead of Cucumber's overall success/failure
• The WDIO after hook is executed with the result, capabilities, and specs
• The method returns an exit code: 0 for success, 1 for failure

Usage

Use Cucumber Execution when running BDD tests with npx wdio run wdio.conf.ts and framework: 'cucumber'. The adapter is automatically loaded and manages the Cucumber lifecycle within each worker process. No direct API usage is required -- the WDIO testrunner handles adapter instantiation.

// wdio.conf.ts - the adapter is loaded automatically
export const config: WebdriverIO.Config = {
    framework: 'cucumber',
    specs: ['./features/**/*.feature'],
    cucumberOpts: {
        require: ['./step-definitions/**/*.ts'],
        tags: '@smoke',
        timeout: 60000,
    }
}

Run the tests:

// Command line
// npx wdio run wdio.conf.ts

Theoretical Basis

The execution model is based on the Adapter pattern: CucumberAdapter adapts Cucumber's internal API to WDIO's framework adapter interface. It implements init() for setup and run() for execution, translating between two different lifecycle models.

Key Design Patterns

• Adapter Pattern: The CucumberAdapter class bridges the WDIO framework adapter contract (init() + run() returning exit code) with Cucumber's API (loadConfiguration(), loadSources(), runCucumber()).
• Observer Pattern: The CucumberFormatter subscribes to Cucumber's envelope event stream and emits WDIO reporter events. It maintains internal state maps (gherkin documents, scenarios, test cases) to correlate events.
• Factory Pattern: The exported adapterFactory.init() function creates and initializes CucumberAdapter instances. The WDIO testrunner uses this factory to create adapters in worker processes.
• Mediator Pattern: An EventEmitter instance mediates communication between the adapter and the formatter, passing hook parameters, failed counts, and other runtime data.

Event Translation

The CucumberFormatter translates Cucumber events to WDIO events:

Cucumber Event	WDIO Event
testRunStarted	suite:start (feature level)
testCaseStarted	suite:start or test:start (scenario level, depending on scenarioLevelReporter)
testStepStarted	test:start or hook:start
testStepFinished	test:pass / test:fail / test:pending / hook:end
testCaseFinished	suite:end (scenario level)
testRunFinished	suite:end (feature level)

Error Handling

• Runtime errors during execution are caught, stored, and re-thrown after the WDIO after hook completes.
• Undefined steps are handled based on the ignoreUndefinedDefinitions flag: either marked as pending (warning) or failed (error).
• Ambiguous step matches are handled based on the failAmbiguousDefinitions flag.
• Retried test cases (via the retry option) emit suite:retry events instead of suite:start.

Related Pages

Implementation:Webdriverio_Webdriverio_CucumberAdapter_Class

• implemented_by: Implementation:Webdriverio_Webdriverio_CucumberAdapter_Class