Writing Good Gherkin

1 The Hook

A team at a fictional council, Manawa District, automated their rates-payment scenarios in Gherkin. A year later a tester opened the feature file to understand how a part-payment was meant to behave. This is what greeted her:

She still had no idea what the rule was. Was $150 a part-payment of a larger bill? What was the bill? What should happen to the balance? The scenario described clicking a website, not the behaviour of part-payments. It was tied so tightly to the screen that when the login page was redesigned six months later, every scenario in the file broke at once — not because the rates logic changed, but because a button id did. The feature file documented the UI of a moment, and nothing about the rules.

Good Gherkin is the opposite of this. It describes what the system does in the language of the business, not how a user clicks through a screen. Written well, the same scenario survives a UI redesign untouched, reads like a sentence a ratepayer would understand, and tells the next tester exactly what the rule is. This lesson is about writing that kind of Gherkin — and recognising the kind above so you never ship it.

2 The Rule

3 The Analogy

4 The Anatomy of a Scenario

Gherkin has a small, fixed grammar. A Feature groups related scenarios. Each Scenario is one concrete example, built from steps that start with keywords:

• Given — the context that is already true before the action. The starting state of the world. (“Given a ratepayer with an outstanding rates bill of $1,200”.)
• When — the single action under test. The event that triggers the behaviour. (“When the ratepayer pays $150”.)
• Then — the expected outcome. What must be observably true afterwards. (“Then the outstanding balance is $1,050”.)
• And / But — extra Given, When, or Then steps, so the scenario reads naturally instead of repeating a keyword.

Here is the Manawa part-payment scenario from the Hook, rewritten as good Gherkin:

Read it aloud — it is a sentence a ratepayer would understand, and it states the rule (a $150 payment reduces a $1,200 bill to $1,050) with no mention of a button, a field, or a URL. One scenario should test one behaviour: one Given context, one When action, one or a few Then outcomes. If you find yourself writing a second When in the middle, you almost certainly have two scenarios.

5 Declarative vs Imperative

This is the single most important distinction in writing Gherkin, and the one the Hook turned on.

Imperative steps describe how a user operates the interface — the clicks, the fields, the keystrokes. Declarative steps describe what the user is trying to do, in business language, leaving the “how” to the automation underneath.

The declarative version is shorter, reads like business, survives a UI change (the dropdown can become radio buttons and the scenario is untouched), and tells the reader the intent rather than the mechanics. The imperative version breaks the moment a field id changes, buries the rule under clicks, and is unreadable to anyone who is not looking at the screen. The “how” — which field, which button — belongs in the automation step definitions, hidden beneath the Gherkin, never in the scenario itself.

6 Backgrounds

When every scenario in a feature shares the same setup, repeating it in each one is noise. A Background is a block of Given steps that runs before every scenario in the feature, so the common context is stated once.

The shared context — an active account contributing at 3% — is declared once in the Background and applies to both scenarios. Keep Backgrounds short and made only of Given steps that genuinely apply to every scenario. The moment a Background grows long, or you find yourself adding a Given that only some scenarios need, it has become a liability — it hides important context from the reader, who now has to scroll up to understand any single scenario.

7 Scenario Outlines

When the same behaviour needs checking against several sets of values, writing one scenario per value is repetitive. A Scenario Outline states the behaviour once with placeholders, and an Examples table supplies the rows. It is Specification by Example from Lesson 1, written as runnable Gherkin.

Here is the Auckland Council rates-rebate rule from Lesson 1, including the boundary case the Three Amigos had to decide:

The outline runs once per row, substituting each <placeholder>. Four data cases, one readable scenario. This is where boundary and negative rows from a Three Amigos session land naturally — the row at exactly the threshold, the row that produces $0. A scenario outline is the right tool when one behaviour varies by data; it is the wrong tool when you are tempted to cram several different behaviours into one table, which makes it unreadable.

8 Gherkin as Living Documentation

The hidden payoff of good Gherkin is documentation that cannot go stale. Because the scenarios are executed as automated tests, they must match the system’s real behaviour or the build fails. That makes the feature files a description of the system that is always true — living documentation.

Contrast that with a Word specification in a shared drive. It is accurate the day it is written and decays from there, because nothing forces it to stay in step with the code. Six months on, no one trusts it. A Gherkin feature file cannot drift the same way: if the behaviour changes and the scenario is not updated, the automated test breaks and someone has to reconcile them. The documentation and the system are chained together.

This is only true if the Gherkin is declarative and business-readable. The imperative click-script from the Hook documents nothing a business owner can use. Declarative scenarios — “a $150 payment reduces a $1,200 bill to $1,050” — can be read by a BA, a product owner, or an auditor, and they double as the test suite. One artefact serves as the requirement, the test, and the documentation at once. That is the whole promise of BDD, and it stands or falls on how you write the Gherkin.

9 Common Mistakes

10 Now You Try

Three graded exercises: spot the anti-patterns in bad Gherkin, rewrite it declaratively, then build a scenario outline with edge and negative cases. Write your answer, run it for AI feedback, then compare to the model answer.

There are at least six problems; any four correctly named earn full marks.

1. Imperative / UI-coupled steps — the scenario describes typing into "#username", "#pwd", "#amount" and clicking "#loginBtn", "#submit". These break when the UI changes and hide the rule. They belong in step definitions, not the scenario.

2. URLs and selectors in steps — "https://anz.co.nz/login" and CSS ids (#username) couple the scenario to one exact screen.

3. Login noise / multiple behaviours — logging in is not the behaviour under test (a transfer is). The login should be a declarative Given ("Given a logged-in customer") or a Background, not five click steps. Logging out at the end is a second unrelated behaviour.

4. Vague Then — "Then it works" asserts nothing checkable. A good Then states the observable outcome: the balance decreased by $500, the payee was credited, a confirmation reference was issued.

5. No clear single When — the action is buried in "type 500 and click submit"; the real When ("the customer transfers $500 to a saved payee") is never stated cleanly.

6. Unclear context — there is no Given establishing the starting balance or the destination account, so the outcome cannot be verified.

Strong answers name the imperative/UI-coupling and the vague "it works" Then as the two most damaging. The fix is Exercise 2.

Feature: Transfer between accounts

Scenario: A successful transfer reduces the source balance
  Given a logged-in customer with $2,000 in their everyday account
  And a saved payee "Power Bill"
  When the customer transfers $500 to "Power Bill"
  Then the everyday account balance is $1,500
  And the payee is credited with $500
  And a confirmation reference is issued

Scenario: A transfer that exceeds the available balance is declined
  Given a logged-in customer with $300 in their everyday account
  When the customer attempts to transfer $500 to "Power Bill"
  Then the transfer is declined with an insufficient-funds message
  And the everyday account balance is unchanged at $300

What makes this strong: no URLs or selectors (the login is a single declarative Given, not five clicks); exactly one behaviour per scenario with one clear When; a checkable Then that states the balance and the outcome rather than "it works"; and a real negative case that asserts the balance is unchanged — a common gap. The "how" of clicking is left to the step definitions underneath, where it belongs.

Feature: KiwiSaver contribution rate change

Background:
  Given a member with an active KiwiSaver account
  And the member is currently contributing at 3%

Scenario Outline: Changing the contribution rate
  When the member changes their rate to 
  Then 

  Examples:
    | rate | result                                              |
    | 4%   | the new rate of 4% applies from the next pay run    |
    | 8%   | the new rate of 8% applies from the next pay run    |
    | 10%  | the new rate of 10% applies from the next pay run   |
    | 5%   | the change is rejected with the list of valid rates |
    | 0%   | the change is rejected with the list of valid rates |
    | -2%  | the change is rejected as an invalid value          |

What makes this strong: the Background holds the shared context (active account, currently at 3%) once; the outline tests one behaviour (changing the rate) across data; valid rows (4%, 8%, 10%) confirm the happy path; and the negative/boundary rows (5% just outside the set, 0%, a negative value) force the rejection path. A weak answer lists only valid rates — it never exercises the rule that rejects invalid ones, which is exactly where the defect hides. Note each row keeps the same behaviour, with only the data and expected result changing.

11 Self-Check

Click each question to reveal the answer.

12 Interview Prep

Real questions asked in NZ QA interviews for BDD and automation roles. Read the model answers, then practise your own version.