Skip to content

nWave-ai/nWave / nWave/skills/nw-bdd-methodology

nw-bdd-methodology

Verified

BDD patterns for acceptance test design - Given-When-Then as a language-neutral specification style, scenario writing rules, realization in the project's incumbent native scenario syntax (Python pytest-bdd binding labelled), anti-patterns, and living documentation

BDD Methodology for Acceptance Test Design

Core Philosophy

Test units of behavior, not units of code. Acceptance tests validate business outcomes through public interfaces, decoupled from implementation.

Outside-In Double-Loop TDD

The acceptance-designer creates the outer loop of Outside-In TDD. Development starts from user perspective, drives inward.

Outer loop (acceptance/BDD): Hours to days | User perspective, business language | Defines "done" | Scenarios describe user goals and observable outcomes, not internals | Failing outer-loop test is the starting signal for implementation

Ownership: ATD authors the public oracle and required test supports. Managed crafters implement production against the approved immutable oracle and return oracle defects to ATD. Full-cycle test authoring applies only when the invocation owns it; routing belongs to nw-tdd-methodology.

Workflow:

  1. ATD writes the failing public observation from the supplied user contract.
  2. The crafter implements production until that observation passes.
  3. Independent review and verification assess the delivery.

Given-When-Then Structure

Given/When/Then is a language-neutral specification STYLE, realized in the project's incumbent native scenario syntax (its BDD framework if it already has one) or as plain native tests named in domain language with Given/When/Then phases as comments or helper names. Gherkin/pytest-bdd are used only when the project already uses them; never introduce them or any other stack for a project that does not (see nw-tdd-cross-language, nw-test-design-mandates). The Gherkin below is illustrative notation of the structure:

Scenario: [Business-focused title describing one behavior]
  Given [preconditions - system state in business terms]
  When [single user action or business event]
  Then [observable business outcome]

Scenario Writing Rules

Rule 1: One scenario, one behavior -- Split multi-behavior scenarios.

Rule 2: Declarative, not imperative -- Business outcomes, not UI interactions. "When I log in with valid credentials" not "When I click Login button and enter email."

Rule 3: Concrete examples, not abstractions -- "Given my account balance is $100.00" not "Given the user has sufficient funds."

Rule 4: Keep scenarios short (3-5 steps) -- Longer means testing multiple behaviors or irrelevant details.

Rule 5: Background for shared Given steps only -- Only Given steps. Actions/validations in scenarios.

Scenario Categorization

  • Happy path: Primary successful workflows
  • Error path: Invalid inputs, failures, unauthorized access (aim for 40%+ while selecting scenarios; a review judges that every declared obligation has a falsifying scenario, never the error-path proportion)
  • Edge case: Boundary conditions, unusual but valid behavior
  • Integration: Cross-component/system interactions

Golden Path + Key Alternatives

Per capability: 1. Happy path (most common success) | 2. Alternative paths (valid but less common) | 3. Error paths (invalid inputs, constraint violations). Select representative examples revealing different business rules. Do not test every combination.

Scenario Outlines for Boundary Testing

Scenario Outline: Account minimum balance validation
  Given I have an account with balance $<initial_balance>
  When I attempt to withdraw $<withdrawal_amount>
  Then the withdrawal is <result>

  Examples: Valid withdrawals
    | initial_balance | withdrawal_amount | result   |
    | 100.00         | 50.00            | accepted |
    | 25.00          | 25.00            | accepted |

  Examples: Invalid withdrawals
    | initial_balance | withdrawal_amount | result                       |
    | 100.00         | 101.00           | rejected (insufficient funds) |

Use outlines for boundary conditions and calculation variations. Avoid when scenarios diverge structurally.

Unique titles (gate-affordance audit A4, 2026-07-28)

Give every Scenario/Scenario Outline Example a UNIQUE title within its feature file. verify-red-green matches a RED run to its GREEN run by test id — a duplicate title collapses two distinct outcomes into one ambiguous id, and the gate refuses rather than guess which one kept failing.

Python binding — pytest-bdd (only when the project already uses pytest-bdd)

Everything in this section is a labelled Python binding; for any other stack use the incumbent native equivalent (fixtures/setup helpers, step or test-case organisation by domain concept, scope-appropriate setup).

Step Definitions with Fixture Injection

from pytest_bdd import scenarios, given, when, then, parsers

scenarios('../features/account.feature')

@given("I am authenticated", target_fixture="authenticated_user")
def authenticated_user(auth_service):
    user = auth_service.create_and_authenticate("test@example.com")
    return user

@given(parsers.parse('my account balance is ${amount:g}'),
       target_fixture="account")
def account_with_balance(authenticated_user, account_service, amount):
    return account_service.create_account(authenticated_user, balance=amount)

Step Organization by Domain

Organize by domain concept, not feature file:

steps/
  authentication_steps.py  # All auth-related steps
  account_steps.py         # All account-related steps
  transaction_steps.py     # All transaction-related steps

Fixture Scopes for Performance

Session: expensive setup (DB engine, app instance) | Module: schema creation | Function: data cleanup (autouse=True)

Production-Like Test Environment

@pytest.fixture(scope="session")
def app():
    """Application instance with production-like configuration."""
    app = create_app({"environment": "test", "database": "postgresql://localhost/test_db"})
    with app.app_context():
        app.db.create_all()
    yield app
    with app.app_context():
        app.db.drop_all()

Drive the real public entry; use doubles only at declared driven ports. Adapter integration exercises real infrastructure. Read nw-distill-port-treatment-policy when selecting the concrete real/fake mechanism under the project's infrastructure policy.

Anti-Patterns

Anti-PatternFix
Testing through UITest through service/API layer
Multiple WHEN actionsSplit into separate scenarios
Feature-coupled stepsOrganize by domain concept
Conjunction steps ("Given A and B" as one step)Break into atomic steps
Incidental detailsInclude only behavior-relevant info
Technical jargon in scenariosBusiness domain language
Abstract scenariosConcrete values, specific examples
Rambling scenarios (8+ steps)Extract to 3-5 focused steps

Living Documentation

Scenarios serve dual purpose: executable tests and living documentation. Organization: Business Goal > Capability > Feature > Scenario > Test. Each scenario traces to business capability. Stakeholders see which capabilities are implemented, tested, passing.

Documentation-Grade Scenarios

Replace HTTP verbs with business actions, JSON with domain concepts, status codes with business outcomes. Add context about WHO and WHY.

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 321kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 321kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 321kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall