test-driven-development · diff
git:20260327.e661ac0 to git:20260328.abb5d77
26 added, 1 removed. Audit A to A.
---
name: test-driven-development
description: This skill should be used when implementing any feature or bugfix, before writing implementation code
user-invocable: false
- effort: high
---
# 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.**
+
+ ## Pre-flight: Model Recommendation
+
+ **Your current effort level is `{{effort_level}}`.**
+
+ Skip this step silently if effort is `high` or higher AND you are Sonnet or Opus.
+ If effort is below `high`, you MUST show the recommendation prompt — regardless of model.
+ If you are not Sonnet or Opus, you MUST show the recommendation prompt - regardless of effort level.
+
+ Otherwise → use `AskUserQuestion`:
+
+ ```json
+ {
+ "questions": [{
+ "question": "Do you want to switch? TDD discipline enforcement requires consistent reasoning to resist rationalizations for skipping steps.\n\nTo switch: cancel, run `/effort high` (and `/model sonnet` if on Haiku), then re-invoke this skill.",
+ "header": "Recommended: Sonnet or Opus at high effort",
+ "options": [
+ { "label": "Continue" },
+ { "label": "Cancel — I'll switch first" }
+ ],
+ "multiSelect": false
+ }]
+ }
+ ```
+
+ If the user selects "Cancel — I'll switch first": output the switching commands above and stop. Do not proceed with the skill.
## 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
```dot
digraph tdd_cycle {
rankdir=LR;
red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
verify_red [label="Verify fails\ncorrectly", shape=diamond];
green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
verify_green [label="Verify passes\nAll green", shape=diamond];
refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
next [label="Next", shape=ellipse];
red -> verify_red;
verify_red -> green [label="yes"];
verify_red -> red [label="wrong\nfailure"];
green -> verify_green;
verify_green -> refactor [label="yes"];
verify_green -> green [label="no"];
refactor -> verify_green [label="stay\ngreen"];
verify_green -> next;
next -> red;
}
```
### RED - Write Failing Test
Write one minimal test showing what should happen.
<Good>
```typescript
test('retries failed operations 3 times', async () => {
let attempts = 0;
const operation = () => {
attempts++;
if (attempts < 3) throw new Error('fail');
return 'success';
};
const result = await retryOperation(operation);
expect(result).toBe('success');
expect(attempts).toBe(3);
});
```
Clear name, tests real behavior, one thing
</Good>
<Bad>
```typescript
test('retry works', async () => {
const mock = jest.fn()
.mockRejectedValueOnce(new Error())
.mockRejectedValueOnce(new Error())
.mockResolvedValueOnce('success');
await retryOperation(mock);
expect(mock).toHaveBeenCalledTimes(3);
});
```
Vague name, tests mock not code
</Bad>
**Requirements:**
- One behavior
- Clear name
- Real code (no mocks unless unavoidable)
### Verify RED - Watch It Fail
**MANDATORY. Never skip.**
```bash
npm test path/to/test.test.ts
```
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.
<Good>
```typescript
async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
for (let i = 0; i < 3; i++) {
try {
return await fn();
} catch (e) {
if (i === 2) throw e;
}
}
throw new Error('unreachable');
}
```
Just enough to pass
</Good>
<Bad>
```typescript
async function retryOperation<T>(
fn: () => Promise<T>,
options?: {
maxRetries?: number;
backoff?: 'linear' | 'exponential';
onRetry?: (attempt: number) => void;
}
): Promise<T> {
// YAGNI
}
```
Over-engineered
</Bad>
Don't add features, refactor other code, or "improve" beyond the test.
### Verify GREEN - Watch It Pass
**MANDATORY.**
```bash
npm test path/to/test.test.ts
```
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 |
## What NOT to Test
Not everything benefits from TDD. Writing tests for these wastes budget and creates maintenance burden:
**Skip tests for:**
- Static markup and CSS classes (layout, colors, spacing, font sizes)
- Element counts ("renders 6 nav items") — only fails on intentional changes
- Pure presentational components with zero logic (just HTML + Tailwind)
- Tooltip styling, container classes, overflow attributes
- That an icon renders as an SVG
**DO test:**
- Conditional rendering (shows X when condition Y)
- Computed values (formats currency, calculates percentage)
- User interactions (click, keyboard, filter, sort, pagination)
- State transitions (toggle, edit mode, selection)
- Edge cases (empty data, zero values, overflow)
- Business rules (color thresholds, frequency detection, amortization math)
**Rule of thumb:** If the test would only fail when someone intentionally changes the UI, it's not testing behavior — it's preventing change. Delete it.
## Why Order Matters
**"I'll write tests after to verify it works"**
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.
**"I already manually tested all the edge cases"**
Manual testing is ad-hoc. You think you tested everything but:
- No record of what you tested
- Can't re-run when code changes
- Easy to forget cases under pressure
- "It worked when I tried it" ≠ comprehensive
Automated tests are systematic. They run the same way every time.
**"Deleting X hours of work is wasteful"**
Sunk cost fallacy. The time is already gone. Your choice now:
- Delete and rewrite with TDD (X more hours, high confidence)
- Keep it and add tests after (30 min, low confidence, likely bugs)
The "waste" is keeping code you can't trust. Working code without real tests is technical debt.
**"TDD is dogmatic, being pragmatic means adapting"**
TDD IS pragmatic:
- Finds bugs before commit (faster than debugging after)
- Prevents regressions (tests catch breaks immediately)
- Documents behavior (tests show how to use code)
- Enables refactoring (change freely, tests catch breaks)
"Pragmatic" shortcuts = debugging in production = slower.
**"Tests after achieve the same goals - it's spirit not ritual"**
No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"
Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones.
Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't).
30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.
## 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. |
| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
| "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. Pragmatic = test-first. |
| "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
| "Existing code has no tests" | You're improving it. Add tests for existing code. |
## 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"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "Keep as reference" or "adapt existing code"
- "Already spent X hours, deleting is wasteful"
- "TDD is dogmatic, I'm being pragmatic"
- "This is different because..."
**All of these mean: Delete code. Start over with TDD.**
## Example: Bug Fix
**Bug:** Empty email accepted
**RED**
```typescript
test('rejects empty email', async () => {
const result = await submitForm({ email: '' });
expect(result.error).toBe('Email required');
});
```
**Verify RED**
```bash
$ npm test
FAIL: expected 'Email required', got undefined
```
**GREEN**
```typescript
function submitForm(data: FormData) {
if (!data.email?.trim()) {
return { error: 'Email required' };
}
// ...
}
```
**Verify GREEN**
```bash
$ npm test
PASS
```
**REFACTOR**
Extract validation for multiple fields if needed.
## Verification Checklist
Before marking work complete:
- [ ] Every function/method with logic (conditionals, computation, side effects) 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. Ask your human partner. |
| 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. |
## Coverage Requirements
### Target: 80%+ Coverage of Logic Paths
- Coverage means branch/logic coverage, not line coverage of markup
- Pure presentational components (no conditionals, no computed values) do NOT need unit tests — they are validated visually
- Do not write tests solely to increase coverage numbers
- All edge cases covered
- Error scenarios tested
- Boundary conditions verified
### Test Types
| Type | Scope | Examples |
|------|-------|----------|
| **Unit** | Individual functions, utilities, pure functions | Component logic, helpers |
| **Integration** | API endpoints, database operations, service interactions | External API calls |
| **E2E** | Critical user flows, complete workflows | Browser automation, UI interactions |
### E2E Test Pattern (Playwright)
```typescript
import { test, expect } from '@playwright/test'
test('user can search and filter markets', async ({ page }) => {
await page.goto('/')
await page.click('a[href="/markets"]')
await expect(page.locator('h1')).toContainText('Markets')
await page.fill('input[placeholder="Search"]', 'election')
await page.waitForTimeout(600) // debounce
const results = page.locator('[data-testid="market-card"]')
await expect(results).toHaveCount(5, { timeout: 5000 })
})
```
### Coverage Verification
```bash
npm run test:coverage
# Verify 80%+ coverage achieved
```
### Coverage Thresholds (jest.config.js)
```json
{
"coverageThresholds": {
"global": {
"branches": 80,
"functions": 80,
"lines": 80,
"statements": 80
}
}
}
```
## Debugging Integration
Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
Never fix bugs without a test.
## Testing Anti-Patterns
Mocks are tools to isolate, not things to test. Before every mock, run these gates:
### Don't test mock behavior
```
BEFORE asserting on any mock element:
Ask: "Am I testing real behavior or mock existence?"
IF mock existence → delete the assertion or unmock the component
```
```typescript
// ❌ BAD: Testing that the mock exists
test('renders sidebar', () => {
render(<Page />);
expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
});
// ✅ GOOD: If sidebar must be mocked, assert on Page's behavior
test('page passes user data to sidebar', () => {
render(<Page user={testUser} />);
expect(Sidebar).toHaveBeenCalledWith(
expect.objectContaining({ user: testUser }), expect.anything()
);
});
```
### Don't add test-only methods to production classes
```
BEFORE adding any method to a production class:
Ask: "Is this only used by tests?"
IF yes → put it in test utilities instead
```
### Mock at the right level
```
BEFORE mocking any method:
1. "What side effects does the real method have?"
2. "Does this test depend on any of those side effects?"
IF yes → mock lower (the actual slow/external operation), not the method the test depends on
```
```typescript
// ❌ BAD: Mock prevents config write that test depends on
test('detects duplicate server', async () => {
vi.mock('ToolCatalog', () => ({
discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
}));
await addServer(config);
await addServer(config); // Should throw - but won't!
});
// ✅ GOOD: Mock the slow part, preserve behavior test needs
test('detects duplicate server', async () => {
vi.mock('MCPServerManager'); // Just mock slow server startup
await addServer(config); // Config written
await addServer(config); // Duplicate detected ✓
});
```
### Preserve real semantics in mocks
```
BEFORE creating any mock:
Ask: "What type does the real implementation return?"
Value vs. stream? Sync vs. async? Array vs. cursor?
IF mock changes the abstraction type → fix it
```
```typescript
// ❌ BAD: Mock returns array, real implementation returns async cursor
const mockDb = {
getUsers: vi.fn().mockResolvedValue([
{ id: '1', name: 'Alice' },
{ id: '2', name: 'Bob' },
])
};
// Test passes, but production breaks on 1000+ users when
// pagination and backpressure actually matter.
// ✅ GOOD: Mock preserves real cursor semantics
const mockDb = {
getUsers: vi.fn().mockReturnValue({
async *[Symbol.asyncIterator]() {
yield { id: '1', name: 'Alice' };
yield { id: '2', name: 'Bob' };
}
})
};
```
### Red flags
- Assertion checks for `*-mock` test IDs
- Methods only called in test files
- Mock setup is >50% of test code
- `mockResolvedValue()` when real code returns a stream
- Mocking "just to be safe"
## Final Rule
```
Production code → test exists and failed first
Otherwise → not TDD
```
No exceptions without your human partner's permission.