tdd-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Test-Driven Development Workflow

测试驱动开发（TDD）工作流

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

此Skill确保所有代码开发遵循TDD原则，并实现全面的测试覆盖率。

When to Activate

适用场景

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

编写新功能或功能模块
修复Bug或问题
重构现有代码
添加API端点
创建新组件

Core Principles

核心原则

1. Tests BEFORE Code

1. 先写测试，再写代码

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

始终先编写测试，再实现代码使测试通过。

2. Coverage Requirements

2. 覆盖率要求

Minimum 80% coverage (unit + integration + E2E)
All edge cases covered
Error scenarios tested
Boundary conditions verified

最低80%覆盖率（单元测试+集成测试+E2E测试）
覆盖所有边缘情况
测试错误场景
验证边界条件

3. Test Types

3. 测试类型

Unit Tests

单元测试

Individual functions and utilities
Component logic
Pure functions
Helpers and utilities

独立函数和工具类
组件逻辑
纯函数
辅助工具

Integration Tests

集成测试

API endpoints
Database operations
Service interactions
External API calls

API端点
数据库操作
服务交互
外部API调用

E2E Tests (Playwright)

端到端（E2E）测试（基于Playwright）

Critical user flows
Complete workflows
Browser automation
UI interactions

关键用户流程
完整工作流
浏览器自动化
UI交互

TDD Workflow Steps

TDD工作流步骤

Step 1: Write User Journeys

步骤1：编写用户旅程

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.

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

示例:
作为用户，我希望能够语义化搜索市场，
以便即使没有精确关键词也能找到相关市场。

Step 2: Generate Test Cases

步骤2：生成测试用例

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

针对每个用户旅程，创建全面的测试用例：

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)

步骤3：运行测试（此时测试应失败）

bash

npm test

bash

npm test

Tests should fail - we haven't implemented yet

测试应失败 - 我们尚未实现功能

undefined

undefined

Step 4: Implement Code

步骤4：实现代码

Write minimal code to make tests pass:

typescript

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

编写最少的代码使测试通过：

typescript

// 基于测试指导实现功能
export async function searchMarkets(query: string) {
  // Implementation here
}

Step 5: Run Tests Again

步骤5：再次运行测试

bash

npm test

bash

npm test

Tests should now pass

此时测试应通过

undefined

undefined

Step 6: Refactor

步骤6：重构

Improve code quality while keeping tests green:

Remove duplication
Improve naming
Optimize performance
Enhance readability

在保持测试通过的同时提升代码质量：

移除重复代码
优化命名
提升性能
增强可读性

Step 7: Verify Coverage

步骤7：验证覆盖率

bash

npm run test:coverage

bash

npm run test:coverage

Verify 80%+ coverage achieved

确认达到80%以上覆盖率

undefined

undefined

Testing Patterns

测试模式

Unit Test Pattern (Jest/Vitest)

单元测试模式（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()
  })
})

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

API集成测试模式

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

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)

E2E测试模式（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('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/)
})

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

src/
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx          # 单元测试
│   │   └── Button.stories.tsx       # Storybook
│   └── MarketCard/
│       ├── MarketCard.tsx
│       └── MarketCard.test.tsx
├── app/
│   └── api/
│       └── markets/
│           ├── route.ts
│           └── route.test.ts         # 集成测试
└── e2e/
    ├── markets.spec.ts               # E2E测试
    ├── trading.spec.ts
    └── auth.spec.ts

Mocking External Services

外部服务Mock

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

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

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

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

bash

npm run test:coverage

Coverage Thresholds

覆盖率阈值

json

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

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)

typescript

// 不要测试内部状态
expect(component.state.count).toBe(5)

✅ CORRECT: Test User-Visible Behavior

✅ 正确：测试用户可见行为

typescript

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

typescript

// 测试用户能看到的内容
expect(screen.getByText('Count: 5')).toBeInTheDocument()

❌ WRONG: Brittle Selectors

❌ 错误：脆弱的选择器

typescript

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

typescript

// 容易失效
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"]')

typescript

// 对变更有更强的适应性
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 */ })

typescript

// 测试之间相互依赖
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
})

typescript

// 每个测试都有自己的测试数据
test('creates user', () => {
  const user = createTestUser()
  // 测试逻辑
})

test('updates user', () => {
  const user = createTestUser()
  // 更新逻辑
})

Continuous Testing

持续测试

Watch Mode During Development

开发时的监听模式

bash

npm test -- --watch

bash

npm test -- --watch

Tests run automatically on file changes

文件变更时自动运行测试

undefined

undefined

Pre-Commit Hook

提交前钩子

bash

undefined

bash

undefined

Runs before every commit

每次提交前运行

npm test && npm run lint

undefined

npm test && npm run lint

undefined

CI/CD Integration

CI/CD集成

yaml

undefined

yaml

undefined

GitHub Actions

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

undefined

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

undefined

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

先写测试 - 始终遵循TDD
每个测试一个断言 - 聚焦单一行为
描述性测试名称 - 说明测试内容
Arrange-Act-Assert结构 - 清晰的测试结构
Mock外部依赖 - 隔离单元测试
测试边缘情况 - 空值、未定义、空集合、大数值等
测试错误路径 - 不只是快乐路径
保持测试快速 - 单元测试每个耗时<50ms
测试后清理 - 无副作用
审查覆盖率报告 - 识别测试缺口

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.

达到80%以上代码覆盖率
所有测试通过（绿色）
无跳过或禁用的测试
测试执行速度快（单元测试<30秒）
E2E测试覆盖关键用户流程
测试在生产前发现Bug

谨记：测试不是可选的。它们是保障自信重构、快速开发和生产环境可靠性的安全网。