Bdd

BDD — Behavior-Driven Development

Write executable specifications that describe what the system does, not how it works.

"Scenarios are not tests. They are executable specifications — living documentation of how the system behaves, written in the language of the business."

BDD Project Detection

Proactively load this skill when any of these indicators are present:

When detected, apply all guidance below to feature files, step definitions, and related test code.

Feature & Scenario Organization

• One feature per business capability — login.feature, checkout.feature, not everything.feature
• Feature title = capability — "User Registration", not "Test the registration endpoint"
• Scenarios describe user-observable outcomes — what the system does, not how it's coded
• Keep features focused — 3–8 scenarios per feature; split if growing beyond that
• Naming convention: lowercase hyphens for filenames (password-reset.feature), Title Case for Feature/Scenario titles

# Good — focused feature, outcome-oriented scenarios
Feature: Password Reset
  Users can reset forgotten passwords via email

  Scenario: Successful password reset
    Given a registered user with email "alice@example.com"
    When they request a password reset
    Then a reset link is sent to "alice@example.com"

  Scenario: Reset request for unknown email
    Given no user exists with email "unknown@example.com"
    When they request a password reset for "unknown@example.com"
    Then no email is sent
    And no error is revealed to the requester

Gherkin Best Practices

Declarative Over Imperative

Describe what happens, not how the user clicks through the UI:

# BAD — imperative (UI mechanics)
Scenario: User logs in
  Given I am on the login page
  When I fill in "username" with "alice"
  And I fill in "password" with "secret123"
  And I click the "Login" button
  And I wait for the dashboard to load
  Then I should see "Welcome, Alice"

# GOOD — declarative (behavior)
Scenario: Successful login
  Given a registered user "alice"
  When alice logs in with valid credentials
  Then alice sees her dashboard

Given / When / Then Semantics

Background for Shared Setup

Use Background when most scenarios share the same preconditions:

Feature: Shopping Cart
  Background:
    Given a customer with an active account
    And the product catalog is loaded

  Scenario: Add item to cart
    When the customer adds "Widget" to their cart
    Then the cart contains 1 item

  Scenario: Remove item from cart
    Given the customer has "Widget" in their cart
    When they remove "Widget"
    Then the cart is empty

Scenario Outlines for Data Variations

Use outlines when the same behavior applies across different inputs — never duplicate scenarios:

Scenario Outline: Shipping cost by region
  Given a package weighing <weight> kg
  When shipped to <region>
  Then the shipping cost is <cost>

  Examples:
    | weight | region   | cost   |
    | 1      | domestic | $5.00  |
    | 1      | europe   | $15.00 |
    | 5      | domestic | $12.00 |

Black-Box Testing

BDD scenarios test through public interfaces only — the system is a black box:

• API testing: send requests, assert responses — never query the database directly
• UI testing: interact through the UI, assert visible state — never check DOM internals
• Service testing: call public methods, assert return values and observable side effects
• No internal assertions: never assert database rows, internal state, private methods, or implementation artifacts
• Mock only at external boundaries: third-party APIs, payment gateways, email services — never mock internal components

# BAD — reaches into implementation
Then the database contains a row in "users" with email "alice@example.com"
And the password hash starts with "$2b$"

# GOOD — asserts observable behavior
Then alice can log in with her new password
And a welcome email is received at "alice@example.com"

Step Definitions

Step definitions are thin glue code — they translate Gherkin into application calls:

• Call application code, don't contain logic — a step definition should be 1–5 lines
• Reuse steps across features — write generic, parameterized steps
• Keep step state in a context/world object — not in global variables
• One action per step — if a step does multiple things, split it or simplify the Gherkin

# GOOD — thin glue, delegates to application code
@when('the customer adds "{item}" to their cart')
def add_to_cart(context, item):
    context.response = context.client.post("/cart/items", json={"item": item})

@then('the cart contains {count:d} item(s)')
def check_cart_count(context, count):
    cart = context.client.get("/cart").json()
    assert len(cart["items"]) == count

# BAD — logic and DB access in step definition
@when('the customer adds "{item}" to their cart')
def add_to_cart(context, item):
    product = db.query("SELECT * FROM products WHERE name = %s", (item,))
    db.execute("INSERT INTO cart_items ...")  # Direct DB manipulation!
    context.cart_count = db.query("SELECT COUNT(*) FROM cart_items ...")[0]

Anti-Patterns

Quality Checklist

Before committing feature files and step definitions:

- [ ] Feature files are readable by non-developers
- [ ] Each scenario tests exactly one behavior
- [ ] Steps are declarative (no UI mechanics or implementation details)
- [ ] No implementation coupling (scenarios survive internal refactors)
- [ ] Step definitions are thin glue (1–5 lines, delegate to app code)
- [ ] Shared state flows through context/world object, not globals
- [ ] Scenario Outlines used for data variations (no copy-paste scenarios)
- [ ] Feature descriptions explain the business value

Rationalization Prevention