---
name: tdd
description: "Test-Driven Development workflow with RED-GREEN-REFACTOR, lore from Kent Beck, Michael Feathers, and Ousterhout's counterpoint"
tags:
  - testing
  - workflow
  - methodology
  - tdd
---

# Test-Driven Development (TDD)

## The Rhythm: RED-GREEN-REFACTOR

```
1. RED    - Write failing test first (define expected behavior)
2. GREEN  - Minimal implementation to pass (don't over-engineer)
3. REFACTOR - Clean up, remove duplication, run tests again
```

## Why TDD Works (The Lore)

### Kent Beck (Test-Driven Development by Example)

> "The act of writing a unit test is more an act of design than verification."

- Tests become executable documentation of intent
- "Fake it til you make it" - start with hardcoded values, generalize
- Small steps reduce debugging time
- Confidence to refactor comes from test coverage

### Michael Feathers (Working Effectively with Legacy Code)

> "The most powerful feature-addition technique I know of is test-driven development."

- TDD works in both OO and procedural code
- Writing tests first forces you to think about interfaces
- Tests are the safety net that enables aggressive refactoring
- Legacy code = code without tests

### Martin Fowler (Refactoring)

> "Kent Beck baked this habit of writing the test first into a technique called Test-Driven Development."

- TDD relies on short cycles
- Tests enable refactoring
- Refactoring becomes safe - tests catch regressions instantly

## The Counterpoint: Know When to Break the Rule

### John Ousterhout (A Philosophy of Software Design)

> "The problem with test-driven development is that it focuses attention on getting specific features working, rather than finding the best design."

**When TDD can hurt:**

- Can lead to tactical programming (feature-focused, not design-focused)
- May produce code that's easy to test but hard to understand
- Risk of over-testing implementation details

**The balance:**

- For exploratory/architectural work, design first, then add tests
- Don't let tests drive you into a corner
- Step back periodically to evaluate overall design

## When to Use TDD

✅ **Use TDD for:**

- New features with clear requirements
- Bug fixes (write test that reproduces bug first)
- Refactoring existing code (add characterization tests first)
- API design (tests reveal ergonomics)
- Any code that will be maintained long-term

❌ **Skip TDD for:**

- Exploratory spikes (but add tests after if keeping the code)
- Emergency hotfixes (but add tests immediately after)
- Pure UI/styling changes
- One-off scripts
- Throwaway prototypes

## The TDD Workflow

```bash
# 1. Write test, watch it fail
bun test src/thing.test.ts  # RED - test fails

# 2. Implement minimal code to pass
bun test src/thing.test.ts  # GREEN - test passes

# 3. Refactor, tests still pass
bun test src/thing.test.ts  # GREEN - still passing

# 4. Repeat for next behavior
```

## TDD Patterns

### Start with the Assertion

Write the assertion first, then work backwards:

```typescript
// Start here
expect(result).toBe(42);

// Then figure out what 'result' is
const result = calculate(input);

// Then figure out what 'input' is
const input = { value: 21 };
```

### Triangulation

Use multiple examples to drive generalization:

```typescript
it("doubles 2", () => expect(double(2)).toBe(4));
it("doubles 3", () => expect(double(3)).toBe(6));
// Now you MUST implement the general solution
```

### Obvious Implementation

When the solution is obvious, just write it:

```typescript
function add(a: number, b: number): number {
  return a + b; // Don't fake this
}
```

### Fake It Til You Make It

When unsure, start with hardcoded values:

```typescript
// First pass
function fibonacci(n: number): number {
  return 1; // Passes for n=1
}

// Add test for n=2, then generalize
```

## Testing Pyramid

```
        /\
       /  \     E2E (few)
      /----\
     /      \   Integration (some)
    /--------\
   /          \ Unit (many)
  --------------
```

- **Unit tests**: Fast, isolated, test one thing
- **Integration tests**: Test component interactions
- **E2E tests**: Test full user flows (expensive, use sparingly)

## Common TDD Mistakes

1. **Writing too many tests at once** - One failing test at a time
2. **Testing implementation, not behavior** - Test what, not how
3. **Skipping the refactor step** - Technical debt accumulates
4. **Over-mocking** - Don't mock what you don't own
5. **Testing private methods** - Test through public interface

## Integration with Beads

When working on a bead:

1. Start bead: `beads_start(id="bd-123")`
2. Write failing test for the requirement
3. Implement to pass
4. Refactor
5. Close bead: `beads_close(id="bd-123", reason="Done: tests passing")`