test-run

用途

test-run 用于执行 keel 项目的测试套件并生成测试报告，同时支持检查受影响测试与追溯覆盖。它面向需要运行测试、验证测试覆盖率、以及进行追溯验证（确认验收标准 AC 是否被通过的测试覆盖）的场景。关键词包括“执行测试”“跑测试”“全量测试”“回归测试”“run tests”。

该技能不负责设计测试用例（应使用 /test-cases），也不用于对运行中系统做黑盒实测（应使用 e2e-test-flow）。

主要能力

全量执行：按 UT → IT → E2E 顺序分层执行所有测试。
按类型执行：--ut 仅单元测试、--it 仅集成测试、--e2e 仅 E2E 测试。
按功能点执行：/test-run F-001，通过追溯矩阵查找功能点关联的所有测试并执行。
追溯验证：--trace 在全量执行基础上增加追溯完整性验证。
受影响测试：--affected 基于 git diff 识别变更文件，仅运行关联测试，可与 --ut/--it/--e2e 组合。
测试框架检测：扫描 package.json、pyproject.toml、go.mod、Makefile 等识别 Jest/Vitest/pytest/Go test 等框架并确定运行命令。
报告生成：输出到 docs/devdocs/05-test-report.md，包含执行摘要、分层结果、失败详情、追溯验证结果与建议。

使用方式

运行模式语法：

/test-run              # 全量执行（UT + IT + E2E）
/test-run --ut         # 仅单元测试
/test-run --it         # 仅集成测试
/test-run --e2e        # 仅 E2E 测试
/test-run F-001        # 按功能点关联的测试
/test-run --trace      # 全量执行 + 追溯验证
/test-run --affected   # 仅运行受变更影响的测试
/test-run --affected --ut  # 受影响的单元测试

前置条件：测试用例文档 docs/devdocs/03-test-cases*.md；项目已配置测试框架（Jest/Vitest/pytest/Go test 等）。

执行流程：读取测试用例文档并解析用例清单与追溯矩阵；--affected 时识别变更范围；检测测试框架；按 UT → IT → E2E 分层执行；收集通过/失败/跳过统计、覆盖率与失败详情；--trace 时进行追溯验证；生成测试报告；输出摘要。

测试命令在 workspace_context.code_roots 各路径下执行，代码根多于一项时逐个执行并在报告中按 root 分组。测试报告恒写 <workspace_context.docs_dir>/devdocs/05-test-report.md。

适用场景

开发完成后执行回归测试与全量测试。
验证测试覆盖率与追溯完整性。
按功能点或变更范围运行关联测试。
与 /dev-workflow 协作：批量完成后建议调用（--trace），单任务完成后必须调用（--affected）。
与 /test-cases（提供用例清单与追溯矩阵）、/testing-guide（覆盖率与断言质量标准）、/sync（追溯矩阵状态更新）协作。

限制

执行前必须检测到测试框架，无法检测时询问用户。
分层执行顺序固定为 UT → IT → E2E，不可打乱。
单个测试失败不终止后续测试；UT 全部失败时，独立调用可提示用户，被调用时继续执行。
单个测试套件超时 5 分钟（可配置）。
必须生成测试报告，失败详情必须包含文件路径和行号。
--trace 模式必须包含追溯验证结果，且必须覆盖所有 AC，未覆盖的 AC 必须明确标记。
不检查 CON-XXX；仅当某条 CON 的验证方式引用了测试编号时，该测试才进入本技能范围。
追溯结果不修改源文件，仅报告，修改由 /sync 负责。

追溯验证规则

检查项	通过条件	失败标记
AC 测试覆盖	每个 AC 至少有 1 个关联测试	❌ 未覆盖
测试通过	AC 关联的所有测试全部通过	⚠️ 测试失败
用例覆盖	文档中的测试编号在实际测试中有对应用例	⚠️ 用例缺失
孤立测试	测试用例有对应的 AC 关联	ℹ️ 孤立测试（信息）

子 Agent 摘要格式

当本 Skill 作为子 Agent 运行时，返回结构化摘要：

skill: test-run
status: success | failed
summary:
  headline: "全量测试通过，覆盖率 85%"
  details:
    tests_run:
      unit: { passed: X, failed: 0, total: X }
      integration: { passed: X, failed: 0, total: X }
      e2e: { passed: X, failed: 0, total: X }
    coverage: "XX%"
    trace_verified: true
blockers: []
output_files:
  - docs/devdocs/05-test-report.md
new_ids: {}
next_recommended:
  skill: verify
  args: "--impl"

参考资料

templates/test-report-template.md - 测试报告模板