89jobrien Test-Driven Development (TDD)
Core Principle
Write tests before code. Always. TDD is not about testing—it's about design through small, disciplined steps.
When to Use This Skill
- User explicitly requests TDD ("use TDD", "test first", "test-driven")
- Implementing new features
- Fixing bugs (write failing test that reproduces bug first)
- Refactoring existing code (ensure tests exist first)
The Three Laws (Never Violate)
- Write NO production code without a failing test first
- Write only enough test to demonstrate one failure
- Write only enough code to pass that test
Protocol
Phase 1: RED - Write Failing Test
□ Write ONE test that defines desired behavior
□ Run test - verify it FAILS
□ Verify it fails for the RIGHT reason (not syntax error)
□ DO NOT write implementation yet
Evidence required: Show test output with failure message
Phase 2: GREEN - Minimal Implementation
□ Write MINIMAL code to make test pass
□ Resist urge to add extra features
□ Run test - verify it PASSES
□ If test still fails, fix implementation (not test)
Evidence required: Show test output with pass
Phase 3: REFACTOR - Clean Code
□ Remove code duplication (DRY)
□ Improve naming for clarity
□ Extract complex logic into functions
□ Run ALL tests - must stay green throughout
□ Check test coverage on changed lines
Evidence required: Show all tests still passing after refactor
Cycle Complete → Repeat
After REFACTOR, start new RED phase for next behavior.
Common Mistakes to Avoid
Writing Multiple Tests at Once
❌ WRONG: Test entire feature in one go
✅ CORRECT: One test at a time. Pass it. Refactor. Next test.
Skipping Refactor Phase
❌ WRONG: "Tests pass, ship it!"
✅ CORRECT: ALWAYS refactor. Clean code is the goal.
Implementation Before Test
❌ WRONG: Write code, then add tests after
✅ CORRECT: If code exists before test, delete it and start with test
Over-Engineering in GREEN
❌ WRONG: Add error handling, edge cases, optimizations
✅ CORRECT: Simplest thing that makes THIS test pass
Workflow Example
Task: "Add user login feature"
RED Phase:
1. Write test: test_login_with_valid_credentials()
2. Run: pytest -v → FAILED (no login function exists)
3. Evidence: "FAILED - AttributeError: 'User' has no 'login'"
GREEN Phase:
4. Write minimal login() method
5. Run: pytest -v → PASSED
6. Evidence: "1 passed in 0.03s"
REFACTOR Phase:
7. Extract password hashing to separate function
8. Improve variable names
9. Run: pytest -v → PASSED (still)
10. Evidence: "1 passed in 0.02s"
Next cycle: test_login_with_invalid_credentials()
Test Patterns
Arrange-Act-Assert (AAA)
def test_user_can_login():
# Arrange
user = User(email="test@example.com", password="secret")
# Act
result = user.login("secret")
# Assert
assert result.success is True
assert result.token is not None
Given-When-Then (BDD style)
def test_login_with_wrong_password():
# Given a registered user
user = create_user(password="correct")
# When they attempt login with wrong password
result = user.login("wrong")
# Then login should fail
assert result.success is False
assert "Invalid password" in result.error
Anti-Patterns
❌ Write test that passes immediately (test proves nothing)
❌ Test implementation details instead of behavior
❌ Skip tests for "simple" code
❌ Write tests after implementation "because we're in a hurry"
❌ Large tests that verify many things at once
✅ Each test verifies ONE behavior
✅ Test names describe the behavior being tested
✅ Tests are independent (no shared state)
✅ Tests run fast (mock external dependencies)
Integration with Other Skills
- pre-task-checkpoint: Run checkpoint before each RED phase to frame what behavior to test
- evidence-reasoning: Show actual test output, never claim "tests pass" without evidence
- completion-discipline: Each GREEN phase requires evidence of passing test
- verification-calibration: Match test rigor to feature stakes (🔴 critical features need comprehensive tests)
- clarifying-questions: Clarify expected behavior BEFORE writing test
Self-Check
Before moving from RED to GREEN:
[ ] Test actually fails?
[ ] Fails for the right reason?
[ ] Test name describes behavior?
Before moving from GREEN to REFACTOR:
[ ] Test passes?
[ ] Implementation is minimal?
[ ] No premature optimization?
Before starting next cycle:
[ ] Code is clean?
[ ] All tests still pass?
[ ] Ready for next behavior?
Meta-Principle
TDD is a DESIGN technique, not a testing technique.
The cycle never changes: RED → GREEN → REFACTOR → Repeat
Writing tests first forces you to think about:
- What behavior do I need?
- How will I know it works?
- What's the simplest implementation?
This produces better-designed, more maintainable code.