test-driven-development

Test-Driven Development (TDD)

Source: obra/superpowers (MIT)

Overview

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.

When to Use

Always: New features, bug fixes, refactoring, behavior changes.

Exceptions (ask your human partner): Throwaway prototypes, generated code, configuration files.

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

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

Red-Green-Refactor

RED — Write Failing Test

• Write one minimal test showing what should happen
• One behavior, clear name, real code (no mocks unless unavoidable)

Verify RED — Watch It Fail

MANDATORY. Run the test. Confirm:

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

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. Run the test. Confirm:

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

REFACTOR — Clean Up

After green only: remove duplication, improve names, extract helpers. Keep tests green. Don't add behavior.

Good Tests

| Quality | Good | Bad | |---------|------|-----| | Minimal | One thing. "and" in name? Split it. | test('validates email and domain and whitespace') | | Clear | Name describes behavior | test('test1') | | Shows intent | Demonstrates desired API | Obscures what code should do |

Red Flags — STOP and Start Over

• Code before test
• Test after implementation
• Test passes immediately
• Can't explain why test failed
• Rationalizing "just this once"
• "Keep as reference" or "adapt existing code"

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

Verification Checklist

Before marking work complete:

• [ ] 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
• [ ] Edge cases and errors covered

Bug Fixes

Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression. Never fix bugs without a test.