It is Wednesday refinement. The story on the screen says “As a customer, I want to reset my password so that I can get back into my account”, and under it sit nineteen lines of Given, When and Then. Line 4 says “When I click the blue Forgot password link”.
Line 11 says “Then I see a green toast in the top right corner”. The designer mentions that the link is moving into a menu next sprint. Nobody says anything, but everyone in the room knows that nineteen lines just became wrong, and that the one rule that matters, how long the reset link stays valid, is not written anywhere.
That scene repeats in teams that adopted Gherkin because it looked rigorous. The format is fine. The habit of writing it like a test script is what fails. Below is a template that survives UI changes and refinement, two full examples, a way to count scenarios, and the checklist interviewers use when they ask a product candidate to write acceptance criteria on a whiteboard.
Why most Gherkin acceptance criteria break in the first sprint
Gherkin is the plain text language behind Cucumber and related tools such as Reqnroll (the community successor to SpecFlow), Behave for Python and Behat for PHP. The Given, When, Then shape comes from the behaviour driven development work of Dan North and Chris Matts in the mid 2000s; North’s essay “Introducing BDD” from 2006 is the usual reference. The idea was simple: describe a behaviour as a precondition, an event and an outcome, in words the business would use.
What goes wrong is the level of description. There are two ways to write the same scenario. The imperative style lists actions on a screen: fill in this field, click that button, see this message. The declarative style states the behaviour: a registered customer requests a reset, the system sends one link valid for 30 minutes. The imperative version has more lines, looks more precise and breaks every time the interface changes. The declarative version is shorter and stays true until the business rule changes.
The second failure is mixing several behaviours into one scenario. A scenario that tests the reset email, the link expiry and the password strength rules at once fails for three different reasons and tells you nothing about which one broke. One scenario, one behaviour, one reason to fail.
The third failure is subtler. Teams write scenarios before they agree on rules. You can recognise this when a scenario has a Then that someone in refinement disputes. Gherkin turns the dispute into text but does not resolve it; that has to happen in conversation, before the first Given is written.
The template, line by line
Here is the template we recommend. Copy it, keep the structure, and replace the bracketed descriptions with your own words.
Feature: <capability, in business words>
<one or two lines: who benefits and why>
Rule: <one business rule, stated as a sentence>
Background:
Given <state shared by every scenario under this rule>
Scenario: <the behaviour, in under ten words>
Given <the specific context for this case>
When <one event: what the user or system does>
Then <the observable outcome>
And <a second outcome, only if it belongs to the same behaviour>
Scenario Outline: <the behaviour across several values>
Given <context with a <parameter>>
When <event>
Then <outcome with <result>>
Examples:
| parameter | result |
| value 1 | out 1 |
| value 2 | out 2 |
Each keyword has a job. Feature names the capability, not the screen. Rule, added to Gherkin in version 6 in 2018, groups the scenarios that illustrate one business rule. It is the most useful keyword that teams skip, because it forces you to write the rule in a sentence.
Background holds the Given steps every scenario under that rule shares, which keeps each scenario short. Scenario is one example of the rule in action. Scenario Outline with an Examples table covers boundaries without copying the same scenario five times.
Inside a scenario, keep exactly one When. Two Whens usually mean two behaviours. Use And and But only to extend a Given or a Then, never to chain more events. Write every step in the third person or as “the customer”, so the scenario reads the same whoever runs it.
On a whiteboard in an interview you do not need the indentation. You do need the Rule line and a single When per scenario. Those two details are what separate a candidate who has used the format from one who has read about it.
Two more template habits save time later. Put data that matters into the step itself, as in “a cart of 60 euros”, instead of hiding it in a fixture called “standard cart”. A reader should see every value the outcome depends on.
And keep tables small: an Examples table with more than 6 to 8 rows usually means the scenario is covering two rules at once, or that a lookup table belongs in a separate specification document referenced from the story. Gherkin also supports doc strings, a block of text between three double quotes, for cases such as an email body that must contain certain words. Use them sparingly, because a long doc string pulls the reader back into implementation detail.
A full example: password reset
Back to the story from the refinement scene. The team agreed three rules in conversation: a reset link is valid for 30 minutes, it works once, and requests are limited to 3 per hour per account. Written with the template:
Feature: Password reset by email
Customers who forget their password can set a new one without contacting support.
Rule: A reset link is valid for 30 minutes after it is sent
Background:
Given a registered customer with the email ana@example.com
Scenario: Link used within the time limit
Given the customer requested a reset link 10 minutes ago
When the customer opens the link and sets a valid new password
Then the new password works for the next sign in
And the old password no longer works
Scenario Outline: Link age decides whether it still works
Given the customer requested a reset link <age> minutes ago
When the customer opens the link
Then the customer <outcome>
Examples:
| age | outcome |
| 29 | can set a new password |
| 30 | can set a new password |
| 31 | is asked to request a new link |
Rule: A reset link works only once
Scenario: Link reused after a successful reset
Given the customer already set a new password with a reset link
When the customer opens the same link again
Then the customer is asked to request a new link
Rule: No more than 3 reset requests per account per hour
Scenario: Fourth request within an hour
Given the customer requested 3 reset links in the last 40 minutes
When the customer requests another link
Then no email is sent
And the customer is told when they can try again
Count what is missing: no colours, no button labels, no toast positions. The Examples table makes the boundary explicit. At 30 minutes exactly, does the link still work? The team had to decide, and the table is where that decision is recorded. Edge cases like this are where most production bugs in reset flows come from, and they cost one row each.
Also notice what is not here at all: password strength rules. They belong to a different rule, probably a different story, and putting them in this feature would turn one story into two without anyone noticing.
Three smaller choices in the example are worth copying. The Background holds only the registered customer, because every scenario under the first rule needs one and none of them needs anything else. The scenario titles describe the case, “Link used within the time limit”, rather than the expected result, so a failing test report reads like a sentence a product owner understands.
And the Then steps describe what the customer can observe or do next, such as being asked to request a new link, without naming the error text. The copy for that message will change at least once before launch; the behaviour should not.
The example also leaves something open on purpose. It says nothing about whether a customer who is already signed in can request a reset, or what happens to active sessions on other devices after the password changes. Both are real questions, and both deserve a red card in the next example mapping session. A set of acceptance criteria that admits its gaps is more useful than one that pretends to be complete. Engineers will find the gaps anyway, usually on the Thursday before the release.
From story to scenarios in seven steps
The writing is the last part. Most of the work happens before anyone types Given.
- Write the rules first, as plain sentences. For the reset story that was three sentences. If you cannot state a rule in one sentence, you have found an open question.
- Run a short example mapping session. The technique, described by Matt Wynne of the Cucumber team, uses four card colours: yellow for the story, blue for rules, green for examples, red for questions. Timebox it to about 25 minutes per story.
- Pick one green example per rule as the happy path. Write it as a declarative scenario.
- Find the boundaries. For every number in a rule (30 minutes, 3 requests), add the values just below, at and just above it. Put them in a Scenario Outline.
- Add the main failure for each rule. What happens when the rule is broken: expired link, reused link, too many requests.
- Read every step aloud to someone outside the team. If a support agent or a salesperson cannot follow it, the language is too technical.
- Check each scenario against the definition of one behaviour. One When, a Then that can fail for one reason, and a title under ten words.
Steps 1 and 2 are where the value is. Teams that skip them write fluent Gherkin about rules nobody agreed on, then argue about it in the sprint review.
How many scenarios a story needs, and when to split it
There is a useful arithmetic behind “enough scenarios”. Treat it as a rule of thumb that no standard defines. It still makes refinement conversations faster.
scenarios per rule = 1 happy path + boundary rows + 1 main failure
scenarios per story = sum of scenarios per rule over all rules
split the story if:
rules > 4
or scenarios per story > 12
or red question cards > 0 at sprint planning
Apply it to the reset story. Rule one: 1 happy path, 3 boundary rows in the outline, 1 failure, which is the 31 minute row and so already counted; call it 4. Rule two: 1 scenario. Rule three: 1 happy path plus 1 failure, so 2. Total 7 scenarios across 3 rules. That fits comfortably in one story.
Now imagine the product owner adds “reset by SMS” and “admin can force a reset” to the same story. That adds at least 2 rules and 5 to 6 scenarios, taking the count to 5 rules and 12 to 13 scenarios. The rule threshold trips, and the scenario count sits right on the line. The formula does not decide for you. It gives you a neutral reason to propose a split without a debate about anyone’s writing.
Large scenario counts also tend to predict stories that spill over a sprint, for a mechanical reason: each scenario is a test someone has to build, run and keep green. The count is a cheap early warning.
A checkout story that went wrong, and the rewrite
An illustrative case, composed from patterns common in e-commerce teams. A team writes acceptance criteria for “As a shopper, I want to use a discount code at checkout”. The first version looks like this:
Scenario: Apply discount
Given I am on the checkout page
And I have 2 items in my cart worth 80 euros
When I click on Have a code
And I type SAVE10 in the field
And I press Apply
Then I see the total change to 72 euros
And I see a green message saying Code applied
And the Apply button turns grey
It looks complete, and it hid three decisions. Does the 10 percent apply before or after shipping? Can two codes stack? What happens if the cart falls below the code’s minimum after the code is applied? The release shipped with stacking allowed by accident, and a weekend promotion lost about 1,800 euros in margin before support noticed customers combining two codes.
The rewrite started from rules, not clicks:
Feature: Discount codes at checkout
Rule: A percentage code applies to the item subtotal, not to shipping
Scenario: 10 percent code on an 80 euro subtotal with 5 euro shipping
Given a cart with an item subtotal of 80 euros and shipping of 5 euros
When the shopper applies a valid 10 percent code
Then the order total is 77 euros
Rule: Only one code can be active per order
Scenario: Second code replaces the first
Given a cart with a 10 percent code applied
When the shopper applies a second valid code
Then only the second code is active
And the shopper is told the first code was removed
Rule: A code with a minimum spend is removed if the subtotal drops below it
Scenario: Item removed after applying a code with a 50 euro minimum
Given a cart of 60 euros with a code that requires 50 euros
When the shopper removes an item worth 20 euros
Then the code is removed
And the shopper sees why
Three rules, four short scenarios, and all three hidden decisions are now on the page. The UI details went into the design file, where they belong.
Look at the arithmetic in the first scenario, because it is the kind of detail that the click version hid. Ten percent of an 80 euro subtotal is 8 euros, so the items cost 72 euros. Shipping stays at 5 euros, and the total is 77 euros. In the original script the total was 72 euros, which silently assumed either free shipping or a discount on shipping too. Two engineers read that line two different ways, and both implementations passed the test.
The rewrite is shorter than the original by line count, and it took longer to write. The team spent about 20 minutes in an example mapping session arguing about stacking before anyone typed a Given. That argument was the real deliverable. The marketing lead had assumed stacking was impossible; the developer had assumed it was a feature. Without the Rule keyword forcing a sentence, neither assumption would have been visible until a customer found the gap.
The rewrite also made testing cheaper. Four declarative scenarios automate with a handful of step definitions that call the pricing service directly, without driving a browser. The original eight step script needed the full checkout page to run, took about 40 seconds per execution in their pipeline and broke twice in a month when the design team renamed the button. Declarative steps let the team test the rule at the level where it actually lives.
The checklist, the interview version, and where this is going
Run this checklist over any set of Gherkin acceptance criteria before refinement ends:
- Every scenario sits under a Rule written as one sentence.
- Each scenario has exactly one When.
- No step names a button, colour, field label or screen position.
- Every number in a rule has boundary examples, ideally in an outline.
- Each rule has its main failure case.
- A person outside the team can read the steps aloud and follow them.
- The scenario count fits the split rule, or the team has agreed to split.
- No open questions remain on the story at sprint planning.
In a product manager or business analyst interview, the prompt is usually “write acceptance criteria for X” with five to ten minutes on a whiteboard. Spend the first two minutes stating the rules out loud and asking one clarifying question, for example about a time limit or a quantity limit.
Then write one happy path and one boundary for the most important rule, in declarative steps. Interviewers rarely want completeness. They want to see you find the rule the prompt left out, and write it in a form engineers and testers can use the same afternoon.
Where is this heading? Language models can now draft dozens of plausible Gherkin scenarios from a story title in seconds. That makes the volume problem worse, not better: teams will drown in scenarios nobody agreed on. The scarce skill moves upstream, to stating rules, finding boundaries and saying no to the fortieth scenario. Expect acceptance criteria reviews to look more like example mapping sessions with a generated draft on the table, and less like writing sessions.