test-gap-analyzer

测试缺口分析器技能

目的

此技能会自动分析代码库，以识别未经测试的函数、覆盖率较低的区域以及缺失的边界情况测试。它会根据 amplihack 的测试金字塔（60% 单元测试、30% 集成测试、10% E2E 测试），按优先级和风险影响整理并生成可执行的测试建议。

何时使用此技能

• 代码审查：合并 PR 前，识别测试缺口
• 测试规划：根据风险确定接下来要优先测试的内容
• 提高覆盖率：系统地针对覆盖率较低的区域
• 发现边界情况：查找未经测试的故障模式和边界条件
• 新模块：发布前确保测试覆盖全面
• 遗留代码：逐步提高测试覆盖率
• 重构：验证变更前后的覆盖率

核心概念

Amplihack 中的测试金字塔

测试应遵循以下分布：

• 60% 单元测试：使用模拟依赖项测试单个函数/方法的行为
• 30% 集成测试：测试多个组件协同工作
• 10% E2E 测试：端到端测试完整的用户工作流

此技能有助于平衡这些层级的测试，同时优先提高覆盖率。

缺口分析类别

此技能会识别以下方面的缺口：

1. 未经测试的函数/方法：测试覆盖率为零的函数
2. 覆盖率较低的区域：低于目标阈值（85%+）的模块/函数
3. 缺失的边界情况：边界条件、错误路径、空值检查
4. 集成缺口：未经测试的组件交互
5. 错误路径覆盖率：异常处理和故障模式

分析流程

第 1 步：扫描代码库

分析器会：

1. 发现指定目录中的所有源代码文件
2. 识别所有函数、方法和类
3. 映射代码结构和依赖关系
4. 确定当前测试覆盖率（如果有）

第 2 步：覆盖率分析

针对每个函数/方法：

1. 检查是否存在测试
2. 如果有覆盖率数据，则计算行覆盖率
3. 识别未经测试的分支和路径
4. 记录错误处理的覆盖情况

第 3 步：识别缺口

按以下方面对缺口分类：

1. 风险等级：根据函数的复杂度和关键程度分为高/中/低
2. 类型：未经测试、覆盖不完整、缺失边界情况
3. 工作量：估算编写充分测试所需的时间
4. 影响：此函数对系统可靠性的重要程度

第 4 步：生成测试建议

针对每个缺口，生成：

1. 具体的测试用例描述
2. 包含示例代码的测试模板
3. 需要覆盖的边界情况
4. 预期行为
5. 需要测试的错误条件

第 5 步：确定优先级

按以下方面整理建议：

1. 风险影响（先处理关键函数）
2. 测试金字塔分布
3. 所需工作量
4. 依赖关系

技能能力

代码分析

• 扫描 Python、JavaScript、TypeScript、Go 代码库
• 识别所有公有和私有函数
• 检测需要更多测试的复杂函数
• 映射函数依赖关系
• 查找未使用的参数和无用代码路径

覆盖率检测

• 解析 .coverage 文件（Python）
• 分析 coverage.json 报告
• 识别未覆盖的分支
• 查找测试不完整的函数
• 检测违反覆盖率阈值的情况

测试缺口发现

• 没有任何测试的函数
• 从未执行的分支
• 未经测试的错误路径
• 遗漏的边界条件
• 未覆盖的集成点
• 缺失的超时场景
• 资源耗尽情况

边界情况识别

• Null/None 输入
• 空集合
• 边界值（0、max_int 等）
• Unicode/多字节字符串
• 并发问题
• 资源限制
• 类型不匹配
• Async/await 模式

测试模板生成

提供可直接使用的测试模板，包括：

• 单元测试（模拟依赖项）
• 集成测试（真实组件）
• E2E 测试（完整工作流）
• 参数化测试
• 基于属性的测试
• 性能测试

使用示例

示例 1：分析 Python 项目

User: Analyze test coverage gaps in my src/ directory

Claude:
1. Scans src/ for all Python files
2. Reads .coverage or uses ast analysis
3. Identifies untested functions
4. Generates gap report with suggestions

Output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Test Gap Analysis Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Summary:
- Total functions: 145
- Untested: 23 (16%)
- Low coverage (< 85%): 34 (23%)

CRITICAL GAPS (High Risk):
1. payment_processor.py::process_payment()
   - Untested | Handles money | 15 min effort
   - Suggested tests:
     - Valid payment processing
     - Insufficient funds error
     - Payment timeout
     - Currency conversion

MEDIUM GAPS:
2. user_service.py::validate_email()
   - 40% coverage | Missing edge cases
   - Suggested tests:
     - Unicode characters
     - Long email addresses
     - Special characters

LOW GAPS:
3. utils.py::format_date()
   - 60% coverage
   - Suggested tests:
     - Timezone handling
     - Daylight saving transitions

示例 2：获取测试模板

User: Generate test templates for my untested auth module

Claude:
Creates templates organized by testing pyramid:

Unit Tests (60%):
- test_token_validation_valid()
- test_token_validation_expired()
- test_token_validation_invalid_signature()

Integration Tests (30%):
- test_auth_flow_with_database()
- test_multi_user_concurrent_auth()

E2E Tests (10%):
- test_user_login_to_protected_resource()
- test_session_persistence_across_requests()

示例 3：覆盖率改进计划

User: Help me improve test coverage from 65% to 85%

Claude:
1. Analyzes current coverage
2. Identifies gaps blocking 85% threshold
3. Prioritizes by impact
4. Estimates effort

Output:
To reach 85% coverage:
- 12 quick wins (< 2 hours each)
- 3 medium tasks (2-4 hours each)
- 2 complex tasks (4+ hours each)

Recommended order:
1. Add error case tests (5 tests, 3 hours) -> +8%
2. Cover auth edge cases (8 tests, 4 hours) -> +6%
3. Add integration tests (12 tests, 6 hours) -> +7%

分析清单

覆盖率检查

• 识别目标目录中的所有源文件
• 确定当前覆盖率百分比
• 找出所有未测试的函数
• 定位覆盖率低于 85% 的函数
• 梳理分支覆盖率缺口

缺口分类

• 按风险等级（高／中／低）分类
• 估算每个缺口所需的工作量
• 识别关键路径函数
• 找出依赖关系
• 按影响程度排序

测试建议生成

• 生成单元测试模板
• 生成集成测试模板
• 建议边界情况
• 提供错误场景测试
• 包含参数化测试示例

报告生成

• 汇总统计数据
• 按优先级列出缺口
• 为每个缺口提供测试模板
• 估算总工作量
• 推荐测试顺序

输出格式

标准报告结构

# Test Gap Analysis Report

## Summary

- Total functions: N
- Untested functions: N (X%)
- Functions < 85%: N (X%)
- Average coverage: X%

## Critical Gaps (Must Test)

1. Function name | Type | Priority | Effort
   Suggested tests: [list]

## Medium Priority Gaps

[Similar structure]

## Low Priority Gaps

[Similar structure]

## Testing Pyramid Distribution

Current:

- Unit: X% | Target: 60%
- Integration: X% | Target: 30%
- E2E: X% | Target: 10%

## Test Templates

[Ready-to-use test code]

## Effort Estimate

- Quick wins: N hours
- Medium tasks: N hours
- Complex work: N hours
- Total: N hours

测试模板示例

单元测试模板

def test_function_name_happy_path():
    """Test function with valid inputs."""
    # Arrange
    input_data = {...}
    expected = {...}

    # Act
    result = function_name(input_data)

    # Assert
    assert result == expected

错误案例模板

def test_function_name_invalid_input():
    """Test function raises ValueError on invalid input."""
    with pytest.raises(ValueError, match="Expected error message"):
        function_name(invalid_input)

边界情况模板

def test_function_name_edge_case():
    """Test function handles edge case correctly."""
    # Test boundary conditions
    result = function_name(boundary_value)
    assert result is not None

集成测试模板

def test_user_service_with_database(test_db):
    """Test user service with real database."""
    user_service = UserService(test_db)
    user = user_service.create_user("[email protected]")
    assert user.id is not None

理念契合

极致简洁

• 聚焦必要的测试，而非追求全面覆盖
• 85% 的覆盖率已足够（超过此值后收益递减）
• 避免测试实现细节
• 测试行为，而非代码结构

杜绝空话，务求实效

• 所有测试模板开箱即用
• 不使用占位测试或 TODO 注释
• 测试能带来实际价值
• 边界情况应具体，而非泛泛而谈

测试金字塔

• 优先编写单元测试（快速、隔离）
• 添加集成测试（验证契约）
• 尽量减少端到端测试（验证用户流程）
• 均衡分布，避免测试变得脆弱

与其他技能集成

配合使用

• code-quality-analyzer：识别复杂度
• module-spec-generator：使测试与规范保持一致
• refactor-advisor：规划测试变更
• type-safety-checker：测试类型契约

输出至

• CI Validation：确保合并前测试通过
• Documentation：展示模块用法
• Regression Prevention：防止回归

常见模式

模式 1：快速发现缺口

User: Quick test coverage review of api/

Claude:
- Scans directory
- Identifies top 5 gaps
- Provides quick recommendations
- Total time: < 2 minutes

模式 2：系统性提升覆盖率

User: Plan test coverage improvement from 60% to 85%

Claude:
- Analyzes gaps
- Creates phased improvement plan
- Prioritizes by risk
- Provides effort estimates
- Generates all test templates

模式 3：新模块测试规划

User: Generate complete test plan for new auth module

Claude:
- Analyzes module structure
- Maps public functions
- Creates test suggestions
- Balances testing pyramid
- Provides all templates

质量检查

分析完成后，请验证：

• 缺口识别准确
• 测试模板可直接使用
• 工作量估算合理
• 优先级排序遵循风险分析
• 测试金字塔分布均衡
• 边界情况具体，而非泛泛而谈
• 已识别集成点
• 已覆盖错误路径

应避免的常见陷阱

❌ 过度测试实现细节

测试行为，而非代码的实现方式。细节可能会改变。

❌ 泛泛而谈的边界情况

要具体：“测试空字符串”，而非“测试边界情况”。

❌ 忽视集成

不要只孤立地测试函数，还要测试它们如何协同工作。

❌ 遗漏错误路径

每种错误情况都应至少有一个测试。

❌ 未测试依赖项

模拟外部系统，但要测试集成点。

成功标准

良好的测试缺口分析应：

• 识别所有未测试的函数
• 按风险和影响确定优先级
• 提供可直接使用的测试模板
• 平衡测试金字塔
• 合理估算工作量
• 包含边界情况建议
• 梳理集成缺口
• 提供可执行的建议

有效测试规划技巧

1. 从关键功能入手：资金、安全性、数据完整性
2. 使用测试模板：不要从头编写
3. 平衡测试金字塔：不要过度测试边界情况
4. 测试契约，而非实现：关注行为，不必纠结细节
5. 涵盖正常流程和错误情况：两者都很重要
6. 自动跟踪覆盖率：及早发现回归问题
7. 迭代改进：达到 85% 的覆盖率切实可行，100% 则过犹不及
8. 记录测试的存在原因：让未来的维护者了解测试意图

工具和命令

Python 项目

# Generate coverage report
coverage run -m pytest
coverage json  # Creates coverage.json

# Analyze gaps with this skill
Claude: Analyze test gaps in my project using coverage.json

TypeScript/JavaScript 项目

# Generate coverage report
jest --coverage

# Analyze gaps
Claude: Analyze test gaps in my TypeScript project

实际示例

分析前

Project Stats:
- 156 functions
- 52% test coverage
- Unknown untested functions
- Scattered test files

分析后

Gap Report:
- 24 untested functions (15%)
- 34 functions < 85% (22%)
- 12 critical gaps (high impact)
- 45 medium gaps (medium impact)
- 40 low gaps (low priority)

Recommendations:
1. Focus on critical gaps (payment, auth, data)
2. Add error case tests (20 tests, 8 hours)
3. Cover edge cases (15 tests, 6 hours)
4. Integration tests (12 tests, 10 hours)

Result after implementing:
- 89% test coverage
- All critical functions tested
- Balanced testing pyramid
- Improved confidence in refactoring

后续步骤

完成差距分析后：

1. 审查报告：了解当前状况
2. 确定差距优先级：优先关注关键功能
3. 使用模板：实现建议的测试
4. 运行测试：确认新测试通过
5. 跟踪覆盖率：监控改进情况
6. 迭代：逐步提高覆盖率

成功指标

有效的测试差距分析会带来：

• 清晰了解覆盖率状况
• 可执行的改进计划
• 测试覆盖率达到 85% 以上
• 均衡的测试金字塔
• 提升开发者信心
• 加快调试和重构
• 减少生产环境问题