Test-Driven Development (TDD)

1. Write all the failing tests (RED phase)

You need to write all the tests needed for your current task up-front, only then can you proceed. This must include edge cases and pathological as well as the happy-path cases. 2. Verify the tests fail due to the behavior of the application, and NOT due to the test. If you have more than one test that you need to write, you should write all of them before moving to the GREEN phase. 3. Write the minimal amount of code necessary to make the test pass (GREEN phase) 4. Verify the test now passes due to the behavior of the application. 5. Refactor the code to clean it up. 6. Verify tests still pass.

Red-Green-Refactor In Depth

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

Test Writing Guidelines

• Always test real behavior.
• Do not write tests that are just mocks.
• Do not write tests that test implementation detail.
• Do not write tests that just test data structure format.
• Do not write tests that test types.
• Focus on writing tests for integration boundaries.
• Only unit test utilities. Production code must be end to end tested.

RED - Write Failing Test

Write one minimal test showing what should happen.

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 foobar.retryOperation(operation);

  expect(result).toBe('success');
  expect(attempts).toBe(3);
});

Clear name, tests real behavior, one thing. Note that the tested operation is imported -- this is a STRONG sign that this is testing something real.

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

Vague name, tests mock not code

Verify RED - Watch It Fail

MANDATORY. Never skip.

# javascript
npm test path/to/test.test.ts
# clojure w/ kaocha
bb test --focus com.example.the-ns/the-test-name

Confirm:

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

Test passes? You're testing existing behavior. Fix test.

Test errors? Fix error, re-run until it fails correctly.

GREEN - Minimal Code

Write simplest code to pass the test.

Don't add features, refactor other code, or "improve" beyond the test.

Verify GREEN - Watch It Pass

MANDATORY.

# javascript
npm test path/to/test.test.ts
# clojure w/ kaocha
bb test --focus com.example.the-ns/the-test-name

Confirm:

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

Test fails? Fix code, not test.

Other tests fail? Fix now.

REFACTOR - Clean Up

After green only:

• Remove duplication
• Improve names
• Extract helpers

Keep tests green. Do not add behavior.

Common Failure Patterns -- DO NOT DO THESE THINGS

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..."

All of these mean: Delete code. Start over with TDD.