Principle:Webdriverio Webdriverio Step Definition Binding

Metadata

Field	Value
Page ID	Step_Definition_Binding
Page Type	Principle
Repository	webdriverio/webdriverio
Knowledge Sources	Repo (webdriverio/webdriverio), Doc (Cucumber Step Definitions)
Domains	Testing, BDD
Related Pages	implemented_by Implementation:Webdriverio_Webdriverio_Given_When_Then_Functions

Overview

A mechanism for binding Gherkin step text to executable automation code using pattern-matched function registration.

Description

Step Definition Binding connects Gherkin feature file steps (Given/When/Then text) to automation code. Each step definition registers a pattern (string or regex) and a function. When a feature file step matches a pattern, the corresponding function executes with captured groups as arguments. This creates the bridge between human-readable specifications and browser automation.

The binding mechanism works in three phases:

1. Registration: Step definition files call Given(), When(), or Then() with a pattern and an async function. These register the pattern-function pair with the Cucumber support code library.
2. Matching: At execution time, Cucumber takes each step text from a pickle (parsed scenario) and searches through registered step definitions for a matching pattern. String patterns use Cucumber expression syntax with typed parameters; regex patterns use capture groups.
3. Execution: When a match is found, the step function is invoked with extracted parameters as arguments. Within the function body, WDIO globals (browser, $, $$, expect) are available for browser automation.

Pattern Types

Step definitions support two pattern types:

• String patterns (Cucumber Expressions): Use typed parameter placeholders such as {string}, {int}, {float}, {word}, and custom parameter types. Example: 'I have {int} items in my cart'.
• Regular expressions: Use standard JavaScript regex with capture groups. Example: /^I go on the website "([^"]*)"$/.

Parameter Extraction

For string patterns, parameter types determine how captured text is converted:

Parameter Type	Matches	Converts To
{string}	Quoted text ("..." or '...')	string
{int}	Integer number	number
{float}	Decimal number	number
{word}	Single word (no spaces)	string
{}	Anonymous (any text)	string

For regular expressions, each capture group (...) is passed as a string argument to the step function.

Usage

Use Step Definition Binding when implementing Cucumber step definitions for WDIO tests. Create step definition files (.ts/.js) that import Given, When, Then from @wdio/cucumber-framework and register patterns with async functions that use browser/$/$$/expect for automation.

import { Given, When, Then } from '@wdio/cucumber-framework'

// Regex pattern with capture group
Given(/^I go on the website "([^"]*)"$/, async (url) => {
    await browser.url(url)
})

// Regex pattern with multiple capture groups
Then(/^should the element "([^"]*)" be (\d+(?:\.\d+)?)px wide and (\d+(?:\.\d+)?)px high$/, async (selector, width, height) => {
    const elemSize = await $(selector).getSize()
    expect(elemSize.width).toBe(Number(width))
    expect(elemSize.height).toBe(Number(height))
})

// String pattern (Cucumber Expression)
Given('I have {int} items in my cart', async (count) => {
    // count is automatically converted to a number
    await expect($$('.cart-item')).toBeElementsArrayOfSize(count)
})

Data Table Steps

Steps can receive data tables as arguments:

When(/^I add the following groceries$/, async (table) => {
    const newTodo = await $('.new-todo')
    table.rawTable.shift() // remove header row

    for (const [item, amount] of table.rawTable) {
        await newTodo.addValue(`${item} (${amount}x)`)
        await browser.keys(Key.Enter)
    }
})

Theoretical Basis

Step definitions use the Strategy pattern: each step text is matched against registered patterns to find the implementation strategy. The pattern can be a string (with {string}, {int}, {float} parameter types) or a regular expression (with capture groups). The binding mechanism is provided by @cucumber/cucumber and re-exported through the WDIO adapter.

The WDIO adapter wraps each step function to integrate with WDIO's before/after step hooks. This wrapping is performed by the wrapSteps() and wrapStep() methods in CucumberAdapter. The wrapper uses setDefinitionFunctionWrapper() from @cucumber/cucumber to intercept step execution and inject:

• Before/After Hook Integration: Each step is wrapped with config.beforeHook and config.afterHook calls via testFnWrapper.
• Retry Logic: If a step definition has a retry option, the wrapper enables automatic retry of the step function.
• Hook Differentiation: The wrapper distinguishes between steps and hooks using function name prefixes (wdioHook* for WDIO hooks, userHook* for user-defined Cucumber hooks).

Step Resolution Rules

• Each step text must match exactly one step definition. Zero matches results in an undefined step; multiple matches results in an ambiguous step.
• The ignoreUndefinedDefinitions option converts undefined steps to pending instead of failed.
• The failAmbiguousDefinitions option converts ambiguous steps to failed instead of the default behavior.
• Step definitions are loaded from files matching the cucumberOpts.require glob patterns.

Related Pages

Implementation:Webdriverio_Webdriverio_Given_When_Then_Functions

• implemented_by: Implementation:Webdriverio_Webdriverio_Given_When_Then_Functions