Community写作与编辑github.com

sametcelikbicak/coverage-guard

一项AI助手技能,强制对任何JavaScript/TypeScript项目实现100%测试覆盖率。支持Vitest、Jest、react-scripts及其他测试运行器,兼容opencode、Claude Code、Cursor、Windsurf和GitHub Copilot。

coverage-guard 是什么?

Coverage Guard 是一个AI助手技能,能够自动分析JavaScript/TypeScript项目并强制实现100%的测试代码覆盖率。它首先自动检测项目使用的测试运行器(如Vitest、Jest、react-scripts等),扫描所有源文件和现有测试,如果缺少测试基础架构则主动引导用户设置。然后,它会为未覆盖的组件生成新测试,运行覆盖率报告,分析覆盖缺口,编写针对性测试来填补空白,并循环验证直到每个文件都达到100%覆盖率。该技能支持多种流行的开发平台,包括opencode、Claude Code、Cursor、Windsurf和GitHub Copilot,极大简化了测试覆盖率管理的繁琐过程,确保代码质量。

兼容平台✓Claude Code~Codex CLI✓Cursor✓OpenCode✓Windsurf
npx skills add sametcelikbicak/coverage-guard

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

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

文档

Coverage Guard

确保任何 JavaScript/TypeScript 项目达到 100% 测试覆盖率。自动检测测试运行器,在缺少测试基础设施时进行设置,为未覆盖的组件编写测试,并循环直到每个文件都达到 100% 覆盖率。

概述

此技能遵循一个完整的流水线:

  1. 检测 运行器和基础设施 → 2. 扫描 源文件和测试 → 3. 设置(若缺失) → 4. 生成 新测试 → 5. 运行 覆盖率 → 6. 填补 缺口 → 7. 验证 → 重复直到 100%

逐步工作流

阶段 1:检测环境

检查项目根目录中的 package.json 以确定:

cat package.json

识别测试运行器和覆盖率工具:

指示符运行器覆盖率命令
"vitest" 在 devDependencies 中Vitestnpx vitest --coverage
"jest" 在 devDependencies 中Jestnpx 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 中Playwrightnpx playwright test(无内置覆盖率;使用 @playwright/test 配合 istanbul)
"mocha" 在 devDependencies 中Mochanpx mocha(通过 c8/nyc 实现覆盖率)
"cypress" 在 devDependencies 中Cypressnpx cypress run(通过 @cypress/code-coverage 实现覆盖率)
"ava" 在 devDependencies 中AVAnpx 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.tsx
  • src/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:为未经测试的源文件编写测试

对于每个没有测试文件的源文件,分析源代码:

  1. 读取源文件
  2. 识别:
    • 所有导出的函数、类、组件
    • 返回类型和可能的返回路径
    • 参数及其类型(必需、可选、默认值)
    • Props 接口(针对 React 组件)
    • 异步行为(Promise、async/await)
    • 副作用(API 调用、localStorage 等)
    • 错误状态和边缘情况
  3. 按照项目约定生成测试文件:
    • 使用检测到的测试运行器的 API(Jest/Vitest 使用 describe/it/expect 等)
    • 对于 React:使用 @testing-library/react(render、screen、fireEvent)
    • 模拟外部依赖
    • 覆盖所有分支、边缘情况和错误路径

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:运行覆盖率报告

根据检测到的运行器执行相应的覆盖率命令:

运行器命令
Vitestnpx vitest --coverage --reporter=verbose
Jestnpx jest --coverage --verbose
react-scriptsnpx react-scripts test --coverage --watchAll=false
其他使用项目配置的覆盖率命令

解析输出以识别:

  • 低于 100% 覆盖率的文件
  • 未覆盖的行、分支、函数和语句
  • 需要测试的特定行号
  • 覆盖率为 0% 的文件(不存在测试)

阶段 6:分析并填补覆盖率缺口

对于每个低于 100% 的文件(包括阶段 4 中已有测试但未达 100% 的文件):

  1. 同时读取源文件和相应的测试文件
  2. 理解未覆盖的行/函数/分支的功能
  3. 识别测试中遗漏的边缘情况
  4. 编写有针对性的测试来覆盖这些缺口:
  • 未覆盖的分支:测试 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 */
  • 不要修改源代码逻辑——仅添加或更新测试
  • 遵循项目现有的测试模式(文件命名、文件夹结构、模拟风格)
  • 对于完全没有测试的文件,首先创建一个覆盖所有主要路径的全面测试文件,然后迭代完善

检测优先级

扫描源文件时,按以下常见目录结构顺序检查:

  1. src/
  2. app/(Next.js app 目录)
  3. components/
  4. lib/
  5. utils/
  6. server/(Next.js/Node.js)
  7. pages/(Next.js pages 目录)
  8. 根目录下的 *.ts / *.tsx 文件

示例

用户:“覆盖率报告显示 login.ts 为 72%,请修复”

AI 操作:

  1. 运行 npx vitest --coverage --reporter=verbose,发现 login.ts 中 45-52 行未覆盖(validateEmail 的错误分支)
  2. 读取源代码,理解 validateEmail 在无效邮箱时抛出异常
  3. 在 login.test.ts 中添加无效邮箱输入的测试用例
  4. 重新运行覆盖率 — login.ts 现在达到 100%

用户:“我们使用 jest,检查覆盖率”

  1. 运行 npx jest --coverage --verbose,识别未覆盖的文件
  2. 发现 src/components/Header.tsx 覆盖率为 0% — 没有测试
  3. 读取 Header.tsx 源码,创建 src/components/Header.test.tsx
  4. 再次运行覆盖率 — Header.tsx 现在达到 100%

用户:“这个项目没有测试设置,请添加覆盖率”

  1. 在 package.json 中未检测到测试运行器
  2. 询问用户:“未检测到测试框架。安装 Vitest 吗?(推荐)”
  3. 用户确认 → 安装 vitest + @vitest/coverage-v8,创建 vitest.config.ts
  4. 扫描 src/,发现 8 个源文件,0 个测试文件
  5. 为所有 8 个文件编写测试
  6. 运行覆盖率 — 全部达到 100%

相关技能