{
    "slug": "naming_tests",
    "term": "Naming Test Methods (Given/When/Then)",
    "category": "testing",
    "difficulty": "beginner",
    "short": "Test method names should describe behaviour, not implementation — test_calculateTotal_givenDiscountedItems_returnsReducedPrice beats test_calculateTotal().",
    "long": "Good test naming patterns: (1) Given/When/Then: givenExpiredToken_whenValidating_thenThrowsException. (2) Should: shouldThrowWhenTokenExpired. (3) Behaviour description: calculatesDiscountForPremiumUsers. Bad patterns: test1, testMethod, testCalculate. PHPUnit: method name is the test name in output. Use @test annotation or prefix test. Name should read as a specification — failing tests produce meaningful error messages. The name should say what the test verifies, not how. BDD frameworks (Behat, Pest) formalise this with descriptive strings.",
    "aliases": [],
    "tags": [
        "testing",
        "naming",
        "phpunit",
        "best-practices"
    ],
    "misconception": "Test names only matter to developers reading the code — test names appear in CI failure output and are the primary way to understand what broke in production.",
    "why_it_matters": "Poorly named tests produce cryptic CI failure messages — 'FAILED: testCalculate' tells you nothing. 'FAILED: givenExpiredToken_whenValidating_thenThrowsException' tells you exactly what broke.",
    "common_mistakes": [
        "Using generic names: test1, testMethod, testSuccess.",
        "Naming after implementation: testCallsDiscountService instead of testAppliesDiscountForPremiumUsers.",
        "Not including the expected outcome in the name."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "unit_testing",
        "tdd",
        "php_jit",
        "test_doubles"
    ],
    "prerequisites": [
        "unit_testing",
        "phpunit"
    ],
    "refs": [
        "https://phpunit.de/documentation.html"
    ],
    "bad_code": "public function testCalculate(): void { }\npublic function testCalculate2(): void { }\npublic function testUserService(): void { }",
    "good_code": "// PHPUnit:\npublic function test_givenPremiumUser_whenCalculatingTotal_appliesDiscount(): void {}\npublic function test_givenExpiredCoupon_whenCheckingOut_throwsException(): void {}\n\n// Pest:\nit('applies discount for premium users', function() {});\nit('throws when coupon is expired', function() {});",
    "quick_fix": "Name tests as: test_givenContext_whenAction_thenOutcome or 'it does X when Y'. Include the scenario and expected behaviour. Never use generic names like test1 or testMethod.",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-23",
    "updated": "2026-03-23",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/naming_tests",
        "html_url": "https://codeclaritylab.com/glossary/naming_tests",
        "json_url": "https://codeclaritylab.com/glossary/naming_tests.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": "[Naming Test Methods (Given/When/Then)](https://codeclaritylab.com/glossary/naming_tests) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/naming_tests"
            }
        }
    }
}