You don't 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 walks through Gherkin acceptance criteria for product managers who have never touched a test file: what the format is, 12 complete Gherkin examples across real product domains, a gallery of vague criteria rewritten as scenarios, and why Given/When/Then has quietly become the best format for briefing AI coding agents.
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?" A user story says what and why ("As a customer, I want to reset my password so I can regain access"); acceptance criteria pin down the observable behavior ("a reset link expires after 60 minutes; an unknown email shows the same confirmation message as a known one"). Without them, "done" is a negotiation that happens after the code is written — usually in a tense review call. With them, done is a checklist agreed before anyone builds anything. Gherkin is simply a structured way of writing those criteria as concrete scenarios rather than abstract rules.
The failure mode most teams know well: a ticket says "user can log in," a developer builds the happy path, and QA discovers nobody decided what happens after five wrong passwords. Acceptance criteria exist to force those decisions early, when they're cheap.
If you're still working on the story layer above the criteria, start with how to write user stories that pass the INVEST test — criteria refine stories, they don't replace them.
Gherkin in 5 Minutes, in Plain English
Gherkin is a plain-language format for writing acceptance criteria as concrete scenarios, using three keywords: Given (the starting situation), When (the action someone takes), and Then (the observable result). It comes from Behavior-Driven Development (BDD) — a practice introduced by Dan North in the mid-2000s to get developers, testers, and business people describing behavior in one shared language. Gherkin is the syntax that BDD tools like Cucumber read, but here's the part PMs miss: you don't need Cucumber, automation, or any tooling to benefit. A Gherkin scenario written in a Notion doc is still clearer than a bullet that says "handles errors gracefully." The format's value is that it 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's it. A few extras you'll see:
- Feature: a one-line header grouping related scenarios (e.g.
Feature: Password reset) - And / But: continue the previous keyword so you don't write "Given... Given..."
- Scenario Outline: one scenario template run against a table of values (covered below)
Translation guide for the jargon-averse: Given = "start here," When = "someone does this," Then = "you should see this." If you can fill in those three blanks, you can write Gherkin.
12 Complete Gherkin Examples, Across Real Product Domains
The fastest way to learn Gherkin is to read a stack of complete examples from features you've actually shipped — auth, payments, search, notifications — and notice the pattern: every scenario names a concrete starting state, a single action, and a checkable outcome. The examples below are copy-adaptable; swap the nouns for your product. Each comes with a plain-English translation, because the test of a good scenario is that a stakeholder who has never heard the word "Gherkin" can read it aloud and nod. Notice what's absent 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 — that discipline is the entire trick.
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
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
Plain English: five strikes in a quarter-hour and you're benched for 30 minutes — 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
Plain English: we never reveal whether an email has an account — 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
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
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
Plain English: cancelling doesn't 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
Plain English: a dead-end search offers a next step instead of a blank page, and we learn 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
Plain English: going back doesn't 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
Plain English: nothing buzzes your phone at night, but the message isn't lost — it's 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
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
Plain English: last-write-wins data loss is not acceptable; conflicts are 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
Plain English: permission changes take effect on the next action — no waiting for the user to log out.
Picture an agency lead specing a client portal: handing a developer examples 11 and 12 settles two arguments that would otherwise surface in week three of the build, phrased as "wait, what should happen if...?"
Scenario Outlines: One Template, Many Cases
A scenario outline is a Gherkin scenario written once as a template, then run against a table of values — the tool for rules that vary by input rather than by flow. Instead of writing 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 0-item cart, the 100-character name, the discount code applied twice. Outlines make you enumerate those boundaries in a table, which is far harder to fudge than a bullet saying "validates input properly." One honest caveat: outlines are the most "syntax-looking" part of Gherkin, so save them for genuinely tabular rules — pricing tiers, validation limits, plan entitlements — and 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 |
Plain English: one table now settles four support tickets before they exist.
Bad Criteria → Gherkin Rewrite Gallery
The most common acceptance criteria failures aren't missing criteria — they're criteria that feel complete but can't 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 rewrite move is always the same: ask "what would I actually observe?" and name one concrete situation where the quality shows up. Below, four real-world offenders and their Gherkin rewrites. Notice that every rewrite is narrower than the original — that's the point. Three narrow, checkable scenarios beat one broad, unfalsifiable sentence, because narrow scenarios can fail, and criteria that can't fail can't 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 every rewrite: a number, a timeframe, or a named state replaced an adjective.
When Gherkin Is Overkill (An Honest Section)
Gherkin is the wrong tool more often than BDD enthusiasts admit: it earns its structure for behavioral logic with branches and edge cases, and 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 honest heuristic: use Gherkin when the answer to "what should happen?" depends on state ("well, if they're on the free plan... but if their trial expired...") and skip it when the answer is a single sentence or a design file. Reaching for scenarios on a two-day prototype signals process theater; skipping them on a billing flow signals a future incident report.
Skip Gherkin for:
- Pure UI polish — spacing, colors, animation timing. Point at the Figma.
- Copy changes — the criterion is the copy.
- Spikes and prototypes — you're 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're about to hand to an AI agent — which brings us to the interesting part.
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, because each scenario is a precondition, an action, and an assertion — 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 guesses; when they paste scenarios 1–3 from this post, the agent knows the lockout threshold is 5 attempts, the window is 15 minutes, and unknown emails must not leak account existence. The deeper payoff comes 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 AI output review from vibes into a pass/fail checklist a non-technical founder can actually run.
Three practices that make this 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 coding. Cucumber's docs describe this workflow as executable specifications — with an AI agent, you get the same effect without installing anything.
- Put edge-case scenarios first. Agents nail happy paths unprompted; your scenarios earn their keep on lockouts, declines, and conflicts.
For a deeper look at this workflow — including how criteria quality changes what AI agents produce — see AI-generated acceptance criteria: what works and what doesn't and generating user stories from a single prompt. If writing the first draft is the blocker, VibeMap's free Acceptance Criteria Generator turns a plain-English feature description into Given/When/Then scenarios you can edit — no signup required.
The Pre-Handoff Checklist
Run every scenario set through this before it reaches a developer or an AI agent:
- Each scenario has exactly one When — 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 (they do in production, too)
- No implementation details — describe behavior, not 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's really a design decision points at the design file instead
FAQ
What is Gherkin in simple terms?
Gherkin is a plain-language format for writing acceptance criteria as concrete scenarios using three keywords: Given (the starting situation), When (the action), Then (the expected result). It reads like structured English, requires no coding, and originated as the syntax for BDD tools like Cucumber — but it's useful in any doc.
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-result statements. Scenarios written in Notion, Linear, or a Google Doc deliver most of the benefit with zero tooling.
What's the difference between BDD and Gherkin?
BDD (Behavior-Driven Development) is the practice: teams collaborating on concrete examples of behavior before building, as described in Dan North's original essay. Gherkin is the notation BDD teams typically use to write those examples. You can borrow the notation without adopting the full practice.
How many scenarios should one user story have?
Typically three to eight. One happy path, then the failure and edge cases that matter: invalid input, permission boundaries, timing conflicts, empty states. If you're past ten, the story is probably too big and should be split — see the INVEST criteria for sizing stories.
What's the difference between acceptance criteria and user stories?
A user story describes who wants what and why ("As a subscriber, I want to cancel online"). Acceptance criteria define the testable conditions proving it works ("Given a subscriber mid-cycle, When they cancel, Then access continues until the period ends"). 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 behavior. The strongest specs pair a short PRD with numbered scenarios per story, so strategy and testable detail live in the same document without blurring together.
Why is Gherkin good for AI coding agents?
Each scenario maps directly onto an automated test: precondition, action, assertion. That gives an AI agent unambiguous targets and gives you a pass/fail review checklist. "Scenario 3 fails" is actionable feedback; "it doesn't work" is not. It's the most machine-checkable format a non-technical founder can write.
What's a scenario outline?
A scenario outline is a Gherkin scenario written once as a template with placeholders, then run against an Examples table of values. Use it for tabular rules — validation limits, pricing tiers, discount logic — where the flow stays identical and only inputs and outcomes change across rows.
Want the full workflow, not just the criteria layer? The free VibeMap Spec Kit covers stories, criteria, and specs end to end — and the free Acceptance Criteria Generator (no signup) drafts your first Given/When/Then set from a sentence. The User Story Generator now outputs acceptance criteria alongside every story, so both halves of your spec arrive together.
