Planning Bdd Atdd

BDD and ATDD

Purpose

Drive development through shared examples and executable specifications using Behavior-Driven Development and Acceptance Test-Driven Development. Ensures shared understanding across business and technical stakeholders, produces living documentation that stays in sync with the code, and enables automated validation of business rules.

Agent Protocol

Trigger

"BDD", "ATDD", "behavior-driven development", "acceptance test-driven development", "Gherkin", "Cucumber", "SpecFlow", "specification by example", "executable specification", "living documentation", "three amigos", "example mapping", "acceptance criteria", "scenario", "feature file", "step definition".

Input Context

• Feature or user story to be implemented
• Business rules and acceptance criteria (existing or to be defined)
• Technical stack: programming language, test framework, BDD tool
• Key examples of expected behavior (inputs, outputs, edge cases)
• Stakeholders available for three amigos session
• Existing test infrastructure (CI pipeline, reporting)

Output Artifact

Gherkin feature files with scenarios, step definition stubs, and example maps that serve as executable specifications and living documentation.

Response Format

## Feature: {name}
{feature description in business language}

### Scenario: {scenario name}
Given {precondition}
When {action}
Then {expected outcome}

### Scenario Outline: {name}
Given {precondition with <placeholder>}
When {action with <placeholder>}
Then {expected outcome with <placeholder>}

Examples:
| placeholder1 | placeholder2 |
| value1       | value2       |

## Example Map
{structured examples table: Rule | Example | Expected Result}

No preamble. No postamble. No explanations.

Completion Criteria

• Feature files written in Gherkin with business-readable language
• Scenarios cover happy path, error cases, and edge cases
• Scenario Outlines used for data-driven scenarios
• Step definitions mapped to automation implementation
• Three amigos session completed with shared understanding
• Example map documented linking rules to concrete examples
• Tags applied for organization and selective execution
• CI pipeline configured to run feature files as automated tests

Max Response Length

7000 tokens

Decision Trees

When to Use BDD vs ATDD vs Both

Are you defining acceptance criteria for a user story?
  |-- YES --> Is there ambiguity in business rules?
  |     |-- YES --> Use Three Amigos + Example Mapping first
  |     |     Output: shared understanding, concrete examples
  |     |-- NO --> Is the feature complex with many edge cases?
  |           |-- YES --> Use ATDD with example mapping
  |           |-- NO --> Use standard acceptance criteria
  |-- NO --> Are you automating validation of business rules?
        |-- YES --> Use BDD with Gherkin + step definitions
        |-- NO --> Consider unit or integration tests instead

Are you writing automated tests for an existing feature?
  |-- YES --> Are you adding new behavior?
  |     |-- YES --> BDD (write scenarios first)
  |     |-- NO --> Integration or unit tests
  |-- NO --> Start with Three Amigos

Gherkin Structure Decision Tree

How many data variations does the scenario need?
  |-- 1 set of values --> Use Scenario (Given-When-Then)
  |-- 2-10 sets --> Use Scenario Outline + Examples table
  |-- 10+ sets --> Use Scenario Outline + Data Table from external source
  |-- Dynamic/runtime data --> Use Scenario with Data Table

Does the scenario need setup steps shared across scenarios?
  |-- YES --> Use Background section
  |-- NO --> Keep Given steps in each scenario

BDD Maturity Model

Workflow

Step 1: Three Amigos Session

Bring together business analyst (what problem to solve), developer (how to build it), and tester (what could go wrong). Walk through the feature or story. Define shared vocabulary — agree on the terms used in scenarios. Identify key examples that capture the behavior. Surface assumptions and implicit rules early. The output is a shared understanding and a set of concrete examples, not a specification document.

Session structure: 30-60 minutes, whiteboard or digital collaboration tool. Begin with the feature description. Each amigo describes their understanding. Identify differences in interpretation — those are the highest-value areas for examples. Document rules explicitly. Capture questions for follow-up. End with 3-10 concrete examples.

Step 2: Example Mapping

Structure examples using the example mapping format. Rules define business logic and constraints. Examples are concrete input/output pairs that illustrate the rule. Questions are things the group doesn't know yet. New stories are things discovered that are out of scope. Arrange on a physical or digital board: rules in yellow, examples in green, questions in purple, new stories in red. This visual structure reveals gaps and duplicates immediately.

Step 3: Write Gherkin Scenarios

Convert examples into Gherkin scenarios. Use Scenario for single examples and Scenario Outline + Examples table for data-driven scenarios. Follow the Given-When-Then structure: Given sets up preconditions, When performs the action, Then verifies outcomes. Use And/But for multiple conditions. Write in business language, not implementation details. Each scenario tests one behavior. Add tags for organization and selective execution.

Step 4: Implement Step Definitions

Map Gherkin steps to automated code. Use parameterization for dynamic values. Apply hooks for cross-cutting concerns (database setup, authentication, cleanup). Use page objects or domain-specific helpers to keep step definitions readable. Run scenarios early and often. Red-green-refactor for ATDD: write failing scenario, implement feature code, make it pass, refactor.

Step 5: Maintain Living Documentation

Integrate feature files into CI pipeline. Generate HTML reports from test execution. Share reports with stakeholders as living documentation. Review feature files regularly — outdated scenarios that pass are worse than failing scenarios. Treat feature files as executable requirements, not test scripts. When business rules change, update the scenario first, then implement.

Gherkin Syntax Reference

Core Keywords

Tags for Organization

@smoke @regression @checkout
Feature: Payment Processing

@critical @P0
Scenario: Successful credit card payment

Rule Groups (Gherkin 6+)

Feature: Shipping

  Rule: Free shipping for orders over $50
    Example: Order of $75 qualifies
      Given ...

  Rule: Express shipping costs $15
    Example: Standard address within 48 states
      Given ...

Example Maps

Template

| Rule | Example | Input | Expected Result |
|------|---------|-------|-----------------|
| {business rule} | {concrete scenario} | {specific values} | {expected outcome} |

Rules vs Examples

Common Anti-Patterns

1. Implementation Details in Gherkin

Writing UI element selectors, API endpoints, or database queries in scenarios. Scenarios become brittle — any UI change breaks tests that validate business rules, not UI behavior. Fix: write in business language. "When the user logs in" not "When the user enters 'admin' into the #username field and 'pass123' into the #password field and clicks the #submit-button".

2. God Scenarios

Scenarios that test multiple behaviors with multiple Then assertions. When the scenario fails, you don't know which behavior broke. Fix: one behavior per scenario. If a scenario has multiple Then statements testing different outcomes, split into multiple scenarios.

3. Scenario Outline Overuse

Using Scenario Outline for every scenario instead of evaluating whether each data variation tests distinct behavior. Leads to unreadable scenarios with 50-row Examples tables. Fix: identify equivalence classes. Test one example per class. Add boundary tests separately.

4. Vague Givens

Using "Given the user is logged in" without specifying as what role or with what permissions. The step becomes a black box that hides setup complexity. Fix: "Given the user is logged in as an admin" or "Given the user is logged in with expired subscription".

5. Orphaned Feature Files

Feature files that exist but are not executed in CI. They pass because they're never run. False sense of coverage. Fix: every feature file must be in the CI pipeline with a test result. Add a lint rule that fails if any feature file is not referenced.

6. Skipping Three Amigos

Developers write Gherkin scenarios without BA or tester input. Scenarios reflect developer understanding, not shared understanding. The entire value of BDD is lost. Fix: never write scenarios without a three amigos session first.

7. Slow Steps

Step definitions that make API calls, database queries, or UI interactions for every step. Scenarios take minutes to run, defeating the fast feedback loop. Fix: use test doubles, in-memory databases, and API stubs for most steps. Only end-to-end tests use real dependencies.

8. Scenario Coupling

Scenarios that depend on the state created by previous scenarios. Order-dependent tests that fail when run in isolation. Fix: each scenario must create its own state. Use Background for shared setup, never depend on other scenarios.

Three Amigos: Roles and Responsibilities

Each role has veto power on ambiguity. If any amigo can't explain what a scenario means, it's not ready.

Facilitation Tips

• Timebox: 30 minutes max per feature
• Artifact: physical or digital board with rules/examples/questions/stories
• Rule: no laptops during the session (except the facilitator)
• Output: 3-10 concrete examples that become Gherkin scenarios
• Avoid: implementation discussion, architecture debates, design details

Specification by Example (SBE) Process

Key Principles

1. Key examples first: derive specifications from concrete examples, not abstract requirements
2. Process as code: examples become automated tests that validate the system
3. Living documentation: tests serve as up-to-date system documentation
4. Common vocabulary: all stakeholders use the same terms

SBE Steps

1. Scope: identify the feature and its business rules
2. Examples: discover concrete input-output pairs
3. Automate: convert examples into executable Gherkin scenarios
4. Validate: run scenarios against the system
5. Evolve: update examples as business rules change

Tool-Specific Guidance

Cucumber (Ruby/JVM/JS)

• Step definition matching: regex or Cucumber Expressions
• Hooks: Before, After, Around, AfterStep
• World: shared context object
• Reports: JSON, HTML, JUnit XML

SpecFlow (.NET)

• Step definition matching: regex, method attributes
• Hooks: BeforeScenario, AfterScenario, BeforeFeature
• Context injection: dependency injection for shared state
• Reports: TRX, HTML, LivingDoc

Behave (Python)

• Step definition matching: decorators with regex
• Hooks: before_scenario, after_scenario, before_all
• Context: context object for shared state
• Reports: JSON, JUnit XML, HTML

JBehave (Java)

• Step definition matching: annotated methods
• Hooks: @Before, @After, @BeforeStory
• Stories: .story files with Gherkin-like syntax
• Reports: HTML, XML, TXT

BDD Adoption Patterns

Team Maturity Stages

Common Adoption Challenges

Challenge: Business stakeholder engagement Business stakeholders skip three amigos sessions. Scenario: BA says "developers can write the scenarios." Result: scenarios reflect technical understanding, not shared understanding. Solution: Timebox sessions to 30 minutes. Prepare examples in advance. Show stakeholders how scenarios protect their requirements. Make it a ritual, not a meeting.

Challenge: Test maintenance burden As product evolves, features and step definitions need updates. Teams abandon BDD when maintenance exceeds creation effort. Solution: Refactor step definitions regularly. Use shared step libraries. Tag scenarios by frequency tier (@smoke runs on every commit, @regression runs nightly). Budget 20% of sprint for test maintenance.

Challenge: Slow execution time BDD scenarios that hit real APIs, databases, or UIs become slow. Teams stop running them frequently. They break and stay broken. Solution: Use test doubles for most scenarios. Reserve end-to-end for critical paths marked @e2e. Run fast scenarios on every commit, slow scenarios nightly. Parallelize execution.

Living Documentation in Practice

Feature Files as Documentation

Feature files are not test scripts — they are executable requirements. They serve as the single source of truth for system behavior. All stakeholders (business, dev, QA) should be able to read and understand them. Documentation quality criteria:

Living Documentation Publishing

Generate living documentation from feature file execution. Include in CI pipeline: run feature files as automated tests, generate HTML report with pass/fail for each scenario, publish report to shared location accessible to all stakeholders, attach report to release notes.

Report should include: feature list with descriptions, scenario count by status (pass/fail/skipped), execution time per scenario, tags and their coverage, trend chart showing pass rate over time. Review living documentation monthly with business stakeholders — if they can't understand it, rewrite the features.

BDD in CI/CD Pipeline

Commit → Build → Unit Tests → BDD Tests → Integration Tests → Deploy
                              ↓
                Feature file execution
                Generate living documentation
                Publish report to stakeholders
                Fail build on P0 scenario failure

Best practices: run smoke BDD tests on every commit (tagged @smoke), run full BDD suite nightly, notify stakeholders on failure, maintain average execution time <30 seconds per feature, parallelize scenario execution for speed, use tags for selective execution by environment.

BDD Tool Comparison

Success Metrics

Rules

• Gherkin scenarios must be understandable by business stakeholders, not just developers
• Scenarios must not reference UI elements unless the feature is specifically about UI behavior
• Feature files are the single source of truth for requirements — not Jira, not a spec doc
• Each scenario should test exactly one behavior — multiple assertions in one scenario is an anti-pattern
• Step definitions must be reusable across scenarios — avoid duplicating step logic
• Hooks must be minimal and fast — slow hooks destroy the feedback loop
• Scenario Outline + Examples is for data variation, not for listing all test cases
• Feature files belong in the code repository alongside the implementation
• Three amigos must include all three roles — skipping one party produces blind spots
• Background sections must be concise — excessive Background hides important setup
• Tags must follow a convention: @{tier} @{domain} @{priority}
• Doc Strings should have a language hint: """json for JSON, """xml for XML
• Data Tables should have a header row with descriptive column names
• Scenario nesting (Rule → Example) replaces Background for Gherkin 6+

Gherkin Code Examples

Step Definition Patterns

Ruby (Cucumber):

Given("the user {string} exists with role {string}") do |email, role|
  @user = FactoryBot.create(:user, email: email, role: role)
end

When("{string} submits a report for {string}") do |email, project_name|
  project = Project.find_by!(name: project_name)
  post project_reports_path(project), params: { report: { title: "Q1 Review" } }
end

Then("the {string} should receive a notification") do |role|
  expect(Notification.where(recipient_role: role).count).to eq(1)
end

Python (Behave):

@given('the inventory has {count} units of "{product}"')
def step_given_inventory(context, count, product):
    context.inventory = {product: int(count)}

@when('a customer orders {count} units of "{product}"')
def step_when_order(context, count, product):
    context.result = context.service.order(product, int(count))

@then('the order is confirmed with status "{status}"')
def step_then_confirmed(context, status):
    assert context.result.status == status

JavaScript (Cucumber.js):

const { Given, When, Then } = require('@cucumber/cucumber');

Given('a policy with coverage type {string}', function (type) {
  this.policy = new Policy({ coverageType: type });
});

When('the member submits a claim for ${int}', function (amount) {
  this.claimResult = this.policy.processClaim(amount);
});

Then('the claim is {string}', function (status) {
  assert.strictEqual(this.claimResult.status, status);
});

Data Table Examples

Scenario: Bulk user import
  Given the system has no users
  When an admin imports the following users:
    | name     | email              | role    | department |
    | Alice    | alice@example.com  | admin   | eng        |
    | Bob      | bob@example.com    | viewer  | design     |
    | Charlie  | charlie@example.com| editor  | product    |
  Then the system has 3 active users
  And Alice has admin permissions

Scenario Outline: Checkout with different payment methods
  Given the cart has items totaling $<total>
  When the customer pays with <method>
  Then the payment status is <status>
  And the confirmation is sent via <channel>

  Examples:
    | total | method   | status  | channel |
    | 25.00 | credit   | success | email   |
    | 50.00 | invoice  | pending | email   |
    | 0.00  | free     | success | none    |

Doc String Usage

Scenario: Submit JSON payload via API
  Given the API endpoint "/api/v1/orders" accepts orders
  When a POST request is sent with:
    """json
    {
      "customer_id": "abc-123",
      "items": [
        {"sku": "SHIRT-001", "qty": 2},
        {"sku": "PANTS-002", "qty": 1}
      ],
      "shipping": "express"
    }
    """
  Then the response status is 201
  And the response contains an order_id

Scenario: Invoice generation with complex formatting
  Given an invoice template with the following format:
    """
    INVOICE #{invoice_number}
    Date: {date}
    Bill To: {customer_name}
    ---
    {line_items}
    ---
    Total: ${total}
    """
  When the invoice is generated for order "ORD-456"
  Then the invoice contains "Total: $150.00"

Expanded Decision Trees

Step Definition Language Decision Tree

What programming language is the project using?
  |-- Ruby --> Use Cucumber-Ruby with Cucumber Expressions
  |-- Python --> Use Behave with regex step definitions
  |-- JavaScript/TypeScript --> Use Cucumber.js with Cucumber Expressions
  |-- Java --> Use Cucumber-JVM with @Annotations
  |-- C#/.NET --> Use SpecFlow with method attributes
  |-- Go --> Use Godog with function-based steps
  |-- Swift --> Use XCTest-Gherkin or Quick+Nimble

Are step definitions becoming complex to maintain?
  |-- YES --> Are steps shared across multiple features?
  |     |-- YES --> Extract shared steps into a common module
  |     |-- NO --> Consider using page objects or domain helpers
  |-- NO --> Keep steps in feature-specific files

BDD Tool Selection Decision Tree

What is the team's primary language?
  |-- Ruby/JVM/JS --> Cucumber (most mature ecosystem)
  |-- .NET --> SpecFlow (native .NET integration)
  |-- Python --> Behave or pytest-bdd
  |-- Java-only --> JBehave (simpler than Cucumber-JVM)
  |-- Go --> Godog
  |-- Mobile (iOS) --> XCTest-Gherkin or Cucumberish

Does the team need living documentation reporting?
  |-- YES --> Cucumber + LivingDoc or SpecFlow LivingDoc
  |-- NO --> Any BDD tool with basic HTML report

Is CI integration important?
  |-- YES --> All major tools support JUnit XML output
  |-- NO --> Any BDD tool

Is parallel execution needed?
  |-- YES --> Cucumber with polyglot or SpecFlow with split tests
  |-- NO --> Any BDD tool

Scenario Writing Strategy Decision Tree

What kind of behavior are you describing?
  |-- Happy path (everything works)
  |     |-- YES --> Standard Given-When-Then
  |-- Error case (something fails)
  |     |-- YES --> Given setup + When action + Then error
  |-- Edge case (boundary condition)
  |     |-- YES --> Scenario Outline with boundary Examples
  |-- Complex business rule
  |     |-- YES --> Rule groups (Gherkin 6+) with multiple Examples

How many steps does the scenario have?
  |-- <7 steps --> Keep as a single scenario
  |-- 7-12 steps --> Can the Background be used?
  |     |-- YES --> Extract common Given steps to Background
  |     |-- NO --> Consider splitting into multiple scenarios
  |-- >12 steps --> Definitely split into smaller scenarios

Expanded Anti-Patterns

9. Over-Abstracting Step Definitions

Making step definitions so generic that they lose meaning. "Given a resource exists" instead of "Given a user account exists with $500 balance". Steps become reusable but scenarios become unreadable. Fix: find the right balance. Steps should be specific enough to communicate intent, generic enough to be reusable. A good heuristic: if the step hides more than 3 parameters, it's too abstract.

10. Magic Numbers and Values

Using hardcoded test values that have no business meaning. Scenario says "user has 3 items" but 3 has no significance. Later, value changes to 5 and scenarios break without reason. Fix: use named constants where values matter. Use Scenario Outlines with meaningful example names. Document why specific values were chosen.

11. Testing the Framework

Writing scenarios that test framework behavior rather than business logic. "Given I navigate to the page, When I click the button, Then the page reloads" — this tests the browser, not the application. Fix: every scenario should test a business rule, not technical behavior. If you're testing framework behavior, write unit tests instead.

12. Too Much Background

Using Background sections that set up too much state. Scenarios become difficult to read because half the Given steps are in the Background. Fix: Background should contain only the setup that is common to ALL scenarios in the feature. If a scenario doesn't use a Background step, move that step into the scenario. Max 3-5 steps in Background.

13. Scenario Interdependence

Scenarios that rely on the output of previous scenarios. Running scenarios individually fails but running the full suite passes. This defeats the purpose of automated testing. Fix: each scenario must be independently executable. Use Background for common setup, never depend on state from other scenarios. Run scenarios in random order to detect dependencies.

14. BDD for Everything

Using BDD for all testing needs including unit tests, integration tests, and performance tests. BDD is for validating business rules through shared understanding. Not for testing database queries, algorithm correctness, or system performance. Fix: use BDD only for scenarios that benefit from business stakeholder readability. Use traditional unit/integration tests for technical concerns.

Expanded Success Metrics

Expanded SBE Process Detail

Key Principles with Implementation Guidance

1. Key examples first: Schedule a 30-minute example mapping session before any development begins. Bring 3 amigos. Focus on concrete examples, not abstract requirements. Write examples on cards. Group by rule. Identify gaps. Output is 5-10 concrete examples.
2. Process as code: Each example becomes an automated scenario. The feature file is both specification and test. If the scenario passes, the specification is met. If it fails, the implementation is wrong. Never disable a failing scenario — either the code is wrong or the specification changed.
3. Living documentation: Feature files should be readable by business stakeholders. Review them monthly. Publish execution reports as documentation. Link to feature files from your product documentation.
4. Common vocabulary: Maintain a glossary of domain terms used in scenarios. Review terms during three amigos sessions. Document synonyms to avoid confusion. Reject technical terms in scenario language.

SBE Workshop Format

Expanded Adoption Patterns

Enterprise BDD Adoption Strategy

Phase 1 — Pilot (Weeks 1-4): Select one team and one feature. Train the team on Gherkin syntax and three amigos facilitation. Write feature files for one feature. Implement step definitions. Run in CI. Measure: time to write first scenario, time to automate first scenario, stakeholder feedback.

Phase 2 — Expand (Weeks 5-12): Add 2-3 more teams. Create shared step definition library. Establish three amigos ritual. Set up living documentation publishing. Measure: scenario count growth, step definition reuse rate, three amigos adoption rate.

Phase 3 — Standardize (Weeks 13-24): Make BDD part of Definition of Ready (scenarios before development) and Definition of Done (scenarios passing in CI). Train all teams. Centralize step library governance. Measure: feature file coverage, scenario pass rate stability, time from scenario writing to automation.

Phase 4 — Optimize (Weeks 25+): BDD metrics in team dashboards. Living documentation as primary requirements reference. Automated traceability from scenarios to requirements. Measure: business stakeholder engagement with living docs, defect escape rate reduction, requirements ambiguity reduction.

Expansion Patterns for Gherkin

Pattern: Feature File Organization

features/
  ├── authentication/
  │   ├── login.feature
  │   ├── registration.feature
  │   └── password_reset.feature
  ├── payments/
  │   ├── checkout.feature
  │   ├── refunds.feature
  │   └── subscription.feature
  └── shared/
      └── step_definitions/
          ├── authentication_steps.rb
          ├── payment_steps.rb
          └── api_helper.rb

Pattern: Tag-Driven Test Execution

@smoke @critical
Feature: User Authentication

  @smoke @P0
  Scenario: Valid credentials login
    Given the user "admin@example.com" exists with password "validPass123"
    When the user logs in with email "admin@example.com" and password "validPass123"
    Then the user is redirected to the dashboard

  @regression @P1
  Scenario: Invalid credentials shows error
    Given the user "admin@example.com" exists with password "validPass123"
    When the user logs in with email "admin@example.com" and password "wrongPass"
    Then an error message "Invalid credentials" is displayed

CI execution strategy:

On every commit: @smoke (fast, <2 min)
On every merge to main: @regression (medium, <15 min)
Nightly: @e2e (full suite, <30 min)
On release candidate: all tags (comprehensive)

References

• references/gherkin-deep-dive.md — Gherkin Deep Dive
• references/spec-example.md — Specification by Example
• references/bdd-tools.md — BDD Tools
• references/atdd-workflow.md — ATDD Workflow
• references/bdd-atdd-advanced.md — Bdd Atdd Advanced Topics
• references/bdd-atdd-fundamentals.md — Bdd Atdd Fundamentals
• references/gherkin-patterns-catalog.md — Gherkin Patterns Catalog
• references/step-definition-guide.md — Step Definition Implementation Guide
• references/bdd-ci-pipeline.md — BDD CI Pipeline Setup

Handoff

create-story for converting discovered stories into backlog items. create-tech-spec for implementation details from step definitions. create-prd for aligning feature files with product requirements.