Acceptance Criteria Examples in Gherkin and Plain Language

Story / behavior:
[What user behavior is being delivered?]

Confirmed rules:
- [Rule that is already decided]
- [Source / owner when the rule is important]

Acceptance criteria:
1. [Observable condition that traces to confirmed behavior]
2. [...]

Open questions:
- [Permission, validation, failure, state, limit, or policy that still needs a decision]

Out of scope:
- [Nearby behavior deliberately excluded]

Optional Gherkin:
Scenario: [behavior]
  Given [confirmed starting state]
  When [action / event]
  Then [observable confirmed outcome]

Acceptance criteria define the observable conditions that must be true for a specific behavior to be accepted. They should clarify confirmed product scope, not invent permissions, validation rules, error states, limits, performance thresholds, or business policy just because those details sound plausible.

Gherkin acceptance criteria express that same confirmed behavior as concrete scenarios: Given describes confirmed starting context, When describes one action or event, Then describes the observable outcome. And and But continue the step above them. Gherkin is a readable scenario format, not a different kind of truth.

Use plain language when the condition is already concise and the starting state is obvious. Use Gherkin when the starting state changes the expected result, when one event triggers behavior worth walking through out loud, or when separate scenarios make branching easier to challenge. Both forms must pass the same two gates used on this page: confirmed first, observable second.

How to use this page: the saved-search story below shows the same confirmed behavior in plain and Gherkin forms with open questions parked separately. Copy-ready formats are in Acceptance criteria template. Gherkin quality checks are in What good acceptance criteria look like and What belongs here, and what does not.

A useful workflow is:

confirmed product behavior → acceptance criteria → test coverage

If the behavior is not confirmed yet, stop one step earlier:

unresolved rule → open question → product decision → acceptance criterion

That distinction is the core of this guide.

Acceptance criteria example: saved search

The example below is hypothetical. The important part is not the feature; it is how confirmed rules are separated from unanswered questions.

User story

As a recruiter who repeatedly reviews the same candidate criteria, I want to save my current search so I can reopen it without rebuilding the filters.

Confirmed rules for this example

Assume the team has already decided that:

• a recruiter can save a search that is valid under the product's existing search rules;
• the selected filter values are part of the saved search;
• the recruiter can reopen that saved search later.

Nothing else is assumed.

Acceptance criteria

1. When the recruiter saves a search that satisfies the existing valid-search rules, the selected filter values are stored with that saved search.
2. The recruiter can reopen the saved search later.
3. When the recruiter reopens the saved search, the filter values stored with that search are applied.

These conditions can be accepted or rejected by observing behavior. They trace to rules the example explicitly declared as confirmed.

Same confirmed behavior in Gherkin

The three plain conditions become two focused scenarios. One scenario covers one behavior, so saving and reopening stay separate even though they share the same story:

Scenario: Save a valid search with its filters
  Given a recruiter has a valid search with selected filter values
  When the recruiter saves that search
  Then the selected filter values are stored with that saved search
  And the saved search can be reopened later

Scenario: Reopen a saved search
  Given a recruiter has a saved search with confirmed filter values
  When the recruiter reopens that saved search
  Then those saved filter values are applied

Given states confirmed context only. When holds the single action. Then and And state observable outcomes. If a line needs an unconfirmed limit, role, validation detail, or failure behavior to sound complete, that line is not ready. Park it under open questions below and keep the scenario to what the team has actually decided.

Background and Scenario Outline pattern in the same story

Use Background only for confirmed setup repeated in every scenario. It keeps shared context visible without repeating it, but every Background line must still pass the confirmed-first gate:

Background:
  Given a recruiter has a valid search with selected filter values

Scenario: Save the search
  When the recruiter saves that search
  Then the selected filter values are stored with that saved search

Scenario: Reopen the saved search
  Given the recruiter has saved that search
  When the recruiter reopens that saved search
  Then those saved filter values are applied

Keep Background short, ideally three or four lines. If scenarios need different starting states, do not force them under one Background. Split the scenarios or use higher-level wording that the team actually means.

Use Scenario Outline only when the same behavior is checked with different example values, not to bundle different behaviors. The values below are illustrative examples of the same confirmed save behavior, not new product rules:

Scenario Outline: Save searches with different illustrative filters
  Given a recruiter has a valid search using <filters>
  When the recruiter saves that search
  Then those filter values are stored with that saved search

  Examples:
    | filters                          |
    | location plus seniority          |
    | skills plus availability         |
    | location plus skills plus remote |

If the examples would need different outcomes, different permissions, or different triggers, write separate scenarios instead of adding columns. An outline that hides three behaviors in one table is harder to review than three short scenarios.

Open questions, not acceptance criteria yet

• Can the recruiter rename a saved search?
• Is there a maximum number of saved searches?
• Can saved searches be shared with teammates?
• Who can delete them?
• Does saving a search create notifications or alerts?
• What should happen if a previously saved filter is no longer available?

Those are reasonable questions. They are not requirements until someone with the relevant product or policy authority answers them. Thoroughness does not justify making up the answers.

The CraftUp rule: confirmed first, observable second

A strong acceptance criterion passes two gates.

Gate 1, Is the behavior confirmed?

Trace the line to something real:

• an agreed PRD requirement;
• a product decision;
• an existing business rule;
• a policy or compliance requirement;
• a confirmed product constraint;
• an approved interaction behavior;
• another source of truth the team actually uses.

If you cannot identify the rule or decision behind a meaningful assertion, write a question instead of a criterion.

Gate 2, Can someone observe whether it is true?

A criterion should let Product, Design, Engineering, or QA determine whether the behavior is acceptable without needing to inspect hidden implementation details.

Weak:

The feature should work correctly.

Weak:

Saving should be intuitive.

Weak unless a threshold has already been decided:

The search must respond within two seconds.

Stronger when the underlying behavior is confirmed:

When the recruiter reopens a saved search, the filter values stored with that search are applied.

The wording did not create the requirement. It made an existing decision observable.

Apply both gates to a Gherkin scenario

Use the saved-search scenarios to run the check line by line.

Gate 1 on Gherkin: every Given must trace to the confirmed rules for the example. Given a recruiter has a valid search with selected filter values passes because valid-search handling and filter storage were declared confirmed. Given the recruiter has at most 10 saved searches fails Gate 1 because no limit was decided. Keep that limit as an open question, not as a Given.

Gate 2 on Gherkin: every Then must be checkable without opening the implementation. Then those saved filter values are applied passes because a reviewer can reopen the search and see the filters. Then the save feels instant fails Gate 2 because no one can agree on pass or fail. Replace it with confirmed observable behavior, or park the performance expectation as an open question until a threshold and test condition are decided.

Acceptance criteria template

Use the smallest artifact that keeps product truth visible.

Plain-language template

Story / behavior:
[What user behavior is being delivered?]

Confirmed rules:
- [Rule that is already decided]
- [Source / owner when the rule is important]

Acceptance criteria:
1. [Observable condition that traces to confirmed behavior]
2. [...]

Open questions:
- [Permission, validation, failure, state, limit, or policy that still needs a decision]

Out of scope:
- [Nearby behavior deliberately excluded]

You do not need every section for trivial work. The separation matters most when the team is at risk of quietly promoting assumptions into scope.

Given / When / Then template

Scenario: [behavior being clarified]
  Given [confirmed starting state]
  When [one action or event]
  Then [observable confirmed outcome]
  And [another observable outcome of the same behavior]

Add another scenario when a different confirmed starting state, trigger, or outcome materially changes the behavior. Do not add scenarios simply to make the specification look comprehensive.

Use this keyword guide when you copy the template:

Do:

• Keep one scenario to one behavior with one When plus its Then result.
• Write Then so Product, Design, Engineering, or QA can agree on pass or fail by observing the product.
• Keep steps declarative: say what behavior happens, not which button, query, table, or service implements it.
• Keep Background short and confirmed. If scenarios need different starting states, split them.
• Use Scenario Outline only for value variations of the same behavior.

Do not:

• Stack two When plus Then pairs in one scenario to cover saving and sharing in one block.
• Couple steps to the interface, such as clicking a named button, opening a named menu, or waiting for a spinner.
• Invent limits, roles, validation details, or failure behavior inside Given or Then to fill gaps.
• Use an outline table to hide different triggers, permissions, or outcomes that deserve separate scenarios.

What good acceptance criteria look like

Use this quality model as a review, not as a fake score.

A criterion can be beautifully written and still be wrong if the underlying product rule was never decided.

Run these Gherkin-specific checks on the saved-search scenarios before handoff:

• One behavior per scenario: if a scenario has two When steps or two Then outcomes for different behaviors, split it. Saving a search and sharing it are two scenarios, not one long chain.
• Observable Then: Then those saved filter values are applied passes because reopening shows the result. Then the save completes cleanly in the backend fails because no reviewer can observe the backend claim directly.
• UI-independent wording: When the recruiter reopens that saved search keeps the behavior stable across interface changes. When the recruiter clicks the blue Save icon in the header couples the requirement to a control that design may move or rename.
• No invented rules in scenario clothing: Then only 10 saved searches are kept looks testable but fails Gate 1 when no limit was decided. Keep it as an open question about limits.
• Short enough to review: if a scenario needs seven And steps to set up, the story may bundle several starting states, triggers, or outcomes. Separate scenarios, shorten Background, or split the story.

What belongs here, and what does not

The Acceptance Criteria Quality Lab above this article lets you try these classifications with your own line. It is deterministic and does not generate new product rules.

Acceptance criteria vs user story vs PRD vs Definition of Done vs test case

These artifacts answer different questions.

PRD

What product scope, requirements, constraints, risks, and outcomes have we actually decided?

A PRD can be the source for multiple delivery behaviors. Use the PRD Generator when initiative-level scope or requirements are still being defined.

User story

Who is trying to do what, in what context, and why?

A story is a bounded delivery unit and conversation aid. It does not automatically define every edge case. Use the User Story Generator when the behavior still needs to be sliced or the actor/intent is unclear. For story shaping, job-story framing, and splitting depth, see user stories best practices; this page stays focused on turning already-confirmed behavior into observable acceptance conditions.

Acceptance criteria

What observable conditions must be true for this specific confirmed behavior to be accepted?

Criteria add behavioral precision without replacing the user need or broader requirement context.

Definition of Done

What shared quality state must completed work meet?

In Scrum, the Definition of Done formally describes the state of the Increment when it meets the required quality measures. Acceptance criteria are a commonly used complementary practice and are specific to the work item. See Scrum.org's acceptance-criteria vs Definition of Done explanation.

Typical DoD or delivery checks might include code review, required automated checks, or documentation standards. Do not copy them into every feature's acceptance criteria merely to make the list longer.

Test case

How will we verify the behavior in a particular setup with particular data and steps?

One acceptance criterion can produce several test cases. A QA test may include exact setup, test data, actions, expected results, environment, and variations that do not belong in the product requirement itself.

Technical design

How will Engineering implement the behavior?

Architecture, storage, APIs, internal components, caches, queues, and implementation trade-offs belong here unless a specific technology is itself a genuine external product constraint.

Plain language vs Given / When / Then

Plain language is a valid default. Use the format that makes the behavior easier for the team to understand and challenge.

Use plain language when

• the condition is already concise;
• starting state is obvious;
• there is little branching behavior;
• Given/When/Then would only add ceremony.

Example:

The recruiter can reopen a saved search and the filters stored with that search are applied.

Use Given / When / Then when

• the starting state changes the expected result;
• an event or action triggers different behavior;
• a scenario makes a business rule easier to discuss;
• the team already works effectively with concrete BDD-style examples.

For the hypothetical saved-search rules above:

Scenario: Reopen a saved search
  Given a recruiter has a saved search with confirmed filter values
  When the recruiter reopens that saved search
  Then those saved filter values are applied

The official Cucumber Gherkin reference describes Given as context, When as an event/action, and Then as an expected result; it also recommends keeping outcomes observable rather than describing state buried inside the system.

Gherkin is syntax, not product truth

A weak requirement does not become good because it uses keywords.

Scenario: Use the feature
  Given I am a user
  When I use the feature
  Then it should work

This is syntactically shaped like Gherkin and behaviorally useless.

Also, using Given/When/Then does not mean a team is “doing BDD.” Cucumber describes BDD as a broader collaborative practice built around shared understanding and concrete examples, not merely a notation choice. See Cucumber's BDD introduction.

If your team does not use executable specifications, Gherkin can still be a readable scenario format. If plain language is clearer, use plain language.

Do not build giant Gherkin scenarios

A scenario such as this is usually a warning sign:

Given ...
And ...
And ...
And ...
When ...
And ...
Then ...
And ...
And ...

Ask whether you have mixed:

• multiple starting states;
• multiple triggers;
• several independent outcomes;
• hidden business rules;
• more than one user behavior.

Separate scenarios when that separation improves understanding. If the work still cannot be described coherently, the story itself may need to be split.

Edge cases: ask first, specify second

Edge-case thinking is valuable because it exposes missing decisions. It becomes dangerous when a checklist silently supplies the answers.

Use these as questions, not automatic requirements.

State

• What if the item already exists?
• What if its state changed since the user last saw it?

Input

• What counts as invalid input?
• Is the validation rule already defined somewhere?

Permission

• Who may perform the action?
• Is that permission model confirmed or merely assumed?

Empty state

• What happens when there is no data?
• Is an empty-state action actually required?

Failure

• What if the action cannot complete?
• Should state be preserved, reverted, retried, or left unchanged?

Repetition

• What happens if the action runs twice?
• Is idempotency a confirmed product requirement or only a technical concern here?

Reversal

• Can the action be undone?
• Who is allowed to reverse it?

Concurrency

• Can another person or system change the same state at the same time?
• If that matters, what behavior has the team decided?

Not every story needs an answer to every category. The checklist finds questions; the product conversation supplies the rules.

This is consistent with Cucumber's Example Mapping, which deliberately captures rules, examples, unanswered questions, and newly discovered/deferred stories as different things.

Business rules need provenance

A rule such as these may be perfectly legitimate:

• only approved roles can issue refunds;
• an account can have one active subscription;
• cancellation is allowed only inside a defined window.

But the criterion should not be the first place where the rule appears.

For higher-risk behavior, record enough provenance to answer:

Where did this rule come from?

Possible sources include:

• PRD requirement;
• product decision;
• legal/compliance policy;
• security constraint;
• pricing or billing policy;
• technical/platform constraint;
• an existing behavior that must remain compatible.

If the source is unclear, write:

Rule source / owner: unresolved

That is more useful than confident-looking fiction.

Strong vs weak acceptance criteria transformations

Subjective wording

Weak

Saving a search should be easy.

Fix

Do not replace “easy” with a random proxy. Ask what confirmed behavior makes the flow acceptable. If the decision is that the user can save the current search and reopen it later, specify those observable behaviors.

Invented performance threshold

Weak when no threshold exists

Results load within two seconds.

Fix

Performance threshold: unresolved.

Once the product/SRE/platform requirement defines a threshold and test condition, that requirement can become an acceptance condition or referenced non-functional requirement.

Unconfirmed permission

Weak

Only admins can delete the workspace.

Fix when permission has not been decided

Open question: which roles may delete the workspace, and which policy or product owner defines that rule?

Implementation leakage

Weak

Cache the result in Redis for 60 seconds.

Behavior-focused, if this is the confirmed need

When the user returns to the view under the confirmed persistence conditions, the previously saved state is available.

Do not rewrite technical details into user behavior unless the persistence behavior is actually required.

KPI confusion

Weak as acceptance criteria

Increase checkout conversion by 20%.

Separate the jobs

• Acceptance criteria: verify the confirmed checkout behavior.
• Product metric: evaluate whether that behavior improves checkout outcomes.

A feature can meet every acceptance criterion and still fail as a product bet.

Example library: five different behavior problems

Each example below is hypothetical and begins by stating the rule that is assumed to be confirmed. The examples are deliberately compact; the goal is to teach a different type of decision, not to produce an exhaustive test suite.

1. Permission rule, archive workspace

Confirmed rule for this example: the approved permission model states that workspace admins can archive a workspace and non-admin members cannot.

Acceptance criteria

• A signed-in workspace admin can archive the workspace.
• A signed-in member who is not an admin cannot archive the workspace.

Open questions

• What confirmation interaction, if any, is required?
• Can an archived workspace be restored?
• What happens to active integrations after archival?

Do not answer those questions unless their behavior is already decided.

2. Validation rule, teammate invitation

Confirmed rule for this example: an invitation can be submitted only when the entered address satisfies the product's existing email-address validation rule.

Acceptance criteria

• An address that satisfies the existing validation rule can be submitted for invitation.
• An address that does not satisfy that rule is not submitted as an invitation.

Open questions

• What feedback should appear for invalid input?
• Can several addresses be invited at once?
• Are there role or domain restrictions?

Notice that the example references the existing validation rule instead of inventing a new regex, character limit, or domain policy.

3. State transition, pause subscription

Confirmed rules for this example: an eligible paid subscriber can schedule a pause for the next billing boundary; current paid access continues until that boundary.

Acceptance criteria

• An eligible paid subscriber can schedule the pause for the next billing boundary.
• Before that boundary, the subscription remains in its current paid-access state.
• At the confirmed boundary, the subscription moves to the paused state.

Open questions

• How long can the pause last?
• Can it be canceled before it begins?
• Which subscriptions are eligible?
• What happens to prepaid time?

Those policy decisions are intentionally left unresolved.

4. Failure behavior, report export

Confirmed rules for this example: when report generation fails, the product must not show the export as successful; the user remains able to review the report configuration.

Acceptance criteria

• If report generation fails, the interface does not show the export as completed successfully.
• After the failure, the report configuration remains available for review.

Open questions

• Is retry required?
• Should the failure explain a specific cause?
• Is background recovery supported?

A generic “show an actionable error” statement would invent detail unless that behavior is already required.

5. Empty state, filtered candidate list

Confirmed rules for this example: when the current confirmed filters match no candidates, the results area shows an explicit no-results state and the current filters remain unchanged.

Acceptance criteria

• When the current filters match zero candidates, the results area shows the confirmed no-results state.
• Entering the no-results state does not change the selected filters.

Open questions

• Should alternative filters be suggested?
• Can the user save the zero-result search?
• Should any analytics event fire?

Again: useful questions, not automatically product scope.

Acceptance criteria are not the whole test suite

Suppose the confirmed acceptance criterion is:

When a recruiter reopens a saved search, the filter values stored with that search are applied.

QA might derive multiple test cases using:

• different supported filter combinations;
• different account states;
• specific test data;
• different browsers or devices where relevant;
• setup/cleanup steps;
• exact expected values;
• regression coverage.

Those tests validate the criterion. They do not all need to be copied into the product requirement.

Use acceptance criteria to define the behavioral contract. Let test design add the depth necessary to verify it.

Acceptance criteria should support conversation, not replace it

Before implementation, criteria are useful when they expose disagreement early:

• Product notices an unresolved rule;
• Design finds a missing state;
• Engineering identifies a feasibility or system constraint;
• QA exposes a behavior that cannot currently be accepted/rejected;
• a policy or domain expert clarifies a rule source.

Cucumber's BDD guidance emphasizes collaborative discovery around concrete examples, and its “three amigos” guidance explicitly values the different perspectives of business/product, development, and testing. You do not need to adopt that ceremony to keep the underlying principle: the artifact is valuable when it improves shared understanding.

See Cucumber's collaboration guidance for the BDD-specific version.

Criteria can change, make the change visible

Acceptance criteria are not sacred after they are written. Valid product decisions can change.

If behavior changes after delivery work starts:

1. update the source requirement or decision;
2. update the criteria;
3. make the scope change visible to the team;
4. revisit design, estimate, implementation, and tests that the change affects.

Do not silently rewrite criteria after the implementation has already been built and then treat the new behavior as though it was always part of the scope.

How many acceptance criteria should a story have?

There is no universal correct number.

Too few can leave important confirmed behavior undefined.

Too many can mean:

• the story contains several user outcomes;
• multiple actors or state transitions are bundled together;
• every QA variation has been promoted into product scope;
• the team is duplicating shared rules instead of referencing them;
• the item is simply too large.

A story with 25 unrelated conditions is a reason to inspect the story, not a reason to celebrate completeness.

If the behavior is too broad, go back to the User Story Generator. The current tool keeps confirmed scope, confirmed acceptance behavior, candidate split questions, and unresolved product questions separate rather than manufacturing missing rules.

Story readiness gate: do not polish ambiguity into Gherkin

Acceptance criteria are premature when the core product decision is still unclear.

Route backward when:

• the actor materially affects behavior but is unknown;
• the desired behavior is still a feature label rather than a capability;
• the story combines several unrelated outcomes;
• a core permission/business rule blocks definition;
• broader initiative scope is still contested;
• the team cannot state what user or product result is being delivered.

Use the PRD Generator when initiative-level requirements or scope are unresolved. Use the User Story Generator when the requirement is understood but the bounded delivery behavior still needs to be shaped.

Do not use Given/When/Then to create false certainty.

PRD → User Story → Acceptance Criteria → testing

A useful conceptual trace is:

product problem / evidence → PRD requirement or product decision → bounded user story / behavior → acceptance criterion → test coverage

Not every organization needs IDs or formal traceability software. The useful question is simpler:

Can the team explain which confirmed product decision this criterion protects?

CraftUp's artifact owners follow that boundary:

• Problem Statement Generator, frame the problem when the problem itself is unclear.
• Product Brief Template, align on opportunity, outcome, direction, boundaries, and unknowns before deep requirements.
• PRD Generator, define confirmed initiative scope, requirements, constraints, risks, and open questions.
• User Story Generator, shape a bounded user-centered delivery behavior while preserving unknowns.
• This page, turn confirmed behavior into observable acceptance conditions and keep unresolved rules unresolved.

After that, Engineering and QA can expand the behavior into the implementation and test coverage their context requires.

Acceptance criteria review checklist

Before calling a criterion ready, ask:

• Confirmed: does it trace to a real behavior, rule, or constraint?
• Observable: can another person determine pass/fail?
• Specific enough: has subjective wording been removed without inventing a proxy?
• Bounded: is it one coherent condition rather than several unrelated behaviors?
• Implementation-neutral: does it avoid prescribing architecture without a product reason?
• Necessary: does it protect meaningful confirmed scope?
• Separate from metrics: is a product KPI being mistaken for implementation acceptance?
• Separate from DoD: is a shared delivery/process check being duplicated here?
• Open questions preserved: did the team keep unresolved permissions, validation, limits, failure behavior, and policy as questions?
• Format fit: is plain language clearer, or does Given/When/Then make the state/action/outcome materially easier to understand?

If the review discovers a missing rule, the correct output is often “decision required”, not another bullet.

FAQ

Do acceptance criteria have to use Given / When / Then?

No. Plain language is often clearer. Use Given/When/Then when starting state, trigger, and observable outcome benefit from scenario structure or when the team deliberately uses Gherkin/BDD-style examples.

Is Gherkin the same thing as BDD?

No. Gherkin is the structured language used by Cucumber specifications. BDD is a broader collaborative development practice around discovery, concrete examples, formulation, and automation. A team can write Given/When/Then without doing BDD, and can practice behavioral collaboration without requiring Gherkin everywhere.

What is the difference between acceptance criteria and Definition of Done?

Acceptance criteria are specific to the behavior or backlog item. A Definition of Done is a shared quality/completion standard. In Scrum specifically, the Definition of Done describes the state of the Increment when it meets the required quality measures.

Should every user story have acceptance criteria?

Use them when explicit conditions reduce meaningful ambiguity. Tiny changes with strong shared understanding may not need a formal list, while risky behavior may need careful criteria and supporting examples. Do not add them only because a template requires a fixed number.

Who should write acceptance criteria?

The exact role split varies. Product/Product Owner, Design, Engineering, QA, and relevant policy/domain experts can all expose different kinds of ambiguity. The goal is shared understanding of confirmed behavior, not ownership of the prose.

Can acceptance criteria change after development starts?

Yes, if the product decision changes. Make the change explicit because it may alter scope, design, estimate, implementation, or test coverage. Do not silently move the acceptance boundary after work has already been built.

Authoritative references for Gherkin and BDD

For syntax and BDD-specific practice, use primary sources rather than SEO summaries:

• Cucumber Gherkin Reference
• Cucumber BDD Introduction
• Cucumber Example Mapping
• Cucumber collaboration / Three Amigos guidance
• Scrum.org: Acceptance Criteria and Definition of Done

The durable rule is simpler than any methodology: make confirmed behavior observable; keep missing product decisions visible until they are actually decided.