Gherkin Syntax and the Given When Then Scenario Format Explained

Gherkin syntax is deliberately small. It has fewer than a dozen keywords, no logic, and nothing resembling a type system, and every one of those omissions is on purpose. The notation exists so that a person who will never open the codebase can read an example, recognise it as wrong, and say so.

That constraint is the whole design. Anything that made Gherkin more expressive would make it less readable by the audience that justifies its existence.

Gherkin syntax in one page

A file has one Feature, some prose, and a set of examples.

Feature: Withdrawing cash
  As a customer
  I want to withdraw cash from the machine
  So that I do not have to visit the counter

  Background:
    Given the machine is in service

  Scenario: The account holds enough money
    Given the account balance is 100
    And the machine holds 500
    When the customer requests 20
    Then the machine dispenses 20
    And the account balance is 80

  Scenario: The account does not hold enough money
    Given the account balance is 10
    When the customer requests 20
    Then the machine dispenses nothing
    And the customer is told the balance is insufficient

That is very nearly all of Gherkin syntax. Indentation is conventional rather than significant. The keywords are what the parser reads, and And and But simply inherit the meaning of whichever keyword came before them.

The Given When Then form

The three clauses divide an example into a context, an event and an outcome, and the division is stricter than it first appears.

Given states what is already true. It is not an action the actor performs; it is the world as found. A Given that reads the customer logs in is really a When wearing the wrong keyword, and the mistake shows up later as a scenario nobody can reason about.

When states the single event under examination. One event. The Given When Then form breaks down as soon as there are two, because the Then can no longer be attributed to either.

Then states the outcome, phrased so it can be checked. In the Given When Then form this is the only clause a stakeholder will scrutinise, so it carries the most weight. Then the balance is 80 can be checked. Then the transaction is handled properly cannot, and the fact that it cannot is the useful signal: nobody agreed what properly meant.

What belongs in a scenario

A scenario is one example, not a summary of a rule. It carries real values, because real values are what expose disagreement. Two people can nod along to large withdrawals need approval and discover at the first concrete case that one of them meant 500 and the other meant 5,000.

Each scenario should also be readable on its own. If understanding one requires having read the previous three, the file is a narrative rather than a specification, and reordering it will silently break it.

The cases where the answer is no matter more than the happy path. A feature described only by scenarios that succeed has documented the least contested part of the behaviour.

The feature file and its parts

A feature file groups the scenarios for one capability. The prose after the Feature keyword is free text and is not executed; the As-a / I-want / So-that shape is a convention worth keeping because the So-that line is where the business value gets stated, and a feature file whose So-that line is empty is worth questioning before it is built.

Background factors out the Given steps every scenario shares. Scenario Outline with an Examples table expresses the same scenario across several sets of values, which keeps a rule with many boundaries from becoming twenty near-identical scenarios.

One file per capability is the usual granularity. Files that grow past a screen or two of scenarios tend to be describing more than one thing.

Gherkin language support across tools

The Gherkin language is standardised enough that a feature file moves between tools with little friction, which is unusual and worth exploiting: the examples outlive the framework that runs them. Keyword sets exist for around seventy natural languages, selected with a # language: de style header, so a team whose domain vocabulary is German or Spanish can write in it rather than translating and losing precision.

Support is not uniform. Some tools implement Rule, some do not; table formatting and docstring handling vary; and a few frameworks use their own notation instead. The framework list by language records which notation each tool actually reads.

The wording mistakes that make examples useless

Three recur often enough to name.

Steps phrased as user-interface operations. When the user clicks the Submit button ties the example to a layout and says nothing about the rule. It also breaks on the first redesign.

Outcomes phrased as internals. Then a row is inserted into the accounts table is checkable but unreadable by the person the example was written for, which removes the only reason to have written it in Gherkin.

Scenarios written after the code. Mechanically identical, and worthless, because the purpose of the notation is to hold a disagreement before it becomes expensive. Written afterwards it records what the code already does, which the code already did.