Implementation:Webdriverio Webdriverio Gherkin Syntax Pattern

Metadata

Field	Value
Page ID	Gherkin_Syntax_Pattern
Page Type	Implementation
Implementation Type	Pattern Doc
Repository	webdriverio/webdriverio
Package	@wdio/cucumber-framework (parser), @cucumber/gherkin (syntax)
Source	examples/wdio/cucumber/features/my-feature.feature (L1-25), packages/wdio-cucumber-framework/src/index.ts (L152-170: getGherkinDocuments parser)
Related Pages	implements Principle:Webdriverio_Webdriverio_Gherkin_Feature_Specification

Overview

Interface specification for writing Gherkin feature files in a WebdriverIO Cucumber project.

Description

Gherkin feature files (.feature) define test scenarios in human-readable syntax. They are parsed by @cucumber/gherkin using Gherkin.Parser, Gherkin.AstBuilder, and Gherkin.GherkinClassicTokenMatcher. The WDIO Cucumber adapter reads these files based on the specs configuration pattern and converts them into executable pickle objects.

The parser is initialized in the CucumberAdapter constructor:

// packages/wdio-cucumber-framework/src/index.ts (constructor)
const builder = new Gherkin.AstBuilder(uuidFn)
const matcher = new Gherkin.GherkinClassicTokenMatcher(
    this._cucumberOpts.language
)
this.gherkinParser = new Gherkin.Parser(builder, matcher)

Feature files are then parsed via the getGherkinDocuments() method which reads file contents, parses them into GherkinDocument objects, and attaches the file URI for later reference.

Gherkin Keyword Reference

Keyword	Purpose	Scope
Feature	Top-level grouping of related scenarios	One per .feature file
Scenario / Example	Individual test case	Multiple per Feature
Given	Precondition step (Arrange)	Within Scenario
When	Action step (Act)	Within Scenario
Then	Assertion step (Assert)	Within Scenario
And / But	Continuation of previous step type	Within Scenario
Background	Shared setup steps for all scenarios	One per Feature/Rule
Rule	Business rule grouping	Within Feature
Scenario Outline / Scenario Template	Parameterized scenario template	Within Feature/Rule
Examples / Scenarios	Data table for Scenario Outline	Within Scenario Outline
Data Tables	Tabular data passed to a step	Below a step
Doc Strings	Multi-line string argument (triple-quoted)	Below a step
@tag	Tag annotation for filtering	Before Feature/Scenario/Examples
#	Comment line	Anywhere

Example Feature File

From the repository example at examples/wdio/cucumber/features/my-feature.feature:

Feature: Example feature
  As a user of WebdriverIO
  I should be able to use different commands
  to get informations about elements on the page

  Scenario: Get size of an element
    Given I go on the website "https://github.com/"
    Then  should the element ".header-logged-out a" be 32px wide and 34.5px high

  Rule: Business rule 1
    Scenario: Get title of website
      Given I go on the website "https://github.com/"
      Then  should the title of the page be "GitHub: Let's build from here · GitHub"

  Rule: Business rule 2
    Scenario: Data Tables
      Given I go on the website "http://todomvc.com/examples/react/dist/"
      When  I add the following groceries
          | Item       | Amount |
          | Milk       | 2      |
          | Butter     | 1      |
          | Noodles    | 1      |
          | Schocolate | 3      |
      Then  I should have a list of 4 items

Scenario Outline Pattern

Feature: Parameterized testing
  Scenario Outline: Validate page title for "<site>"
    Given I go on the website "<url>"
    Then  should the title of the page be "<expected_title>"

    Examples:
      | site   | url                    | expected_title       |
      | GitHub | https://github.com/    | GitHub               |
      | Google | https://www.google.com | Google               |

Each row in the Examples table produces a separate pickle (concrete scenario) at parse time, with placeholder values (<site>, <url>, <expected_title>) replaced by the corresponding cell values.

Parser Integration (Source Reference)

The getGherkinDocuments() method in CucumberAdapter handles parsing:

// packages/wdio-cucumber-framework/src/index.ts (L152-170)
getGherkinDocuments(
    files: WebdriverIO.Config['specs'] = []
): (GherkinDocument | GherkinDocument[])[] {
    return this.readFiles(files).map((specContent, idx) => {
        const docs: GherkinDocument[] = [specContent].flat(1).map(
            (content, ctIdx) =>
                ({
                    ...this.gherkinParser.parse(content),
                    uri: Array.isArray(specContent)
                        ? files[idx][ctIdx]
                        : files[idx],
                } as GherkinDocument)
        )
        const [doc, ...etc] = docs
        return etc.length ? docs : doc
    })
}

After parsing, the adapter uses Gherkin.compile(doc, , uuidFn) to convert documents into pickles for tag-based filtering and execution.

File Placement Convention

Feature files should be placed according to the specs pattern in wdio.conf.ts:

// wdio.conf.ts
export const config: WebdriverIO.Config = {
    specs: ['./features/**/*.feature'],
    framework: 'cucumber',
    cucumberOpts: {
        require: ['./step-definitions/**/*.ts']
    }
}

Related Pages

• implements: Principle:Webdriverio_Webdriverio_Gherkin_Feature_Specification