Behaviour-Driven Development (BDD)
debt(d7/e5/b3/t6)
Closest to 'only careful code review or runtime testing' (d7), because misuse of BDD (scenarios describing implementation details, no domain expert involvement) is not catchable by Behat/phpSpec/Codeception themselves — they happily run technically-correct but business-irrelevant scenarios. Detection requires human review of feature files.
Closest to 'touches multiple files / significant refactor in one component' (e5), because rewriting feature files to reflect business behaviour means rewriting scenarios, step definitions, and often involving stakeholders — more than a parameterised swap but localised to the test suite.
Closest to 'localised tax' (b3), because BDD scenarios live in a features/ directory and affect the testing workflow but don't shape production code architecture; applies_to covers web/cli but the burden is concentrated in the acceptance test layer.
Closest to 'serious trap' (t6), slightly below t7 because the misconception ('BDD is just TDD with different syntax') leads developers to adopt the tooling without the collaboration practice, missing the entire point — a notable contradiction with how the name suggests it works, but not catastrophic since the tests still provide some value.
Also Known As
TL;DR
Explanation
BDD extends TDD by making tests readable to non-technical stakeholders. The Given-When-Then structure (Gherkin syntax) describes behaviour: Given a context, When an action occurs, Then an outcome is expected. In PHP, Behat is the primary BDD framework. The value is not the syntax but the conversation it forces — writing in Gherkin requires alignment on what the system should actually do before anyone writes code.
Diagram
sequenceDiagram
participant PO as Product Owner
participant DEV as Developer
participant QA as QA
PO->>DEV: User story
DEV->>DEV: Write Gherkin scenario
Note over DEV: Given user is logged in<br/>When they add item to cart<br/>Then cart count increases
DEV->>QA: Review scenario
QA-->>DEV: Approved
DEV->>DEV: Implement step definitions
DEV->>DEV: Run Behat - fails
DEV->>DEV: Implement feature
DEV->>DEV: Run Behat - passes
Note over DEV,QA: Scenario = living documentation
Common Misconception
Why It Matters
Common Mistakes
- Writing BDD scenarios for technical implementation details instead of business behaviour.
- Not involving domain experts in writing scenarios — Gherkin written only by developers defeats the purpose.
- Too many steps in a scenario — each scenario should test one behaviour; multiple behaviours need multiple scenarios.
- Using BDD for unit tests — BDD is for business-facing acceptance criteria, not internal implementation testing.
Code Examples
# BDD scenario testing implementation, not behaviour:
Scenario: Test the UserRepository::findByEmail method
Given the database has a users table
When I call UserRepository::findByEmail('alice@example.com')
Then the PDOStatement should return one row
# This tests a method, not a business behaviour# BDD scenario testing business behaviour:
Feature: User authentication
Scenario: Registered user logs in with correct credentials
Given a user exists with email 'alice@example.com' and password 'secret'
When Alice submits the login form with correct credentials
Then she should be redirected to the dashboard
And she should see a welcome message
Scenario: Wrong password is rejected
Given a user exists with email 'alice@example.com'
When Alice submits the login form with the wrong password
Then she should see an error message
And she should remain on the login page