tdd

Files (2)

• SKILL.md
• testing-anti-patterns.md · references/

SKILL.md (first lines)

# Test-Driven Development

## Constraint

No production code exists without a failing test that demanded it. Code written before its test gets deleted — not kept as reference, not adapted, not glanced at. Start clean from the test.

## The Cycle

### 1. RED — Write a Failing Test

One test. One behavior. Descriptive name.

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

Requirements:
- Tests a single behavior (if the name contains "and", split it)
- Exercises real code, not mocks (mock only at I/O boundaries)
- Name states the expected behavior, not "test1" or "works"

### 2. Confirm RED — Run It, Watch It Fail

```bash
npm test path/to/test.test.ts
```

Confirm:
- The test **fails** (not errors from syntax or imports)
- The failure reason matches expectations (feature absent, not typo)

If it passes: the behavior already exists. Revise the test.
If it errors: fix the error, re-run until it fails for the right reason.

### 3. GREEN — Minimal Implementation

Write the least code that makes the test pass. Nothing speculative. No options bags, no configurability, no "while I'm here" improvements.

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

### 4. Confirm GREEN — Run It, Watch It Pass

```bash
npm test path/to/test.test.ts
```

Confirm:
- New test passes
- Existing tests still pass
- No warnings or errors in output

If the new test fails: fix implementation, not the test.
If other tests break: fix the regression now.

### 5. REFACTOR — Clean Up Under Green

Only after green. Remove duplication, improve naming, extract helpers. Verify tests remain green after every change. Do not introduce new behavior.

### 6. Repeat

Next behavior, next failing test.

## Why Sequence Matters

Tests written after implementation pass on first run. A test that never failed has two problems:

- **No proof it detects the bug it claims to cover.** It may assert the wrong thing, test an implementation detail, or be vacuously true.
- **Bias toward what was built, not what was specified.** Post-hoc tests verify remembered edge cases. Pre-hoc tests force edge case discovery during design.

"Tests after" answer "what does this code do?" — "Tests before" answer "what should this code do?" These are different questions with different coverage characteristics.

Deleting existing implementation to restart with TDD is not waste. The sunk time is gone. Retaining code that lacks a red-green lineage means carrying unverified assumptions forward.

## Deflecting Rationalizations

| Rationalization | Counter |
|-----------------|---------|
| "Too simple to need a test" | Simple code breaks. The test takes seconds. |
| "I'll add tests after" | Post-hoc tests pass immediately — that proves nothing. |
| "Already tested manually" | Manual checks leave no record and cannot re-run. |
| "Deleting N hours of work is wasteful" | Sunk cost. Unverified code is the actual waste. |
| "Keep it as reference, write tests first" | You will adapt it. That is testing after. Delete. |
| "Need to explore first" | Explore, then discard the spike and start with a test. |
| "Hard to test means unclear requirements" | Hard to test means hard to use. Simplify the interface. |
| "TDD slows me down" | Debugging without tests is slower. |
| "Existing code has no tests" | New changes get tests. Legacy is not an exemption. |

## Halt Signals

Any of these indicate the cycle was broken. Delete the untested code and restart:

- Production code exists without a corresponding test that failed first
- A test passes on its first run
- Unable to explain why a test failed
- "Just this once" reasoning surfacing
- Impulse to keep pre-existing code as "reference"

## Test Quality

| Property | Indicator |
|----------|-----------|
| Focused | One behavior per test. "and" in the name signals it should split. |
| Descriptive | Name states expected behavior in plain language. |
| Intent-revealing | Test demonstrates the desired API, not internal mechanics. |
| Deterministic | No dependence on timing, execution order, or external state. |
| Boundary-mocked | Mocks exist only at I/O edges (network, filesystem, clock). Internal modules use real instances. |

## When Stuck

From renathoaz/arsyn, MIT.

More from renathoaz/arsyn