@wwkit/harness 1.0.8 → 1.0.10

package/skills/pytest-case-fix/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: pytest-case-fix
+description: |
+  分析测试失败原因并修复。按失败类型分类处理：断言错误修复测试或源码、Mock 配置错误修正 patch、环境问题标记人工处理。
+  适用：测试代理内层 loop 的修复阶段，修复 pytest-execute 报告的失败用例。
+  不适用：创建新用例（使用 pytest-case-create）、覆盖率分析（使用 pytest-coverage-analyze）。
+---
+
+# 用例修复
+
+## 工作流模式
+
+本 Skill 采用 **顺序执行** 工作流：
+
+1. **分类失败**：按错误类型对失败用例分类
+2. **分析原因**：逐个分析失败根因
+3. **执行修复**：按分类进行修复
+4. **语法验证**：验证修复后的文件语法正确
+5. **输出记录**：修复记录 + 人工处理项 + 源码 Bug 清单（写入 `{report_dir}/bug_list.md`）
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| failed_tests | 是 | list | 失败用例清单（来自 pytest-execute） |
+| test_dir | 是 | string | 测试目录路径（由 agent Step 1 统一解析） |
+| report_dir | 是 | string | 报告输出目录（由 agent Step 1 统一解析） |
+| test_type | 是 | string | 测试类型：unit 或 integration |
+| config | 是 | object | 来自 pytest-env-ensure 的配置对象 |
+
+## 输出
+
+- 修复记录列表
+- 人工处理项列表
+- 源码 Bug 清单（已修复 + 需人工处理）
+- 是否有修改的结论（有修改 → 回到 execute；无修改 → 内层 loop 退出）
+- 将源码 Bug 清单写入 `{report_dir}/bug_list.md`
+
+---
+
+## 阶段一：分类失败
+
+**操作**：按错误类型对失败用例分类
+
+| 分类 | 错误类型 | 说明 |
+|------|---------|------|
+| 断言失败 | AssertionError | 测试逻辑有误或源码有 bug |
+| Mock 配置错误 | AttributeError, TypeError | patch 路径不对或 Mock 对象属性缺失 |
+| 导入错误 | ImportError, ModuleNotFoundError | 依赖缺失，环境问题 |
+| 超时 | TimeoutError | 可能有真实网络调用未被 Mock |
+| 其他 | 其他异常 | 未知错误 |
+
+---
+
+## 阶段二：分析原因
+
+### 断言失败（AssertionError）
+
+逐个分析：
+
+1. 读取测试用例代码
+2. 读取被测源码
+3. 判断失败原因：
+   - **测试逻辑有误**：断言条件写错 → 修复测试
+   - **Mock 返回值不对**：Stub 数据与预期不符 → 修复 Mock 的 return_value
+   - **源码逻辑有 bug**：测试暴露了真实缺陷 → 修复源码
+
+### Mock 配置错误（AttributeError, TypeError）
+
+1. 检查 `@patch` 路径是否正确
+2. 检查 Mock 对象是否配置了所需的属性/方法
+3. 检查 `return_value` / `side_effect` 是否设置
+
+### 导入错误（ImportError, ModuleNotFoundError）
+
+1. 检查是否缺少依赖包
+2. 标记为 **人工处理**，不在 fix 轮次中解决
+
+### 超时（TimeoutError）
+
+1. 检查是否有真实网络调用未被 Mock
+2. 修复为 Mock 调用（unit 类型）
+3. 集成测试的超时可能是环境问题 → 标记人工处理
+
+### 其他
+
+1. 记录详细错误信息
+2. 标记为 **人工处理**
+
+---
+
+## 阶段三：执行修复
+
+### 修复测试用例
+
+| 场景 | 修复操作 |
+|------|---------|
+| 断言条件写错 | 修正断言表达式 |
+| Mock 返回值不对 | 修改 return_value 为正确值 |
+| patch 路径不对 | 修正 @patch 路径为正确的模块路径 |
+| Mock 属性缺失 | 添加 side_effect 或配置 Mock 对象属性 |
+| Stub 数据格式不对 | 修正 Stub 数据结构 |
+| 测试数据有误 | 修正测试输入数据 |
+
+### 修复源码
+
+| 场景 | 修复操作 |
+|------|---------|
+| 函数返回值有误 | 修正返回逻辑 |
+| 异常处理不完整 | 补充 try-except 分支 |
+| 边界条件处理错误 | 修正条件判断 |
+| 类型转换错误 | 修正类型处理 |
+
+### 修复原则
+
+1. **只修复失败相关的代码**，不改动其他部分
+2. **修复测试优先于修复源码**（先确认测试正确，再修源码）
+3. **一次只修一个失败**，避免引入新问题
+4. **不修改 conftest.py**（除非失败直接由 conftest 导致）
+5. **修改源码前必须保存原始内容**（读取并记录文件原始内容，用于回滚）
+
+---
+
+## 阶段四：语法验证与快速测试
+
+**操作**：
+
+### 4.1 语法检查
+
+对每个修复的文件运行语法检查：
+
+```
+uv run python -m py_compile "<file>"
+```
+
+### 4.2 源码修复的快速测试
+
+如果修复了**源码文件**（非测试文件），额外运行对应测试文件的快速验证：
+
+```
+uv run pytest "<对应测试文件>" -v --tb=short --timeout=60 -m {test_type}
+```
+
+**目的**：py_compile 只检查语法，无法发现运行时错误（类型错误、属性不存在等）。快速测试确保源码修复不引入新问题。
+
+### 4.3 回滚机制
+
+- 阶段三修复前已保存原始内容
+- 语法检查失败或快速测试引入新错误 → 用原始内容覆盖文件，回滚修改
+- 回滚后标记为人工处理
+
+**决策**：
+
+| 条件 | 动作 |
+|------|------|
+| 语法正确 + 快速测试通过（或无源码修复） | 进入阶段五 |
+| 语法错误 | 用原始内容回滚，标记为人工处理 |
+| 快速测试引入新错误 | 用原始内容回滚，标记为人工处理 |
+| 快速测试超时 | 回滚源码修改，标记为人工处理 |
+
+---
+
+## 阶段五：输出记录
+
+**操作**：
+
+1. 在 chat 中输出修复报告
+2. 将源码 Bug 清单写入 `{report_dir}/bug_list.md`
+
+### 修复报告（chat 输出）
+
+```
+## 用例修复报告
+
+### 修复记录
+| # | 文件 | 方法 | 失败类型 | 修复类型 | 修复内容 |
+|---|------|------|---------|---------|---------|
+| 1 | test_MyService.py | test_create_with_valid_data | 断言失败 | 修复测试 | 修正断言条件 |
+| 2 | MyService.py | - | 断言失败 | 修复源码 | 修正返回值逻辑 |
+| 3 | test_MyService.py | test_parse_raises_on_empty | Mock错误 | 修复测试 | 修正 patch 路径 |
+
+### 人工处理项
+| # | 文件 | 方法 | 失败类型 | 原因 |
+|---|------|------|---------|------|
+| 4 | test_MyService.py | test_import_module | 导入错误 | 缺少依赖包 xxx |
+
+### 结论
+- 修复 X 项，人工处理 Y 项
+- [有修改] → 建议重新执行测试
+- [无修改] → 无法自动修复，建议人工介入
+```
+
+### 源码 Bug 清单（写入 {report_dir}/bug_list.md）
+
+仅记录修复类型为"修复源码"的条目，以及源码层面无法自动修复需人工处理的条目。
+
+```markdown
+# 源码 Bug 清单
+
+> 生成时间: {YYYY-MM-DD HH:MM:SS}
+> 测试类型: {test_type}
+> 测试目录: {test_dir}
+
+## 已自动修复
+
+| # | 源码文件 | 方法 | Bug 描述 | 修复内容 | 触发用例 |
+|---|---------|------|---------|---------|---------|
+| 1 | MyService.py | create | 返回值逻辑错误 | 修正返回值 | test_create_with_valid_data |
+| 2 | Calculator.py | clamp | min/max 返回值互换 | 修正分支逻辑 | test_clamp_boundary |
+
+## 需人工处理
+
+| # | 源码文件 | 方法 | Bug 描述 | 原因 | 触发用例 |
+|---|---------|------|---------|------|---------|
+| 3 | OrderService.py | create_order | 类型校验缺失 | 需业务确认预期行为 | test_create_order_invalid_user_id |
+| 4 | ConfigManager.py | get_bool | truthy 逻辑反转 | 修复后语法错误已回滚，需人工分析 | test_get_bool_unknown |
+```
+
+**源码 Bug 判定规则**：
+
+| 条件 | 归类 |
+|------|------|
+| 阶段二判定为"源码逻辑有 bug"且阶段三成功修复 | 已自动修复 |
+| 阶段二判定为"源码逻辑有 bug"但修复后语法验证失败已回滚 | 需人工处理 |
+| 阶段二判定为"源码逻辑有 bug"但无法确定修复方案 | 需人工处理 |
+
+**文件写入规则**：
+- 路径：`{report_dir}/bug_list.md`
+- 目录不存在时自动创建
+- 每次内层 loop 执行时覆盖写入（保留最新状态）
+- 无源码 Bug 时仍写入文件，内容为"本次测试未发现源码 Bug"
+
+---
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| 有修复（修复数 > 0） | 输出修复记录，回到 pytest-execute 重新执行 |
+| 无修复（全部标记人工处理） | 输出人工处理项，内层 loop 提前退出 |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 修复后语法错误 | 回滚该文件修改，标记人工处理 |
+| 无法确定失败原因 | 记录详情，标记人工处理 |
+| 源码修复引入新问题 | 回滚源码修改，标记人工处理 |
+
+## 一定要做
+
+1. 必须按错误类型分类处理
+2. 修复测试优先于修复源码
+3. 一次只修一个失败
+4. 修改源码前必须保存原始内容（用于回滚）
+5. 修复后必须验证语法
+6. 源码修复后必须运行对应测试的快速验证（防止引入新问题）
+7. 语法错误或快速测试失败必须回滚（用原始内容覆盖）
+8. 无法修复的必须标记为人工处理
+9. 必须输出是否有修改的结论
+10. 修复源码的条目必须记录到源码 Bug 清单
+11. 源码 Bug 清单必须写入 `{report_dir}/bug_list.md`
+12. 无源码 Bug 时仍写入 bug_list.md，内容为"本次测试未发现源码 Bug"
+
+## 一定不要做
+
+1. 不要修改与失败无关的代码
+2. 不要修改 conftest.py（除非直接导致失败）
+3. 不要在一次修复中改动多个文件（逐个修复）
+4. 不要跳过语法验证
+5. 不要跳过源码修复后的快速测试
+6. 不要忽略语法验证或快速测试失败（必须回滚）
+7. 不要尝试修复导入错误（标记人工处理）
+8. 不要在未保存原始内容的情况下修改源码（无法回滚）

package/skills/pytest-coverage-analyze/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: pytest-coverage-analyze
+description: |
+  运行 pytest 覆盖率分析并按评分规则计算质量得分。解析 coverage.json 提取覆盖率数据，扫描测试文件检查质量维度。
+  适用：测试代理外层 loop 的分析阶段，评估当前测试覆盖范围和质量。
+  不适用：非 pytest 项目、非覆盖率相关的代码分析。
+---
+
+# 覆盖率与质量分析
+
+## 工作流模式
+
+本 Skill 采用 **顺序执行** 工作流：
+
+1. **运行覆盖率**：执行 pytest --cov 生成 JSON 报告
+2. **解析覆盖率**：从 coverage.json 提取行/分支/函数覆盖率
+3. **质量检查**：扫描测试文件检查质量维度
+4. **评分计算**：按评分规则计算总分
+5. **输出结果**：得分 + 未覆盖区域 + 改进建议
+
+## 输入
+
+| 参数 | 必填 | 类型 | 说明 |
+|------|------|------|------|
+| target | 是 | string | 被测模块路径（如 src/mypackage） |
+| test_dir | 是 | string | 测试目录路径（由 agent Step 1 统一解析） |
+| report_dir | 是 | string | 报告输出目录（用于 coverage.json 输出路径） |
+| test_type | 是 | string | 测试类型：unit 或 integration |
+| config | 是 | object | 来自 pytest-env-ensure 的配置对象 |
+| previous_score | 否 | number | 上一轮得分（用于无改进检测） |
+
+## 输出
+
+- 总分（0-100）
+- 各维度得分明细
+- 未覆盖文件/函数/分支列表
+- 改进建议
+- 是否达标的结论
+
+---
+
+## 阶段一：运行覆盖率
+
+**操作**：
+
+使用传入的 `test_dir` 运行覆盖率分析：
+
+```
+# unit 超时 60s，integration 超时 300s
+uv run pytest "{test_dir}" --cov="{target}" --cov-report=term --cov-report=json:"{report_dir}/coverage.json" --cov-report=html:"{report_dir}/htmlcov" --timeout={timeout} -m {test_type}
+```
+
+**超时配置**：
+- test_type=unit → timeout=60
+- test_type=integration → timeout=300
+- 超时值来自 config.md 的 `test_timeout` 配置
+
+**失败处理**：
+
+| 条件 | 动作 |
+|------|------|
+| pytest 执行成功 | 进入阶段二 |
+| pytest 有失败用例 | 仍然解析覆盖率（覆盖率基于已执行的用例），记录失败数 |
+| pytest 执行错误（非测试失败） | 退出，输出错误信息 |
+
+---
+
+## 阶段二：解析覆盖率
+
+**输入**：`{report_dir}/coverage.json` 文件
+
+**操作**：
+
+1. 读取 `coverage.json`
+2. 提取 `totals` 字段：
+   - `num_statements`, `covered_lines` → 行覆盖率
+   - `num_branches`, `covered_branches` → 分支覆盖率
+   - `num_functions`, `covered_functions` → 函数覆盖率
+3. 提取 `files` 字段：每个文件的覆盖率明细
+4. 识别未覆盖的文件、函数、分支
+
+**计算公式**：
+
+- 行覆盖率 = num_statements > 0 ? covered_lines / num_statements × 100% : 100%
+- 分支覆盖率 = num_branches > 0 ? covered_branches / num_branches × 100% : 100%
+- 函数覆盖率 = num_functions > 0 ? covered_functions / num_functions × 100% : 100%
+
+> **除零保护**：当分母为 0 时（源码无分支/无函数/无语句），该项覆盖率记为 100%（满分）。
+> 这与 `references/scoring-rules.md` 的"分母为 0 时该项给满分"规则一致。
+
+---
+
+## 阶段三：质量检查
+
+**操作**：扫描传入的 `test_dir` 目录下所有测试文件
+
+### 检查项（按 test_type 加载对应权重）
+
+**unit 质量维度（20 分）**：
+
+| 维度 | 检查方法 |
+|------|---------|
+| 断言完整性(5) | 统计每个 test 函数是否含 `assert` 关键字 |
+| 异常路径覆盖(5) | 源码中含 `raise`/`try` 的函数，测试中是否有 `pytest.raises` |
+| 边界值覆盖(5) | 源码中含 `if`/`elif` 的函数，测试用例数 ≥ 分支数 |
+| 命名规范(5) | test 函数名匹配 `^test_\w+_\w+$` |
+
+**integration 质量维度（50 分）**：
+
+| 维度 | 检查方法 |
+|------|---------|
+| 场景完整性(15) | 核心业务场景是否都有对应测试（按源码公开方法数统计） |
+| 数据流验证(10) | 测试中是否验证了输入→处理→输出完整链路（含多步 assert） |
+| 断言完整性(10) | 每个 test 函数至少含 1 个 assert |
+| fixture 使用(10) | 是否合理使用 setup/teardown fixture |
+| 命名规范(5) | test 函数名匹配 `^test_\w+_\w+$` |
+
+**通用规则**：
+- 分母为 0 时（无适用项），该项给满分
+- 超限封顶：`min(实际/阈值, 1.0)`
+
+---
+
+## 阶段四：评分计算
+
+**输入**：覆盖率数据 + 质量检查结果
+
+**操作**：按 `references/scoring-rules.md` 的评分规则计算总分
+
+**评分公式**：
+
+```
+总分 = 行覆盖率得分 + 分支覆盖率得分 + 函数覆盖率得分 + 质量维度得分
+
+单项得分 = min(实际值/阈值, 1.0) × 满分
+```
+
+**等级**：
+
+| 等级 | 分数 |
+|------|------|
+| A | 90-100 |
+| B | 80-89 |
+| C | 60-79 |
+| D | <60 |
+
+---
+
+## 阶段五：输出结果
+
+**输出格式**：
+
+```
+## 覆盖率与质量分析报告
+
+### 总分：XX / 100（等级：X）
+
+### 覆盖率明细
+| 维度 | 实际 | 阈值 | 权重 | 得分 |
+|------|------|------|------|------|
+| 行覆盖率 | XX% | XX% | XX | XX |
+| 分支覆盖率 | XX% | XX% | XX | XX |
+| 函数覆盖率 | XX% | XX% | XX | XX |
+
+### 质量明细
+| 维度 | 达标/应测 | 权重 | 得分 |
+|------|----------|------|------|
+| 断言完整性 | X/X | X | X |
+| 异常路径覆盖 | X/X | X | X |
+| 边界值覆盖 | X/X | X | X |
+| 命名规范 | X/X | X | X |
+
+### 未覆盖区域
+| 文件 | 未覆盖函数 | 未覆盖行数 |
+|------|-----------|-----------|
+| src/xxx.py | func_a, func_b | 15 |
+
+### 改进建议
+1. 为 func_a 添加正向测试用例
+2. 为 func_b 的 if 分支添加边界值用例
+3. ...
+
+### 结论
+- 得分 XX，阈值 XX → [达标/未达标]
+- [未达标] → 建议进入用例创建阶段
+```
+
+---
+
+## 决策
+
+| 条件 | 动作 |
+|------|------|
+| score ≥ coverage_threshold | 输出"达标"，流程结束 |
+| score < coverage_threshold | 输出未覆盖区域，交给 pytest-case-create |
+| score ≤ previous_score（非首轮） | 输出"无改进"，提前退出外层 loop |
+
+## 失败处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| coverage.json 不存在 | 退出，提示覆盖率报告未生成 |
+| 目标模块路径无效 | 退出，提示路径不存在 |
+| 测试目录不存在 | 输出 0 分，提示需要创建测试目录 |
+| 测试目录为空（无 test_*.py 文件） | 输出 0 分，将全部源码文件列为未覆盖，提示需要先创建用例 |
+| pytest 超时 | 退出，提示测试执行超时，建议检查是否有 hang 住的用例或增加 timeout 配置 |
+
+> **注意**：agent 在首轮检测到 test_dir 为空时会跳过本技能，直接进入 case-create。
+> 此场景仅作为兜底保护，确保即使 agent 未跳过也不会崩溃。
+
+## 一定要做
+
+1. 必须使用传入的 test_dir 运行覆盖率分析，并根据 test_type 选择评分权重
+2. 覆盖率数据必须来自 coverage.json，不做主观判断
+3. 质量检查必须通过文件扫描，不猜测
+4. 分母为 0 时该项给满分（覆盖率维度和质量维度均适用）
+5. 必须输出未覆盖区域清单（供 case-create 使用）
+6. 非首轮时必须检查是否无改进
+
+## 一定不要做
+
+1. 不要混合 unit 和 integration 的覆盖率数据
+2. 不要修改源码或测试文件
+3. 不要跳过质量检查只看覆盖率
+4. 不要主观判断测试质量，只做可程序化检查的判断
+5. 不要忽略 coverage.json 解析错误

package/skills/pytest-coverage-analyze/references/scoring-rules.md

@@ -0,0 +1,57 @@
+# 评分规则
+
+> 覆盖率数据完全来自 `coverage.json`（pytest-cov 生成），质量维度通过文件扫描检查，无主观判断。
+
+## 单元测试评分（unit）— 满分 100
+
+### 覆盖率维度（80 分）
+
+| 维度 | 满分 | 阈值 | 数据来源 | 计分公式 |
+|------|------|------|---------|---------|
+| 行覆盖率 | 30 | 90% | coverage.json: covered_lines / num_statements | `min(实际/阈值, 1) × 30` |
+| 分支覆盖率 | 30 | 70% | coverage.json: covered_branches / num_branches | `min(实际/阈值, 1) × 30` |
+| 函数覆盖率 | 20 | 90% | coverage.json: covered_functions / num_functions | `min(实际/阈值, 1) × 20` |
+
+### 质量维度（20 分）
+
+| 维度 | 满分 | 检查方法 | 计分公式 |
+|------|------|---------|---------|
+| 断言完整性 | 5 | 扫描测试文件，统计含 `assert` 关键字的 test 函数比例 | `(有assert函数数 / 总函数数) × 5` |
+| 异常路径覆盖 | 5 | 源码含 `raise`/`try` 的函数，测试中是否有对应 `pytest.raises` | `(有异常测试数 / 应测异常函数数) × 5` |
+| 边界值覆盖 | 5 | 源码含 `if`/`elif` 的函数，测试用例数 ≥ 分支数 | `(达标函数数 / 应测函数数) × 5` |
+| 命名规范 | 5 | test 函数名匹配 `^test_\w+_\w+$` | `(规范命名数 / 总数) × 5` |
+
+## 集成测试评分（integration）— 满分 100
+
+### 覆盖率维度（50 分）
+
+| 维度 | 满分 | 阈值 | 数据来源 | 计分公式 |
+|------|------|------|---------|---------|
+| 行覆盖率 | 20 | 70% | coverage.json: covered_lines / num_statements | `min(实际/阈值, 1) × 20` |
+| 分支覆盖率 | 20 | 50% | coverage.json: covered_branches / num_branches | `min(实际/阈值, 1) × 20` |
+| 函数覆盖率 | 10 | 70% | coverage.json: covered_functions / num_functions | `min(实际/阈值, 1) × 10` |
+
+### 质量维度（50 分）
+
+| 维度 | 满分 | 检查方法 | 计分公式 |
+|------|------|---------|---------|
+| 场景完整性 | 15 | 核心业务场景是否都有对应测试（按源码公开方法数统计） | `(有测试的场景数 / 应测场景数) × 15` |
+| 数据流验证 | 10 | 测试中是否验证了输入→处理→输出完整链路（含多步 assert） | `(有数据流验证的函数数 / 总函数数) × 10` |
+| 断言完整性 | 10 | 每个测试函数至少含 1 个 assert | `(有assert函数数 / 总函数数) × 10` |
+| fixture 使用 | 10 | 是否合理使用 setup/teardown fixture | `(有fixture的测试类数 / 总类数) × 10` |
+| 命名规范 | 5 | test 函数名匹配 `^test_\w+_\w+$` | `(规范命名数 / 总数) × 5` |
+
+## 通用规则
+
+- **分母为 0**：若应测数为 0（无适用项），该项直接给满分。
+- **超限封顶**：`min(实际/阈值, 1.0)` 确保单项不超过满分。
+- **数据来源**：覆盖率维度完全依赖 coverage.json；质量维度通过 grep/扫描测试文件检查。
+
+## 等级
+
+| 等级 | 分数范围 | 含义 |
+|------|---------|------|
+| A | 90-100 | 优秀 |
+| B | 80-89 | 合格 |
+| C | 60-79 | 需改进 |
+| D | <60 | 不合格 |