Behaviour- and Acceptance-Driven Development
Drive software from concrete, agreed examples of behaviour. Discover them in conversation, formulate them as Given-When-Then scenarios, and keep the executable scenarios as living documentation. The acceptance layer answers "are we building the right thing?" The inner domain logic is still driven test-first by tdd-guide. ATDD and BDD are two names for this one practice.
Essentials
- Discover before you formulate - run a three-amigos conversation over real examples first, see references/discovery-three-amigos.md
- Map examples to size and split the story - yellow/blue/green/red cards expose scope and gaps, see references/discovery-three-amigos.md
- Write scenarios in Gherkin Given-When-Then - Feature, Scenario, Background, Outline; declarative steps, see references/gherkin-reference.md
- Treat scenarios as living documentation - specs and tests become one trustworthy artefact, see references/specification-by-example.md
Gotchas
- Gherkin/Cucumber is a collaboration tool that tests the team's shared UNDERSTANDING of unwritten software, not a testing tool: automation is the third practice, never the purpose, see references/appendix-discovery.md.
- "Three amigos" means three PERSPECTIVES (business / development / testing), not exactly three people: invite more; the conversation is the point.
- Driving scenarios end-to-end through the UI/browser is slow, volatile, and fails to localise the bug: stub external services/queues/DBs and drive the core domain directly.
- Given-When-Then is the recommended template, not the goal; the essential thing is concrete agreed examples, so do not over-engineer the grammar with deep nesting or imperative "click button X" steps.
- ATDD and BDD are not rival methodologies: same example-driven, acceptance-level idea; do not split the practice in two.
- A rule that needs many examples to pin down is a signal to split the rule, not to write ten scenarios, and a rule simple enough to need none needs none; the count is emergent, not a quota.
Example
Feature: Assign the best nearby taxi
Rule: A closer taxi with a higher rating wins
Scenario: Close taxi with higher rating is preferred
Given taxi A with rating 0.8 is 1400m from the customer
And taxi B with rating 0.9 is 1500m from the customer
When the customer requests a taxi
Then taxi B should be assigned
Progressive Disclosure
- Read references/gherkin-reference.md - Load when writing or reviewing feature files: keyword meanings, file structure, declarative vs imperative steps.
- Read references/discovery-three-amigos.md - Load when running discovery: the three perspectives, the workshop, and example-mapping card colours.
- Read references/specification-by-example.md - Load when establishing the process: the seven patterns, specs-as-tests, and trustworthy living documentation.
- Read references/appendix-discovery.md - Load when you need the underlying framing: testing understanding vs software, the three practices, and stubbing externals to drive the core.
1---2name: bdd-guide3description: Use when driving software from concrete agreed examples of behaviour: running three-amigos discovery and example mapping before coding, formulating Given-When-Then scenarios in feature files, and treating them as living documentation that tests the team their shared understanding. ATDD and BDD are one practice here. Triggers on BDD, ATDD, Gherkin, Given-When-Then, Cucumber, feature file, scenario / scenario outline, three amigos, example mapping, specification by example, living documentation, acceptance-test-driven, even when the user doesn't say 'BDD'.4---56# Behaviour- and Acceptance-Driven Development78Drive software from concrete, agreed examples of behaviour. Discover them in conversation, formulate them as Given-When-Then scenarios, and keep the executable scenarios as living documentation. The acceptance layer answers "are we building the right thing?" The inner domain logic is still driven test-first by **tdd-guide**. ATDD and BDD are two names for this one practice.910## Essentials1112- **Discover before you formulate** - run a three-amigos conversation over real examples first, see [references/discovery-three-amigos.md](references/discovery-three-amigos.md)13- **Map examples to size and split the story** - yellow/blue/green/red cards expose scope and gaps, see [references/discovery-three-amigos.md](references/discovery-three-amigos.md)14- **Write scenarios in Gherkin Given-When-Then** - Feature, Scenario, Background, Outline; declarative steps, see [references/gherkin-reference.md](references/gherkin-reference.md)15- **Treat scenarios as living documentation** - specs and tests become one trustworthy artefact, see [references/specification-by-example.md](references/specification-by-example.md)1617## Gotchas1819- Gherkin/Cucumber is a **collaboration** tool that tests the team's shared UNDERSTANDING of unwritten software, not a testing tool: automation is the third practice, never the purpose, see [references/appendix-discovery.md](references/appendix-discovery.md).20- "Three amigos" means three PERSPECTIVES (business / development / testing), not exactly three people: invite more; the conversation is the point.21- Driving scenarios end-to-end through the UI/browser is slow, volatile, and fails to localise the bug: stub external services/queues/DBs and drive the core domain directly.22- Given-When-Then is the recommended template, not the goal; the essential thing is concrete agreed examples, so do not over-engineer the grammar with deep nesting or imperative "click button X" steps.23- ATDD and BDD are not rival methodologies: same example-driven, acceptance-level idea; do not split the practice in two.24- A rule that needs many examples to pin down is a signal to split the rule, not to write ten scenarios, and a rule simple enough to need none needs none; the count is emergent, not a quota.2526## Example2728```gherkin29Feature: Assign the best nearby taxi3031 Rule: A closer taxi with a higher rating wins3233 Scenario: Close taxi with higher rating is preferred34 Given taxi A with rating 0.8 is 1400m from the customer35 And taxi B with rating 0.9 is 1500m from the customer36 When the customer requests a taxi37 Then taxi B should be assigned38```3940## Progressive Disclosure4142- Read [references/gherkin-reference.md](references/gherkin-reference.md) - Load when writing or reviewing feature files: keyword meanings, file structure, declarative vs imperative steps.43- Read [references/discovery-three-amigos.md](references/discovery-three-amigos.md) - Load when running discovery: the three perspectives, the workshop, and example-mapping card colours.44- Read [references/specification-by-example.md](references/specification-by-example.md) - Load when establishing the process: the seven patterns, specs-as-tests, and trustworthy living documentation.45- Read [references/appendix-discovery.md](references/appendix-discovery.md) - Load when you need the underlying framing: testing understanding vs software, the three practices, and stubbing externals to drive the core.
xonovex