​

Test-Driven Development (TDD)

​

Overview

​

When to Use

• New features
• Bug fixes
• Refactoring
• Behavior changes

• Throwaway prototypes
• Generated code
• Configuration files

​

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

• Don’t keep it as “reference”
• Don’t “adapt” it while writing tests
• Don’t look at it
• Delete means delete

​

Red-Green-Refactor

digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\ncorrectly", shape=diamond];
    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nAll green", shape=diamond];
    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
    next [label="Next", shape=ellipse];

    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> next;
    next -> red;
}

​

RED - Write Failing Test

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);
});

test('retry works', async () => {
  const mock = jest.fn()
    .mockRejectedValueOnce(new Error())
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(3);
});

• One behavior
• Clear name
• Real code (no mocks unless unavoidable)

​

Verify RED - Watch It Fail

npm test path/to/test.test.ts

• Test fails (not errors)
• Failure message is expected
• Fails because feature missing (not typos)

​

GREEN - Minimal Code

async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
  for (let i = 0; i < 3; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === 2) throw e;
    }
  }
  throw new Error('unreachable');
}

async function retryOperation<T>(
  fn: () => Promise<T>,
  options?: {
    maxRetries?: number;
    backoff?: 'linear' | 'exponential';
    onRetry?: (attempt: number) => void;
  }
): Promise<T> {
  // YAGNI
}

​

Verify GREEN - Watch It Pass

npm test path/to/test.test.ts

• Test passes
• Other tests still pass
• Output pristine (no errors, warnings)

​

REFACTOR - Clean Up

• Remove duplication
• Improve names
• Extract helpers

​

Repeat

​

Good Tests

​

Why Order Matters

• Might test wrong thing
• Might test implementation, not behavior
• Might miss edge cases you forgot
• You never saw it catch the bug

• No record of what you tested
• Can’t re-run when code changes
• Easy to forget cases under pressure
• “It worked when I tried it” ≠ comprehensive

• Delete and rewrite with TDD (X more hours, high confidence)
• Keep it and add tests after (30 min, low confidence, likely bugs)

• Finds bugs before commit (faster than debugging after)
• Prevents regressions (tests catch breaks immediately)
• Documents behavior (tests show how to use code)
• Enables refactoring (change freely, tests catch breaks)

​

Common Rationalizations

​

Red Flags - STOP and Start Over

• Code before test
• Test after implementation
• Test passes immediately
• Can’t explain why test failed
• Tests added “later”
• Rationalizing “just this once”
• “I already manually tested it”
• “Tests after achieve the same purpose”
• “It’s about spirit not ritual”
• “Keep as reference” or “adapt existing code”
• “Already spent X hours, deleting is wasteful”
• “TDD is dogmatic, I’m being pragmatic”
• “This is different because…”

​

Example: Bug Fix

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

$ npm test
FAIL: expected 'Email required', got undefined

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

$ npm test
PASS

​

Verification Checklist

• Every new function/method has a test
• Watched each test fail before implementing
• Each test failed for expected reason (feature missing, not typo)
• Wrote minimal code to pass each test
• All tests pass
• Output pristine (no errors, warnings)
• Tests use real code (mocks only if unavoidable)
• Edge cases and errors covered

​

When Stuck

​

Debugging Integration

​

Testing Anti-Patterns

• Testing mock behavior instead of real behavior
• Adding test-only methods to production classes
• Mocking without understanding dependencies

​

Final Rule

Production code → test exists and failed first
Otherwise → not TDD