{
    "slug": "behaviour_driven_development",
    "term": "Behaviour-Driven Development (BDD)",
    "category": "testing",
    "difficulty": "intermediate",
    "short": "A development practice where tests are written in business-readable language (Given/When/Then) that domain experts, developers, and testers all understand.",
    "long": "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.",
    "aliases": [
        "BDD",
        "Gherkin",
        "Behat",
        "Given-When-Then"
    ],
    "tags": [
        "testing",
        "bdd",
        "agile",
        "php"
    ],
    "misconception": "BDD is just TDD with different syntax — BDD's primary value is the collaboration and shared vocabulary it creates, not the test format itself.",
    "why_it_matters": "BDD scenarios catch misunderstandings between what the business wants and what developers build before code is written, not after it ships.",
    "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."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "test_driven_development",
        "acceptance_testing",
        "test_naming_conventions",
        "unit_testing"
    ],
    "prerequisites": [
        "acceptance_testing",
        "test_driven_development",
        "domain_driven_design"
    ],
    "refs": [
        "https://behat.org/",
        "https://en.wikipedia.org/wiki/Behavior-driven_development"
    ],
    "bad_code": "# BDD scenario testing implementation, not behaviour:\nScenario: Test the UserRepository::findByEmail method\n    Given the database has a users table\n    When I call UserRepository::findByEmail('alice@example.com')\n    Then the PDOStatement should return one row\n    # This tests a method, not a business behaviour",
    "good_code": "# BDD scenario testing business behaviour:\nFeature: User authentication\n  Scenario: Registered user logs in with correct credentials\n    Given a user exists with email 'alice@example.com' and password 'secret'\n    When Alice submits the login form with correct credentials\n    Then she should be redirected to the dashboard\n    And she should see a welcome message\n\n  Scenario: Wrong password is rejected\n    Given a user exists with email 'alice@example.com'\n    When Alice submits the login form with the wrong password\n    Then she should see an error message\n    And she should remain on the login page",
    "quick_fix": "Write Behat scenarios in business language before writing PHP code — the scenario describes behaviour from the user's perspective, not the implementation",
    "severity": "info",
    "effort": "high",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/behaviour_driven_development",
        "html_url": "https://codeclaritylab.com/glossary/behaviour_driven_development",
        "json_url": "https://codeclaritylab.com/glossary/behaviour_driven_development.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Behaviour-Driven Development (BDD)](https://codeclaritylab.com/glossary/behaviour_driven_development) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/behaviour_driven_development"
            }
        }
    }
}