Test driven development

Test-Driven Development

Write the test first and watch it fail. A test you never saw fail proves nothing — it can pass for reasons unrelated to the behavior it was meant to pin.

This is a rigid skill. The bright line: production code is written only against a test you have watched fail. It holds for features, bug fixes, refactors, and behavior changes alike. Exceptions — throwaway prototypes, generated code, pure configuration — are agreed with the user before skipping the cycle, not self-granted.

The cycle

One behavior at a time: red, verify red, green, verify green, refactor.

1. Red — write one failing test

One behavior, a name that describes it, real code over mocks.

// Good: clear name, real behavior, one thing
test('retries failed operations 3 times', async () => {
  let attempts = 0;
  const operation = () => {
    attempts++;
    if (attempts < 3) throw new Error('fail');
    return 'success';
  };
  const result = await retryOperation(operation);
  expect(result).toBe('success');
  expect(attempts).toBe(3);
});

A vague name ("retry works") asserting against a mock tests the mock, not the code.

2. Verify red — watch it fail

Run the test. Confirm three things: it fails rather than errors, the failure message is the one you expected, and it fails because the feature is missing — not because of a typo. A test that passes here is testing behavior that already exists; fix the test. A test that errors is not failing correctly; fix the error and re-run until it fails for the right reason. One exception-shaped red IS the right reason: a reproducing test for a crash bug fails by the very exception under repair — "errors" above means accidental ones (typos, wrong fixtures), not the crash being reproduced; don't contort the test to avoid it. (The same red-before-green discipline governs any verifier, not only tests — verification-before-completion states the general form for gates and checks.)

3. Green — write the least code that passes

Just enough to pass the test. No speculative parameters, no extra options the test never asked for, no improvements to neighboring code. Over-engineering here (a config object with maxRetries, backoff, and onRetry when the test asked for three retries) is scope the tests don't cover.

4. Verify green — watch it pass

Run again. Confirm: the new test passes, every other test still passes, and the output is pristine — no stray errors or warnings. A failure here means fix the code, not the test.

5. Refactor — clean up on green

Remove duplication, improve names, extract helpers. No new behavior, and the tests stay green throughout. Then write the next failing test.

If code exists before its test

Delete it and start from the test. The time already spent is gone either way; what the rewrite buys is code whose tests have been seen to catch its absence. Keeping the old code "as reference" turns into adapting it, and adapting it is test-after with extra steps — the tests end up describing what the code does instead of what it should do.

Why the order matters

• Tests written after the code pass immediately, and a test that has never failed demonstrates nothing — it may assert the wrong thing, test the implementation rather than the behavior, or miss the cases you forgot.
• Tests-after answer "what does this code do?"; tests-first answer "what should this code do?" The implementation biases what you check — you verify remembered edge cases instead of discovering them.
• Manual testing is ad hoc: no record of what was covered, nothing to re-run when the code changes next month.

Common shortcuts and what they miss

Shortcut	What it misses
"Too simple to test"	Simple code breaks too; the test costs seconds.
"I'll add tests after"	Passing immediately proves nothing; see above.
"Already manually tested it"	No record, no re-run, edge cases fade.
"Keep the old code as reference"	Reference becomes adaptation; adaptation is test-after.
"Need to explore the API first"	Explore freely — then discard the spike and start test-first.
"This is hard to test"	Hard to test usually means hard to use; simplify the design the test is resisting.

Good tests

Quality	Looks like
Minimal	One behavior; an "and" in the name means split it
Clear	The name states the behavior, not "test1"
Intent	Demonstrates the API you wish existed

When stuck

Problem	Move
Don't know how to test it	Write the wished-for call and the assertion first; ask the user if still stuck
Test setup is huge	Extract helpers; if still complex, the design is too coupled
Must mock everything	Coupling problem — introduce dependency injection
Test too complicated	The interface is too complicated; simplify it
A runner that discovers its own tests	Red against a fixture tree, never the real one — test-first a root/target arg, then red the defect through it

Bug fixes

A bug fix starts with a failing test that reproduces the bug, then follows the same cycle — the test proves the fix and prevents the regression. Diagnosing an unexplained failure belongs to systematic-debugging, which returns here once the cause is proven. Before claiming the fix complete, red-green the regression test (revert the fix, watch it fail, restore) and hand the evidence to verification-before-completion.

Completion check

• Every new behavior has a test that was seen failing for the expected reason
• Minimal code; all tests pass; output pristine
• Mocks only where unavoidable — see testing-anti-patterns.md
• Edge cases and error paths covered

When writing or changing mocks or test utilities, read testing-anti-patterns.md first.