Test-Driven Development

Constraint

No production code exists without a failing test that demanded it. Code written before its test gets deleted — not kept as reference, not adapted, not glanced at. Start clean from the test.

The Cycle

1. RED — Write a Failing Test

One test. One behavior. Descriptive name.

test('rejects empty email with validation error', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

Requirements:

• Tests a single behavior (if the name contains "and", split it)
• Exercises real code, not mocks (mock only at I/O boundaries)
• Name states the expected behavior, not "test1" or "works"

2. Confirm RED — Run It, Watch It Fail

npm test path/to/test.test.ts

Confirm:

• The test fails (not errors from syntax or imports)
• The failure reason matches expectations (feature absent, not typo)

If it passes: the behavior already exists. Revise the test. If it errors: fix the error, re-run until it fails for the right reason.

3. GREEN — Minimal Implementation

Write the least code that makes the test pass. Nothing speculative. No options bags, no configurability, no "while I'm here" improvements.

function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // existing logic...
}

4. Confirm GREEN — Run It, Watch It Pass

npm test path/to/test.test.ts

Confirm:

• New test passes
• Existing tests still pass
• No warnings or errors in output

If the new test fails: fix implementation, not the test. If other tests break: fix the regression now.

5. REFACTOR — Clean Up Under Green

Only after green. Remove duplication, improve naming, extract helpers. Verify tests remain green after every change. Do not introduce new behavior.

6. Repeat

Next behavior, next failing test.

Why Sequence Matters

Tests written after implementation pass on first run. A test that never failed has two problems:

• No proof it detects the bug it claims to cover. It may assert the wrong thing, test an implementation detail, or be vacuously true.
• Bias toward what was built, not what was specified. Post-hoc tests verify remembered edge cases. Pre-hoc tests force edge case discovery during design.

"Tests after" answer "what does this code do?" — "Tests before" answer "what should this code do?" These are different questions with different coverage characteristics.

Deleting existing implementation to restart with TDD is not waste. The sunk time is gone. Retaining code that lacks a red-green lineage means carrying unverified assumptions forward.

Deflecting Rationalizations

Halt Signals

Any of these indicate the cycle was broken. Delete the untested code and restart:

• Production code exists without a corresponding test that failed first
• A test passes on its first run
• Unable to explain why a test failed
• "Just this once" reasoning surfacing
• Impulse to keep pre-existing code as "reference"

Test Quality

When Stuck

Debugging Integration

Every bug fix starts with a failing test that reproduces the defect. The test proves the fix works and guards against recurrence. No exceptions.

Testing Anti-Patterns

Consult @references/testing-anti-patterns.md before introducing mocks or test utilities. Key traps:

• Asserting against mock return values instead of real behavior
• Injecting test-only methods into production classes
• Mocking modules without understanding the dependency graph

Completion Checklist

• Every new function/method has a test that failed before the implementation existed
• Each test failed for the expected reason (missing feature, not syntax error)
• Implementation is minimal — no speculative additions
• All tests pass with clean output
• Mocks exist only at I/O boundaries
• Edge cases and error paths are covered

Incomplete checklist means incomplete TDD. Go back and fill the gaps.

Gotchas

• Post-hoc tests masquerading as TDD — Writing the code "mentally" then formalizing a test is still test-after. The test must exist in the file and fail before the implementation is written.
• Testing implementation details — If refactoring breaks a test without changing behavior, the test is coupled to internals. Assert on outputs and side effects, not on how the code achieves them.
• Multiple behaviors per test — Compound assertions obscure which behavior failed. One test, one reason to fail.
• Skipping the red confirmation — Running the test and seeing it fail is not optional. A test that was never observed failing has unknown detection capability.
• Over-mocking — Each mock replaces a real code path with an assumption. Excessive mocking produces tests that verify assumptions about dependencies, not actual behavior.
• Ignoring refactor phase — Green is not done. Duplication, poor names, and structural issues addressed now prevent compounding debt across subsequent cycles.
• Flaky tests — Non-determinism (time, ordering, network) in tests erodes trust in the entire suite. Fix or delete flaky tests immediately.