# Tdd Workflow > Use this skill when writing new features, fixing bugs, or refactoring code. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests. - Skill: `auto-skiller/tdd-workflow` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add auto-skiller/tdd-workflow` - Raw SKILL.md: https://api.skillmd.com/api/skills/auto-skiller/tdd-workflow/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: Auto-Skiller (https://skillmd.com/u/auto-skiller) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/auto-skiller/tdd-workflow --- # Test-Driven Development Workflow ## 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. ## When to Activate - Writing new features or functionality - Fixing bugs or issues - Refactoring existing code - Adding API endpoints - Creating new components **Exceptions (ask your human partner):** - Throwaway prototypes - Generated code - Configuration files Thinking "skip TDD just this once"? Stop. That's rationalization. ## Core Principles ### 1. Tests BEFORE Code ALWAYS write tests first, then implement code to make tests pass. ### 2. Coverage Requirements - Minimum 80% coverage (unit + integration + E2E) - All edge cases covered - Error scenarios tested - Boundary conditions verified ### 3. Test Types #### Unit Tests - Individual functions and utilities - Component logic - Pure functions - Helpers and utilities #### Integration Tests - API endpoints - Database operations - Service interactions - External API calls #### E2E Tests (Playwright) - Critical user flows - Complete workflows - Browser automation - UI interactions ### 4. Git Checkpoints - If the repository is under Git, create a checkpoint commit after each TDD stage - Do not squash or rewrite these checkpoint commits until the workflow is complete - Each checkpoint commit message must describe the stage and the exact evidence captured - Count only commits created on the current active branch for the current task - Do not treat commits from other branches, earlier unrelated work, or distant branch history as valid checkpoint evidence - Before treating a checkpoint as satisfied, verify that the commit is reachable from the current `HEAD` on the active branch and belongs to the current task sequence - The preferred compact workflow is: - one commit for failing test added and RED validated - one commit for minimal fix applied and GREEN validated - one optional commit for refactor complete - Separate evidence-only commits are not required if the test commit clearly corresponds to RED and the fix commit clearly corresponds to GREEN ## Red-Green-Refactor Cycle ### 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.** This step is the RED gate for all production changes. Before modifying production code, verify a valid RED state via one of these paths: - **Runtime RED:** - The relevant test target compiles successfully - The new or changed test is actually executed - The result is RED - **Compile-time RED:** - The new test newly instantiates, references, or exercises the buggy code path - The compile failure is itself the intended RED signal In either case, the failure is caused by the intended business-logic bug, undefined behavior, or missing implementation. The failure is not caused only by unrelated syntax errors, broken test setup, missing dependencies, or unrelated regressions. A test that was only written but not compiled and executed does not count as RED. Do not edit production code until this RED state is confirmed. ```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. If the repository is under Git, create a checkpoint commit immediately after this stage is validated. Recommended commit message format: - `test: add reproducer for ` - This commit may also serve as the RED validation checkpoint if the reproducer was compiled and executed and failed for the intended reason - Verify that this checkpoint commit is on the current active branch before continuing ### 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. If the repository is under Git, stage the minimal fix now but defer the checkpoint commit until GREEN is validated. ### Verify GREEN - Watch It Pass **MANDATORY.** Rerun the same relevant test target after the fix and confirm the previously failing test is now GREEN. Only after a valid GREEN result may you proceed to refactor. ```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. If the repository is under Git, create a checkpoint commit immediately after GREEN is validated. Recommended commit message format: - `fix: ` - The fix commit may also serve as the GREEN validation checkpoint if the same relevant test target was rerun and passed - Verify that this checkpoint commit is on the current active branch before continuing ### REFACTOR - Clean Up After green only: - Remove duplication - Improve names - Optimize performance - Enhance readability Keep tests green. Don't add behavior. If the repository is under Git, create a checkpoint commit immediately after refactoring is complete and tests remain green. Recommended commit message format: - `refactor: clean up after implementation` - Verify that this checkpoint commit is on the current active branch before considering the TDD cycle complete ### 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 | ## 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.** ## Testing Patterns ### Unit Test Pattern (Jest/Vitest) ```typescript import { render, screen, fireEvent } from '@testing-library/react' import { Button } from './Button' describe('Button Component', () => { it('renders with correct text', () => { render() expect(screen.getByText('Click me')).toBeInTheDocument() }) it('calls onClick when clicked', () => { const handleClick = jest.fn() render() fireEvent.click(screen.getByRole('button')) expect(handleClick).toHaveBeenCalledTimes(1) }) it('is disabled when disabled prop is true', () => { render() expect(screen.getByRole('button')).toBeDisabled() }) }) ``` ### API Integration Test Pattern ```typescript import { NextRequest } from 'next/server' import { GET } from './route' describe('GET /api/markets', () => { it('returns markets successfully', async () => { const request = new NextRequest('http://localhost/api/markets') const response = await GET(request) const data = await response.json() expect(response.status).toBe(200) expect(data.success).toBe(true) expect(Array.isArray(data.data)).toBe(true) }) it('validates query parameters', async () => { const request = new NextRequest('http://localhost/api/markets?limit=invalid') const response = await GET(request) expect(response.status).toBe(400) }) it('handles database errors gracefully', async () => { // Mock database failure const request = new NextRequest('http://localhost/api/markets') // Test error handling }) }) ``` ### E2E Test Pattern (Playwright) ```typescript import { test, expect } from '@playwright/test' test('user can search and filter markets', async ({ page }) => { // Navigate to markets page await page.goto('/') await page.click('a[href="/markets"]') // Verify page loaded await expect(page.locator('h1')).toContainText('Markets') // Search for markets await page.fill('input[placeholder="Search markets"]', 'election') // Wait for debounce and results await page.waitForTimeout(600) // Verify search results displayed const results = page.locator('[data-testid="market-card"]') await expect(results).toHaveCount(5, { timeout: 5000 }) // Verify results contain search term const firstResult = results.first() await expect(firstResult).toContainText('election', { ignoreCase: true }) // Filter by status await page.click('button:has-text("Active")') // Verify filtered results await expect(results).toHaveCount(3) }) ``` ## Test File Organization ``` src/ ├── components/ │ ├── Button/ │ │ ├── Button.tsx │ │ ├── Button.test.tsx # Unit tests │ │ └── Button.stories.tsx # Storybook │ └── MarketCard/ │ ├── MarketCard.tsx │ └── MarketCard.test.tsx ├── app/ │ └── api/ │ └── markets/ │ ├── route.ts │ └── route.test.ts # Integration tests └── e2e/ ├── markets.spec.ts # E2E tests ├── trading.spec.ts └── auth.spec.ts ``` ## Mocking External Services ### Supabase Mock ```typescript jest.mock('@/lib/supabase', () => ({ supabase: { from: jest.fn(() => ({ select: jest.fn(() => ({ eq: jest.fn(() => Promise.resolve({ data: [{ id: 1, name: 'Test Market' }], error: null })) })) })) } })) ``` ### Redis Mock ```typescript jest.mock('@/lib/redis', () => ({ searchMarketsByVector: jest.fn(() => Promise.resolve([ { slug: 'test-market', similarity_score: 0.95 } ])), checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true })) })) ``` ### OpenAI Mock ```typescript jest.mock('@/lib/openai', () => ({ generateEmbedding: jest.fn(() => Promise.resolve( new Array(1536).fill(0.1) // Mock 1536-dim embedding )) })) ``` ## Test Coverage Verification ### Run Coverage Report ```bash npm run test:coverage ``` ### Coverage Thresholds ```json { "jest": { "coverageThresholds": { "global": { "branches": 80, "functions": 80, "lines": 80, "statements": 80 } } } } ``` ## Common Testing Mistakes to Avoid ### FAIL: WRONG: Testing Implementation Details ```typescript // Don't test internal state expect(component.state.count).toBe(5) ``` ### PASS: CORRECT: Test User-Visible Behavior ```typescript // Test what users see expect(screen.getByText('Count: 5')).toBeInTheDocument() ``` ### FAIL: WRONG: Brittle Selectors ```typescript // Breaks easily await page.click('.css-class-xyz') ``` ### PASS: CORRECT: Semantic Selectors ```typescript // Resilient to changes await page.click('button:has-text("Submit")') await page.click('[data-testid="submit-button"]') ``` ### FAIL: WRONG: No Test Isolation ```typescript // Tests depend on each other test('creates user', () => { /* ... */ }) test('updates same user', () => { /* depends on previous test */ }) ``` ### PASS: CORRECT: Independent Tests ```typescript // Each test sets up its own data test('creates user', () => { const user = createTestUser() // Test logic }) test('updates user', () => { const user = createTestUser() // Update logic }) ``` ## Testing Anti-Patterns When adding mocks or test utilities, avoid these common pitfalls: - Testing mock behavior instead of real behavior - Adding test-only methods to production classes - Mocking without understanding dependencies ## Verification Checklist Before marking work complete: - [ ] Every new function/method 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 - [ ] 80%+ coverage achieved 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. | ## Debugging Integration Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression. Never fix bugs without a test. ## Continuous Testing ### Watch Mode During Development ```bash npm test -- --watch # Tests run automatically on file changes ``` ### Pre-Commit Hook ```bash # Runs before every commit npm test && npm run lint ``` ### CI/CD Integration ```yaml # GitHub Actions - name: Run Tests run: npm test -- --coverage - name: Upload Coverage uses: codecov/codecov-action@v3 ``` ## Best Practices 1. **Write Tests First** - Always TDD 2. **One Assert Per Test** - Focus on single behavior 3. **Descriptive Test Names** - Explain what's tested 4. **Arrange-Act-Assert** - Clear test structure 5. **Mock External Dependencies** - Isolate unit tests 6. **Test Edge Cases** - Null, undefined, empty, large 7. **Test Error Paths** - Not just happy paths 8. **Keep Tests Fast** - Unit tests < 50ms each 9. **Clean Up After Tests** - No side effects 10. **Review Coverage Reports** - Identify gaps ## Success Metrics - 80%+ code coverage achieved - All tests passing (green) - No skipped or disabled tests - Fast test execution (< 30s for unit tests) - E2E tests cover critical user flows - Tests catch bugs before production --- **Remember**: Tests are not optional. They are the safety net that enables confident refactoring, rapid development, and production reliability.