Gherkin Syntax

---

Origins

Gherkin was created in 2008 by Aslak Hellesøy as the human-readable input format for the Cucumber testing framework.¹ Its roots reach back further — to Dan North's invention of Behavior-Driven Development in 2003, where the Given–When–Then structure first appeared as a way to write tests that read like specifications.²

The point was never the syntax itself. The point was to find a way to write tests that non-developers could read — business analysts, product owners, customers — so that the specification of behavior and the verification of behavior were the same document. Gherkin is the most successful realization of that goal.

The Structure

Gherkin's vocabulary is small. The core keywords:

• Feature: the high-level capability being described.
• Scenario: one concrete example of behavior.
• Given: the context, the setup, the initial state.
• When: the action or event.
• Then: the observable outcome.
• And, But: connectors that extend any of the above.
• Background: shared setup for every scenario in a feature.
• Scenario Outline / Examples: a table-driven form that runs the same scenario across multiple data sets.

A Worked Example

A simple feature, written in Gherkin:

Feature: Password reset

  Scenario: User resets password within the time limit
    Given a registered user has requested a password reset
    When they click the reset link within one hour
    Then they can set a new password

  Scenario: User resets password after expiry
    Given a registered user has requested a password reset
    When they click the reset link after 61 minutes
    Then they see an "expired link" message

  Scenario Outline: Reset link single-use enforcement
    Given a user has reset their password using a valid link
    When they click the same link again
    Then they see an "invalid link" message

Three things to notice. First, every scenario is specific — concrete values, concrete actions, concrete outcomes. Second, no developer vocabulary appears anywhere — no APIs, no databases, no HTTP codes. Third, the document is simultaneously a specification (a stakeholder can read it) and a test (Cucumber can execute it against the running system).

Why It Works

The Given–When–Then structure does something subtle: it forces the writer to separate state from action from outcome. This separation is exactly the muscle that vague acceptance writing fails to develop. Compare:

• "User can reset password." — A statement of capability, but no scenario.
• "User clicks reset link and gets to set new password if the link is fresh." — A scenario, but state and outcome are tangled.
• "Given a registered user has requested a password reset, when they click the reset link within one hour, then they can set a new password." — State, action, outcome separated. Each can be inspected, varied, and re-used.

The structure also encourages declarative rather than imperative writing. Good Gherkin says “the user resets their password”, not “the user clicks the username field, types 'foo', tabs to the password field…” The implementation detail belongs in step definitions and the UI, not in the spec.

Common Failure Modes

• UI-centric scenarios. When Gherkin reads like a click-by-click manual test script, it has lost its abstraction. Pull the language back to what the user is trying to do, not how they do it.
• Developer vocabulary leaking in. "Then the API returns a 200" is not a behavior the business cares about. The leak signals that the scenario was written by developers for developers — which is fine, but then it's a unit test in costume, not a behavior spec.
• Endless Givens. Long setup chains usually mean the scenario is doing too much. Split it, or push shared state into a Background.
• Conjunction-heavy Thens. A scenario that asserts six things in its Then is verifying multiple behaviors. One scenario, one outcome.
• Gherkin as documentation only. If no one ever executes the scenarios, they drift. Either automate them or stop pretending they are tests — call them specifications and accept the maintenance cost.

Gherkin Without Cucumber

Gherkin is most powerful when wired to an execution framework — Cucumber, SpecFlow, Behat, Behave. But many teams use the syntax purely for refinement and acceptance writing, without automating it. That is fine. The discipline of Given–When–Then sharpens the conversation even when nothing executes against it. Teams that later choose to automate find that the up-front investment in clean scenarios pays back quickly.

Coaching Tips

Write the first scenario together.

Whole team in a room, one screen, one scenario. The pattern transfers faster from collaboration than from a template.

Keep Thens singular.

One observable outcome per scenario. Use Scenario Outlines for variations, not nested conjunctions.

Use business vocabulary.

"Customer applies a coupon" is good Gherkin; "User submits POST to /coupons" is not. The first scales; the second rots.

Move shared setup to Background.

Repeated Givens are a smell. Background blocks DRY up the file and make the unique parts of each scenario stand out.

Treat scenarios as living docs.

If they aren't read or executed, they rot. Either keep them in front of the team or stop maintaining them.

Don't Gherkinize everything.

Some behaviors don't benefit. Unit tests, internal algorithms, and low-level integration cases are usually clearer in their native test language.

Summary

Gherkin is a small syntax with an outsized effect on shared understanding. By forcing the separation of state, action, and outcome, it makes ambiguity surface during refinement rather than during implementation. Whether or not the scenarios end up automated, the discipline of writing them gives a team a common, executable-looking language for the most important conversation it has: what does success look like, concretely, in this case?

Back to Story Crafting