Test Driven Development

Test-Driven Development

Iron Law

NO IMPLEMENTATION WITHOUT A FAILING TEST FIRST

Write the test. Run it. See it fail (RED). Then implement until it passes (GREEN). Then refactor.

When TDD Applies

DO use TDD for:

• New features and new logic
• Bug fixes (write a test that reproduces the bug first)
• Any code path that has business logic

DO NOT use TDD for:

• Config changes, renames, formatting
• Trivial one-line fixes with no logic
• See leverage-patterns.md Test-First section for the full rule

Red-Green-Refactor Cycle

RED   -> Write a test that FAILS for the right reason
         Run it. Confirm it fails. If it passes without code -> test is wrong.

GREEN -> Write the MINIMUM code to make the test pass
         No extras. No "while I'm here" additions.

REFACTOR -> Clean up code without changing behavior
            Run tests again. Must still pass.

For verifying regression tests are genuine (not vacuous): see verification-before-completion Red-Green protocol. For TDD during bug investigation: see systematic-debugging Phase 4 — Create Failing Test Case.

Test Naming Convention

Pattern: test_<what>_<when>_<expected> (or should_<expected>_when_<condition>)

# Java
@Test void createUser_withDuplicateEmail_throwsConflictException()

# NestJS/Jest
it('should throw ConflictException when email already exists', ...)

# Python/pytest
def test_create_user_with_duplicate_email_raises_conflict():

# Flutter
test('createUser throws ConflictException when email is duplicate', ...)

Stack Dispatch

Quick Checklist

Before claiming a test is real:

• Test FAILED before implementation (you saw the red output)
• Test PASSES after implementation (you saw the green output)
• Test name describes behavior, not implementation
• One assertion per logical outcome (not 10 assertions in one test)
• Mocks are used for external dependencies only (not to avoid writing logic)