# Gherkin syntax reference

## Contents

- [Keywords](#keywords)
- [Steps](#steps)
- [Step arguments](#step-arguments)
- [Tags](#tags)
- [Comments](#comments)
- [Spoken languages](#spoken-languages)

## 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:

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

Fix by being more specific:

```gherkin
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:

```gherkin
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 ` ``` `:

```gherkin
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.

```gherkin
@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.

```gherkin
# 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)

```gherkin
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        |
```