test-updates

测试更新与维护

概述

一套详细的测试管理系统，运用 TDD/BDD 原则来维护、生成和增强各代码库中的测试。此技能践行自身倡导的原则——它在自身开发中使用 TDD 原则，并以鲜活示例展示最佳实践。

核心理念

• RED-GREEN-REFACTOR：严格遵循 TDD 周期
• 行为优先：采用描述代码应如何运行的 BDD 模式
• 不变量编码：测试守护设计决策，而不只是行为
• 元级自我实践：该技能自身的测试展示了它所教授的原则
• 质量门槛：在认定测试完成前进行详细验证

它是什么

一套模块化测试管理系统，可以：

• 发现需要测试或更新的内容
• 遵循 TDD 原则生成测试
• 使用 BDD 模式增强现有测试
• 从多个角度验证测试质量

快速开始

首次使用快速检查清单

• 验证是否已安装 pytest（pip install pytest）
• 确保源代码位于 src/ 或类似目录中
• 如果 tests/ 目录不存在，则创建该目录
• 先运行 Skill(sanctum:git-workspace-review) 以了解变更
• 从 Skill(test-updates) --target <specific-module> 开始，针对特定模块进行更新

详细测试更新

# Run full test update workflow
Skill(test-updates)

**验证：**运行 pytest -v 以确认测试通过。

针对性测试更新

# Update tests for specific paths
Skill(test-updates) --target src/sanctum/agents
Skill(test-updates) --target tests/test_commit_messages.py

**验证：**运行 pytest -v 以确认测试通过。

为新功能采用 TDD

# Apply TDD to new code
Skill(test-updates) --tdd-only --target new_feature.py

**验证：**运行 pytest -v 以确认测试通过。

直接使用脚本

人类可读输出：

# Analyze test coverage gaps
python plugins/sanctum/scripts/test_analyzer.py --scan src/

# Generate test scaffolding
python plugins/sanctum/scripts/test_generator.py \
    --source src/my_module.py --style pytest_bdd

# Check test quality
python plugins/sanctum/scripts/quality_checker.py \
    --validate tests/test_my_module.py

**验证：**运行 pytest -v 以确认测试通过。

程序化输出（供 Claude Code 使用）：

# Get JSON output for programmatic parsing - test_analyzer
python plugins/sanctum/scripts/test_analyzer.py \
    --scan src/ --output-json

# Returns:
# {
#   "success": true,
#   "data": {
#     "source_files": ["src/module.py", ...],
#     "test_files": ["tests/test_module.py", ...],
#     "uncovered_files": ["module_without_tests", ...],
#     "coverage_gaps": [{"file": "...", "reason": "..."}]
#   }
# }

# Get JSON output - test_generator
python plugins/sanctum/scripts/test_generator.py \
    --source src/my_module.py --output-json

# Returns:
# {
#   "success": true,
#   "data": {
#     "test_file": "path/to/test_my_module.py",
#     "source_file": "src/my_module.py",
#     "style": "pytest_bdd",
#     "fixtures_included": true,
#     "edge_cases_included": true,
#     "error_cases_included": true
#   }
# }

# Get JSON output - quality_checker
python plugins/sanctum/scripts/quality_checker.py \
    --validate tests/test_my_module.py --output-json

# Returns:
# {
#   "success": true,
#   "data": {
#     "static_analysis": {...},
#     "dynamic_validation": {...},
#     "metrics": {...},
#     "quality_score": 85,
#     "quality_level": "QualityLevel.GOOD",
#     "recommendations": [...]
#   }
# }

**验证：**运行 pytest -v 以确认测试通过。

何时使用

在以下情况下使用此技能：

• 代码变更后更新测试
• 为新功能生成测试
• 提升现有测试质量
• 验证详细的测试覆盖率

非常适用于：

• 提交前的测试验证
• CI/CD 流水线集成
• 在测试保障下进行重构
• 帮助新开发者熟悉项目

何时不使用

• 审核 测试套件——使用 pensive:test-review
• 编写生产代码
  • 先专注于实现
• 审核 测试套件——使用 pensive:test-review
• 编写生产代码
  • 先专注于实现

工作流集成

阶段 1：发现

1. 扫描代码库，查找测试缺口
2. 分析近期变更
3. 找出失效或过时的测试

检测模式请参阅 modules/test-discovery.md。

阶段 2：策略

1. 选择合适的 BDD 风格（参见 modules/bdd-patterns.md）
2. 规划测试结构
3. 定义质量标准
4. 找出要编码为测试的设计不变量

阶段 2.5：不变量编码测试

在编写行为测试之前，先找出代码所依赖的设计 不变量，并编写测试，确保一旦这些不变量遭到违反， 测试就会失败。

需要编码的内容：

• 模块边界约束（A 绝不从 B 导入）
• 数据流方向（事件从发布者流向订阅者， 绝不反向流动）
• API 契约结构（公共接口未经版本控制不得更改）
• 数据结构选择（如果选择映射而非列表， 就测试支持这一选择的特性）
• 错误处理策略（快速失败边界、恢复区域）

示例：

def test_plugins_never_import_from_other_plugins():
    """Encode the invariant: plugins are independent modules.

    If this test breaks, someone is coupling plugins
    directly. Present the 3 options to a human:
    1. Preserve: revert the import, keep plugins independent
    2. Layer: add a shared interface in leyline instead
    3. Revise: merge the plugins (requires ADR)
    """
    for plugin_dir in plugin_dirs:
        imports = extract_imports(plugin_dir)
        for imp in imports:
            assert not imp.startswith("plugins."), (
                f"{plugin_dir} imports {imp} — violates plugin independence invariant"
            )

重要性： 编码不变量的测试至关重要。之后，当 Agent 遇到与不变量冲突的功能时，测试失败会迫使人们有意识地做出决定，而不是让代码悄然偏离。没有这些测试，错误的不变量决策会不断累积，直到代码库无法挽救。

更新现有测试时：

如果需要更改编码不变量的测试，切勿 悄悄更新断言。应标记出来供人工审核，并提供三个选项：保留不变量、在其基础上扩展，或修订不变量。这需要判断力，也需要人的智慧：模型默认会取训练数据的“平均值”，而且在这类问题上经常出错。

阶段 3：实现

1. 编写失败的测试（RED）——使用 Skill(superpowers:test-driven-development) 执行循环；modules/tdd-workflow.md 介绍本地流程
2. 编写最精简的通过测试的代码（GREEN）
3. 重构以提升清晰度（REFACTOR）

参见 modules/test-generation.md，了解生成模板。

阶段 4：验证

1. 静态分析和 lint
2. 动态测试执行
3. 覆盖率和质量指标

参见 modules/quality-validation.md，了解验证标准。

质量保证

该技能会执行多项质量检查：

• 静态检查：Lint、类型检查、模式验证
• 动态检查：在沙盒环境中执行测试
• 指标：覆盖率、变异分数、复杂度分析
• 不变量：确认设计决策测试未被弱化
• 审查：用于同行验证的结构化清单

示例

BDD 风格的测试生成

参见 modules/bdd-patterns.md，了解更多模式。

class TestGitWorkflow:
    """BDD-style tests for Git workflow operations."""

    def test_commit_workflow_with_staged_changes(self):
        """Committing with staged changes produces a formatted commit.

        GIVEN a Git repository with staged changes
        WHEN the user runs the commit workflow
        THEN it should create a commit with proper message format
        AND all tests should pass
        """
        # Test implementation following TDD principles
        pass

验证： 运行 pytest -v，确认测试通过。

增强测试

• 添加边界情况和错误场景
• 纳入性能基准测试
• 添加变异测试以提升稳健性

参见 modules/test-enhancement.md，了解增强策略。

与现有技能集成

1. git-workspace-review：了解更改的背景
2. 结构映射：使用 modules/structure-mapping.md 映射布局、语言和大型文件
3. test-driven-development：严格遵循 TDD 准则
4. skills-eval：验证质量和合规性

成功指标

• 测试覆盖率 > 85%
• 所有测试均遵循 BDD 模式
• CI 中没有失败的测试
• 变异分数 > 80%

故障排除常见问题

常见问题

问：生成后测试失败 答：这是预期情况！该技能遵循 TDD 原则——生成的测试一开始就应当失败。请遵循 RED-GREEN-REFACTOR 循环：

1. 运行测试，并确认失败原因正确
2. 编写最少的代码使测试通过
3. 重构以提升清晰度

问：明明有测试，质量评分却很低 答：请检查以下常见问题：

• 缺少 BDD 模式（Given/When/Then）
• 断言含糊，例如 assert result is not None
• 测试缺少文档
• 测试过长、过于复杂（超过 50 行）

问：生成的测试与我的代码结构不匹配 答：脚本会分析 AST 模式，可能需要一些指导：

• 使用 --style 标志匹配你偏好的 BDD 风格
• 检查源文件是否有适当的函数/类定义
• 检查生成的脚手架，并按需自定义

问：变异测试耗时太长 答：变异测试会占用大量资源：

• 使用 --quick-mutation 标志进行子集测试
• 优先处理关键模块
• 可在夜间运行以进行详细分析

问：找不到对应文件的测试 答：分析器会使用命名约定：

• 源文件：my_module.py → 测试文件：test_my_module.py
• 检查测试文件是否遵循 pytest 命名模式
• 验证测试目录结构是否符合标准

性能提示

• 大型代码库：使用 --target 聚焦特定目录
• CI 集成：与其他检查并行运行验证
• 内存用量：对于超大型项目，分批处理文件

获取帮助

1. 查看脚本输出中的详细错误信息
2. 使用 --verbose 标志查看更多信息
3. 查看验证报告中的具体建议
4. 从小型模块入手了解模式，然后再扩大范围

退出标准

• 将所有测试更新应用到目标文件后，pytest -v 通过且无失败
• pytest --cov 报告的范围内文件测试覆盖率超过 85%
• 所有新测试都包含符合 modules/bdd-patterns.md 中 BDD 模式的 GIVEN/WHEN/THEN 文档字符串
• 对每个更新的测试文件运行 quality_checker.py --validate <test_file> --output-json 后，返回的 quality_score ≥ 80
• 如果不变量编码测试发生变化，则必须先标记为需人工审核，并提供三种选项（保留/分层/修订），之后才能修改任何断言