Principle:Webdriverio Webdriverio Gherkin Feature Specification

Metadata

Field	Value
Page ID	Gherkin_Feature_Specification
Page Type	Principle
Repository	webdriverio/webdriverio
Knowledge Sources	Doc (Gherkin Reference), Repo (webdriverio/webdriverio)
Domains	Testing, BDD, Specification
Related Pages	implemented_by Implementation:Webdriverio_Webdriverio_Gherkin_Syntax_Pattern

Overview

A structured, human-readable syntax for specifying application behavior as executable test scenarios.

Description

Gherkin Feature Specification uses the Gherkin language to describe application behavior in plain text using keywords: Feature (top-level description), Scenario (individual test case), Given/When/Then (test steps), Background (shared setup), Rule (business rule grouping), and Scenario Outline with Examples (data-driven scenarios). This approach makes test specifications readable by non-technical stakeholders while remaining executable.

In a WebdriverIO Cucumber project, feature files are the entry point for test execution. They are placed in directories matching the specs configuration pattern and are parsed by the @cucumber/gherkin library before being matched against step definitions for execution.

Gherkin Keywords

The following keywords form the vocabulary of a Gherkin feature file:

• Feature: The top-level keyword that groups related scenarios. Each .feature file contains exactly one Feature block. It includes a name and an optional free-text description.
• Scenario (or Example): An individual test case representing a specific behavior. Each scenario contains a sequence of steps.
• Given: A step that establishes preconditions (the system state before the action under test).
• When: A step that describes the action being tested.
• Then: A step that asserts the expected outcome.
• And / But: Continuation keywords that repeat the previous step type for readability.
• Background: A set of steps that run before every scenario in a feature, used for common setup.
• Rule: A grouping keyword that organizes scenarios under a business rule within a feature.
• Scenario Outline (or Scenario Template): A parameterized scenario template that runs once per row in an Examples table.
• Examples (or Scenarios): A data table that provides parameter values for a Scenario Outline.
• Data Tables: Tabular data passed directly to a step, represented as a pipe-delimited table beneath the step text.
• Doc Strings: Multi-line string arguments delimited by triple quotes (""") beneath a step.

Usage

Use Gherkin Feature Specification when following BDD practices where business requirements should be expressed as executable specifications. Write .feature files using Gherkin syntax, place them in directories matching the specs config pattern, and bind steps to automation code via step definitions.

Feature: Example feature
  As a user of WebdriverIO
  I should be able to use different commands
  to get information 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"

  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      |
          | Chocolate  | 3      |
      Then  I should have a list of 4 items

Scenario Outline Example

Feature: Login validation
  Scenario Outline: Attempt login with various credentials
    Given I am on the login page
    When I enter username "<username>" and password "<password>"
    Then I should see "<result>"

    Examples:
      | username | password | result        |
      | admin    | secret   | Dashboard     |
      | user     | wrong    | Invalid login |
      | ""       | ""       | Required      |

Theoretical Basis

Gherkin is a line-oriented language that uses indentation and keywords to structure specifications. The parser (from @cucumber/gherkin) builds an AST (Abstract Syntax Tree) with Feature, Scenario, and Step nodes. Each step text is matched against registered step definitions using string patterns or regular expressions. The Given-When-Then structure follows the Arrange-Act-Assert testing pattern:

• Given = Arrange (set up preconditions)
• When = Act (perform the action under test)
• Then = Assert (verify the expected outcome)

Scenario Outlines enable parameterized testing via Examples tables. The Gherkin parser expands each Scenario Outline into multiple concrete scenarios (called pickles), one per row in the Examples table. Each pickle has its placeholder values (<column_name>) replaced with the corresponding cell values.

Parsing Pipeline

The WDIO Cucumber adapter uses three classes from @cucumber/gherkin to parse feature files:

1. Gherkin.AstBuilder: Constructs the AST from parser events, using a UUID function for node identification.
2. Gherkin.GherkinClassicTokenMatcher: Tokenizes Gherkin text using the configured language (default: 'en').
3. Gherkin.Parser: Coordinates the tokenizer and AST builder to produce a GherkinDocument from raw feature file text.

After parsing, Gherkin.compile() transforms the AST into pickles -- concrete, executable test scenarios with all Scenario Outline expansions resolved.

Language Support

Gherkin supports over 70 spoken languages. When the language configuration is set (e.g., 'fr' for French), the GherkinClassicTokenMatcher recognizes localized keywords (e.g., Fonctionnalité instead of Feature, Soit instead of Given).

Related Pages

Implementation:Webdriverio_Webdriverio_Gherkin_Syntax_Pattern

• implemented_by: Implementation:Webdriverio_Webdriverio_Gherkin_Syntax_Pattern