The three parts
Every Given/When/Then scenario is a small contract. It describes a piece of behaviour in three moves, each answering a different question.
- Given — the starting context. What is true before anything happens?
- When — the trigger. What action or event occurs?
- Then — the observable outcome. What must be true afterwards?
Written well, a scenario is unambiguous, executable, and self-documenting. Written badly, it's prose in disguise.
A concrete example
Scenario: Applying a discount code at checkout
Given a shopper has a cart totalling $80
And the discount code "SPRING10" is active
When the shopper applies "SPRING10" at checkout
Then the cart total is $72
And the discount line reads "SPRING10 — 10% off"Notice what this scenario doesn't do: it doesn't describe the UI, the database schema, or the implementation. It describes behaviour. That's the point — the same scenario can drive an API test, a UI test, and a conversation with a product manager.
Common mistakes
1. Writing implementation, not behaviour
Bad: When the shopper clicks the button with id="apply-discount". Good scenarios describe intent, not clicks.
2. Using vague words
Bad: Then the total is updated correctly. "Correctly" is not verifiable. Pick a number.
3. Chaining unrelated behaviours
One scenario, one behaviour. If your Then has five bullets covering unrelated outcomes, split it.
4. Depending on hidden state
If Given doesn't set up everything the scenario relies on, the test will pass by accident and fail mysteriously later.
Given / When / Then for AI coding agents
AI coding agents love this format. Every part maps cleanly onto code: the Given becomes setup fixtures, the When becomes the call under test, the Then becomes the assertion. Feed an agent a Gherkin scenario and it can produce the implementation, the test, and the assertion in one pass — with far less drift than a natural-language prompt.
Writing your first scenario
Start from a behaviour someone actually cares about, then work through four passes:
- Name the outcome first. Write the
Thenbefore anything else — if you can't state a verifiable result, the behaviour isn't defined yet. - Work backwards to the trigger. One
When, one action. If you need two, you have two scenarios. - List only the context the outcome depends on. Everything in
Givenshould be load-bearing; delete anything the assertion doesn't rely on. - Then break it. Copy the scenario and change one thing — an expired code, an empty cart, a missing permission. The variants are where the real requirements hide.
Executable turns product intent into structured Given/When/Then scenarios and flags the variants you haven't covered yet — part of a spec-driven development workflow.