The four steps of the cycle
Discuss. Before a story is pulled into a sprint, the three amigos (product owner, developer, tester) talk through what it means using concrete examples rather than abstract rules. The goal is shared understanding, and the by-product is a list of examples and open questions. Distill. The examples are cleaned into a small set that covers the rules, the boundaries and the exceptions, written in a form that can be automated: a table, or a given-when-then scenario. Develop. The developer wires the examples to the code as executable acceptance tests, watches them fail, and builds until they pass, using unit-level TDD inside the loop. Demo. The passing examples are shown to the product owner, who confirms they mean what was intended. If the demo surprises anyone, the cycle starts again at discuss.
The point is not the tooling. Gojko Adzic calls the underlying practice specification by example: the examples are the specification, the tests and the documentation, all at once, and they stay in sync because a change to one is a change to all. Teams that treat ATDD as a way of generating test scripts miss the part that pays: the conversation. For where these tests sit relative to unit and end-to-end checks, see the test automation pyramid.
Running a three amigos session
Keep it short, keep it to three or four people, and keep it about one story. A 25 to 45 minute agenda that works:
- Read the story aloud (2 minutes). The product owner explains what it is for and who benefits. No solutioning yet.
- Ask for the first example (5 minutes). The tester asks: give me one concrete case where this works. Write it down with real values, not placeholders.
- Push the edges (15 minutes). Everyone proposes variations: the boundary, the empty case, the two rules that collide, the thing that happened last month in production. Each becomes a row or a question.
- Park the unknowns (5 minutes). Any example the product owner cannot answer becomes an open question with an owner and a due date. Do not guess.
- Distill (5 to 10 minutes). Cross out duplicates, merge rows that test the same rule, and check that each remaining example would fail today. Three to eight examples is normal; twenty means the story is too big.
A worked example: a discount rule
A story reads: apply discounts at checkout. The first draft of the rules from the product owner: orders above 100.00 get 10 percent off; loyalty members get a further 5 percentage points; a coupon code adds 10 percentage points but cannot combine with the loyalty bonus; total discount is capped at 20 percent. Four sentences, and the session found two ambiguities in the first ten minutes: does exactly 100.00 count as above, and does a coupon work on an order below the threshold? The table records the answers the product owner gave.
| Order total | Customer | Coupon | Expected discount | Why |
|---|---|---|---|---|
| 100.00 | guest | none | 0.00 | not above the threshold; the boundary was clarified in the session |
| 100.01 | guest | none | 10.00 | base rule, 10 percent |
| 250.00 | member | none | 37.50 | base 10 plus loyalty 5, 15 percent |
| 250.00 | guest | SAVE10 | 50.00 | base 10 plus coupon 10, 20 percent |
| 250.00 | member | SAVE10 | 50.00 | coupon 20 beats loyalty 15; no stacking |
| 80.00 | member | SAVE10 | 8.00 | below threshold the coupon applies alone; this was the second open question |
| 1000.00 | member | SAVE10 | 200.00 | cap at 20 percent holds at any size |
Notice what the table did. It exposed the boundary question that a prose specification hid. It forced a decision on coupon behavior below the threshold, which the developer would otherwise have decided alone at 4 pm on a Thursday. And it produced seven tests whose expected values the product owner personally agreed to, so a failing test is a real disagreement about the product, not a testing error.
ATDD, BDD and TDD compared
| Aspect | TDD | ATDD | BDD |
|---|---|---|---|
| Level | unit: one class or function | feature: one story's behavior | feature: one story's behavior |
| Who writes the tests | the developer | the three amigos together | the three amigos, in a shared ubiquitous language |
| Written in | the programming language | tables or given-when-then scenarios | given-when-then scenarios, business vocabulary |
| Primary purpose | drive design, prevent regressions | confirm the story does what was asked | build shared understanding of behavior |
| Feedback loop | seconds | minutes | minutes |
| Typical failure mode | tests coupled to implementation | examples written by one person after the fact | scenarios so wordy nobody reads them |
In practice, ATDD and BDD are two names for one habit. BDD, as Dan North framed it, stresses the language: scenarios read like sentences the business would say. ATDD stresses the workflow: agree examples first, automate them, build to them. Pick the name your organization likes and do the work. TDD is different in kind: it lives inside the developer's loop and drives code design. A team doing ATDD without TDD ends up with slow acceptance suites carrying the weight that unit tests should. Both feed continuous testing: acceptance tests run on every build, and the story is not done until they are green.
Tool-agnostic guidance
Any framework that can read a table or a scenario and call your code will do. What matters more: keep the acceptance suite fast (under 10 minutes for the full set, under a minute for one story's examples) by testing through a service or domain layer rather than the user interface where you can; keep examples in version control next to the code, so a change to behavior and a change to the specification arrive in one commit; and treat a slow or flaky acceptance suite as a product problem, not a test problem. The examples are the team's memory of what it agreed.
If the product owner cannot say what the expected value should be, it is still a question. Park it, assign it, and do not let a developer answer it by writing code.
Common failure modes
- Examples written after the code. The tests pass on the first run and nobody learns anything. ATDD's value is in the disagreement it surfaces before coding; without the discuss step it is just automation.
- One person writes all the examples. Usually the tester. The developer treats them as someone else's tests and the product owner never sees them. The three-way conversation is the practice.
- Scenarios as scripts. Twelve steps of click-this, type-that. Acceptance examples describe behavior and outcomes, not user interface mechanics. If a screen changes, the examples should not.
- Too many examples. Forty rows for a story means the rule is not understood or the story is three stories. Distill to the smallest set that would catch a wrong implementation.
- The suite that nobody trusts. Once acceptance tests are slow or flaky, teams stop reading failures. Fix or delete; a suite with 5 percent flaky runs is worth less than no suite (see flaky tests).
Common questions
Is ATDD the same as BDD?
In substance, yes. Both agree on concrete behavior with the business before coding and automate the agreed examples. BDD emphasizes a shared language and the given-when-then form; ATDD emphasizes the workflow and often uses tables. Teams rarely need to choose.
Who should write the acceptance tests?
The examples are written together in the three amigos session. The automation glue that connects an example to the code is usually written by the developer, sometimes paired with the tester. The product owner should be able to read every example without help.
How many examples does a story need?
Three to eight is typical: one happy path, the boundaries of each rule, and the interactions between rules. If you need more, split the story. If you need fewer than three, the story may be too small to be worth a session.
Does ATDD replace exploratory testing?
No. Acceptance tests confirm the behavior the team thought of. Exploratory testing finds the behavior nobody thought of. Teams that do ATDD well still run an exploratory session on each story before calling it done.
What if the product owner will not attend the sessions?
Start with 20 minutes and one story, and show the ambiguity the session found. Product owners attend when they see that the session saves them a rework conversation two weeks later. If attendance stays impossible, a proxy who can make decisions is the minimum; a proxy who has to ask is not.
Should acceptance tests run through the user interface?
Only the few that verify the interface itself. Most examples are about rules and should execute below the interface, against a service or domain layer. That keeps the suite fast and the examples stable when screens change.
Sources
- Gojko Adzic, Specification by Example (book page)
- Martin Fowler, Specification By Example
- Martin Fowler, Given When Then
- Dan North, Introducing BDD
Further reading named in the text
- Gojko Adzic, Bridging the Communication Gap: Specification by Example and Agile Acceptance Testing (Neuri, 2009)
- Ken Pugh, Lean-Agile Acceptance Test-Driven Development: Better Software Through Collaboration (Addison-Wesley, 2011)
- Kent Beck, Test-Driven Development: By Example (Addison-Wesley, 2002)
This guide is part of the agile testing hub. It is best read alongside role of tester in agile teams and definition of done, which cover the neighbouring questions.