Community编程与开发github.com

测试驱动开发准则

编码技能。编写测试或执行TDD:新功能、错误修复、重构。强制实施测试优先开发,确保单元测试、集成测试和端到端测试覆盖率超过80%。通过 /tests-guidelines、“tests”、“coverage”、“unit test”、“integration test”、“TDD”触发。

测试驱动开发准则 是什么?

该技能强制执行测试驱动开发(TDD)工作流,确保所有代码在编写前都有测试,实现80%以上的代码覆盖率。它支持单元测试、集成测试和端到端测试(使用Playwright),自动检测项目的测试运行器(npm、pnpm、yarn、Bun、pytest、Go、Rust),并提供了分步指南,涵盖编写用户旅程、生成测试用例、实施代码、重构和验证覆盖率。该技能适用于Claude Code、Cursor、Codex等AI编码代理,通过/tests-guidelines命令或自然语言提示触发。它强调了编写描述性测试名称、隔离测试、模拟外部依赖以及避免常见错误(如测试实现细节或使用脆弱的选择器)等最佳实践。此外,它还集成了监视模式、预提交钩子和CI/CD流水线,以确保持续测试。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/orenatobr/tests-guidelines/tree/HEAD/skills/tests-guidelines

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

测试驱动开发工作流

此技能确保所有代码开发遵循TDD原则,并具备全面的测试覆盖率。

何时激活

  • 编写新功能或功能特性
  • 修复错误或问题
  • 重构现有代码
  • 添加API端点
  • 创建新组件

核心原则

1. 测试先于代码

始终先编写测试,然后实现代码使测试通过。

2. 覆盖率要求

  • 最低80%覆盖率(单元测试 + 集成测试 + 端到端测试)
  • 覆盖所有边缘情况
  • 测试错误场景
  • 验证边界条件

3. 测试类型

单元测试

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

集成测试

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

端到端测试 (Playwright)

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

TDD工作流步骤

步骤0:检测测试运行器

不要假定npm test。下面步骤和示例中的命令使用<test>、<test-watch>和<coverage>作为项目实际运行器的占位符。在开始之前一次性解析它们:

  1. 找到项目的运行器。读取package.json(packageManager、scripts.test)、锁定文件、pyproject.toml/pytest.ini、go.mod、Cargo.toml。第一个匹配项胜出;不要假定npm test。

  2. 区分包管理器和测试运行器。它们不是一回事。 项目可以使用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>
npmnpm testnpm test -- --watchnpm run test:coveragenpm run lint
pnpmpnpm testpnpm test --watchpnpm test:coveragepnpm lint
yarnyarn testyarn test --watchyarn test:coverageyarn lint
Bun(脚本运行jest/vitest)bun run testbun run test --watchbun run test:coveragebun run lint
Bun(原生bun:test)bun testbun test --watchbun test --coveragebun 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

最佳实践

  1. 先编写测试 - 始终TDD
  2. 每个测试一个断言 - 专注于单一行为
  3. 描述性测试名称 - 解释测试内容
  4. 安排-执行-断言 - 清晰的测试结构
  5. 模拟外部依赖 - 隔离单元测试
  6. 测试边缘情况 - null、undefined、空、大量数据
  7. 测试错误路径 - 不仅仅是快乐路径
  8. 保持测试快速 - 单元测试每个<50ms
  9. 测试后清理 - 无副作用
  10. 审查覆盖率报告 - 识别差距

成功指标

  • 达到80%以上代码覆盖率
  • 所有测试通过(绿色)
  • 没有跳过或禁用的测试
  • 快速测试执行(单元测试<30秒)
  • 端到端测试覆盖关键用户流程
  • 测试在发布前捕获错误

记住:测试不是可选项。它们是在重构、快速开发和生产可靠性方面提供信心的安全网。

相关技能