1. Home
  2. Blog
  3. Software Testing

Software Testing

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.

9 min read
Acceptance criteria with Given When Then examples and a quality checklist

Key takeaways

  • 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:

  1. 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”.
  2. 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”.
  3. AC3, expired: Given today is 1 January 2027, When the shopper applies SAVE10, Then the total is unchanged and the message reads “Code expired”.
  4. AC4, input tolerance: Given the shopper types ” save10 ” with spaces and lowercase letters, When it is applied, Then it is accepted.
  5. 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”.
  6. 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

Work with Stack Quora

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.

Keep reading

More guides on testing, AI & modern development

Enjoyed this article? Pick a topic and jump straight into our newest tutorials.

Artificial Intelligence

Levenshtein Distance: Formula, Worked Table and Python Code

Levenshtein distance explained: the edit operations, the dynamic programming table for kitten and sitting, Python code with two-row memory, normalised…

Read article →
Software Development

URL Encoding Explained: Spaces, Plus Signs and UTF-8

URL encoding explained with tested Python and JavaScript code: percent encoding, reserved characters, %20 vs plus, UTF-8 bytes, encodeURI vs…

Read article →
DevOps

Gitignore: Patterns, Negation and Fixing Tracked Files

A tested gitignore guide: pattern rules, leading and trailing slashes, negation with !, the ignored parent folder trap, git check-ignore…

Read article →
Software Testing

Acceptance Criteria: Given When Then Examples and Checklist

How to write acceptance criteria testers can run: rule-based and Given When Then formats, a worked discount code example turned…

Read article →
Software Testing

State Transition Testing: Diagram, Table and Example

State transition testing explained with a login lockout example: states, events, the diagram, the state table, valid and invalid transitions,…

Read article →
Databases & SQL

Second Highest Salary in SQL: 5 Tested Ways and the Tie Trap

Find the second highest salary in SQL five ways: MAX subquery, LIMIT OFFSET, DENSE_RANK, a correlated subquery and per department,…

Read article →
Databases & SQL

SQL ROW_NUMBER: Top N per Group, Dedupe and Pagination

SQL ROW_NUMBER explained with tested queries: PARTITION BY, top N per group, deleting duplicates, pagination, the tie trap and how…

Read article →
Software Development

JavaScript Set: Union, Intersection and Removing Duplicates

JavaScript Set explained with tested examples: add, has, delete, deduplicating arrays, the new union and intersection methods, equality rules and…

Read article →
Test Automation

Python Unittest: Assert Methods, setUp and Mocks With Examples

A practical Python unittest tutorial: TestCase, assert methods, setUp and tearDown, subTest, skips, expected failures and mock, with a test…

Read article →
Software Development

Python Map and Filter: Examples vs List Comprehensions

Python map and filter explained with tested examples: lazy map objects, multiple iterables, filter(None), chaining, and a timed comparison with…

Read article →
Artificial Intelligence

Jaccard Similarity: Formula, Python, MinHash

Jaccard similarity measures overlap between two sets as intersection over union. Work the formula, compute it in Python for words…

Read article →
Software Development

Unix Timestamp Explained: Seconds vs ms

A Unix timestamp counts seconds since 1 January 1970 UTC. Learn seconds vs milliseconds, converting in Python, JavaScript and SQL,…

Read article →
DevOps

Git Hooks: Pre-commit and Commit-msg Examples

Git hooks run scripts at key moments such as commit and push. See tested pre-commit, commit-msg and prepare-commit-msg hooks, sharing…

Read article →
Test Automation

API Testing in Python: Pytest + Requests Suite

Build an API testing suite in Python with pytest and requests: fixtures, status codes, headers, JSON schema validation, CRUD flows,…

Read article →
Software Testing

Test Design Techniques: 9 Methods + Examples

Test design techniques help you write fewer tests that catch more bugs. Learn 9 black-box, white-box and experience-based methods with…

Read article →
Databases & SQL

SQL Temporary Table: Create, Use and Drop It

SQL temporary tables store interim results for one session. Learn syntax for SQL Server, PostgreSQL, MySQL, Oracle and SQLite, session…

Read article →
Databases & SQL

SQL CROSS JOIN: Every Combination + Examples

SQL CROSS JOIN returns every combination of rows from two tables. See the row math, product variants, calendar grids that…

Read article →
Software Development

JavaScript Date: Format, Parse, Timezone Bugs

JavaScript Date explained with tested Node.js code: zero-based months, the date-only UTC parsing trap, toISOString, getTimezoneOffset, Intl formatting, date math…

Read article →
Software Development

Python Requests: GET, POST, Timeouts, Retries

Python requests explained with code tested against a local API: GET with params, POST json vs data, headers and auth,…

Read article →
Artificial Intelligence

TF-IDF Explained: Formula and Worked Example

TF-IDF scores a word by how often it appears in a document and how rare it is across all documents….

Read article →
DevOps

Git Tag: Create, Push and Delete Release Tags

Git tag explained with tested commands: annotated vs lightweight tags, listing and sorting, pushing with follow-tags, deleting local and remote…

Read article →
Test Automation

Pytest Coverage: pytest-cov and Branch Gaps

Measure pytest coverage with pytest-cov: term-missing reports, branch coverage, HTML reports, pyproject settings and a fail-under gate for CI, with…

Read article →
Software Testing

Error Guessing in Testing: Checklist + Demo

Error guessing uses tester experience to predict where code breaks. Get a ready checklist of risky inputs, a step by…

Read article →
Databases & SQL

SQL LAG and LEAD: Compare Rows, 5 Examples

SQL LAG and LEAD read values from the previous or next row without a self join. Five tested examples: change,…

Read article →
Databases & SQL

SQL STRING_AGG: Combine Rows Into One String

SQL STRING_AGG joins values from many rows into one string per group. See syntax for PostgreSQL, SQL Server, MySQL GROUP_CONCAT,…

Read article →
Artificial Intelligence

BM25 Explained: How Keyword Search Ranks Results, With Python Code and Hybrid Search

BM25 explained with a pure Python implementation we ran: the formula, IDF, term saturation, the k1 and b parameters, why…

Read article →
DevOps

Git Bisect Explained: Find the Commit That Broke Your Code, Manually or Automatically

Git bisect explained with a tested repository: find the one bad commit among 41 in 5 test runs, automate it…

Read article →
Test Automation

pytest Markers Explained: Custom Marks, skip, skipif, xfail and -m Filters

pytest markers explained with a tested suite: register custom marks, run only smoke tests with -m, combine filters with and,…

Read article →
Software Testing

Positive vs Negative Testing: Differences, 24 Real Test Cases and a Checklist

Positive vs negative testing explained with a real signup form: 6 positive and 18 negative test cases run in pytest,…

Read article →
Artificial Intelligence

Cosine Similarity Explained: Formula, Worked Example and Python Code

Cosine similarity explained simply: the formula, a worked example by hand, pure Python and NumPy code, cosine vs Euclidean distance…

Read article →
DevOps

Git Squash Commits: 4 Easy Ways, Tested Step by Step (rebase -i, reset, merge)

Git squash commits explained with 4 tested methods: interactive rebase, reset –soft, merge –squash and fixup with autosquash. Before-and-after logs,…

Read article →
Test Automation

pytest parametrize Explained: 7 Patterns with Tested Examples

pytest parametrize explained with 7 tested patterns: basic cases, readable ids, stacked decorators, pytest.param with xfail and skip, indirect fixtures…

Read article →
Software Testing

Retesting vs Regression Testing: 8 Key Differences with a Real Bug Fix Example

Retesting vs regression testing explained with a real bug fix run in pytest: retesting confirmed the fix, the regression run…

Read article →
Artificial Intelligence

RAG Chunking Strategies Explained: Fixed, Overlap, Sentence, Recursive and Headings, Measured

RAG chunking strategies compared on one document with tiktoken 0.14: fixed-size, overlap, sentence packing, recursive splitting and heading-based chunks, measuring…

Read article →
DevOps

Git Stash Explained: Save, Apply, Pop and Untracked Files, Tested

Git stash explained with commands we ran on Git 2.56: push with a message, untracked files, list and show, apply…

Read article →
Test Automation

Test Doubles Explained: Dummy, Stub, Spy, Mock and Fake, with Tested Python Code

Test doubles explained with one Python example run in pytest 9.2: dummy, stub, spy, mock and fake, when to use…

Read article →