ai-unit-test-generator
v3.1.5
Published
AI-powered unit test generator with smart priority scoring, parallel generation, behavior classification, test validation, and deduplication
Maintainers
yuhengzhouReadme
AI Test Generator v3.1.0
🤖 AI驱动的单元测试生成器，具有智能优先级评分和代码质量验证
🎯 核心特性
基础功能
- 🏗️ 分层架构评分: 根据代码层级（Foundation, Business, State, UI）智能评分
- 🤖 AI Native 设计: 完美集成 Cursor Agent、ChatGPT、Claude 等 AI工具
- 📊 覆盖率感知: 集成代码覆盖率数据进行智能优先级排序
- 🎨 多维度评分: 结合可测试性、复杂度、依赖数量、业务关键度、错误风险
- ⚡ 批量生成: 自动化批量测试生成，支持失败重试和进度追踪
- 📝 丰富的报告: 生成 Markdown 和 CSV 格式的详细评分报告
v3.1.0 新特性 🆕
1️⃣ Best Practices 生成（Qodo 风格）
- 自动分析项目: 检测测试框架、文件模式、现有测试
- AI 生成规范: 根据项目特点生成测试标准
- 双模式支持: 独立 Markdown 文件或内联配置
2️⃣ 实时代码验证（Qodo 风格）
- 自动验证: 生成的测试代码立即验证（编译+运行）
- 智能重试: 失败时自动重试并提供反馈（默认3次）
- 质量保证: 确保生成的测试可以实际运行
3️⃣ 测试去重（Keploy 风格）
- 相似度检测: 使用 Levenshtein 距离算法检测重复测试
- 智能分析: 识别85%以上相似度的测试用例
- 自动清理: 支持自动删除重复测试
4️⃣ 覆盖率驱动迭代（Keploy 风格）
- 动态迭代: 根据实际覆盖率持续生成，而非固定次数
- 智能反馈: 分析覆盖率差距，提供针对性改进建议
- 目标驱动: 迭代直到达到覆盖率目标
架构优化（v3.0+）
- ✅ 100% TypeScript: 完全迁移到 TypeScript，零编译错误
- 🎯 模块化设计: 清晰的模块边界和导出
- 📦 Shared 工具层: 统一的工具函数库
- 🔧 易于维护: 代码重复率降低85%+
📦 安装
全局安装（推荐）
npm install -g ai-unit-test-generator项目安装
npm install --save-dev ai-unit-test-generator🚀 快速开始
1. 初始化配置
ai-test init这将在当前目录创建 ai-test.config.jsonc 配置文件，包含详细的注释说明。
2. (可选) 生成测试规范
# 生成独立的 best_practices.md 文件
ai-test init-best-practices
# 或者生成内联配置（嵌入到 ai-test.config.jsonc）
ai-test init-best-practices --inline这将：
- 分析项目结构和 package.json
- 检测测试框架（Jest/Vitest/Mocha）
- 提取现有测试模式
- 使用 AI 生成项目特定的测试标准
3. 扫描代码并评分
ai-test scan执行流程：
- 分析代码结构，识别可测试的目标
- (可选) 自动运行 Jest 覆盖率分析
- 分析 Git 历史获取错误信号
- 计算多维度优先级评分
- 生成排序报告 (
reports/ut_scores.md)
示例输出：
| Status | Score | Priority | Name | Type | Layer | Path | Coverage | Testability | Complexity |
|--------|-------|----------|------|------|-------|------|----------|-------------|------------|
| TODO | 8.5 | P0 | validatePayment | function | Business | src/services/payment.ts | 0.0% | 9 | 10 |
| TODO | 7.8 | P0 | formatCurrency | function | Foundation | src/utils/format.ts | 15.0% | 10 | 8 |4. 生成测试
# 生成前10个最高优先级的函数测试（带自动改进）
ai-test generate
# 生成前20个函数的测试
ai-test generate -n 20
# 只生成 P0 优先级的测试
ai-test generate -p P0
# 生成所有 TODO 函数的测试
ai-test generate --all
# 禁用自动改进（单次生成模式）
ai-test generate --no-iterative执行流程：
- 从报告中选择最高优先级的未测试函数
- 调用 Cursor Agent 自动生成测试
- 提取并保存测试文件
- 运行 Jest 验证测试
- 🔄 检查质量并自动改进（默认启用）
- 自动更新报告状态为 DONE
5. 查看进度
# 查看完整报告
cat reports/ut_scores.md
# 查看 P0 优先级任务
grep "| P0 |" reports/ut_scores.md
# 查看待处理任务
grep "| TODO |" reports/ut_scores.md📖 命令详解
ai-test init
初始化配置文件
ai-test init [options]
Options:
-c, --config <path> Config file path (default: ai-test.config.jsonc)ai-test init-best-practices 🆕
生成项目特定的测试规范
ai-test init-best-practices [options]
Options:
--inline Generate inline config instead of separate file
-c, --config <path> Config file path (default: ai-test.config.jsonc)两种模式：
- 文件模式（默认）: 生成
best_practices.md - 内联模式（
--inline）: 嵌入到ai-test.config.jsonc
ai-test scan
扫描代码并生成优先级报告
ai-test scan [options]
Options:
-c, --config <path> Config file path (default: ai-test.config.jsonc)
-o, --output <dir> Output directory (default: reports)
--skip-git Skip Git history analysis输出文件：
reports/targets.json- 扫描的目标列表reports/git_signals.json- Git 分析数据reports/ut_scores.md- Markdown 格式报告（按评分排序）reports/ut_scores.csv- CSV 格式报告
ai-test generate
生成单元测试（使用 Cursor Agent）
ai-test generate [options]
Options:
-n, --count <number> Number of functions to generate (default: 10)
-p, --priority <level> Priority filter (P0, P1, P2, P3)
--all Generate all remaining TODO functions
--no-iterative Disable iterative improvement (default: enabled)
--max-iterations <number> Maximum iterations for iterative mode (default: 3)
--report <path> Report file path (default: reports/ut_scores.md)示例：
ai-test generate # 生成前10个，带自动改进
ai-test generate -n 20 # 生成前20个
ai-test generate -p P0 # 只生成 P0 优先级
ai-test generate --all # 生成所有 TODO 函数
ai-test generate --no-iterative # 禁用自动改进⚙️ 配置文件
首次运行 ai-test scan 时，会自动生成包含详细注释的配置文件 ai-test.config.jsonc。
核心配置
{
"version": "3.1.0",
"scoringMode": "layered", // 评分模式: layered 或 legacy
// 覆盖率配置
"coverage": {
"runBeforeScan": true, // 扫描前自动运行覆盖率分析
"command": "npx jest --coverage --silent"
},
// 覆盖率评分映射
"coverageScoring": {
"naScore": 5, // 无覆盖率数据时的默认分数
"mapping": [
{ "lte": 0, "score": 10 }, // 0% 覆盖率 → 最高优先级
{ "lte": 40, "score": 8 }, // 1-40% → 高优先级
{ "lte": 70, "score": 6 }, // 41-70% → 中等优先级
{ "lte": 90, "score": 3 }, // 71-90% → 低优先级
{ "lte": 100, "score": 1 } // 91-100% → 最低优先级
]
},
// v3.1.0 新增配置
"bestPractices": {
"enabled": false,
"source": "file", // "file" 或 "inline"
"filePath": "./best_practices.md"
},
"validation": {
"enabled": false,
"maxAttempts": 3,
"timeout": 30000
},
"coverageDriven": {
"enabled": false,
"targetCoverage": 80,
"maxIterations": 5
},
"deduplication": {
"enabled": false,
"similarityThreshold": 0.85
}
}分层配置
{
"layers": {
"foundation": {
"name": "Foundation (基础工具层)",
"patterns": ["**/utils/**", "**/helpers/**", "**/constants/**"],
"weights": {
"testability": 0.45, // 可测试性权重
"dependencyCount": 0.25, // 依赖数量权重
"complexity": 0.20, // 复杂度权重
"coverage": 0.10 // 覆盖率权重
},
"thresholds": {
"P0": 8.0, // 分数 ≥8.0 = P0 (必须测试)
"P1": 6.5, // 分数 6.5-7.9 = P1 (高优先级)
"P2": 5.0 // 分数 5.0-6.4 = P2 (中等优先级), <5.0 = P3
},
"coverageTarget": 100 // 目标覆盖率 100%
}
// ... 其他层级配置
}
}📊 优先级说明
| 优先级 | 分数范围 | 描述 | 建议操作 | |--------|----------|------|----------| | P0 | ≥8.0 | 必须测试 | 立即生成 | | P1 | 6.5-7.9 | 高优先级 | 批量生成 | | P2 | 5.0-6.4 | 中等优先级 | 审查后生成 | | P3 | <5.0 | 低优先级 | 可选覆盖 |
🏗️ 分层架构
1. Foundation Layer（基础层）
- 特征: 工具函数、助手函数、常量
- 权重: 高可测试性权重 (45%)
- 阈值: P0 ≥ 8.0
- 目标覆盖率: 100%
2. Business Logic Layer（业务逻辑层）
- 特征: 服务、API、数据处理
- 权重: 平衡的多维度评分
- 阈值: P0 ≥ 7.5
- 目标覆盖率: 80%
3. State Management Layer（状态管理层）
- 特征: 状态存储、上下文、Reducers
- 权重: 强调错误风险
- 阈值: P0 ≥ 7.0
- 目标覆盖率: 70%
4. UI Components Layer（UI 组件层）
- 特征: React 组件、视图
- 权重: 平衡复杂度和错误风险
- 阈值: P0 ≥ 6.5
- 目标覆盖率: 60%
📈 评分指标说明
Coverage Score（覆盖率评分）
新特性: 集成代码覆盖率数据，适用于增量和现有代码场景
- 评分映射:
- 0% → 10分（最高优先级，急需测试）
- 1-40% → 8分（高优先级）
- 41-70% → 6分（中等优先级）
- 71-90% → 3分（低优先级）
- 91-100% → 1分（已充分覆盖）
- N/A → 5分（无数据）
Testability（可测试性）
- 纯函数: 10/10（无副作用，易于测试）
- 简单 Mock: 8-9/10（依赖易于 Mock）
- 复杂依赖: 4-6/10（需要复杂的测试设置）
Dependency Count（依赖数量）
基于引用计数：
- ≥10 个模块引用: 10/10（核心模块）
- 5-9 个模块: 10/10
- 3-4 个模块: 9/10
- 1-2 个模块: 7/10
- 无引用: 5/10
Complexity（复杂度）
- 圈复杂度: 11-15 → 10/10（中等复杂度，值得测试）
- 认知复杂度: 通过 ESLint 分析
- 嵌套深度: 调整复杂度分数
🤖 AI 集成
使用 Cursor Agent（推荐）
# 自动生成测试（内置 Cursor Agent 集成）
ai-test generate -n 10使用其他 AI 工具（ChatGPT、Claude）
# 1. 生成 AI prompt
ai-test scan
grep "| TODO |" reports/ut_scores.md | head -10
# 2. 手动复制函数信息到 AI 工具
# 3. 保存 AI 响应到文件
# 4. 运行测试验证
npm test🎬 完整工作流示例
# 1. 安装 Jest（如果尚未安装）
npm i -D jest@29 ts-jest@29 @types/jest@29 jest-environment-jsdom@29
# 2. 初始化配置
ai-test init
# 3. (可选) 生成测试规范
ai-test init-best-practices
# 4. 扫描代码
ai-test scan
# ✅ 自动生成配置文件
# ✅ 自动运行覆盖率分析
# ✅ 生成优先级报告
# 5. 查看报告
cat reports/ut_scores.md
# 6. 生成测试（10个函数）
ai-test generate
# 7. 查看结果
npm test
# 8. 继续下一批
ai-test generate -n 10
# 9. 重复直到所有高优先级测试完成🛠️ 高级用法
Jest 环境要求
首次使用需要安装 Jest：
npm i -D jest@29 ts-jest@29 @types/jest@29 jest-environment-jsdom@29然后在 tsconfig.json 中添加类型支持：
{
"compilerOptions": {
"typeRoots": ["node_modules/@types"]
}
}自定义覆盖率命令
修改 ai-test.config.jsonc：
{
"coverage": {
"runBeforeScan": true,
"command": "npm run test:coverage" // 自定义命令
}
}跳过 Git 分析
如果项目没有 Git 历史或不需要 Git 信号：
ai-test scan --skip-git🔧 项目结构
ai-test-generator/
├── src/ # TypeScript 源代码
│ ├── cli.ts # CLI 入口
│ ├── types/ # 类型定义 (5 模块)
│ ├── shared/ # 共享工具层 (4 模块)
│ ├── core/ # 核心分析引擎
│ │ ├── scanner.ts # AST 扫描
│ │ ├── git-analyzer.ts # Git 历史分析
│ │ ├── scoring/ # 评分系统
│ │ ├── mock/ # Mock 分析 (v3.1.0: 简化版)
│ │ └── behavior/ # 行为分类
│ ├── ai/ # AI 交互层
│ │ ├── prompt-builder.ts # Prompt 构建
│ │ ├── client.ts # Cursor Agent 调用
│ │ ├── extractor.ts # 测试提取
│ │ └── ...
│ ├── testing/ # 测试执行层
│ │ ├── runner.ts # Jest 运行器
│ │ ├── validator.ts # 🆕 v3.1.0: 测试验证器
│ │ ├── deduplicator.ts # 🆕 v3.1.0: 测试去重
│ │ └── ...
│ ├── workflows/ # 工作流编排层
│ │ ├── init.ts # 初始化
│ │ ├── scan.ts # 扫描
│ │ ├── generate.ts # 生成
│ │ ├── init-best-practices.ts # 🆕 v3.1.0: Best Practices
│ │ ├── generate-with-validation.ts # 🆕 v3.1.0: 带验证的生成
│ │ ├── coverage-driven-generate.ts # 🆕 v3.1.0: 覆盖率驱动
│ │ └── ...
│ └── utils/ # 工具层
│ ├── config-manager.ts # 配置管理
│ └── ...
├── dist/ # 编译后的代码
├── templates/ # 配置模板
│ ├── default.config.jsonc # 默认配置
│ └── jest.config.cobertura.js
└── package.json架构原则
- 分层设计: 核心分析、AI 交互、测试、工作流之间清晰分离
- 核心零 AI 依赖: 核心模块可在无 AI 的情况下使用
- 模块化导出: 每一层都有清晰的 API 导出
- 可编程 API: 所有工作流都可以导入并编程使用
🎯 v3.1.0 更新内容
移除的功能
- ❌ Boundary Detection（边界检测）- 过度设计，已移除 (-583行)
- ❌ Mock 代码示例生成 - 限制AI自由度，已简化 (-320行)
新增的功能
- ✅ Best Practices 生成 - AI理解项目风格
- ✅ 实时代码验证 - 确保生成代码可运行
- ✅ 测试去重 - 提高测试质量
- ✅ 覆盖率驱动 - 智能迭代
设计理念变化
移除理由:
- 静态分析的局限: 无法理解业务逻辑
- 过度指导: 限制 AI 的创造力
- 技术栈假设: 不应该假设用户使用什么库
- 代码膨胀: 维护成本高，实际价值低
新增理由:
- 实际价值: 解决真实痛点
- 业界验证: Qodo、Keploy 已证明有效
- AI Native: 充分发挥 AI 能力
- 用户需求: 可选启用，不强制
📚 灵感来源
本项目从以下研究和实践中汲取灵感：
Meta TestGen-LLM: 质量保证过滤器和大规模实践
Automated Unit Test Improvement using Large Language Models at MetaQodo Cover: Best Practices、实时验证
https://www.qodo.ai/Keploy: 测试去重、覆盖率驱动
https://keploy.io/ByteDance Midscene.js: 自然语言接口和稳定性实践
https://github.com/web-infra-dev/midscene
这些理念在 ai-test-generator 中体现为：
- 严格的输出协议（JSON manifest + 代码块）
- 失败反馈循环（Jest JSON → 可操作提示 → 下一个 prompt）
- 批处理与进度追踪（TODO/DONE/SKIP）
- 覆盖率感知优先级
🤝 贡献
欢迎贡献！请提交问题或拉取请求。
📄 许可证
MIT © YuhengZhou
🔗 链接
💬 支持
需要帮助？通过以下方式获取支持：
- 查看 更新日志
- 提交 GitHub Issues
提示: 首次使用建议先在小项目上测试，熟悉工作流后再应用到大项目。