devdocs-test-run

用途

devdocs-test-run 用于执行测试套件并生成测试报告。它支持全量执行、按类型分层执行、按功能点关联执行和追溯验证。

触发条件包括：用户需要执行测试；用户需要验证测试覆盖率；用户需要追溯验证（AC 是否被通过的测试覆盖）；以及 /devdocs-dev-workflow 批量完成后自动触发。

主要能力

运行模式与语法：

/devdocs-test-run —— 全量执行（UT + IT + E2E），按 UT → IT → E2E 顺序分层执行所有测试
/devdocs-test-run --ut —— 仅执行单元测试（UT-XXX）
/devdocs-test-run --it —— 仅执行集成测试（IT-XXX）
/devdocs-test-run --e2e —— 仅执行 E2E 测试（E2E-XXX）
/devdocs-test-run F-001 —— 按功能点关联的测试，通过追溯矩阵查找功能点关联的所有测试并执行
/devdocs-test-run --trace —— 全量执行 + 追溯完整性验证

执行流程：

读取测试用例文档（扫描 docs/devdocs/03-test-cases*.md，解析 UT/IT/E2E 编号与追溯矩阵）
检测测试框架（扫描 package.json / pyproject.toml / go.mod / Makefile，识别框架并确定运行命令）
分层执行测试
收集测试结果（通过/失败/跳过统计、覆盖率数据、失败详情）
[--trace] 追溯验证
生成测试报告（输出到 docs/devdocs/05-test-report.md）
输出摘要（通过率 + 覆盖率、失败详情、追溯状态）

测试框架检测优先级：

package.json → scripts.test / devDependencies（vitest → npx vitest run；jest → npx jest；mocha → npx mocha）
pyproject.toml / setup.cfg / pytest.ini（pytest → python -m pytest）
go.mod（Go test → go test ./...）
Makefile / Cargo.toml / 其他（按框架惯例检测）
无法检测 → AskUserQuestion 询问用户

测试文件定位方式：03-test-cases*.md 中的测试文件路径；代码中的 @testcase 标注（反向查找）；测试框架约定路径（tests/、.test.ts、_test.go）。

追溯验证（--trace）验证规则：

AC 测试覆盖：每个 AC 至少有 1 个关联测试，否则标记 ❌ 未覆盖
测试通过：AC 关联的所有测试全部通过，否则标记 ⚠️ 测试失败
标注一致性：代码 @verifies 与文档追溯矩阵一致，否则标记 ⚠️ 标注不一致
孤立测试：测试用例有对应的 AC 关联，否则标记 ℹ️ 孤立测试

使用方式

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

Skill 协作场景：

测试用例来源：/devdocs-test-cases（前置：提供 UT/IT/E2E 用例清单和追溯矩阵）
测试质量标准：/testing-guide（协作：覆盖率和断言质量判定标准）
开发完成后调用：/devdocs-dev-workflow（被调用：批量开发完成后自动触发全量测试）
追溯更新：/devdocs-sync（后续：测试结果可触发追溯矩阵状态更新）

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

skill: devdocs-test-run
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
status: pass | fail
output_file: docs/devdocs/05-test-report.md

适用场景

需要执行测试套件并生成报告的项目
需要按测试类型分层执行（UT/IT/E2E）的团队
需要按功能点关联执行测试的场景
需要验证 AC 是否被通过的测试覆盖（追溯验证）的场景
作为 devdocs-dev-workflow 批量开发完成后的自动测试环节

限制

执行约束：

执行前必须检测到测试框架（无法检测时询问用户）
分层执行顺序：UT → IT → E2E（不可打乱）
单个测试失败不终止后续测试（收集全部结果后汇总）
UT 全部失败时，独立调用可提示用户，被调用时继续执行
超时保护：单个测试套件超时 5 分钟（可配置）

报告约束：

必须生成测试报告（输出到 05-test-report.md）
报告必须包含执行摘要和分层结果
失败详情必须包含文件路径和行号
--trace 模式必须包含追溯验证结果
每层报告条目数必须与实际执行数一致（完整性校验）
所有失败详情字段完整度一致（不因数量多而省略）

追溯约束：

追溯验证必须覆盖所有 AC
未覆盖的 AC 必须明确标记
标注不一致必须警告（代码 vs 文档）
追溯结果不修改源文件（仅报告，修改由 /devdocs-sync 负责）

报告包含：执行摘要（通过率、覆盖率、执行时间）、分层结果（UT/IT/E2E 各自统计）、失败详情（文件路径、行号、错误信息、关联 AC）、[--trace] 追溯验证结果、建议（未覆盖 AC 的处理建议）。

参考资料：templates/test-report-template.md（测试报告模板）。

其他语言支持与具体平台、收费、价格等信息暂未提供。

技能介绍

用途

主要能力

使用方式

适用场景

限制