Test-Driven Development Workflow

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

When to Activate

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

Initial Setup

If the project doesn't have a testing framework configured yet:

•
Detect project type and recommend framework:
- •JS/TS (Vite): Vitest + React Testing Library
- •JS/TS (Next.js): Jest or Vitest + React Testing Library
- •JS/TS (Node): Vitest or Jest
- •Python: pytest + pytest-asyncio
- •E2E: agent-browser for all project types

•

Install and configure:

bash

# JS/TS example with Vitest
pnpm add -D vitest @testing-library/react @testing-library/jest-dom
# Python example
pip install pytest pytest-asyncio pytest-cov

•
Create config files: vitest.config.ts or pytest.ini
•
Set coverage thresholds at 80% minimum
•
Add test scripts to package.json or pyproject.toml

See the tdd-example-walkthrough.md supporting file for a complete worked example.

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 (agent-browser)

•Critical user flows
•Complete workflows
•Browser automation
•UI interactions

TDD Workflow Steps

Step 1: Write User Journeys

code

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.

Step 2: Generate Test Cases

For each user journey, create comprehensive test cases:

typescript

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
  })
})

Step 3: Run Tests (They Should Fail)

bash

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

Step 4: Implement Code

Write minimal code to make tests pass:

typescript

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

Step 5: Run Tests Again

bash

npm test
# Tests should now pass

Step 6: Refactor

Improve code quality while keeping tests green:

•Remove duplication
•Improve naming
•Optimize performance
•Enhance readability

Step 7: Verify Coverage

bash

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

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(<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

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 (agent-browser)

bash

# Test: user can search and filter markets
agent-browser open http://localhost:3000
agent-browser snapshot -i
agent-browser find text "Markets" click           # Navigate to markets
agent-browser wait --load networkidle
agent-browser snapshot -i

# Search for markets
agent-browser find label "Search markets" fill "election"
agent-browser wait 600                            # Debounce
agent-browser snapshot -i                         # Verify results appear

# Filter by status
agent-browser find text "Active" click
agent-browser snapshot -i                         # Verify filtered results

# Test: user can create a new market
agent-browser open http://localhost:3000/creator-dashboard
agent-browser snapshot -i
agent-browser find label "name" fill "Test Market"
agent-browser find label "description" fill "Test description"
agent-browser find label "endDate" fill "2025-12-31"
agent-browser find role button click --name "Submit"
agent-browser wait --text "Market created successfully"
agent-browser get url                             # Verify redirect to /markets/test-market

code


## 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

code


## 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

❌ WRONG: Testing Implementation Details

typescript

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

✅ CORRECT: Test User-Visible Behavior

typescript

// Test what users see
expect(screen.getByText('Count: 5')).toBeInTheDocument()

❌ WRONG: Brittle Selectors

typescript

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

✅ CORRECT: Semantic Selectors

typescript

// Resilient to changes
await page.click('button:has-text("Submit")')
await page.click('[data-testid="submit-button"]')

❌ WRONG: No Test Isolation

typescript

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

✅ 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
})

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

•Write Tests First - Always TDD
•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

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