plum117 · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026 · Oct 21, 2026
@@ -15,7 +15,7 @@ Instructions on how to install `WebdriverIO` can be found [here.](https://webdri
 
 ## Configuration
 
-Following code shows the default wdio test runner configuration...
+The following code shows a minimal test runner configuration:
 
 ```js
 // wdio.conf.js
@@ -90,16 +90,15 @@ Example: `[path.join(__dirname, 'step-definitions', 'my-steps.js')]`
 
 <Option type="Boolean" default="false">
 
-Fail if there are any undefined or pending steps
+Fail the run on a pending step. An undefined step fails the run also without `strict`, unless [`ignoreUndefinedDefinitions`](#ignoreundefineddefinitions) is `true`.
 
 </Option>
 
 ### tags
 
 <Option type="String" default="">
 
-Only execute the features or scenarios with tags matching the expression. Note that untagged
-features will still spawn a Selenium session (see issue [webdriverio/webdriverio#1247](https://github.com/webdriverio/webdriverio/issues/1247)).
+Only execute the features or scenarios with tags matching the expression. A feature file with no matching scenario is reported as skipped and starts no browser session.
 Please see the [Cucumber documentation](https://docs.cucumber.io/cucumber/api/#tag-expressions) for more details.
 If passing as a command-line argument, compound expressions may need to be enclosed in three sets of double quotes if WebdriverIO is invoked using `npx` on Windows.
 
@@ -109,7 +108,7 @@ E.g.: `npx wdio wdio.config.js --cucumberOpts.tags """@Smoke and not @Pending"""
 
 ### timeout
 
-<Option type="Number" default="30000">
+<Option type="Number" default="60000">
 
 Timeout in milliseconds for step definitions.
 
@@ -125,9 +124,9 @@ Specify the number of times to retry failing test cases.
 
 ### retryTagFilter
 
-<Option type="RegExp">
+<Option type="String">
 
-Only retries the features or scenarios with tags matching the expression (repeatable). This option requires '--retry' to be specified.
+Only retry the scenarios with tags matching the tag expression. Requires [`retry`](#retry).
 
 </Option>
 
@@ -143,7 +142,7 @@ Default language for your feature files
 
 <Option type="String" default="defined">
 
-Run tests in defined / random order
+Run the scenarios in the order of the feature files (`'defined'`) or in a random order (`'random'`). With `'random:<seed>'`, for example `'random:42'`, a random order is the same in each run. With `'random'`, the log shows the seed of the run (`Random order using seed: 42`).
 
 </Option>
 
@@ -152,7 +151,7 @@ Run tests in defined / random order
 <Option type="string[]">
 
 Name and output file path of formatter to use.
-WebdriverIO primarily supports only the [Formatters](https://github.com/cucumber/cucumber-js/blob/main/docs/formatters.md) that writes output to a file.
+WebdriverIO primarily supports only the [Formatters](https://github.com/cucumber/cucumber-js/blob/main/docs/formatters.md) that writes output to a file. Formatters don't run with [`parallelMode`](#parallelmode).
 
 </Option>
 
@@ -177,7 +176,7 @@ Add cucumber tags to feature or scenario name
 
 <Option type="Boolean" default="false">
 
-Treat undefined definitions as warnings.
+Report an undefined step as pending, with ` (undefined step)` at the end of its title, and do not fail the run for it.
 
 </Option>
 ***Please note that this is a @wdio/cucumber-framework specific option and not recognized by cucumber-js itself***<br/>
@@ -191,15 +190,66 @@ Report an ambiguous step (a step that matches more than one step definition) as
 </Option>
 ***Please note that this is a @wdio/cucumber-framework specific option and not recognized by cucumber-js itself***<br/>
 
-### profile
+### profiles
 
 <Option type="string[]" default="[]">
 
-Specify the profile to use.
+The profiles of the Cucumber configuration file to use.
 
 </Option>
 ***Kindly take note that only specific values (worldParameters, name, retryTagFilter) are supported within profiles, as `cucumberOpts` takes precedence. Additionally, when using a profile, make sure that the mentioned values are not declared within `cucumberOpts`.***
 
+### file
+
+<Option type="string | false" default="undefined">
+
+Path of the Cucumber configuration file to load, or `false` to load none. Without it, Cucumber looks for its default configuration files.
+
+</Option>
+
+### dryRun
+
+<Option type="Boolean" default="false">
+
+Run no step and no hook: Cucumber only matches each step with its step definitions, so undefined and ambiguous steps are still reported. The run does not fail.
+
+</Option>
+
+### worldParameters
+
+<Option type="object" default="{}">
+
+Parameters for your World, as `this.parameters`.
+
+</Option>
+
+### scenarioLevelReporter
+
+<Option type="Boolean" default="false">
+
+Report each scenario as one test. Its steps and hooks are not reported.
+
+</Option>
+***Please note that this is a @wdio/cucumber-framework specific option and not recognized by cucumber-js itself***<br/>
+
+### parallelMode
+
+<Option type="'contexts' | 'userContexts'" default="undefined">
+
+Run the scenarios of a feature file at the same time, each in its own WebDriver BiDi browsing context. `'contexts'` shares cookies and storage between scenarios, `'userContexts'` isolates them. Requires the `'wdio:experimentalBiDiCommands': true` capability. See [Parallel Tests in a Spec File](https://webdriver.io/docs/parallel-tests).
+
+</Option>
+***Please note that this is a @wdio/cucumber-framework specific option and not recognized by cucumber-js itself***<br/>
+
+### maxParallelContexts
+
+<Option type="number" default="os.cpus().length">
+
+Number of scenarios that run at the same time when [`parallelMode`](#parallelmode) is set.
+
+</Option>
+***Please note that this is a @wdio/cucumber-framework specific option and not recognized by cucumber-js itself***<br/>
+
 ## Publishing Report
 
 Cucumber provides a feature to publish your test run reports to `https://reports.cucumber.io/`, which can be controlled either by setting the `publish` flag in `cucumberOpts` or by configuring the `CUCUMBER_PUBLISH_TOKEN` environment variable. However, when you use `WebdriverIO` for test execution, there's a limitation with this approach. It updates the reports separately for each feature file, making it difficult to view a consolidated report.
@@ -233,7 +283,7 @@ export const config = {
 }
 ```
 
-Please note that `./reports/` is the directory where `cucumber message` reports will be stored.
+Please note that `./reports/` is the directory where `cucumber message` reports will be stored. With `parallelMode`, Cucumber writes no message report, so there is nothing to publish.
 
 ----
 

@@ -6,7 +6,7 @@ import path from 'node:path'
 import logger from '@wdio/logger'
 
 import type { Payload } from './types.js'
-import { convertStatus, getAmbiguousStepMessage } from './utils.js'
+import { getFeatureStack, getStepResult, withAmbiguousMessage } from './utils.js'
 
 const log = logger('CucumberFormatter')
 
@@ -24,7 +24,6 @@ import type {
     TestStepStarted,
     TestStepFinished,
     TestStepResult,
-    TestCaseFinished,
     Hook,
     StepDefinition
 } from '@cucumber/messages'
@@ -223,53 +222,21 @@ export default class CucumberFormatter extends Formatter {
         step: PickleStep | undefined,
         result: TestStepResult
     ) {
-        let state = convertStatus(result.status)
-        let error = result.message ? new Error(result.message) : undefined
         const title = step ? step?.text : this.getTitle(scenario)
-        let titleSuffix = ''
-
-        if (result.status === Status.UNDEFINED) {
-            if (this.ignoreUndefinedDefinitions) {
-                /**
-                 * mark test as pending
-                 */
-                state = 'pending'
-                titleSuffix = ' (undefined step)'
-            } else {
-                /**
-                 * mark test as failed
-                 */
-                state = 'fail'
-                this.failedCount++
-
-                const err = new Error(
-                    (step ? `Step "${title}" is not defined. ` : `Scenario ${title} has undefined steps. `) +
-                    'You can ignore this error by setting cucumberOpts.ignoreUndefinedDefinitions as true.'
-                )
-
-                err.stack = `${err.message}\n${this.getFeatureStack(uri, feature, scenario, step)}`
-                error = err
+        const { state, error, pendingReason, titleSuffix, failed } = getStepResult(
+            result,
+            {
+                title,
+                isStep: Boolean(step),
+                ignoreUndefinedDefinitions: this.ignoreUndefinedDefinitions,
+                failAmbiguousDefinitions: this.failAmbiguousDefinitions,
+                featureStack: () => getFeatureStack(uri, feature, scenario, step),
             }
-        } else if (result.status === Status.FAILED && !(result as unknown as TestCaseFinished).willBeRetried) {
-            state = 'fail'
-            this.failedCount++
-            error = new Error(result.message?.split('\n')[0])
-            error.stack = result.message as string
-        } else if (result.status === Status.AMBIGUOUS && this.failAmbiguousDefinitions) {
-            state = 'fail'
+        )
+        if (failed) {
             this.failedCount++
-            const message = result.message || (
-                (step
-                    ? `Step "${title}" matches multiple step definitions. `
-                    : `Scenario "${title}" contains a step matching multiple step definitions. `) +
-                'Make the step definitions unique by removing duplicate or overlapping expressions.'
-            )
-            error = new Error(message.split('\n')[0])
-            error.stack = `${message}\n${this.getFeatureStack(uri, feature, scenario, step)}`
         }
 
-        // reporters show the reason of a skipped test from `pendingReason`, not from its error
-        const pendingReason = result.status === Status.AMBIGUOUS && state === 'skip' ? result.message : undefined
         const common = {
             title: title,
             state,
@@ -305,25 +272,6 @@ export default class CucumberFormatter extends Formatter {
         this.emit('test:' + state, payload)
     }
 
-    /**
-     * stack lines with the location of the scenario and the step in the feature file
-     */
-    private getFeatureStack(uri: string, feature: Feature, scenario: Pickle, step?: PickleStep) {
-        let stack = `\tat Feature(${uri}):1:1\n`
-        const children = feature.children?.flatMap((child) => child.rule ? child.rule.children : [child]) ?? []
-        const featScenario = children.find(c => scenario.astNodeIds && c.scenario?.id === scenario.astNodeIds[0])?.scenario
-        if (featScenario) {
-            stack += `\tat Scenario(${featScenario.name}):${featScenario.location?.line}:${featScenario.location?.column}\n`
-
-            const steps = [...children.flatMap((c) => c.background?.steps ?? []), ...(featScenario.steps ?? [])]
-            const featStep = steps.find(s => step?.astNodeIds && s.id === step.astNodeIds[0])
-            if (featStep) {
-                stack += `\tat Step(${featStep.text}):${featStep.location?.line}:${featStep.location?.column}\n`
-            }
-        }
-        return stack
-    }
-
     onGherkinDocument(gherkinDocEvent: GherkinDocument) {
         this.updateCurrentPickle({
             uri: gherkinDocEvent.uri,
@@ -538,17 +486,12 @@ export default class CucumberFormatter extends Formatter {
      */
     private withAmbiguousMessage(event: TestStepFinished): TestStepFinished {
         const result = event.testStepResult
-        if (result?.status !== Status.AMBIGUOUS || result.message) {
-            return event
-        }
-        const testStep = this._testCases
+        const stepDefinitionIds = () => this._testCases
             .find((tc) => tc.id === this._currentTestCase?.testCaseId)
             ?.testSteps.find((step) => step.id === event.testStepId)
-        const stepDefinitions = (testStep?.stepDefinitionIds ?? [])
-            .map((id) => this._stepDefinitions.get(id))
-            .filter((definition): definition is StepDefinition => Boolean(definition))
-        const message = getAmbiguousStepMessage(stepDefinitions)
-        return message ? { ...event, testStepResult: { ...result, message } } : event
+            ?.stepDefinitionIds ?? []
+        const withMessage = result && withAmbiguousMessage(result, stepDefinitionIds, this._stepDefinitions)
+        return withMessage === result ? event : { ...event, testStepResult: withMessage }
     }
 
     onTestStepFinished(testStepFinishedEvent: TestStepFinished) {

@@ -192,6 +192,13 @@ export class CucumberAdapter {
             this._cucumberOpts.tags = this.generateDynamicSkipTags().concat(this._cucumberOpts.tags || []).join(' and ')
         }
 
+        // One seed for loadSources and the run; Cucumber logs the seed of the run to a discarded stream
+        if (this._cucumberOpts.order === 'random') {
+            const seed = Math.floor(Math.random() * 1000 * 1000)
+            this._cucumberOpts.order = `random:${seed}`
+            log.warn(`Random order using seed: ${seed}`)
+        }
+
         // Filter the specs according to the tag expression
         // Some workers would only spawn to then skip the spec (Feature) file
         // Filtering at this stage can prevent the spawning of a massive number of workers
@@ -323,8 +330,10 @@ export class CucumberAdapter {
             return this._runSequential(supportCodeLibrary)
         }
 
-        // Parse Gherkin documents from filtered specs
-        const gherkinDocuments = this.getGherkinDocuments([this._specs])
+        // Parse Gherkin documents from filtered specs; a spec `file.feature:12` keeps
+        // its line numbers in `specs` for Cucumber's line filter
+        const featurePaths = [...new Set(this._specs.map((spec) => spec.replace(/(:\d+)+$/, '')))]
+        const gherkinDocuments = this.getGherkinDocuments([featurePaths])
         const { sources, runtime } = await this._loadRunConfiguration({ cwd: this._cwd })
 
         try {