Registry / testing / wdio-cucumber-framework

wdio-cucumber-framework

library2.2.8jsnpmunverified

The `wdio-cucumber-framework` package acts as an essential adapter for integrating the Cucumber.js testing framework into WebdriverIO projects. It allows developers to write Behavior-Driven Development (BDD) tests using Cucumber's Gherkin syntax and execute them via the WebdriverIO test runner. The current stable version, 2.2.8, is primarily designed to work with Cucumber.js v4. Users needing compatibility with older Cucumber.js versions must install specific legacy versions of this adapter (v1.1.1 for Cucumber.js v2, and v0.3.1 for Cucumber.js v1). This framework is released as part of the WebdriverIO ecosystem and typically sees updates in line with major WebdriverIO releases or significant changes in Cucumber.js. Its key differentiator is providing a seamless bridge between WebdriverIO's powerful automation capabilities and Cucumber's readability and BDD structure, offering specific configuration options not native to Cucumber.js itself, like `failAmbiguousDefinitions`.

testing

npm install wdio-cucumber-framework

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WDIO-CUCUMBER-FRAM

wdio-cucumber-framework

testingjavascriptv2.2.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Framework Configuration

✓ // wdio.conf.js export const config = { // ... framework: 'cucumber', // ... };

✗ import { CucumberFramework } from 'wdio-cucumber-framework';

The framework is loaded by WebdriverIO via its string name in the `wdio.conf.js` file, not through direct `import` or `require` statements in user code.

Step Definition Files

✓ // wdio.conf.js export const config = { // ... cucumberOpts: { require: [ './features/step-definitions/*.ts', './features/support/*.ts' ] } // ... };

Step definition files are configured using the `cucumberOpts.require` array within `wdio.conf.js`. This tells Cucumber.js where to find your step implementations.

Custom Compiler

✓ // wdio.conf.js export const config = { // ... cucumberOpts: { compiler: ['ts:ts-node/register'] } // ... };

For TypeScript or Babel support, specify a `compiler` in `cucumberOpts`. This registers a pre-processor for your step definition files, enabling features like TypeScript directly.

This configuration snippet shows a basic `wdio.conf.ts` setup using the Cucumber framework, specifying feature and step definition paths, and common Cucumber options like `timeout` and `tagExpression`.

import type { Options } from '@wdio/types'; import path from 'path'; export const config: Options.WebdriverIO = { // Host address of the running Selenium server. hostname: 'localhost', port: 4444, // Patterns to search for feature files specs: [ './features/**/*.feature' ], // Patterns to exclude. exclude: [ // 'path/to/excluded/files' ], // Capabilities capabilities: [{ maxInstances: 5, browserName: 'chrome', acceptInsecureCerts: true }], // Level of logging verbosity: trace | debug | info | warn | error | silent logLevel: 'info', // If you are using Cucumber, this is the place to specify the framework framework: 'cucumber', // Cucumber options cucumberOpts: { require: [path.join(__dirname, 'features/step-definitions/**/*.ts')], backtrace: false, compiler: ['ts:ts-node/register'], dryRun: false, failFast: false, ignoreUndefinedDefinitions: false, strict: true, tagExpression: '@smoke or @regression', // Example tag expression timeout: 60000, snippets: true, source: true }, // Services allow you to integrate additional functionality into your test process services: ['selenium-standalone'], // reporters: ['spec'], // By default, WebdriverIO will use 'wdio desktop' as the browser name when not set. // This can be changed to 'wdio mobile' for mobile browser usage. // This property is used for `browser.capabilities.browserName` and reporting. // If you are using `wdio-allure-reporter`, this is helpful for creating custom categories. // Use only if you do not specify `browserName` in `capabilities` section. // browserName: 'chrome', // The number of times to retry the entire spec file when it fails. // retries: 0, // Options for the `ts-node` module autoCompileOpts: { autoCompile: true, tsNodeOpts: { project: './tsconfig.json', transpileOnly: true } } };

Debug

Known issues

breakingMajor versions of `wdio-cucumber-framework` are tied to specific major versions of Cucumber.js. Version 2.x supports Cucumber.js v4. Using incompatible versions will lead to runtime errors or unexpected behavior.

fix

Ensure `wdio-cucumber-framework` version aligns with your Cucumber.js version. For Cucumber.js v2, use `wdio-cucumber-framework@1.1.1`. For Cucumber.js v1, use `wdio-cucumber-framework@0.3.1`.

affects: all

gotchaThe `failAmbiguousDefinitions` and `ignoreUndefinedDefinitions` options are specific to `wdio-cucumber-framework` and are *not* native Cucumber.js options. Using them in standard Cucumber.js configurations outside of WebdriverIO will have no effect.

fix

Be aware that these options only apply when running Cucumber tests through WebdriverIO and this specific adapter. Refer to the `wdio-cucumber-framework` documentation for their correct usage.

affects: >=0.3.1

gotchaWhen using `tagExpression`, untagged features will still spawn a Selenium session. This can lead to unnecessary resource consumption or longer test runs if you expect `tagExpression` to entirely filter out untagged features from execution.

fix

Ensure all features intended for conditional execution have appropriate tags. Consider using `specs` filtering in `wdio.conf.js` for broader feature file exclusion if untagged features are not desired at all.

affects: all

gotchaThe `timeout` option under `cucumberOpts` sets the timeout for individual step definitions. If a step takes longer than this duration, it will fail. This is distinct from WebdriverIO's global `waitforTimeout` or `connectionRetryTimeout`.

fix

Adjust `cucumberOpts.timeout` to a sufficiently high value (in milliseconds) to accommodate long-running steps, especially those involving complex UI interactions or data processing. The default is 30000ms (30 seconds).

affects: all

Errors

Common errors & fixes

Error: Cannot find module 'wdio-cucumber-framework' or 'Cucumber'

The `wdio-cucumber-framework` package or the underlying `@cucumber/cucumber` package is not installed, or there's a typo in the `framework` option in `wdio.conf.js`.

fix

Ensure `npm install wdio-cucumber-framework @cucumber/cucumber --save-dev` has been run and check that `framework: 'cucumber'` is correctly spelled in your `wdio.conf.js`.

TypeError: Given/When/Then is not a function

Your step definition files are not being loaded correctly, or you are trying to use Cucumber.js constructs outside of a loaded step definition context.

fix

Verify that your `cucumberOpts.require` array in `wdio.conf.js` correctly points to your step definition files (e.g., `path.join(__dirname, 'features/step-definitions/**/*.ts')`). Also, ensure proper compilers like `ts-node/register` are configured for TypeScript.

Ambiguous step definition for "..."

Cucumber.js found multiple matching step definitions for a given Gherkin step.

fix

Refine your step definition regular expressions to be more specific, or set `cucumberOpts.failAmbiguousDefinitions: true` in `wdio.conf.js` to treat this as an error and stop the test run immediately, aiding in debugging.

Undefined step definition for "..."

A Gherkin step in your feature file does not have a corresponding step definition implemented.

fix

Implement the missing step definition in your step files. You can also temporarily set `cucumberOpts.ignoreUndefinedDefinitions: true` to treat this as a warning instead of a failure during development, or `cucumberOpts.strict: true` to ensure all steps are defined.

Upgrade

Version history

2.2.8latest on npm

Audit

Dependencies

webdriveriorequiredCore test runner that loads and executes this framework.

@cucumber/cucumberrequiredThe underlying Cucumber.js library that this adapter integrates with. Version compatibility is crucial.

Agent activity

21 hits · last 30 days

node

Resources

githubhttps://github.com/webdriverio/wdio-cucumber-framework ↗

packagehttps://www.npmjs.com/package/wdio-cucumber-framework ↗

homepagehttps://webdriver.io ↗