timequity/test-driven-development

Test-Driven Development (TDD)

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

Core principle: If you didn't watch the test fail, you don't know if it tests the right thing.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Write code before the test? Delete it. Start over.

Red-Green-Refactor

RED — Write Failing Test

Write one minimal test showing what should happen.

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

Requirements:

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

Verify RED — Watch It Fail

MANDATORY. Never skip.

npm test path/to/test.test.ts

Confirm:

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

GREEN — Minimal Code

Write simplest code to pass the test.

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

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

Verify GREEN — Watch It Pass

MANDATORY.

npm test path/to/test.test.ts

Confirm:

• Test passes
• Other tests still pass
• Output pristine

REFACTOR — Clean Up

After green only:

• Remove duplication
• Improve names
• Extract helpers

Keep tests green. Don't add behavior.

Common Rationalizations

| Excuse | Reality | |--------|---------| | "Too simple to test" | Simple code breaks. Test takes 30 seconds. | | "I'll test after" | Tests passing immediately prove nothing. | | "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. | | "TDD will slow me down" | TDD faster than debugging. |

Red Flags — STOP and Start Over

• Code before test
• Test passes immediately
• Can't explain why test failed
• "Just this once"

Verification Checklist

Before marking work complete:

• [ ] Every new function has a test
• [ ] Watched each test fail before implementing
• [ ] Wrote minimal code to pass each test
• [ ] All tests pass
• [ ] Output pristine (no errors, warnings)