Workflow:Webdriverio Webdriverio Cucumber BDD Testing
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, BDD, E2E_Testing |
| Last Updated | 2026-02-12 01:30 GMT |
Overview
End-to-end process for implementing Behavior-Driven Development (BDD) tests using WebdriverIO with the Cucumber framework and Gherkin feature files.
Description
This workflow demonstrates how to write human-readable test specifications in Gherkin syntax (Given/When/Then) and connect them to browser automation through Cucumber step definitions. The @wdio/cucumber-framework adapter integrates Cucumber into the WDIO testrunner, enabling non-technical stakeholders to read and validate test scenarios while developers implement the underlying automation. Feature files describe business behavior in plain language, and step definition files map each step to WebdriverIO browser commands.
Usage
Execute this workflow when your team practices Behavior-Driven Development and wants test specifications that non-technical stakeholders (product owners, QA analysts) can read and approve. This is the right approach when test requirements are expressed as user stories with acceptance criteria in Given/When/Then format.
Execution Steps
Step 1: Install Cucumber Framework
Install the @wdio/cucumber-framework package alongside the standard WDIO testrunner packages. This adapter bridges the Cucumber test runner with WebdriverIO's browser automation capabilities.
Key considerations:
- Install @wdio/cucumber-framework as a dev dependency
- The configuration wizard can set this up automatically if cucumber is selected as the framework
- Cucumber is used instead of Mocha or Jasmine; only one framework can be active at a time
Step 2: Configure for Cucumber
Set the framework option to cucumber in wdio.conf.ts and configure the cucumberOpts block. Point specs to .feature files and specify the require path for step definition files. Configure tags, timeouts, and other Cucumber-specific options.
Key considerations:
- specs points to .feature files (Gherkin syntax)
- cucumberOpts.require points to step definition TypeScript/JavaScript files
- cucumberOpts.tags filters which scenarios to run
- cucumberOpts.timeout sets the step timeout (default is often too low for browser tests)
Step 3: Write Feature Files
Create .feature files in Gherkin syntax that describe test scenarios using Feature, Scenario, Given, When, Then, and And keywords. Each scenario represents a distinct test case. Scenarios can use Scenario Outline with Examples tables for data-driven testing.
Key considerations:
- Feature files are plain text, readable by non-technical team members
- Each scenario should be independent and test one behavior
- Use Background for shared preconditions across scenarios
- Scenario Outline with Examples enables parameterized testing
- Data tables provide structured input data to steps
Step 4: Implement Step Definitions
Create step definition files that import Given, When, and Then from @wdio/cucumber-framework and map Gherkin steps to browser automation code. Each step uses a regex or Cucumber expression pattern to match the corresponding line in feature files.
Key considerations:
- Step definitions use regex patterns or Cucumber expressions to match feature steps
- Captured groups become function parameters
- The global browser object provides WebdriverIO commands within steps
- Step definitions should be reusable across multiple scenarios
- Keep steps focused on a single action or assertion
Step 5: Run and Report
Execute the test suite with npx wdio run wdio.conf.ts. Cucumber scenarios appear as individual tests in reporter output. Each step (Given/When/Then) is reported with pass/fail status. Failed steps include the specific assertion or browser error.
Key considerations:
- Each scenario runs as an independent test with its own browser session (by default)
- Step failures are reported at the step level with Gherkin context
- Tags can be used to run specific subsets of scenarios
- Allure reporter integrates natively with Cucumber for rich HTML reports