gherkin-reference.md

Gherkin syntax reference

Contents

Keywords

Primary

Keyword Purpose
Feature High-level description; groups related scenarios
Rule Groups scenarios under one business rule (Gherkin 6+)
Scenario / Example One concrete example illustrating a rule
Given Initial context — the scene (past tense)
When The event or action (present tense)
Then Expected outcome (present/future)
And / But Continue the previous keyword type
* Bullet-point alternative to And
Background Shared preconditions run before each scenario
Scenario Outline Template run once per Examples row
Examples Data table for Scenario Outline parameters

Secondary

Syntax Purpose
""" Doc Strings
| Data Tables
@ Tags
# Comments

Steps

Given

Describes the initial state. Something that happened in the past. Sets up the system in a known state before the action.

  • Don't describe user interaction in Givens
  • Multiple Givens use And/But
  • Think: preconditions

When

Describes the event or action. A person interacting with the system, or an event triggered by another system.

  • Usually one When per scenario
  • Keep it technology-agnostic — "imagine it's 1922"

Then

Describes the expected outcome. An observable result — something the system produces or a state it ends up in.

  • Use concrete assertions
  • Multiple outcomes use And/But

Step uniqueness

Cucumber ignores the keyword when matching steps. These are duplicates and will conflict:

Given there is money in my account
Then there is money in my account

Fix by being more specific:

Given my account has a balance of £430
Then my account should have a balance of £430

Step arguments

Data Tables

Pass structured data to a step:

Given the following worktrees exist:
  | name      | branch    | clean |
  | main      | main      | true  |
  | feature-x | feature-x | false |

Escape | as \|, newlines as \n, backslashes as \\.

Doc Strings

Pass multi-line text to a step, delimited by """ or ```:

Given the config file contains:
  """json
  {"limit": 200, "timeout": 30}
  """

The content type annotation (e.g. json) is optional. Indentation is preserved relative to the opening delimiter.

Tags

Tags are @name annotations placed above Feature, Rule, Scenario, or Examples. They filter which scenarios to run.

@smoke
Feature: VCS detection

  @slow @integration
  Scenario: Detect jj in deeply nested directory
    ...

Tag expressions support and, or, not, and parentheses:

@smoke and not @slow
(@integration or @e2e) and not @wip

Comments

Lines starting with # (optionally preceded by whitespace). Block comments are not supported.

# This is a comment
Feature: Something

Spoken languages

Gherkin supports 70+ spoken languages via a # language: header on the first line. Default is English (en). For Go projects, English is conventional.

Background tips

  • Keep it short (≤ 4 lines)
  • Only include details the reader needs to understand the scenarios
  • Use higher-level steps rather than spelling out every detail
  • One Background per Feature or Rule
  • If it scrolls off screen, split the feature or use higher-level steps

Scenario Outline tips

  • Use <parameter> placeholders in step text
  • Each Examples row runs as a separate subtest
  • Parameters work in step text, doc strings, and data tables
  • Multiple Examples sections are allowed (useful with different tags)
Scenario Outline: spend coins
  Given a wallet with <initial> coins
  When I spend <amount>
  Then I have <remaining> left

  Examples:
    | initial | amount | remaining |
    | 100     | 10     | 90        |
    | 100     | 50     | 50        |