Test-Driven Development Workflow - Everything Claude Code

This guide ensures all code development follows TDD principles with comprehensive test coverage.

Core Principles

Tests BEFORE Code

ALWAYS write tests first, then implement code to make tests pass.

80%+ Coverage

Minimum 80% coverage (unit + integration + E2E). All edge cases covered.

Three Test Types

Unit, integration, and E2E tests. All required.

When to Use TDD

Writing new features or functionality
Fixing bugs or issues
Refactoring existing code
Adding API endpoints
Creating new components

Test Types

Unit Tests

Test individual functions and components in isolation.Coverage:

Individual functions and utilities
Component logic
Pure functions
Helpers and utilities

Integration Tests

Test how different parts of the system work together.Coverage:

API endpoints
Database operations
Service interactions
External API calls

E2E Tests (Playwright)

E2E Tests

Test complete user workflows in a real browser.Coverage:

Critical user flows
Complete workflows
Browser automation
UI interactions

The TDD Workflow

Write User Journeys

As a [role], I want to [action], so that [benefit]

Example:
As a user, I want to search for markets semantically,
so that I can find relevant markets even without exact keywords.

Generate Test Cases

describe('Semantic Search', () => {
  it('returns relevant markets for query', async () => {
    // Test implementation
  })

  it('handles empty query gracefully', async () => {
    // Test edge case
  })

  it('falls back to substring search when Redis unavailable', async () => {
    // Test fallback behavior
  })

  it('sorts results by similarity score', async () => {
    // Test sorting logic
  })
})

Run Tests (They Should Fail)

npm test
# Tests should fail - we haven't implemented yet

RED phase: Tests must fail first to verify they’re testing correctly.

Implement Code

Write minimal code to make tests pass:

// Implementation guided by tests
export async function searchMarkets(query: string) {
  // Implementation here
}

Run Tests Again

npm test
# Tests should now pass

GREEN phase: Tests pass with minimal implementation.

Refactor

Improve code quality while keeping tests green:

Remove duplication
Improve naming
Optimize performance
Enhance readability

IMPROVE phase: Refactor with confidence. Tests protect against regressions.

Verify Coverage

npm run test:coverage
# Verify 80%+ coverage achieved

Testing Patterns

Unit Test Pattern (Jest/Vitest)

import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'

describe('Button Component', () => {
  it('renders with correct text', () => {
    render(<Button>Click me</Button>)
    expect(screen.getByText('Click me')).toBeInTheDocument()
  })

  it('calls onClick when clicked', () => {
    const handleClick = jest.fn()
    render(<Button onClick={handleClick}>Click</Button>)

    fireEvent.click(screen.getByRole('button'))

    expect(handleClick).toHaveBeenCalledTimes(1)
  })

  it('is disabled when disabled prop is true', () => {
    render(<Button disabled>Click</Button>)
    expect(screen.getByRole('button')).toBeDisabled()
  })
})

API Integration Test Pattern

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)

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('user can create a new market', async ({ page }) => {
  // Login first
  await page.goto('/creator-dashboard')

  // Fill market creation form
  await page.fill('input[name="name"]', 'Test Market')
  await page.fill('textarea[name="description"]', 'Test description')
  await page.fill('input[name="endDate"]', '2025-12-31')

  // Submit form
  await page.click('button[type="submit"]')

  // Verify success message
  await expect(page.locator('text=Market created successfully')).toBeVisible()

  // Verify redirect to market page
  await expect(page).toHaveURL(/\/markets\/test-market/)
})

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

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

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

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

npm run test:coverage

Coverage Thresholds

{
  "jest": {
    "coverageThresholds": {
      "global": {
        "branches": 80,
        "functions": 80,
        "lines": 80,
        "statements": 80
      }
    }
  }
}

All thresholds set to 80%. Tests fail if coverage drops below this.

Common Testing Mistakes

❌ Testing Implementation Details

// Don't test internal state
expect(component.state.count).toBe(5)

❌ Brittle Selectors

// Breaks easily
await page.click('.css-class-xyz')

❌ No Test Isolation

// Tests depend on each other
test('creates user', () => { /* ... */ })
test('updates same user', () => { /* depends on previous test */ })

Continuous Testing

Watch Mode During Development

npm test -- --watch
# Tests run automatically on file changes

Pre-Commit Hook

# Runs before every commit
npm test && npm run lint

CI/CD Integration

# GitHub Actions
- name: Run Tests
  run: npm test -- --coverage
- name: Upload Coverage
  uses: codecov/codecov-action@v3

Best Practices

Write Tests First

Always TDD. No exceptions.

One Assert Per Test

Focus on single behavior.

Descriptive Test Names

Explain what’s tested.

Arrange-Act-Assert

Clear test structure.

Mock External Dependencies

Isolate unit tests.

Test Edge Cases

Null, undefined, empty, large.

Test Error Paths

Not just happy paths.

Keep Tests Fast

Unit tests < 50ms each.

Clean Up After Tests

No side effects.

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

ECC TDD Tools

tdd-guide Agent

Specialized agent that enforces write-tests-first workflow.

/tdd Command

Invoke TDD workflow immediately.

tdd-workflow Skill

Comprehensive TDD methodology and patterns.

/test-coverage Command

Analyze test coverage and identify gaps.

Example TDD Session

Start TDD Workflow

/tdd

Activates tdd-guide agent.

Write Failing Test

test('validates email format', () => {
  expect(validateEmail('invalid')).toBe(false)
  expect(validateEmail('[email protected]')).toBe(true)
})

Run: npm test — Should fail (RED)

Implement Function

export function validateEmail(email: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
}

Run: npm test — Should pass (GREEN)

Refactor

Improve code quality, keep tests green.

Verify Coverage

npm run test:coverage

Ensure 80%+ coverage.

Code Review

/code-review

Final quality check.

Tests are not optional. They are the safety net that enables confident refactoring, rapid development, and production reliability.

Get Started

Core Concepts

Platform Support

Guides

​Core Principles

Tests BEFORE Code

80%+ Coverage

Three Test Types

​When to Use TDD

​Test Types

​Unit Tests

Unit Tests

​Integration Tests

Integration Tests

​E2E Tests (Playwright)

E2E Tests

​The TDD Workflow

​Testing Patterns

​Unit Test Pattern (Jest/Vitest)

​API Integration Test Pattern

​E2E Test Pattern (Playwright)

​Test File Organization

​Mocking External Services

​Supabase Mock

​Redis Mock

​OpenAI Mock

​Test Coverage Verification

​Run Coverage Report

​Coverage Thresholds

​Common Testing Mistakes

​❌ Testing Implementation Details

​❌ Brittle Selectors

​❌ No Test Isolation

​Continuous Testing

​Watch Mode During Development

​Pre-Commit Hook

​CI/CD Integration

​Best Practices

Write Tests First

One Assert Per Test

Descriptive Test Names

Arrange-Act-Assert

Mock External Dependencies

Test Edge Cases

Test Error Paths

Keep Tests Fast

Clean Up After Tests

Review Coverage Reports

​Success Metrics

​ECC TDD Tools

tdd-guide Agent

/tdd Command

tdd-workflow Skill

/test-coverage Command

​Example TDD Session

Core Principles

When to Use TDD

Test Types

Unit Tests

Integration Tests

E2E Tests (Playwright)

The TDD Workflow

Testing Patterns

Unit Test Pattern (Jest/Vitest)

API Integration Test Pattern

E2E Test Pattern (Playwright)

Test File Organization

Mocking External Services

Supabase Mock

Redis Mock

OpenAI Mock

Test Coverage Verification

Run Coverage Report

Coverage Thresholds

Common Testing Mistakes

❌ Testing Implementation Details

❌ Brittle Selectors

❌ No Test Isolation

Continuous Testing

Watch Mode During Development

Pre-Commit Hook

CI/CD Integration

Best Practices

Success Metrics

ECC TDD Tools

Example TDD Session