Test-driven development (TDD)

Write the test first. Watch it fail. Write minimal code to pass. Refactor.

THE IRON LAW: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST.

Write production code before the test? Delete it. Start over. Do not keep it for "reference" or "adapt" it. Delete means delete.

Violating the letter of the rules is violating the spirit of the rules.

REQUIRED PREREQUISITE: You must have already completed slow-powers:working-in-isolation — establish an isolated workspace before writing any test or production code.

REQUIRED NEXT SKILL: You must complete slow-powers:verifying-development-work next, after the TDD implementation work is done and before claiming the task is complete or handing work back to the user.

Red-green-refactor cycle

1. RED — Write a failing test:
   • Write one minimal, focused test showing what the behavior should do.
   • Use real code and real inputs; avoid mocks unless absolutely unavoidable. Before committing a test, scan it against the Testing anti-patterns table below; if it matches a row, read the named section of the testing anti-patterns reference first.
2. Verify RED — Watch it fail:
   • Run the test command: npm test / pytest / go test.
   • MANDATORY: Verify it fails for the expected reason (for example, a function is undefined or a value is incorrect), not because of a typo or build error.
3. GREEN — Write minimal code:
   • Write the simplest possible implementation to make the test pass.
   • Avoid over-engineering or speculative optimization.
4. Verify GREEN — Watch it pass:
   • Run the test suite. Verify the test passes, and no regressions are introduced.
5. REFACTOR — Clean up:
   • Clean up names, remove duplication, and extract helper methods.
   • Keep the test suite green. Do not add new behavior during refactoring.

Example: code vs. mock testing

Good (focuses on real behavior)

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

Bad (focuses on mock implementation detail)

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

Testing anti-patterns — scan before you commit a test

While writing or changing a test, check it against this table. If a row matches, read the named section of the testing anti-patterns reference before moving on — mocks are the most common source of these, but not the only one.

Common rationalizations

Red flags — STOP and start over

• Code before test
• "I already manually tested it"
• "Tests after achieve the same purpose"
• "It's about spirit not ritual"
• "This is different because..."

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