Behavior-Driven Development
An agile testing practice that uses natural language scenarios to describe system behaviour, fostering collaboration between technical and non-technical stakeholders.
What It Is
Behavior-Driven Development (BDD) extends TDD by shifting the focus from technical tests to shared understanding of system behaviour. It uses a structured natural language format, Given-When-Then, to describe how a feature should behave in various scenarios. These scenarios are written collaboratively by developers, testers, and business representatives, ensuring everyone speaks the same language before any code is written.
BDD was popularised by Dan North as a response to the confusion many teams felt when adopting TDD. By framing tests as behaviour specifications rather than unit-test mechanics, BDD makes the practice accessible to product owners, business analysts, and domain experts who may not read code.
Given-When-Then Format
Each scenario follows a simple structure:
- Given some initial context or precondition
- When an action or event occurs
- Then an expected outcome is observed
This format is concrete enough to be automated, yet readable enough for non-technical stakeholders to validate.
When to Use It
BDD shines in contexts where clear communication between technical and business teams is critical:
- Complex domain logic: Insurance, finance, healthcare, and compliance-heavy systems benefit from explicit examples that domain experts can review.
- Cross-functional teams: When product owners, testers, and developers work closely, BDD provides a shared vocabulary that reduces translation errors.
- Regulated industries: Scenarios become auditable evidence that requirements were understood and met.
- Remote or asynchronous teams: Written scenarios replace hallway conversations and serve as durable reference material.
- Legacy system replacement: BDD scenarios capture existing behaviour so the new system can be validated against it.
BDD may be overhead for simple CRUD applications or internal tools with no external business stakeholder. Use judgment: if no one outside engineering will read the scenarios, lightweight unit tests may suffice.
Key Concepts
Given-When-Then
The structured grammar that makes BDD scenarios predictable and automatable. It separates preconditions, actions, and outcomes so that each scenario has a single, clear purpose. Multiple Givens or Thens are allowed, but each scenario should exercise only one behaviour.
Feature Files
Scenarios are collected in feature files, typically one per major capability. A feature file contains a narrative description (the user story) followed by concrete examples (the scenarios). Tools such as Cucumber, SpecFlow, or Behave parse these files and bind each step to test automation code.
Living Documentation
Because feature files are executed by automated test runners, they stay current. Unlike Word documents or wikis, living documentation cannot drift out of date without the build breaking. This makes it a trustworthy reference for new team members, auditors, and support staff.
Ubiquitous Language
Borrowed from Domain-Driven Design, ubiquitous language means using the same terms in scenarios, code, and conversation. If the business says policyholder, the code should say Policyholder, not User or CustomerEntity. This alignment eliminates the mental translation tax that causes so many bugs.
| Concept | Description | Tool Examples |
|---|---|---|
| Feature File | Human-readable document containing scenarios for one capability | Cucumber .feature, SpecFlow .feature, Behave .feature |
| Step Definition | Code that binds a natural language step to automation logic | Cucumber JVM, Cucumber JS, SpecFlow bindings |
| Scenario Outline | Parameterized scenario run against multiple data sets | Examples table in Gherkin syntax |
Common Pitfalls
Scenarios Too Technical
When scenarios read like API test scripts or SQL queries, business stakeholders stop reading them. If the product owner cannot understand a scenario without a developer translating, the scenario has failed its primary purpose. Keep the language business-oriented and push technical details down into step definitions.
Business Disengaging
BDD depends on active business participation. If scenarios are written solely by testers or developers, they become a slower form of traditional test scripting. Schedule regular Three Amigos sessions and keep scenarios short enough that a business representative can review them in minutes, not hours.
Brittle UI-Focused Scenarios
Scenarios that reference CSS selectors, button IDs, or page layouts break every time the UI changes. BDD should describe behaviour, not presentation. Use page objects, component models, or API bindings to isolate the scenario text from implementation churn.
The New Zealand Context
New Zealand software projects often involve non-technical clients in agriculture, government, or small business who need transparent confirmation that their investment is delivering the right outcomes. BDD scenarios provide that transparency in plain English, building trust and reducing the risk of expensive rework.
Many New Zealand teams are distributed across Auckland, Wellington, Christchurch, and remote workers in smaller centres. Written scenarios serve as durable contracts between these locations, reducing the need for repeated clarification calls. They also help when outsourcing or nearshoring parts of development: a well-written feature file is a clearer brief than a user story alone.
Local compliance requirements, such as those from the Privacy Act or sector-specific regulators, can be encoded directly into scenarios. A feature titled Data retention policy ensures personal data is deleted after two years becomes both a requirement and an automated compliance check.
Career Level Guidance
| Level | Focus | Milestones |
|---|---|---|
| Junior | Write readable Given-When-Then scenarios; implement step definitions; run feature files locally | Can translate a user story into 3-5 scenarios; step definitions are clean and reusable; no UI selectors in feature text |
| Senior | Facilitate Three Amigos sessions; design test architecture; keep living documentation current | Leads scenario workshops; designs page object / API abstraction layers; reviews feature files for business clarity |
| Test Lead | Define BDD standards; integrate with CI/CD; measure scenario coverage and business engagement | Sets organisation-wide BDD conventions; tracks scenario-to-story coverage; trains product owners to write scenarios |
Industry Reality
- Most teams adopt the syntax of BDD (Given-When-Then) without the collaborative practice — scenarios are written after the fact by testers alone, producing what practitioners call "Given-When-Then unit tests" with zero business involvement.
- Three Amigos sessions are widely recognised as valuable but frequently skipped under sprint pressure; senior practitioners often run them informally as a ten-minute Slack thread or stand-up sub-conversation rather than a formal workshop.
- Feature files drift quickly in fast-moving codebases. Teams commonly freeze scenario vocabulary at release boundaries rather than updating continuously, meaning living documentation lives for months then goes stale in a single big refactor.
- In New Zealand government and insurance projects, BDD scenarios are sometimes accepted by auditors as evidence of requirements sign-off — giving testers who can write clear, non-technical Gherkin a distinct professional advantage in regulated sectors.
- Many shops replace Cucumber or SpecFlow with plain-language docstrings inside standard test frameworks (pytest, RSpec) to avoid the glue-code overhead, preserving the collaborative intent while simplifying the toolchain.
Context guide
How the right level of Behaviour-Driven Development (BDD) effort changes based on team context.
| Context | Priority | Why |
|---|---|---|
| Government or regulated service (Benefits NZ, Revenue NZ, CoverNZ, HealthNZ) with engaged policy staff | Essential | Complex eligibility rules and legislative requirements need domain-expert sign-off on each scenario. Feature files serve as auditable evidence that policy intent was implemented correctly. |
| Financial services (Harbour Bank, Pacific Bank, KiwiSaver providers) with non-technical product owners | Essential | Financial calculation logic (interest, fees, contribution matching) is easily misunderstood. Given-When-Then examples let product owners validate every calculation boundary before code ships, reducing expensive regulatory remediation. |
| Distributed NZ team with members across Auckland, Wellington, and Christchurch | High | Written scenarios replace hallway conversations that never happen across locations. Feature files become durable shared references that survive timezone gaps, shift handovers, and staff turnover. |
| Privacy Act 2020 or NZISM-scoped project handling personal data | High | Compliance obligations (data retention, access control, breach notification) can be encoded as executable scenarios. A passing BDD suite demonstrates to a Privacy Commissioner audit that each obligation was explicitly tested. |
| Small internal tooling project (fewer than 3 stakeholders, no external users) | Low | If no one outside engineering will read the scenarios, the overhead of Gherkin tooling and workshop facilitation outweighs the benefit. Lightweight unit tests and plain acceptance criteria in Jira are sufficient. |
| Legacy replacement for Pacific Air or TeleNZ systems with undocumented behaviour | High | Reverse-engineering scenarios from the old system creates a behaviour contract that the new system must satisfy. This is often the only reliable way to capture tribal knowledge held by staff who built the legacy product. |
Trade-offs
What you gain and what you give up when you adopt Behaviour-Driven Development (BDD).
| Advantage | Disadvantage | Use instead when… |
|---|---|---|
| Requirements gaps surface in workshop, not UAT — misunderstandings are caught while changes are still free | Three Amigos sessions require sustained business participation; if the product owner disengages after two sprints, BDD silently reverts to scripted testing with higher overhead | The product owner is unavailable or unwilling to engage with scenarios — use plain acceptance criteria in Jira instead |
| Feature files become living documentation that cannot drift without the build breaking — unlike Word documents or Confluence pages | Glue-code layer (step definitions) adds significant maintenance overhead; each refactor can break dozens of steps, and the cost grows with scenario count | The team is small and technical — plain docstrings in pytest or RSpec preserve the intent with far less tooling overhead |
| Scenario Outline with Examples tables makes data-driven testing readable to business stakeholders — complex eligibility matrices become self-documenting | BDD scenarios operate at acceptance-test level and are slow; a suite of 300 scenarios can take 30+ minutes to run, creating friction in fast CI pipelines | Speed is the priority and business readability is not needed — use parameterised unit tests or property-based testing at a lower level |
| Passing feature files are accepted by regulators and auditors (including NZ government procurement) as evidence that requirements were understood and implemented | BDD only covers anticipated behaviour — exploratory testing, chaos testing, and security testing are still required to find what nobody specified in advance | The primary risk is unexpected system behaviour rather than misunderstood requirements — invest in exploratory and chaos testing instead |
Enterprise reality
How BDD changes when 200–300 developers across 10+ squads are running it simultaneously — banks, government agencies, and telcos in New Zealand face a different set of problems than a 5-person startup.
- Three Amigos sessions are replaced by automated scenario-generation pipelines at scale. Harbour Bank runs Cucumber-JVM with a shared step-definition library maintained by a dedicated BDD platform team — individual squads write feature files but cannot publish step definitions without a pull request review, preventing the duplicate-step explosion that kills maintainability in 300+ file suites.
- Governance becomes a first-class concern. Under the Privacy Act 2020 and NZISM, government agencies such as Benefits NZ and Revenue NZ require that every scenario touching personal data carries a compliance tag (@privacy-act, @pci-dss for card data) and is included in a signed-off audit artefact before go-live. A missing tag means the release is blocked — not just a test failure, a compliance event.
- Volume demands specialised tooling. Serenity BDD, Cucumber Cloud (Cucumber.io), and Xray for Jira are common in large NZ enterprises because they generate traceability reports linking each scenario to a user story, a JIRA ticket, and a CI build — something that grep and HTML reports cannot do at 5,000-scenario scale. Without traceability tooling, scenario-to-requirement mapping becomes a manual spreadsheet that nobody trusts.
- Coordinating across 10+ squads introduces scenario ownership conflicts and language drift that simply do not exist on small teams. When TechServNZ delivers programmes with separate squads for front end, API, and integration, a term used consistently in one squad's feature files (e.g. "customer" vs "account holder") may conflict with another squad's ubiquitous language, causing step-definition collisions in the shared Cucumber runtime. Enterprise BDD requires a language governance council — usually the test chapter lead and product architecture — to arbitrate terminology before scenarios are written, not after the clash appears in the pipeline.
◆ What I would do
Professional judgment — when to adopt Behaviour-Driven Development (BDD), when to adapt it, and what to watch for.
@privacy-act and @compliance so the CI pipeline can produce a filtered HTML report containing only those scenarios for the legal review package. I would be explicit with the team that a “passing scenario” is not the same as “compliant system” — scenarios only prove we implemented what we specified; the legal team’s job is to verify that the specification itself reflects the Act correctly before scenarios are written.The bottom line: BDD earns its overhead only when the conversation it forces is the thing preventing defects — if no one outside engineering will ever read a scenario, replace Gherkin with plain docstrings and spend the saved hours on exploratory testing.
Best Practices
- ✓ Write scenarios in the language of the domain, not the UI — if a button label or field name changes, your scenario text should not need to change.
- ✓ Cap each feature file at around ten scenarios; more than that signals the feature is too broad and should be split.
- ✓ Use Scenario Outline with an Examples table to cover multiple data combinations without duplicating prose.
- ✓ Treat step definitions as a thin glue layer only — business logic belongs in production code, not in step definitions.
- ✓ Establish a shared step vocabulary early and curate it: duplicated or near-duplicate steps are a strong signal that the team's ubiquitous language is fragmented.
- ✓ Tag scenarios by risk or priority (e.g., @smoke, @regression, @compliance) so CI pipelines can run fast subsets and full suites separately.
- ✓ Always include at least one negative or edge-case scenario per feature — happy-path-only BDD suites give false confidence and miss the failures that matter most.
- ✓ Publish generated HTML reports to an internal wiki or share with product owners after each sprint — the moment scenarios become invisible to the business, BDD's core value evaporates.
Common Misconceptions
❌ Myth: BDD is just a different syntax for writing automated tests.
Reality: The automation is a by-product. BDD is fundamentally a communication and requirements practice; the executable scenarios are the artifact of shared understanding, not the goal. Teams that adopt Gherkin without the collaborative workshops get slower test automation with no improvement in requirements quality.
❌ Myth: BDD replaces unit testing and exploratory testing.
Reality: BDD scenarios operate at the acceptance-test level and describe feature behaviour from a user perspective. They complement, not replace, unit tests (which verify internal logic quickly) and exploratory testing (which finds issues no specification anticipated). A healthy test strategy needs all three layers.
❌ Myth: Once you have a suite of passing BDD scenarios, your documentation is done.
Reality: Scenarios document intended behaviour at the time they were written. As the product evolves, scenarios must be actively maintained. "Living documentation" only lives if the team treats feature files with the same care as production code — including regular refactoring and deletion of obsolete scenarios.
Senior engineer insight
The teams that get the most from BDD are the ones who treat scenario workshops as design sessions, not documentation sessions — when the Three Amigos conversation surfaces a disagreement about what "approved" actually means, that is the moment BDD is earning its keep. The teams that struggle have usually installed the tooling (Cucumber, SpecFlow) but skipped the collaboration, so their feature files are comprehensive test scripts that nobody outside engineering has ever read. The single pattern that consistently works is the "example mapping" card exercise: write each rule on an index card, each example on a yellow card, and each open question on a red card. If you walk out of a story workshop with more red cards than yellow ones, you are not ready to start the sprint.
The most common mistake: automating scenarios too early. Teams wire up Cucumber on day one, spend two weeks building glue code, and then discover the business requirements were wrong anyway. Write the scenarios, read them aloud with the product owner, and only automate once the conversation is settled — the automation is the last step, not the first.
From the field
A Wellington-based team building a KiwiSaver withdrawal portal adopted Cucumber because the product owner had read about BDD and was enthusiastic. The testers wrote every scenario themselves after sprint planning, translating JIRA acceptance criteria into Gherkin, and the suite grew to over 300 feature files in eight months. The assumption was that living documentation would keep everyone aligned. What actually happened was that the product owner stopped attending Three Amigos sessions within three sprints ("you're covering it in the feature files, right?"), two critical eligibility rules were specified ambiguously and both interpretations passed the scenarios, and a Privacy Commissioner audit flagged that the scenarios described the originally intended behaviour rather than what the legislation actually required. The team restructured: scenarios were co-written in workshop using example mapping, the product owner signed off on each scenario before a story was picked up, and a compliance lead was added as a fourth Amigo for any feature touching personal data. The lesson that applies beyond that team: BDD does not eliminate misunderstanding, it creates a structured moment to surface it — and if you skip that moment, the scenarios record the misunderstanding in executable form and make it harder to spot.
Why teams fail here
- Gherkin without the conversation: Teams adopt Given-When-Then syntax as a test formatting convention and skip the Three Amigos workshop entirely. The scenarios become slower test scripts with no improvement in shared understanding — the most common failure mode in NZ agile shops.
- Business disengagement after launch: The product owner co-writes the first sprint's scenarios enthusiastically, then stops attending workshops as velocity pressure mounts. Within two sprints testers are writing all scenarios alone, and BDD has silently reverted to scripted testing with extra overhead.
- Scenario explosion and maintenance debt: Without a deliberate curation policy, feature files multiply faster than the team can maintain them. Passing scenarios for deleted features, duplicate step definitions with minor wording differences, and thousand-row Examples tables that nobody reviews — all signal a suite in decline.
- Implementation language leaking into feature text: Developers under time pressure write scenarios referencing database states, API endpoints, or CSS selectors. The feature text becomes unreadable to business stakeholders, the scenario breaks on any UI refactor, and the living documentation is no longer living or documented — it is a brittle integration test with a Gherkin costume.
Key takeaway
BDD done well is not a testing tool — it is a structured conversation that happens to produce executable documentation; the scenarios are the receipt for shared understanding, not the product of automated test authoring.
How this has changed
The field moved. Here is how Behaviour-Driven Development (BDD) evolved from its origins to current practice.
Dan North invents BDD while coaching TDD at a UK bank. The core insight: rename "test" to "behaviour" and structure tests as "should" statements. This reframing makes tests meaningful to non-developers.
Cucumber created by Aslak Hellesøy. Given/When/Then syntax provides a business-readable format bridging specification and automated test. Gherkin feature files become the BDD vocabulary.
Three Amigos practice (BA, developer, tester jointly authoring scenarios before sprint) emerges as the "conversation" that makes BDD work. Gojko Adzic frames BDD as a communication practice, not just a testing framework.
SpecFlow, Behat, Jasmine, and Behave bring BDD to every major platform. The backlash grows — teams using BDD purely as test automation without the three-amigos conversation find it adds overhead without value.
AI tools can draft Gherkin scenarios from user stories and detect duplicate scenarios. The value of BDD remains in the collaboration it forces — the scenarios are a by-product of shared understanding, not the goal.
Self-Check
Click each question to reveal the answer.
Q: Your team at Benefits NZ is building a new benefit eligibility portal. The product owner is available and engaged, but the scenarios are currently being written by the testers alone after the user story is signed off. What is wrong with this approach, and what would you change?
A: Writing scenarios after sign-off and without the product owner defeats BDD's core purpose: shared understanding before implementation. The scenarios become a slower form of scripting rather than a communication tool, and any misunderstandings in the story are locked in by the time testing starts. The fix is to hold a Three Amigos session before the sprint begins — bring the developer, tester, and product owner together to draft scenarios from the acceptance criteria, surfacing ambiguities while changes are still cheap.
Q: An TransitNZ road-user charge system has a complex eligibility rule: trucks over 3.5 tonnes pay differently depending on axle count and whether they carry hazardous goods. Would BDD be a good fit here, and why?
A: Yes — this is an ideal BDD scenario. The rule involves multiple interacting variables that domain experts (transport policy staff) understand far better than developers, and it is exactly the kind of complex domain logic where Given-When-Then examples anchor shared understanding. A Scenario Outline with an Examples table covering axle counts, weight bands, and hazardous-goods flags lets the policy team validate each combination directly in the feature file, and the same file becomes auditable evidence that each rule was implemented correctly.
Q: What is the key difference between BDD and ATDD (Acceptance Test-Driven Development), and when would you choose one over the other?
A: Both practices define acceptance criteria before implementation and automate them as tests, but BDD prescribes the Given-When-Then grammar and emphasises ubiquitous language so that scenarios are readable by non-technical stakeholders. ATDD is a broader term for any approach where acceptance tests drive development — it does not mandate a specific format. Choose BDD when you have business stakeholders who will actively read and validate scenarios; lean toward a lighter ATDD approach (e.g., plain-English docstrings in pytest) when the team is small, the domain is technical, and the overhead of Gherkin tooling outweighs the communication benefit.
Q: A developer on your team says "We have 200 passing Cucumber scenarios, so we don't need exploratory testing anymore — everything is covered." What is wrong with this claim, and how do you respond?
A: BDD scenarios only cover behaviours that were anticipated and specified before implementation. Exploratory testing discovers issues no specification predicted — edge cases, usability problems, unexpected interactions between features, and emergent bugs that arise from real user behaviour. A suite of 200 passing scenarios gives confidence that the system behaves as intended, not that it behaves correctly under all conditions. The right response is to explain that BDD and exploratory testing target different risk surfaces and a healthy test strategy needs both, along with fast unit tests that verify internal logic independently.