Coverage Guard
确保任何 JavaScript/TypeScript 项目达到 100% 测试覆盖率。自动检测测试运行器,在缺少测试基础设施时进行设置,为未覆盖的组件编写测试,并循环直到每个文件都达到 100% 覆盖率。
概述
此技能遵循一个完整的流水线:
- 检测 运行器和基础设施 → 2. 扫描 源文件和测试 → 3. 设置(若缺失) → 4. 生成 新测试 → 5. 运行 覆盖率 → 6. 填补 缺口 → 7. 验证 → 重复直到 100%
逐步工作流
阶段 1:检测环境
检查项目根目录中的 package.json 以确定:
cat package.json
识别测试运行器和覆盖率工具:
| 指示符 | 运行器 | 覆盖率命令 |
|---|---|---|
"vitest" 在 devDependencies 中 | Vitest | npx vitest --coverage |
"jest" 在 devDependencies 中 | Jest | npx jest --coverage |
"react-scripts" 在 devDependencies 中 | react-scripts (Jest) | npx react-scripts test --coverage |
"next" 在 devDependencies 中 | Next.js (Jest) | npx next test --coverage 或检查 jest.config |
"@angular/core" 在 dependencies 中 | Angular (Karma/Jasmine) | ng test --code-coverage |
"@playwright/test" 在 devDependencies 中 | Playwright | npx playwright test(无内置覆盖率;使用 @playwright/test 配合 istanbul) |
"mocha" 在 devDependencies 中 | Mocha | npx mocha(通过 c8/nyc 实现覆盖率) |
"cypress" 在 devDependencies 中 | Cypress | npx cypress run(通过 @cypress/code-coverage 实现覆盖率) |
"ava" 在 devDependencies 中 | AVA | npx ava(通过 c8 实现覆盖率) |
| 未找到 | 无 → 进入阶段 2 → 阶段 3 设置 |
阶段 2:扫描源文件和现有测试
查找所有需要测试的源文件(组件、模块、工具函数):
# 常见的源文件目录
find src -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) ! -name "*.test.*" ! -name "*.spec.*" ! -name "*.d.ts" ! -path "*/node_modules/*" ! -path "*/dist/*" ! -path "*/build/*" ! -path "*/.next/*"
查找所有现有的测试文件:
find src -type f \( -name "*.test.*" -o -name "*.spec.*" \) ! -path "*/node_modules/*"
将每个源文件映射到测试文件:
src/components/Button.tsx→src/components/Button.test.tsx或src/components/__tests__/Button.test.tsxsrc/utils/format.ts→src/utils/format.test.ts或src/utils/__tests__/format.test.ts- 遵循项目现有的测试文件放置约定
对每个源文件进行分类:
- 有测试 → 添加到覆盖率分析列表
- 无测试 → 标记为需要生成测试
阶段 3:设置测试基础设施(若缺失)
如果在阶段 1 中未检测到测试运行器,则交互式询问用户:
? 未检测到测试框架。您想设置哪一个?
1) Vitest(推荐 — 快速、现代、原生 ESM)
2) Jest(使用最广泛)
3) react-scripts(Create React App)
4) 无 — 跳过,我将手动设置
用户选择后,安装依赖并创建配置:
Vitest 设置:
npm install -D vitest @vitest/coverage-v8
创建 vitest.config.ts:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
exclude: [
'**/node_modules/**',
'**/dist/**',
'**/*.config.*',
'**/*.d.ts',
],
},
},
})
添加到 package.json 的脚本:
{
"scripts": {
"test": "vitest",
"test:coverage": "vitest --coverage"
}
}
Jest 设置:
npm install -D jest @types/jest ts-jest
npx ts-jest config:init
npm install -D jest @testing-library/react @testing-library/jest-dom jest-environment-jsdom
创建 jest.config.ts:
export default {
testEnvironment: 'jsdom',
transform: {
'^.+\.tsx?$': 'ts-jest',
},
coverageReporters: ['text', 'json', 'html'],
collectCoverageFrom: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'],
}
添加到 package.json 的脚本:
{
"scripts": {
"test": "jest",
"test:coverage": "jest --coverage"
}
}
react-scripts 设置:
npm install -D @testing-library/react @testing-library/jest-dom @testing-library/user-event
覆盖率内置:
{
"scripts": {
"test": "react-scripts test",
"test:coverage": "react-scripts test --coverage"
}
}
设置完成后,运行一个快速测试以确认一切正常:
npm test
如果失败,先修复配置问题再继续。
阶段 4:为未经测试的源文件编写测试
对于每个没有测试文件的源文件,分析源代码:
- 读取源文件
- 识别:
- 所有导出的函数、类、组件
- 返回类型和可能的返回路径
- 参数及其类型(必需、可选、默认值)
- Props 接口(针对 React 组件)
- 异步行为(Promise、async/await)
- 副作用(API 调用、localStorage 等)
- 错误状态和边缘情况
- 按照项目约定生成测试文件:
- 使用检测到的测试运行器的 API(Jest/Vitest 使用
describe/it/expect等) - 对于 React:使用
@testing-library/react(render、screen、fireEvent) - 模拟外部依赖
- 覆盖所有分支、边缘情况和错误路径
- 使用检测到的测试运行器的 API(Jest/Vitest 使用
React 组件示例(src/components/Button.tsx → src/components/Button.test.tsx):
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'
describe('Button', () => {
it('使用标签渲染', () => {
render(<Button label="点击我" />)
expect(screen.getByText('点击我')).toBeInTheDocument()
})
it('点击时调用 onClick', () => {
const onClick = vi.fn() // Jest 中使用 jest.fn()
render(<Button label="点击" onClick={onClick} />)
fireEvent.click(screen.getByText('点击'))
expect(onClick).toHaveBeenCalledTimes(1)
})
it('当 disabled 属性为 true 时禁用', () => {
render(<Button label="点击" disabled />)
expect(screen.getByText('点击')).toBeDisabled()
})
})
工具函数示例(src/utils/format.ts → src/utils/format.test.ts):
import { formatCurrency, truncate } from './format'
describe('formatCurrency', () => {
it('格式化整数金额', () => {
expect(formatCurrency(1000)).toBe('$1,000.00')
})
it('格式化小数金额', () => {
expect(formatCurrency(99.95)).toBe('$99.95')
})
it('处理零', () => {
expect(formatCurrency(0)).toBe('$0.00')
})
it('处理负值', () => {
expect(formatCurrency(-50)).toBe('-$50.00')
})
})
阶段 5:运行覆盖率报告
根据检测到的运行器执行相应的覆盖率命令:
| 运行器 | 命令 |
|---|---|
| Vitest | npx vitest --coverage --reporter=verbose |
| Jest | npx jest --coverage --verbose |
| react-scripts | npx react-scripts test --coverage --watchAll=false |
| 其他 | 使用项目配置的覆盖率命令 |
解析输出以识别:
- 低于 100% 覆盖率的文件
- 未覆盖的行、分支、函数和语句
- 需要测试的特定行号
- 覆盖率为 0% 的文件(不存在测试)
阶段 6:分析并填补覆盖率缺口
对于每个低于 100% 的文件(包括阶段 4 中已有测试但未达 100% 的文件):
- 同时读取源文件和相应的测试文件
- 理解未覆盖的行/函数/分支的功能
- 识别测试中遗漏的边缘情况
- 编写有针对性的测试来覆盖这些缺口:
- 未覆盖的分支:测试
if和else两条路径、三元条件 - 未覆盖的函数:测试所有可能的返回路径
- 未覆盖的行:追踪逻辑并编写能够到达这些行的用例
- 未覆盖的异步路径:测试 Promise 的 resolved 和 rejected 分支
- 未覆盖的错误处理:测试错误回调、catch 块、错误边界
使用检测到的测试运行器的模式:
- Vitest:
vi.mock()、vi.spyOn()、vi.fn() - Jest:
jest.mock()、jest.spyOn()、jest.fn() - react-scripts:同 Jest
阶段 7:验证
在添加/更新测试后重新运行覆盖率:
# 使用检测到的命令
npx vitest --coverage # 针对 Vitest
npx jest --coverage # 针对 Jest
确认所有文件在语句、分支、函数和行上均显示 100%。
阶段 8:重复
如果覆盖率仍低于 100%,则循环回到阶段 6。
按运行器配置
Vitest 覆盖率配置
确保 vitest.config.ts:
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
exclude: [
'**/node_modules/**',
'**/dist/**',
'**/*.config.*',
'**/*.d.ts',
],
},
},
})
Jest 覆盖率配置
确保 jest.config.ts 包含:
export default {
collectCoverage: true,
coverageReporters: ['text', 'json', 'html'],
collectCoverageFrom: [
'src/**/*.{ts,tsx,js,jsx}',
'!src/**/*.d.ts',
'!src/**/*.test.*',
'!src/**/*.spec.*',
],
}
提示
- 从已有测试但覆盖率较低的文件开始——这是最快的突破口
- 然后优先处理逻辑最简单的未经测试的文件
- 对于 React 组件:测试渲染、用户交互、条件渲染、错误状态以及空/加载状态
- 对于工具函数:测试边缘情况(空字符串、null/undefined、边界值、特殊字符)
- 对于 API 服务:测试成功响应、错误响应、加载状态、超时和网络故障
- 如果发现无法覆盖的死代码,建议删除它或添加覆盖率忽略注释:
- Vitest/V8:
/* c8 ignore next */或/* c8 ignore next 3 */ - Jest/Istanbul:
/* istanbul ignore next */或/* istanbul ignore if */
- Vitest/V8:
- 不要修改源代码逻辑——仅添加或更新测试
- 遵循项目现有的测试模式(文件命名、文件夹结构、模拟风格)
- 对于完全没有测试的文件,首先创建一个覆盖所有主要路径的全面测试文件,然后迭代完善
检测优先级
扫描源文件时,按以下常见目录结构顺序检查:
src/app/(Next.js app 目录)components/lib/utils/server/(Next.js/Node.js)pages/(Next.js pages 目录)- 根目录下的
*.ts/*.tsx文件
示例
用户:“覆盖率报告显示 login.ts 为 72%,请修复”
AI 操作:
- 运行
npx vitest --coverage --reporter=verbose,发现 login.ts 中 45-52 行未覆盖(validateEmail的错误分支) - 读取源代码,理解
validateEmail在无效邮箱时抛出异常 - 在
login.test.ts中添加无效邮箱输入的测试用例 - 重新运行覆盖率 — login.ts 现在达到 100%
用户:“我们使用 jest,检查覆盖率”
- 运行
npx jest --coverage --verbose,识别未覆盖的文件 - 发现
src/components/Header.tsx覆盖率为 0% — 没有测试 - 读取 Header.tsx 源码,创建
src/components/Header.test.tsx - 再次运行覆盖率 — Header.tsx 现在达到 100%
用户:“这个项目没有测试设置,请添加覆盖率”
- 在 package.json 中未检测到测试运行器
- 询问用户:“未检测到测试框架。安装 Vitest 吗?(推荐)”
- 用户确认 → 安装 vitest + @vitest/coverage-v8,创建 vitest.config.ts
- 扫描 src/,发现 8 个源文件,0 个测试文件
- 为所有 8 个文件编写测试
- 运行覆盖率 — 全部达到 100%