Acceptance Criteria: Given When Then Examples Testers Can Actually Run
Acceptance criteria are the conditions a user story must meet before anyone calls it done. Learn the two common formats, how to write criteria that are specific and testable, and how a worked discount code example turned into automated tests that caught a boundary bug.
- Acceptance criteria describe observable results for one user story, written before development starts.
- Use the Given When Then format for behaviour with clear steps, and a rule list for simple constraints.
- Each criterion should be specific enough to become a test without asking anyone a question.
- We turned six criteria for a discount code into six pytest tests. A planted off-by-one bug passed five of them and failed the boundary criterion.
A developer finishes a story and moves it to “done”. The tester finds that expired codes still work. The product owner says “obviously expired codes should fail”. The developer says “that was never written down”. Every team has lived some version of this argument. Acceptance criteria prevent it by stating, before work starts, exactly what must be true for the story to be accepted.
This guide explains how to write criteria that leave no room for that argument. We use one realistic story throughout, and we turned its criteria into automated tests with pytest 9.2.0 on Python 3.13.6 to show how directly good criteria map to tests.
What are acceptance criteria?
Acceptance criteria are a short list of conditions attached to a user story. They describe what the user can observe when the story works: what they see, what is saved, what is refused. They answer the question “how will we know this story is done?” in terms a product owner, developer and tester all agree on.
They describe what, not how. “The total shows 72.00” is a criterion. “Store the discount in a decimal column” is a design decision that belongs in technical notes.
Why they matter
- Shared understanding: writing them together exposes different assumptions before any code exists.
- Estimation: a story with eight criteria is clearly bigger than one with two.
- Test design: each criterion is a ready-made test case, which saves time in writing test cases.
- Scope control: anything not in the criteria is a new story, not a hidden requirement.
- Sign-off: they give user acceptance testing a clear target.
Acceptance criteria vs definition of done vs test cases
| Item | Applies to | Example |
|---|---|---|
| Acceptance criteria | One specific story | An expired code shows “Code expired” and the total does not change |
| Definition of done | Every story in the team | Code reviewed, unit tests pass, deployed to staging |
| Test cases | Detailed checks of a criterion | Steps, data and expected results, including edge cases |
One criterion often produces several test cases. “Codes are not case sensitive” might become tests for lowercase, mixed case and spaces around the code.
The two common formats
Rule-oriented (checklist)
A plain list of statements, each of which is true or false:
- The code field accepts up to 20 characters.
- Codes are not case sensitive and ignore spaces around them.
- Only one code can be applied per order.
Good for simple constraints, validation rules and UI details.
Scenario-oriented (Given When Then)
Each criterion is a short scenario with a starting context, one action and an observable result:
Given a cart total of 80.00 and the active code SAVE10
When the shopper applies SAVE10
Then the total shows 72.00
And the message "Code applied" is displayed
Good for behaviour that depends on state or sequence. It comes from behaviour-driven development and maps directly to tools like Cucumber, SpecFlow and pytest-bdd. Our TDD vs BDD guide covers where the format comes from.
Rules for good Given When Then
- Given is state, not actions. “Given a cart total of 80.00”, not “Given the user adds a book and a pen”.
- When is one event. If you need two, you probably have two scenarios.
- Then is observable by the user or another system: a message, a total, a record, an email. Avoid internal details like “the flag is set”.
- Use concrete values. “A valid amount” forces the reader to guess; “80.00” does not.
- Keep each scenario to about three to six lines. Long scenarios hide several behaviours.
- Write in the language of the business, so the product owner can read and approve it.
Tip: read each Then line and ask “could a tester check this without asking anyone?” If the answer is no, the criterion is not finished yet.
Worked example: a discount code
User story: As a shopper, I want to apply a discount code at checkout so that I pay less for my order.
The rules from the product owner: SAVE10 gives 10% off, needs a minimum cart total of 50.00 and expires at the end of 31 December 2026. Here are the criteria we agreed:
- AC1, valid code: Given a cart total of 80.00 and the active code SAVE10, When the shopper applies SAVE10, Then the total shows 72.00 and the message “Code applied”.
- AC2, below minimum: Given a cart total of 45.00, When the shopper applies SAVE10, Then the total stays 45.00 and the message reads “Add 5.00 more to use this code”.
- AC3, expired: Given today is 1 January 2027, When the shopper applies SAVE10, Then the total is unchanged and the message reads “Code expired”.
- AC4, input tolerance: Given the shopper types ” save10 ” with spaces and lowercase letters, When it is applied, Then it is accepted.
- AC5, unknown code: Given the code FREE100 does not exist, When it is applied, Then the total is unchanged and the message reads “Code not recognised”.
- AC6, boundary: Given a cart total of exactly 50.00, When the shopper applies SAVE10, Then the total shows 45.00.
AC2 is a good example of a criterion that improves the product: instead of a vague “minimum not met”, it tells the shopper exactly what to do. AC6 exists because the phrase “minimum of 50.00” is ambiguous until someone asks whether 50.00 itself qualifies. That question is pure boundary value analysis.
Turning criteria into automated tests
Because every criterion has concrete values, each one became a test almost word for word. We kept the Given When Then text as comments so the link stays visible:
TODAY = date(2026, 11, 18)
def test_ac1_valid_code_reduces_total():
# Given a cart total of 80.00 and the active code SAVE10
# When the shopper applies SAVE10
# Then the total shows 72.00 and the message "Code applied"
assert apply_code(80.00, "SAVE10", TODAY) == (72.00, "Code applied")
def test_ac2_below_minimum_explains_gap():
assert apply_code(45.00, "SAVE10", TODAY) == (45.00, "Add 5.00 more to use this code")
def test_ac3_expired_code_rejected():
assert apply_code(80.00, "SAVE10", date(2027, 1, 1)) == (80.00, "Code expired")
def test_ac6_exactly_minimum_qualifies():
assert apply_code(50.00, "SAVE10", TODAY) == (45.00, "Code applied")
AC4 and AC5 follow the same shape. Running the file:
test_promo_ac.py::test_ac1_valid_code_reduces_total PASSED
test_promo_ac.py::test_ac2_below_minimum_explains_gap PASSED
test_promo_ac.py::test_ac3_expired_code_rejected PASSED
test_promo_ac.py::test_ac4_code_is_case_and_space_insensitive PASSED
test_promo_ac.py::test_ac5_unknown_code PASSED
test_promo_ac.py::test_ac6_exactly_minimum_qualifies PASSED
6 passed in 0.13s
Naming tests after the criterion ID makes the report readable by non-developers: a failing test_ac3 immediately tells the product owner which promise is broken.
The bug a criterion caught
We then changed one character in the implementation, from total < minimum to total <= minimum, a very common off-by-one mistake. The result:
FAILED t_bug.py::test_ac6_exactly_minimum_qualifies - AssertionError
1 failed, 5 passed in 0.16s
Five criteria still passed. Without AC6, this bug would have shipped, and every shopper with a cart of exactly 50.00 would have been told to “add 0.00 more”. One extra line in the story, written in a five-minute conversation, prevented a confusing bug in production.
More acceptance criteria examples
Password reset
Given a registered email address
When the user requests a password reset
Then a reset link is emailed within 1 minute
And the link expires after 30 minutes
Given an email address that is not registered
When the user requests a password reset
Then the same confirmation message is shown
And no email is sent
The second scenario protects privacy: showing a different message would reveal which emails have accounts.
Search filter (rule format)
- Selecting “In stock” hides products with zero stock.
- Filters combine with AND: “In stock” plus “Under 20” shows only items matching both.
- The result count updates without a page reload.
- Clearing filters restores the original result count.
Non-functional acceptance criteria
Criteria are not only about features. Performance, security and accessibility needs belong in them too, as long as they are measurable:
- The search results page loads in under 2 seconds for 95% of requests with 1,000 products.
- The discount code field can be reached and submitted using only the keyboard.
- Applying more than 10 invalid codes in a minute shows a rate limit message.
Requirements that apply to every story, such as “all pages work on mobile”, usually belong in the definition of done instead.
Who writes them, and when
The product owner usually owns acceptance criteria, but the best ones come from a short conversation between the product owner, a developer and a tester, often called the “three amigos”. Write them during backlog refinement, before the story enters a sprint, and update them if the conversation during development changes the scope. Criteria added after development has finished are a sign that the story was not ready.
Quality checklist
- Is each criterion testable with a clear pass or fail?
- Does each one use concrete values rather than words like “fast”, “valid” or “user friendly”?
- Are error paths covered, not just the happy path? Our guide to positive vs negative testing helps here.
- Are boundaries stated explicitly, such as “50.00 or more”?
- Does each criterion describe an outcome the user or another system can observe?
- Is the list short enough? More than about eight criteria usually means the story should be split.
- Has the product owner agreed to every line?
Common mistakes
- Vague words: “The page should be fast” cannot fail. Give a number.
- Implementation details: “Use Redis for the cache” constrains design without describing user value.
- Happy path only: most production bugs live in the error and edge cases.
- Writing them after coding: they then describe what was built rather than what was needed.
- Several actions in one When: split them so a failure points to one behaviour.
- Copying the story: “The user can apply a discount” repeats the story and adds nothing testable.
Final thoughts
Good acceptance criteria are short, concrete and testable. Write them before development, use Given When Then for behaviour and a rule list for constraints, and always include the error and boundary cases. Our six-criterion discount example turned straight into six tests, and the single boundary criterion was the only one that caught a realistic off-by-one bug. That is the return on spending ten minutes on criteria before writing code.
Frequently asked questions
What are acceptance criteria in agile?
They are the specific, testable conditions a user story must meet to be accepted as done. They describe observable outcomes and are agreed before development starts.
What is the Given When Then format?
It is a scenario format where Given sets the starting state, When describes one action, and Then states the observable result. It comes from behaviour-driven development.
Who writes acceptance criteria?
The product owner owns them, but they work best when written together with a developer and a tester during backlog refinement, before the story starts.
How many acceptance criteria should a user story have?
Usually between three and eight. Fewer often means error cases are missing, and many more usually means the story is too big and should be split.
What is the difference between acceptance criteria and definition of done?
Acceptance criteria are specific to one story. The definition of done is a shared checklist that applies to every story, such as code review and passing tests.
Keep learning
Need help with testing, WordPress or SEO?
We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.