测试驱动开发工作流
此技能确保所有代码开发遵循TDD原则,并具备全面的测试覆盖率。
何时激活
- 编写新功能或功能特性
- 修复错误或问题
- 重构现有代码
- 添加API端点
- 创建新组件
核心原则
1. 测试先于代码
始终先编写测试,然后实现代码使测试通过。
2. 覆盖率要求
- 最低80%覆盖率(单元测试 + 集成测试 + 端到端测试)
- 覆盖所有边缘情况
- 测试错误场景
- 验证边界条件
3. 测试类型
单元测试
- 独立函数和工具函数
- 组件逻辑
- 纯函数
- 辅助函数和工具函数
集成测试
- API端点
- 数据库操作
- 服务交互
- 外部API调用
端到端测试 (Playwright)
- 关键用户流程
- 完整工作流
- 浏览器自动化
- UI交互
TDD工作流步骤
步骤0:检测测试运行器
不要假定npm test。下面步骤和示例中的命令使用<test>、<test-watch>和<coverage>作为项目实际运行器的占位符。在开始之前一次性解析它们:
-
找到项目的运行器。读取
package.json(packageManager、scripts.test)、锁定文件、pyproject.toml/pytest.ini、go.mod、Cargo.toml。第一个匹配项胜出;不要假定npm test。 -
区分包管理器和测试运行器。它们不是一回事。 项目可以使用Bun安装依赖,但仍然运行Jest或Vitest。检查
package.json中的scripts.test和测试文件:scripts.test调用jest/vitest-> 通过检测到的PM运行(npm test、pnpm test、yarn test或bun run test)。scripts.test是bun test,或者测试文件import { test, expect } from "bun:test",或者没有jest/vitest配置但存在Bun -> 使用Bun的原生运行器(bun test)。参见下面的Bun原生测试模式。- Python:
<test>=pytest,<coverage>=pytest --cov --cov-fail-under=80。Go:go test ./...和go test -cover ./...。Rust:cargo test。
运行器命令矩阵:
| 运行器 | <test> | <test-watch> | <coverage> | <lint> |
|---|---|---|---|---|
| npm | npm test | npm test -- --watch | npm run test:coverage | npm run lint |
| pnpm | pnpm test | pnpm test --watch | pnpm test:coverage | pnpm lint |
| yarn | yarn test | yarn test --watch | yarn test:coverage | yarn lint |
| Bun(脚本运行jest/vitest) | bun run test | bun run test --watch | bun run test:coverage | bun run lint |
Bun(原生bun:test) | bun test | bun test --watch | bun test --coverage | bun run lint |
bun test(Bun的内置运行器)不等同于bun run test(运行package.json中的test脚本)。选择错误是常见失败原因 - 例如,在仅ESM的项目中通过npx/bun run调用Jest会失败,而bun test原生运行测试套件。在RED门之前确认项目期望哪个,然后在下面所有出现npm test的地方替换<test>/<coverage>。
步骤1:编写用户旅程
作为一个[角色],我想要[行动],以便[收益]
示例:
作为一个用户,我想对市场进行语义搜索,
以便即使没有精确关键词也能找到相关的市场。
步骤2:生成测试用例
针对每个用户旅程,创建全面的测试用例:
describe('语义搜索', () => {
it('返回与查询相关的市场', async () => {
// 测试实现
})
it('优雅地处理空查询', async () => {
// 测试边缘情况
})
it('当Redis不可用时回退到子字符串搜索', async () => {
// 测试回退行为
})
it('按相似度分数对结果排序', async () => {
// 测试排序逻辑
})
})
步骤3:运行测试(它们应该失败)
<test>
# 测试应该失败 - 我们尚未实现
步骤4:实现代码
编写最少的代码使测试通过:
// 由测试指导的实现
export async function searchMarkets(query: string) {
// 此处为实现
}
步骤5:再次运行测试
<test>
# 测试现在应该通过
步骤6:重构
在保持测试通过的同时提高代码质量:
- 消除重复
- 改进命名
- 优化性能
- 增强可读性
步骤7:验证覆盖率
<coverage>
# 验证达到80%以上覆盖率
测试模式
单元测试模式 (Jest/Vitest)
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'
describe('Button组件', () => {
it('使用正确的文本渲染', () => {
render(<Button>点击我</Button>)
expect(screen.getByText('点击我')).toBeInTheDocument()
})
it('点击时调用onClick', () => {
const handleClick = jest.fn()
render(<Button onClick={handleClick}>点击</Button>)
fireEvent.click(screen.getByRole('button'))
expect(handleClick).toHaveBeenCalledTimes(1)
})
it('当disabled属性为true时禁用', () => {
render(<Button disabled>点击</Button>)
expect(screen.getByRole('button')).toBeDisabled()
})
})
Bun原生测试模式 (bun:test)
当项目使用Bun的内置运行器时(参见步骤0),从bun:test导入并使用bun test运行 - 而不是bun run test。API类似于Jest,因此describe/it/expect和大多数匹配器都可沿用。
import { describe, it, expect, mock } from 'bun:test'
import { searchMarkets } from './search'
describe('searchMarkets', () => {
it('对空查询返回空列表', async () => {
expect(await searchMarkets('')).toEqual([])
})
it('按相似度分数对结果排序', async () => {
const results = await searchMarkets('election')
expect(results).toEqual([...results].sort((a, b) => b.score - a.score))
})
})
bun test # 运行一次(RED/GREEN门)
bun test --watch # 开发期间的监视模式
bun test --coverage # 覆盖率报告
- 使用
bun:test中的mock.module(...)/mock(...)模拟模块,而非jest.mock(...)。 - 在
bunfig.toml的[test]部分(例如coverageThreshold)配置覆盖率阈值,而不是Jest的coverageThresholds配置块。
API集成测试模式
import { NextRequest } from 'next/server'
import { GET } from './route'
describe('GET /api/markets', () => {
it('成功返回市场', 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('验证查询参数', async () => {
const request = new NextRequest('http://localhost/api/markets?limit=invalid')
const response = await GET(request)
expect(response.status).toBe(400)
})
it('优雅地处理数据库错误', async () => {
// 模拟数据库故障
const request = new NextRequest('http://localhost/api/markets')
// 测试错误处理
})
})
端到端测试模式 (Playwright)
import { test, expect } from '@playwright/test'
test('用户可以搜索和筛选市场', async ({ page }) => {
// 导航到市场页面
await page.goto('/')
await page.click('a[href="/markets"]')
// 验证页面加载完成
await expect(page.locator('h1')).toContainText('市场')
// 搜索市场
await page.fill('input[placeholder="搜索市场"]', 'election')
// 等待防抖和结果
await page.waitForTimeout(600)
// 验证搜索结果已显示
const results = page.locator('[data-testid="market-card"]')
await expect(results).toHaveCount(5, { timeout: 5000 })
// 验证结果包含搜索词
const firstResult = results.first()
await expect(firstResult).toContainText('election', { ignoreCase: true })
// 按状态筛选
await page.click('button:has-text("活跃")')
// 验证筛选结果
await expect(results).toHaveCount(3)
})
test('用户可以创建新市场', async ({ page }) => {
// 先登录
await page.goto('/creator-dashboard')
// 填写市场创建表单
await page.fill('input[name="name"]', '测试市场')
await page.fill('textarea[name="description"]', '测试描述')
await page.fill('input[name="endDate"]', '2025-12-31')
// 提交表单
await page.click('button[type="submit"]')
// 验证成功消息
await expect(page.locator('text=市场创建成功')).toBeVisible()
// 验证重定向到市场页面
await expect(page).toHaveURL(/\/markets\/test-market/)
})
测试文件组织
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 # 端到端测试
├── trading.spec.ts
└── auth.spec.ts
模拟外部服务
Supabase模拟
jest.mock('@/lib/supabase', () => ({
supabase: {
from: jest.fn(() => ({
select: jest.fn(() => ({
eq: jest.fn(() => Promise.resolve({
data: [{ id: 1, name: '测试市场' }],
error: null
}))
}))
}))
}
}))
Redis模拟
jest.mock('@/lib/redis', () => ({
searchMarketsByVector: jest.fn(() => Promise.resolve([
{ slug: 'test-market', similarity_score: 0.95 }
])),
checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
}))
OpenAI模拟
jest.mock('@/lib/openai', () => ({
generateEmbedding: jest.fn(() => Promise.resolve(
new Array(1536).fill(0.1) // 模拟1536维嵌入
))
}))
测试覆盖率验证
运行覆盖率报告
<coverage>
覆盖率阈值
{
"jest": {
"coverageThresholds": {
"global": {
"branches": 80,
"functions": 80,
"lines": 80,
"statements": 80
}
}
}
}
常见测试错误及避免方法
失败:错误:测试实现细节
// 不要测试内部状态
expect(component.state.count).toBe(5)
通过:正确:测试用户可见的行为
// 测试用户看到的内容
expect(screen.getByText('计数: 5')).toBeInTheDocument()
失败:错误:脆弱的定位器
// 容易中断
await page.click('.css-class-xyz')
通过:正确:语义化的定位器
// 对变化具有弹性
await page.click('button:has-text("提交")')
await page.click('[data-testid="submit-button"]')
失败:错误:没有测试隔离
// 测试相互依赖
test('创建用户', () => { /* ... */ })
test('更新同一用户', () => { /* 依赖前一个测试 */ })
通过:正确:独立测试
// 每个测试设置自己的数据
test('创建用户', () => {
const user = createTestUser()
// 测试逻辑
})
test('更新用户', () => {
const user = createTestUser()
// 更新逻辑
})
持续测试
开发期间的监视模式
<test-watch>
# 文件更改时自动运行测试
预提交钩子
# 每次提交前运行
<test> && <lint>
CI/CD集成
# GitHub Actions
- name: 运行测试
run: <coverage>
- name: 上传覆盖率
uses: codecov/codecov-action@v3
最佳实践
- 先编写测试 - 始终TDD
- 每个测试一个断言 - 专注于单一行为
- 描述性测试名称 - 解释测试内容
- 安排-执行-断言 - 清晰的测试结构
- 模拟外部依赖 - 隔离单元测试
- 测试边缘情况 - null、undefined、空、大量数据
- 测试错误路径 - 不仅仅是快乐路径
- 保持测试快速 - 单元测试每个<50ms
- 测试后清理 - 无副作用
- 审查覆盖率报告 - 识别差距
成功指标
- 达到80%以上代码覆盖率
- 所有测试通过(绿色)
- 没有跳过或禁用的测试
- 快速测试执行(单元测试<30秒)
- 端到端测试覆盖关键用户流程
- 测试在发布前捕获错误
记住:测试不是可选项。它们是在重构、快速开发和生产可靠性方面提供信心的安全网。