--- name: test-driven-development description: This skill should be used when implementing any feature or bugfix, before writing implementation code user-invocable: false --- # 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. ```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 ```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 **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. ```typescript async function retryOperation(fn: () => Promise): Promise { 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 ```typescript async function retryOperation( fn: () => Promise, options?: { maxRetries?: number; backoff?: 'linear' | 'exponential'; onRetry?: (attempt: number) => void; } ): Promise { // YAGNI } ``` Over-engineered 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(); 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(); 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.