167 lines
4.7 KiB
Markdown
167 lines
4.7 KiB
Markdown
---
|
|
name: test-driven-development
|
|
description: Write the test first. Watch it fail. Write minimal code to pass. Enforces TDD discipline.
|
|
source: obra/superpowers (pinned 2026-03-19)
|
|
---
|
|
|
|
# Test-Driven Development (TDD)
|
|
|
|
## 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.
|
|
|
|
**Violating the letter of the rules is violating the spirit of the rules.**
|
|
|
|
## When to Use
|
|
**Always:**
|
|
- New features
|
|
- Bug fixes
|
|
- Refactoring
|
|
- Behavior changes
|
|
|
|
**Exceptions (ask your human partner):**
|
|
- Throwaway prototypes
|
|
- Generated code
|
|
- Configuration files
|
|
|
|
Thinking "skip TDD just this once"? Stop. That's rationalization.
|
|
|
|
## The Iron Law
|
|
```
|
|
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
|
|
```
|
|
|
|
Write code before the test? Delete it. Start over.
|
|
|
|
**No exceptions:**
|
|
- Don't keep it as "reference"
|
|
- Don't "adapt" it while writing tests
|
|
- Don't look at it
|
|
- Delete means delete
|
|
|
|
Implement fresh from tests. Period.
|
|
|
|
## Red-Green-Refactor
|
|
|
|
### RED - Write Failing Test
|
|
Write one minimal test showing what should happen.
|
|
|
|
**Requirements:**
|
|
- One behavior
|
|
- Clear name
|
|
- Real code (no mocks unless unavoidable)
|
|
|
|
### Verify RED - Watch It Fail
|
|
**MANDATORY. Never skip.**
|
|
|
|
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.**
|
|
|
|
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. Don't add behavior.
|
|
|
|
### Repeat
|
|
Next failing test for next feature.
|
|
|
|
## 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 |
|
|
|
|
## Why Order Matters
|
|
Tests written after code pass immediately. Passing immediately proves nothing:
|
|
- Might test wrong thing
|
|
- Might test implementation, not behavior
|
|
- Might miss edge cases you forgot
|
|
- You never saw it catch the bug
|
|
|
|
Test-first forces you to see the test fail, proving it actually tests something.
|
|
|
|
## Common Rationalizations
|
|
| Excuse | Reality |
|
|
|--------|---------|
|
|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
|
|
| "I'll test after" | Tests passing immediately prove nothing. |
|
|
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
|
|
| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
|
|
| "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
|
|
| "Need to explore first" | Fine. Throw away exploration, start with TDD. |
|
|
| "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
|
|
| "TDD will slow me down" | TDD faster than debugging. |
|
|
|
|
## 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"
|
|
|
|
**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
|
|
- [ ] Output pristine (no errors, warnings)
|
|
- [ ] Tests use real code (mocks only if unavoidable)
|
|
- [ ] Edge cases and errors covered
|
|
|
|
Can't check all boxes? You skipped TDD. Start over.
|
|
|
|
## When Stuck
|
|
| Problem | Solution |
|
|
|---------|----------|
|
|
| Don't know how to test | Write wished-for API. Write assertion first. |
|
|
| Test too complicated | Design too complicated. Simplify interface. |
|
|
| Must mock everything | Code too coupled. Use dependency injection. |
|
|
| Test setup huge | Extract helpers. Still complex? Simplify design. |
|
|
|
|
## Debugging Integration
|
|
Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
|
|
|
|
Never fix bugs without a test.
|
|
|
|
## Final Rule
|
|
```
|
|
Production code → test exists and failed first
|
|
Otherwise → not TDD
|
|
```
|
|
|
|
No exceptions without your human partner's permission.
|