1# Gherkin syntax reference
  2
  3## Contents
  4
  5- [Keywords](#keywords)
  6- [Steps](#steps)
  7- [Step arguments](#step-arguments)
  8- [Tags](#tags)
  9- [Comments](#comments)
 10- [Spoken languages](#spoken-languages)
 11
 12## Keywords
 13
 14### Primary
 15
 16| Keyword                | Purpose                                               |
 17| ---------------------- | ----------------------------------------------------- |
 18| `Feature`              | High-level description; groups related scenarios      |
 19| `Rule`                 | Groups scenarios under one business rule (Gherkin 6+) |
 20| `Scenario` / `Example` | One concrete example illustrating a rule              |
 21| `Given`                | Initial context — the scene (past tense)              |
 22| `When`                 | The event or action (present tense)                   |
 23| `Then`                 | Expected outcome (present/future)                     |
 24| `And` / `But`          | Continue the previous keyword type                    |
 25| `*`                    | Bullet-point alternative to And                       |
 26| `Background`           | Shared preconditions run before each scenario         |
 27| `Scenario Outline`     | Template run once per Examples row                    |
 28| `Examples`             | Data table for Scenario Outline parameters            |
 29
 30### Secondary
 31
 32| Syntax | Purpose     |
 33| ------ | ----------- |
 34| `"""`  | Doc Strings |
 35| `\|`   | Data Tables |
 36| `@`    | Tags        |
 37| `#`    | Comments    |
 38
 39## Steps
 40
 41### Given
 42
 43Describes the initial state. Something that happened in the past. Sets up the system in a known state before the action.
 44
 45- Don't describe user interaction in Givens
 46- Multiple Givens use `And`/`But`
 47- Think: preconditions
 48
 49### When
 50
 51Describes the event or action. A person interacting with the system, or an event triggered by another system.
 52
 53- Usually one When per scenario
 54- Keep it technology-agnostic — "imagine it's 1922"
 55
 56### Then
 57
 58Describes the expected outcome. An observable result — something the system produces or a state it ends up in.
 59
 60- Use concrete assertions
 61- Multiple outcomes use `And`/`But`
 62
 63### Step uniqueness
 64
 65Cucumber ignores the keyword when matching steps. These are duplicates and will conflict:
 66
 67```gherkin
 68Given there is money in my account
 69Then there is money in my account
 70```
 71
 72Fix by being more specific:
 73
 74```gherkin
 75Given my account has a balance of £430
 76Then my account should have a balance of £430
 77```
 78
 79## Step arguments
 80
 81### Data Tables
 82
 83Pass structured data to a step:
 84
 85```gherkin
 86Given the following worktrees exist:
 87  | name      | branch    | clean |
 88  | main      | main      | true  |
 89  | feature-x | feature-x | false |
 90```
 91
 92Escape `|` as `\|`, newlines as `\n`, backslashes as `\\`.
 93
 94### Doc Strings
 95
 96Pass multi-line text to a step, delimited by `"""` or ` ``` `:
 97
 98```gherkin
 99Given the config file contains:
100  """json
101  {"limit": 200, "timeout": 30}
102  """
103```
104
105The content type annotation (e.g. `json`) is optional. Indentation is preserved relative to the opening delimiter.
106
107## Tags
108
109Tags are `@name` annotations placed above `Feature`, `Rule`, `Scenario`, or `Examples`. They filter which scenarios to run.
110
111```gherkin
112@smoke
113Feature: VCS detection
114
115  @slow @integration
116  Scenario: Detect jj in deeply nested directory
117    ...
118```
119
120Tag expressions support `and`, `or`, `not`, and parentheses:
121
122```
123@smoke and not @slow
124(@integration or @e2e) and not @wip
125```
126
127## Comments
128
129Lines starting with `#` (optionally preceded by whitespace). Block comments are not supported.
130
131```gherkin
132# This is a comment
133Feature: Something
134```
135
136## Spoken languages
137
138Gherkin supports 70+ spoken languages via a `# language:` header on the first line. Default is English (`en`). For Go projects, English is conventional.
139
140## Background tips
141
142- Keep it short (≤ 4 lines)
143- Only include details the reader needs to understand the scenarios
144- Use higher-level steps rather than spelling out every detail
145- One Background per Feature or Rule
146- If it scrolls off screen, split the feature or use higher-level steps
147
148## Scenario Outline tips
149
150- Use `<parameter>` placeholders in step text
151- Each Examples row runs as a separate subtest
152- Parameters work in step text, doc strings, and data tables
153- Multiple Examples sections are allowed (useful with different tags)
154
155```gherkin
156Scenario Outline: spend coins
157  Given a wallet with <initial> coins
158  When I spend <amount>
159  Then I have <remaining> left
160
161  Examples:
162    | initial | amount | remaining |
163    | 100     | 10     | 90        |
164    | 100     | 50     | 50        |
165```