mcouthon/agents/bdd

# 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

# 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

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 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 |

# 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"

# 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]

-[ ] 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