You do not need to write code to write Gherkin. You need to be able to describe a situation, an action, and an expected result, which is exactly what you already do every time you explain a bug to a developer.
This guide is for product managers who have never opened a test file. Twelve complete examples, a gallery of vague criteria rewritten as scenarios, an honest section on when the format is overkill, and why Given/When/Then turned out to be the best way to brief an AI coding agent.
What acceptance criteria actually are
Acceptance criteria are the specific, testable conditions a feature must meet before it counts as done. They sit underneath a user story and answer one question: how will we know this works?
The story says what and why. "As a customer, I want to reset my password so I can regain access." The criteria pin down what you would actually observe. A reset link expires after 60 minutes. An unknown email shows the same confirmation message as a known one.
Without them, "done" becomes a negotiation that happens after the code is written, usually in a tense review call where everyone remembers the requirements slightly differently. With them, done is a checklist agreed before anyone builds anything.
Every team knows the failure mode. A ticket says "user can log in." A developer builds the happy path. QA discovers that nobody ever decided what happens after five wrong passwords. Acceptance criteria exist to force those decisions early, while they are still cheap.
If you are still working on the story layer above the criteria, start with writing user stories that pass INVEST. Criteria refine stories, they do not replace them.
Gherkin in five minutes
Gherkin is a plain-language format for writing acceptance criteria as concrete scenarios. Three keywords do all the work: Given the starting situation, When the action someone takes, Then the observable result.
It comes from Behaviour-Driven Development, a practice introduced by Dan North in the mid-2000s to get developers, testers, and business people describing behaviour in one shared language. Gherkin is the syntax that BDD tools like Cucumber can read.
Here is the part most PMs miss: you do not need Cucumber, or automation, or any tooling at all. A Gherkin scenario written in a Notion doc is still clearer than a bullet saying "handles errors gracefully." The value is that the format forces you to name a concrete situation instead of a vague quality.
The anatomy, once:
Scenario: A returning customer logs in
Given a registered user with a verified email
When they enter their correct email and password
Then they land on their dashboard
That is genuinely it. A few extras you will run into:
- Feature: a one-line header grouping related scenarios, like
Feature: Password reset - And / But: continue the previous keyword so you are not writing "Given... Given..."
- Scenario Outline: one template run against a table of values, covered below
Translation for the jargon-averse. Given means start here. When means someone does this. Then means you should see this. If you can fill in those three blanks, you can write Gherkin.
Twelve complete examples
The fastest way to learn this is to read a stack of examples from features you have actually shipped. Notice the pattern as you go: every scenario names a concrete starting state, one action, and a checkable outcome.
Notice what is missing too. No implementation detail ("clicks the blue button rendered by AuthModal"). No vague qualities ("quickly," "intuitively"). No compound actions. One situation, one action, one result, and that discipline is the entire trick.
Each example comes with a plain-English translation, because the real test of a scenario is whether a stakeholder who has never heard the word Gherkin can read it aloud and nod.
Authentication
1. Successful login
Given a registered user with a verified email
When they submit the correct email and password
Then they are taken to their dashboard
And a session is created that lasts 30 days
In plain English: a real user with the right credentials gets in, and stays logged in for a month.
2. Account lockout
Given a registered user
When they enter the wrong password 5 times within 15 minutes
Then their account is locked for 30 minutes
And they receive an email with an unlock link
In plain English: five strikes in a quarter of an hour and you are benched for half an hour, but we email you a way back in.
3. Password reset for an unknown email
Given an email address with no account
When someone requests a password reset for it
Then the same "check your inbox" confirmation is shown
But no email is sent
In plain English: we never reveal whether an email has an account, because that would let attackers fish for valid addresses.
Payments
4. Successful upgrade
Given a user on the free plan with a valid card on file
When they upgrade to the Pro plan
Then they are charged the prorated amount for the current period
And Pro features unlock within 10 seconds
In plain English: upgrading mid-cycle charges only the remaining days, and access is near-instant.
5. Declined card
Given a user upgrading to Pro
When their card is declined by the payment provider
Then they see the provider's decline reason in plain language
And their plan remains unchanged
And no partial charge appears on their statement
In plain English: a failed payment changes nothing and explains itself. No mystery charges, no half-upgraded accounts.
6. Cancellation timing
Given a Pro subscriber 10 days into a monthly billing cycle
When they cancel their subscription
Then Pro access continues until the end of the paid period
And no further charges occur
In plain English: cancelling does not punish you. You keep what you paid for, then it stops.
Search
7. Zero results
Given a product catalog that contains no items matching "xylophone"
When a shopper searches for "xylophone"
Then an empty state is shown with 3 suggested popular categories
And the search term is logged for the merchandising team
In plain English: a dead-end search offers a next step instead of a blank page, and we learn something from it.
8. Filter persistence
Given a shopper who filtered results to "under $50" and "in stock"
When they open a product and navigate back to results
Then both filters are still applied
In plain English: going back does not wipe your filters. Every PM has been burned by this one.
Notifications
9. Quiet hours
Given a user with quiet hours set from 22:00 to 07:00 in their timezone
When a non-critical notification is triggered at 23:30 their time
Then the push notification is held until 07:00
But it appears immediately in the in-app inbox
In plain English: nothing buzzes your phone at night, but the message is not lost, it is waiting in-app.
10. Digest batching
Given a user who received 12 comment notifications in one hour
When the hourly digest job runs
Then they receive a single email summarizing all 12 comments
And no individual comment emails are sent
In plain English: twelve events become one email, not twelve.
Edge cases and permissions
11. Concurrent edits
Given two teammates editing the same project brief
When the second teammate saves after the first
Then the second teammate sees a conflict warning with both versions
And neither save silently overwrites the other
In plain English: silent data loss is not acceptable. Conflicts get surfaced, not swallowed.
12. Role downgrade mid-session
Given an admin who is logged in with an active session
When an owner changes their role to viewer
Then their next action requiring admin rights is blocked
And they see a message explaining their role changed
In plain English: permission changes take effect on the next action, not whenever the user happens to log out.
Picture an agency lead specifying a client portal. Handing a developer examples 11 and 12 settles two arguments that would otherwise surface in week three, phrased as "wait, what should happen if..."
Scenario outlines: one template, many cases
A scenario outline is a scenario written once as a template, then run against a table of values. It is the right tool for rules that vary by input rather than by flow.
Instead of five nearly identical scenarios for password validation, you write one with placeholders in angle brackets and an Examples table listing each case.
This matters for PMs because boundary values are where features quietly break. The zero-item cart. The 100-character name. The discount code applied twice. Outlines force you to enumerate those boundaries in a table, which is much harder to fudge than a bullet saying "validates input properly."
One honest caveat: outlines are the most syntax-looking part of Gherkin. Save them for genuinely tabular rules, like pricing tiers, validation limits, and plan entitlements. Use plain scenarios everywhere else.
Scenario Outline: Discount code validation
Given a cart totaling <cart_total>
When the shopper applies the code "<code>"
Then the discount applied is <result>
Examples:
| cart_total | code | result |
| $80 | SAVE10 | $8 off |
| $15 | SAVE10 | error: $20 minimum not met |
| $80 | EXPIRED1 | error: code expired |
| $80 | SAVE10 (used twice) | error: already redeemed |
In plain English: one table now settles four support tickets before they exist.
The rewrite gallery
The most common failure is not missing criteria. It is criteria that feel complete but cannot be checked. "Handles errors gracefully." "Search is fast." "Works on mobile."
Each one smuggles in a judgment call that gets made later, by whoever is most tired at review time.
The fix is always the same move: ask what you would actually observe, then name one concrete situation where the quality shows up. Notice that every rewrite below is narrower than the original. That is the point. Three narrow, checkable scenarios beat one broad sentence, because narrow scenarios can fail, and criteria that cannot fail cannot protect you.
Bad: "Handles payment errors gracefully."
Given a shopper at checkout
When the payment provider times out after 30 seconds
Then the order is not created
And the shopper sees a retry option with their cart intact
Bad: "Search should be fast."
Given a catalog of 50,000 products
When a shopper searches for any term
Then first results render within 800ms at the 95th percentile
Bad: "Users can manage their team."
Given a workspace owner with 3 team members
When they remove a member
Then that member loses access within 60 seconds
And the member receives a removal notification email
And the workspace seat count decreases by 1
Bad: "The form validates input."
Given a signup form
When a user submits an email without an "@" symbol
Then an inline error appears under the email field
And the form is not submitted
And previously entered fields keep their values
The pattern in all four: a number, a timeframe, or a named state replaced an adjective.
When Gherkin is overkill
Gherkin is the wrong tool more often than BDD enthusiasts admit.
It earns its structure on behavioural logic with branches and edge cases. It wastes everyone's time on visual polish, copy tweaks, exploratory prototypes, and one-line content changes. "Given a user on the pricing page, When the page loads, Then the headline says Plans" is ceremony, not clarity. A screenshot in the ticket does that job better.
The heuristic I would use: reach for Gherkin when the answer to "what should happen?" depends on state. When you find yourself saying "well, if they're on the free plan, but if their trial expired..." that is the signal. Skip it when the answer is one sentence or a design file.
Reaching for scenarios on a two-day prototype is process theatre. Skipping them on a billing flow is a future incident report.
Skip Gherkin for:
- Pure UI polish. Spacing, colours, animation timing. Point at the Figma.
- Copy changes. The criterion is the copy.
- Spikes and prototypes. You are learning, not specifying.
- One-condition features. "The export button downloads a CSV" needs no Given.
Use it without apology for auth, payments, permissions, notifications, data mutations, anything with a state machine hiding inside it, and anything you are about to hand to an AI agent.
Handing Gherkin to AI coding agents
Given/When/Then has found a second life as the most machine-checkable format for briefing AI coding agents, and the reason is structural. Each scenario is a precondition, an action, and an assertion, which is the exact anatomy of an automated test.
When a founder prompts an agent with "build login, make it secure," the agent fills every gap with a guess. When they paste scenarios 1 to 3 from this post, the agent knows the lockout threshold is five attempts, the window is 15 minutes, and unknown emails must not leak account existence.
The bigger payoff arrives at review time. Instead of the unfixable bug report "it doesn't work," you point at a failing scenario: "scenario 3 fails, the unknown-email path returns a different message." That turns reviewing AI output from a vibes exercise into a pass/fail checklist a non-technical founder can actually run.
Three practices that make it work:
- Number your scenarios. "Scenario 5 fails" is a better prompt than a paragraph of description.
- Ask the agent to restate scenarios as tests before it writes code. Cucumber's docs call this working with executable specifications. With an agent you get the same effect without installing anything.
- Put the edge cases first. Agents nail happy paths unprompted. Your scenarios earn their keep on lockouts, declines, and conflicts.
For more on this, what LLMs skip in acceptance criteria covers the categories models omit by default and how to prompt around them.
The pre-handoff checklist
Run every scenario set through this before it reaches a developer or an agent.
- Each scenario has exactly one When, meaning one action per scenario
- Every Then is observable: a number, a message, a state change, not an adjective
- The unhappy paths outnumber the happy path, as they do in production
- No implementation details, describing behaviour rather than buttons and components
- Boundary values live in a scenario outline table, not in prose
- A stakeholder outside the team could read each scenario aloud without stumbling
- Scenarios are numbered, so failures can be named
- Anything that is really a design decision points at the design file instead
FAQ
What is Gherkin in simple terms?
A plain-language format for writing acceptance criteria as concrete scenarios, using three keywords: Given for the starting situation, When for the action, Then for the expected result. It reads like structured English, requires no coding, and originated as the syntax for BDD tools like Cucumber, though it is useful in any document.
Do I need Cucumber or any tools to use Gherkin?
No. Cucumber turns Gherkin into automated tests, but the format's main value for PMs is communication: forcing vague requirements into concrete situation, action, and result statements. Scenarios written in Notion, Linear, or a Google Doc deliver most of the benefit with zero tooling.
What is the difference between BDD and Gherkin?
BDD is the practice, teams collaborating on concrete examples of behaviour before building. Gherkin is the notation those teams usually write the examples in. You can borrow the notation without adopting the full practice, and plenty of people do.
How many scenarios should one user story have?
Usually three to eight. One happy path, then the failures and edge cases that actually matter: invalid input, permission boundaries, timing conflicts, empty states. If you are past ten, the story is probably too big and wants splitting.
What is the difference between acceptance criteria and user stories?
A story describes who wants what and why. Criteria define the testable conditions proving it works. Stories set direction; criteria define done.
Can Gherkin scenarios replace a PRD?
No, they complement one. A PRD covers context, goals, scope, and trade-offs. Gherkin covers per-feature behaviour. The strongest specs pair a short PRD with numbered scenarios per story, so strategy and testable detail live together without blurring into each other.
Why is Gherkin good for AI coding agents?
Each scenario maps onto an automated test: precondition, action, assertion. That gives the agent unambiguous targets and gives you a pass/fail review checklist. "Scenario 3 fails" is actionable. "It doesn't work" is not.
What is a scenario outline?
A scenario written once as a template with placeholders, then run against an Examples table of values. Use it for tabular rules like validation limits, pricing tiers, and discount logic, where the flow stays identical and only inputs and outcomes change.
If writing the first draft is the blocker, the Acceptance Criteria Generator turns a plain-English feature description into Given/When/Then scenarios you can edit. Free, no signup, and the pre-handoff checklist above still applies.
