tdd

name	tdd
description	Red-green-refactor test-driven development.

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

Rationalization	Counter
"Too simple to need a test"	Simple code breaks. The test takes seconds.
"I'll add tests after"	Post-hoc tests pass immediately — that proves nothing.
"Already tested manually"	Manual checks leave no record and cannot re-run.
"Deleting N hours of work is wasteful"	Sunk cost. Unverified code is the actual waste.
"Keep it as reference, write tests first"	You will adapt it. That is testing after. Delete.
"Need to explore first"	Explore, then discard the spike and start with a test.
"Hard to test means unclear requirements"	Hard to test means hard to use. Simplify the interface.
"TDD slows me down"	Debugging without tests is slower.
"Existing code has no tests"	New changes get tests. Legacy is not an exemption.

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

Property	Indicator
Focused	One behavior per test. "and" in the name signals it should split.
Descriptive	Name states expected behavior in plain language.
Intent-revealing	Test demonstrates the desired API, not internal mechanics.
Deterministic	No dependence on timing, execution order, or external state.
Boundary-mocked	Mocks exist only at I/O edges (network, filesystem, clock). Internal modules use real instances.

When Stuck

Symptom	Response
Cannot figure out what to test	Write the assertion first. Design the API you wish existed.
Test requires excessive setup	The design is too coupled. Simplify the interface.
Everything needs mocking	Dependency injection missing. Refactor to inject collaborators.
Test is more complex than the code	Extract test helpers. If still complex, the production design needs simplifying.

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.