ATDD (Acceptance Test-Driven Development)
A collaborative practice where the team defines acceptance tests from the user's perspective before development begins, ensuring shared understanding of requirements.
What it is
ATDD is a collaborative requirements practice where the whole team—business stakeholders, developers, and testers—work together to define acceptance criteria as concrete, testable examples before any code is written. These examples are then automated and become the living acceptance test suite.
The practice is often framed around The Three Amigos:
- Business (Product Owner / BA) — clarifies the problem, desired outcomes, and business rules.
- Development — identifies technical constraints, implementation approach, and edge cases.
- Testing — probes for ambiguity, missing scenarios, and risks from a quality perspective.
By the end of a Three Amigos session, the team has a shared set of acceptance criteria written as executable examples. These examples are automated (often using Gherkin syntax and tools like SpecFlow or Cucumber), run in CI, and operationalise the team's Definition of Done.
When to use it
| Occasion | Why ATDD helps |
|---|---|
| Story refinement / backlog grooming | Clarify acceptance criteria before sizing; expose hidden complexity early. |
| Before development starts | Prevents rework caused by misunderstood requirements. |
| When onboarding new team members | Executable specs document intent better than static requirements. |
| Regulated or compliance-heavy projects | Provides auditable traceability from requirement to test. |
Key concepts
| Concept | Description |
|---|---|
| The Three Amigos | A structured conversation between business, development, and testing to reach shared understanding before implementation. |
| Gherkin Format | Given / When / Then syntax that bridges natural language with automation. Readable by non-technical stakeholders. |
| Executable Specifications | Acceptance criteria written as automated tests that run in CI and always reflect the current system behaviour. |
| Living Documentation | The automated test suite becomes up-to-date documentation that evolves with the codebase. |
Common pitfalls
| Pitfall | How to avoid it |
|---|---|
| Writing tests without business involvement | Always include the Product Owner or BA in Three Amigos. If they can't attend, defer the story. |
| UI-specific tests that break on every layout change | Write acceptance tests at the business-rule layer (API or service level) where possible. |
| Focusing on tooling before requirements | Start with conversation and examples. Tooling comes after the team understands what to build. |
| Treating ATDD as a testing activity only | It is a whole-team practice. Developers must be involved in writing and maintaining the specs. |
| Too many acceptance tests | Focus on the "happy path" and critical edge cases. Don't exhaustively cover what unit tests should catch. |
NZ context
New Zealand's regulated industries—finance, health, and government—often require requirements traceability for audit and compliance purposes. ATDD provides a natural mechanism for this: each acceptance test directly traces back to a business requirement, and every failure is a signal that the system no longer meets agreed criteria.
For teams working under the Privacy Act 2020 or Financial Markets Conduct Act, ATDD examples can include data-privacy and consent scenarios, ensuring compliance is built in from the start rather than bolted on later.
Career level guidance
| Level | Focus | What to practise |
|---|---|---|
| Junior | Participation & comprehension | Attend Three Amigos sessions, ask clarifying questions, read Gherkin scenarios, and learn how acceptance tests map to story criteria. |
| Senior | Facilitation & automation | Facilitate Three Amigos, challenge ambiguous requirements, write Gherkin scenarios, automate acceptance tests, and mentor juniors on testable thinking. |
| Test Lead | Strategy & organisational adoption | Roll out ATDD across squads, choose and maintain tooling, coach Product Owners on writing testable acceptance criteria, and measure defect escape rates pre vs post adoption. |
Industry Reality
- Most teams claim to do ATDD but skip the Three Amigos entirely — a BA writes acceptance criteria solo, hands them to a tester who automates them, and developers never see them until a test fails in CI.
- Gherkin files often drift into "test scripts in disguise" — hundreds of low-level steps that test implementation details rather than user outcomes, making them just as brittle as the UI tests they were meant to replace.
- Product Owners in high-growth NZ startups are frequently too time-poor for pre-sprint Three Amigos sessions; senior testers end up inferring acceptance criteria from Jira comments and Slack threads, then hoping for a quick sign-off.
- The "living documentation" promise is real only if someone actively maintains it — on mature products, 20–30% of Gherkin scenarios can be obsolete or duplicated within 18 months if no one curates the suite.
- In government and finance projects (Revenue NZ, CoverNZ, major banks), ATDD is taken seriously because traceability to requirements is a compliance requirement — these shops invest in proper tooling and dedicated BAs who write testable acceptance criteria.
Context guide
How the right level of Acceptance Test-Driven Development (ATDD) effort changes based on team context.
| Context | Priority | Why |
|---|---|---|
| Revenue NZ or CoverNZ digital service — requirements must trace to policy or legislation for audit | Essential | Each acceptance scenario becomes a traceable link between a legislative rule and the code implementing it. Compliance auditors can point to a passing test as evidence the rule was implemented and tested — without ATDD that evidence has to be assembled manually from Jira tickets and test reports. |
| HealthNZ (HealthNZ) patient data workflow — Privacy Act 2020 obligations in scope | Essential | Consent and data-access rules must be agreed between clinical, legal, and engineering before a single line of code is written. ATDD Three Amigos sessions force that cross-functional alignment; mistakes discovered in UAT on health data flows are costly and sometimes reportable to the Privacy Commissioner. |
| Harbour Bank or Pacific Bank — core banking feature with multiple downstream system integrations | High | Integration boundaries (core banking, card systems, KiwiSaver APIs) multiply the number of edge cases that need to be agreed up front. ATDD acceptance scenarios make integration contracts explicit, so each system owner can validate their portion independently rather than discovering disagreements in end-to-end testing. |
| Wellington-based SaaS startup — small squad, Product Owner embedded in team, shipping weekly | Medium | With a co-located PO and frequent informal conversation, the full Three Amigos ceremony may be heavier than the team needs. Apply the principle (agree acceptance criteria before coding) with a lighter format — a shared Notion doc, a 10-minute alignment huddle, or acceptance criteria written in the story ticket and reviewed synchronously during standup. |
| TransitNZ digital product — high public visibility, tight delivery schedule, mixed stakeholder literacy | Medium | Public-facing government interfaces attract media scrutiny when they fail. Structured Three Amigos sessions help align agency stakeholders who have deep domain knowledge but low technical literacy, translating policy intent into testable criteria without requiring them to read Gherkin files. |
| Internal tooling or prototype — requirements fluid, no compliance obligations, single end-user stakeholder | Low | When requirements are intentionally exploratory and will change weekly, writing acceptance tests before code creates ceremony that slows learning. Favour exploratory development with lightweight unit tests, then introduce ATDD once the feature shape stabilises and the team knows what "done" actually means. |
Trade-offs
What you gain and what you give up when you adopt Acceptance Test-Driven Development (ATDD).
| Advantage | Disadvantage | Use instead when… |
|---|---|---|
| Cross-functional alignment before coding Business, development, and testing all agree on what "done" means before anyone writes code, eliminating the most common source of late-sprint rework. |
Requires sustained stakeholder time Three Amigos sessions add ceremony — typically 30 minutes per story per sprint. In orgs where Product Owners or BAs are shared across multiple squads, this time is hard to protect consistently. |
Requirements are intentionally exploratory and expected to change rapidly — write lightweight unit tests instead and introduce ATDD once the feature shape is stable. |
| Auditable traceability from requirement to test Each acceptance scenario is a direct, automated link between a business rule and the code that implements it — invaluable for Revenue NZ, CoverNZ, or Financial Markets Conduct Act compliance evidence. |
Suite maintenance compounds over time Without active curation, Gherkin suites accumulate obsolete, duplicated, or over-specified scenarios. On a 2-year-old product, 20–30% of scenarios may be stale, making the suite expensive to run and confusing to interpret. |
The team lacks the discipline to prune the suite each sprint — a well-maintained integration test layer may deliver better long-term ROI with less ceremonial overhead. |
| Living documentation that reflects actual system behaviour Because acceptance tests run in CI on every commit, they are always current — unlike static Word documents or Confluence pages that drift within weeks of being written. |
Risk of encoding ambiguity as passing tests When acceptance criteria are automated the same day they are written — before any Three Amigos challenge — misunderstood requirements become tests that pass confidently against wrong behaviour, creating false confidence that is harder to detect than a failing test. |
The team cannot maintain the discipline of challenging acceptance criteria before automating — use specification-by-example workshops without automation to get the alignment benefit without the false-confidence risk. |
| Shifts defect discovery left, reducing rework cost Edge cases and ambiguous business rules surfaced in a 30-minute Three Amigos session cost a fraction of the same issue discovered in UAT, where the story must be reopened, re-estimated, and re-tested. |
Does not replace exploratory testing A complete passing acceptance suite only proves the system meets its specification. Unspecified behaviour — concurrency, accessibility, third-party integration edge cases — has no safety net until someone writes a scenario for it first, which means exploratory testing remains essential. |
The system under test has highly unpredictable user behaviour patterns (e.g. a data migration or infrastructure change) — exploratory and scenario-based testing provide better coverage than pre-specified acceptance scenarios alone. |
Enterprise reality
How ATDD changes at 200–300-developer scale in NZ enterprise — banks, government, telcos
- Three Amigos sessions are no longer ad hoc conversations — at Harbour Bank, formal "Story Readiness" gates require a documented acceptance criteria sign-off before a story enters a sprint, with the BA's approval recorded in Jira as evidence for the Reserve Bank's model risk review process. Manual sign-off ceremonies that work in a 6-person squad become bottlenecks across 15+ squads if not automated via workflow tooling.
- Gherkin suite governance becomes a dedicated role — large government programmes (Revenue NZ, Benefits NZ) appoint a "Feature Engineering Lead" or "Living Documentation Owner" who enforces scenario naming conventions, deduplication rules, and mapping of each scenario to a specific clause of the Privacy Act 2020 or relevant secondary legislation. Without this, a 1,500-scenario suite becomes unmaintainable within 18 months.
- Tooling shifts from team-level Cucumber or SpecFlow to enterprise platforms — Tricentis Tosca, Xray for Jira, or Zephyr Scale handle volume, cross-squad traceability matrices, and NZISM-aligned audit exports that individual SpecFlow projects cannot produce. At TeleNZ scale, acceptance test results must feed a central test management dashboard consumed by architecture review boards, not just CI pipelines.
- Cross-squad coordination requires contract testing alongside ATDD — when 10+ squads share APIs, a passing acceptance suite in one squad can mask a breaking change for another. Enterprises layer Pact or Spring Cloud Contract on top of ATDD so integration boundaries are verified independently; discovering this gap late costs weeks of incident investigation and can trigger change-management obligations under PCI DSS if a payment API is involved.
◆ What I would do
Professional judgment — when to adopt Acceptance Test-Driven Development (ATDD), when to adapt it, and what to watch for.
The bottom line: ATDD's value is in the conversation, not the automation — if your Three Amigos session isn't surfacing at least one requirement ambiguity per story, you're running a status meeting with extra steps, and no amount of Gherkin tooling will fix that.
Best Practices
- ✓ Run Three Amigos as a time-boxed 30-minute conversation per story, not an open-ended workshop — focus on the "what ifs" that expose hidden edge cases.
- ✓ Write acceptance scenarios at the domain / API layer rather than the UI layer; UI tests belong in a separate, smaller suite of critical-journey smoke tests.
- ✓ Keep each scenario focused on a single business rule — one Given/When/Then block per scenario, no multi-step epics masquerading as a single test.
- ✓ Use Background sections in Gherkin to share setup context rather than repeating Given steps across every scenario in a feature file.
- ✓ Treat a failing acceptance test as a requirements conversation, not just a bug — bring the PO and developer together before reopening the story.
- ✓ Gate CI merges on acceptance test passage so the suite stays green; a failing spec that gets bypassed breaks the contract model entirely.
- ✓ Review and prune the acceptance test suite at the end of each sprint — retire scenarios that test deprecated behaviour rather than leaving them skipped.
- ✓ When rolling ATDD out in NZ regulated environments, map each acceptance scenario to a specific privacy, consent, or compliance rule from the outset so the traceability is built in, not retrofitted.
Common Misconceptions
❌ Myth: ATDD is just BDD with a different name.
Reality: ATDD and BDD share tooling (Gherkin, Cucumber, SpecFlow) but have different scopes. ATDD focuses on defining acceptance criteria that drive development — its primary goal is shared understanding of requirements. BDD extends that to describe system behaviour in a ubiquitous language used across the codebase. You can do ATDD without ever writing a single Gherkin file; you cannot do BDD without a shared domain language agreed across the team.
❌ Myth: Once acceptance tests are automated, testers are no longer needed in Three Amigos.
Reality: Automation is the output of ATDD, not the input. Testers bring a risk-oriented perspective to Three Amigos that developers and POs rarely produce naturally — they ask "what happens when the user does X in the wrong order?" and "what's the boundary between valid and invalid?" Removing them from the conversation makes the acceptance criteria narrower and the resulting tests less effective as a safety net.
❌ Myth: A large suite of passing acceptance tests means the software is correct.
Reality: Acceptance tests only validate what the team thought to specify. If the Three Amigos sessions missed an important scenario — a concurrency edge case, a data-privacy boundary, an accessibility requirement — no acceptance test will catch it. ATDD reduces requirements-misunderstanding defects significantly, but it must be combined with exploratory testing, risk-based testing, and security review for complete coverage.
Senior engineer insight
Teams who do ATDD well treat the Three Amigos session as a requirements stress-test, not a rubber-stamp — they bring concrete examples to the meeting and argue about edge cases until the acceptance criteria are genuinely unambiguous. Teams who struggle either skip the session entirely (a BA writes criteria alone) or run it as a status meeting where no one challenges anything. The one pattern that reliably works: start every scenario with "Given a specific named user in a named state" rather than a generic "Given a logged-in user" — specificity forces the room to confront assumptions immediately.
The most common mistake: automating the acceptance tests before the team has reached genuine shared understanding. When testers automate acceptance criteria that no one has challenged, they lock in the ambiguity rather than resolving it — and those tests will pass confidently against the wrong behaviour.
From the field
A Wellington-based fintech squad adopted ATDD for their KiwiSaver contribution adjustment flow. They assumed Three Amigos sessions were just a fancy name for backlog refinement — so they merged the two and let developers write the acceptance criteria to keep things efficient. The first sprint felt fast; the third sprint saw five stories reworked after the Compliance BA reviewed the suite and found the criteria encoded team assumptions about Revenue NZ rounding rules rather than the actual legislative definition. The fix: a dedicated 30-minute pre-refinement session with the BA as the only person allowed to write the Given/When/Then first draft, with developers and testers annotating it. Defect escapes to UAT dropped by 60% over the next quarter. The lesson that travels: whoever owns the business rule must own the first draft of the acceptance criterion — everyone else's job is to poke holes in it.
Why teams fail here
- Skipping the amigo who matters most: Product Owners in fast-moving NZ startups bow out of Three Amigos "just this sprint" — testers infer acceptance criteria from Jira comments, developers build to their own interpretation, and the divergence only surfaces in UAT.
- Gherkin as a test-scripting language: Scenarios balloon into 20-step Given/When/Then chains testing implementation details instead of business rules, making the suite brittle and indistinguishable from the UI automation it was supposed to replace.
- Automating before understanding: Teams rush to automate acceptance criteria the same day they are written, before anyone has challenged the wording — ambiguity gets encoded into passing tests that confidently validate wrong behaviour.
- Treating a green suite as a release gate: Once all acceptance tests pass, teams stop exploratory testing — but ATDD only covers what the team thought to specify; unspecified behaviour (concurrency, accessibility, third-party integration edge cases) has no safety net until someone writes a scenario for it first.
Key takeaway
ATDD done well is not a testing practice — it is a shared-understanding practice where acceptance tests are the artifact that proves the team has agreed on what "done" actually means before anyone writes a line of code.
How this has changed
The field moved. Here is how ATDD (Acceptance Test-Driven Development) evolved from its origins to current practice.
Agile Manifesto published. Ward Cunningham and others articulate the idea that tests should be derived from acceptance criteria agreed between customer and developer. The practice is unnamed but present in early XP teams.
Kent Beck formalises test-driven development in "Test Driven Development: By Example." Brian Marick begins documenting what becomes ATDD — the business-facing counterpart to developer-facing TDD.
Brian Marick coins the term "Agile Testing" and the quadrant model. "Acceptance Test-Driven Development" enters the vocabulary as the practice where acceptance tests are written before implementation, driving development from the outside in.
FIT (Framework for Integrated Tests) and FitNesse enable business-readable acceptance tests written in table form. Gojko Adzic publishes "Bridging the Communication Gap" — a comprehensive guide to specification by example and ATDD.
ATDD is now commonly implemented through BDD tools (Cucumber, SpecFlow) with Given/When/Then syntax that business stakeholders can read and validate. The core principle — acceptance criteria agreed before development begins — survives across many naming conventions.
Self-check questions
Click each question to reveal the answer.
Q: What is the primary goal of a Three Amigos session in ATDD?
A: The primary goal is to reach shared understanding of what needs to be built before development begins. Business, development, and testing perspectives are combined to surface ambiguity, hidden edge cases, and missing requirements — producing a concrete set of acceptance criteria the whole team agrees on.
Q: What does "executable specification" mean in the context of ATDD?
A: An executable specification is an acceptance criterion written in a form that can be run as an automated test, typically using Gherkin syntax (Given/When/Then). Because the spec is code, it can be run in CI on every commit, meaning it always reflects the actual behaviour of the system rather than becoming stale documentation.
Q: Why should acceptance tests generally be written at the API or service layer rather than the UI layer?
A: UI acceptance tests break every time a layout or selector changes, even when the underlying business rule is unchanged. API or service-layer tests are more stable because they target business logic directly, run faster, and give clearer failure messages — making the suite maintainable long-term.
Q: Name two NZ regulated industries where ATDD's traceability is especially valuable and explain why?
A: Financial services (e.g. KiwiSaver providers under the Financial Markets Conduct Act) and government agencies (e.g. Revenue NZ, CoverNZ) benefit most. Both require evidence that software meets specified requirements for audit purposes. ATDD acceptance tests provide a direct, automated link between a business requirement and the code that satisfies it, making compliance audits substantially easier.
Q: What is the risk of having too many acceptance tests in a suite?
A: An oversized acceptance test suite slows CI pipelines, is expensive to maintain, and often duplicates what unit or integration tests should cover. Acceptance tests should focus on the happy path and critical edge cases that represent genuine business rules. Low-level detail belongs in unit tests, keeping the acceptance suite small, fast, and focused on user outcomes.
Q: Your team is building a new income declaration flow on the Benefits NZ benefit portal. A story has been refined, but the Product Owner is unavailable for a Three Amigos session this sprint. Should you proceed with writing acceptance tests or defer the story — and why?
A: Defer the story, or at minimum escalate the risk. The business representative is essential to ATDD because the acceptance criteria must reflect actual policy intent — not the testing team's assumptions about how Benefits NZ income rules work. Writing acceptance tests without PO input risks encoding the wrong rules into the definition of done, causing rework after compliance review. A 30-minute Three Amigos session next sprint is far cheaper than discovering a policy breach in production.
Q: An Revenue NZ digital project team has 200 Gherkin scenarios, all passing in CI. A new tax rule changes how student loan repayments are calculated for overseas-based borrowers. Why does ATDD not guarantee the change is safe to release without additional work?
A: ATDD only validates what was specified in the acceptance criteria. If no Three Amigos session produced scenarios covering overseas-based borrower edge cases under the new rule, those paths have no acceptance tests and no safety net. The team still needs to run a new Three Amigos session for the changed rule, write new acceptance scenarios, and supplement with exploratory testing to surface unspecified interactions — such as how the change interacts with hardship exemptions or auto-repayment thresholds.
Q: What is the key difference between ATDD and BDD, given they both use Gherkin syntax and tools like SpecFlow?
A: ATDD is primarily a requirements-discovery practice — its goal is to align the team on what to build by writing acceptance criteria as testable examples before development starts. BDD extends this with a focus on expressing system behaviour in a ubiquitous domain language shared across the entire codebase and team conversations. You can practise ATDD using plain English acceptance criteria or spreadsheets; BDD specifically requires the team to agree on and consistently use domain language. Shared tooling (Gherkin/SpecFlow) does not make the practices identical.
Q: A developer on your team says "We have 150 passing acceptance tests so we don't need to do exploratory testing before the RealMe integration release." What is wrong with this claim and how do you respond?
A: Acceptance tests only cover scenarios the team thought to specify in Three Amigos sessions. They cannot catch missing edge cases, unspecified concurrency issues, accessibility gaps, or interactions between the RealMe identity layer and downstream systems that were never discussed. A large passing suite proves the system meets its agreed specification — it does not prove the specification was complete. Respond by noting that exploratory testing specifically targets unspecified risk: the testers probe areas where the team's assumptions about RealMe session handling, token expiry, or fail-over behaviour may be wrong, which no acceptance test can cover until someone first thinks to write the scenario.