devdocs-test-run

Test Execution

Execute test suites and generate test reports, supporting full execution, layered execution by type, execution by feature point association, and traceability verification.

Language Rules

Support questions in Chinese and English
Reply uniformly in Chinese

Trigger Conditions

User needs to execute tests
User needs to verify test coverage
User needs traceability verification (whether ACs are covered by passing tests)
/devdocs-dev-workflow Automatically triggered after batch completion
Keywords: "execute tests", "run tests", "full test", "regression test", "run tests"

Run Modes

Syntax

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

Mode Description

Mode	Description
Full Execution	Execute all tests in layered order: UT → IT → E2E
`--ut`	Execute only unit tests (UT-XXX)
`--it`	Execute only integration tests (IT-XXX)
`--e2e`	Execute only E2E tests (E2E-XXX)
`F-XXX`	Find and execute all tests associated with a feature point via the traceability matrix
`--trace`	Full execution + traceability completeness verification

Prerequisites

Test case document:docs/devdocs/03-test-cases*.md
The project has a test framework configured (Jest/Vitest/pytest/Go test, etc.)

Execution Flow

1. 读取测试用例文档
   ├── 扫描 docs/devdocs/03-test-cases*.md
   ├── 解析测试用例清单（UT/IT/E2E 编号）
   └── 解析追溯矩阵（AC → 测试映射）
           │
           ▼
2. 检测测试框架
   ├── 扫描 package.json / pyproject.toml / go.mod / Makefile
   ├── 识别测试框架（Jest/Vitest/pytest/Go test 等）
   └── 确定运行命令
           │
           ▼
3. 分层执行测试
   ├── 单元测试（UT-XXX）
   │   └── 运行命令 + 收集结果
   ├── 集成测试（IT-XXX）
   │   └── 运行命令 + 收集结果
   └── E2E 测试（E2E-XXX）
       └── 运行命令 + 收集结果
           │
           ▼
4. 收集测试结果
   ├── 通过/失败/跳过 统计
   ├── 覆盖率数据（如可用）
   └── 失败详情（文件:行号 + 错误信息）
           │
           ▼
5. [--trace] 追溯验证
   ├── 扫描代码中的 @verifies/@testcase 标注
   ├── 对比追溯矩阵（03-test-cases*.md）
   ├── 标记未覆盖的 AC
   └── 标记无通过测试的 AC
           │
           ▼
6. 生成测试报告
   └── 输出到 docs/devdocs/05-test-report.md
           │
           ▼
7. 输出摘要
   ├── 通过率 + 覆盖率
   ├── 失败详情（如有）
   └── [--trace] 追溯状态

Test Framework Detection

Detection Priority

1. package.json → scripts.test / devDependencies
   ├── vitest → npx vitest run
   ├── jest → npx jest
   └── mocha → npx mocha
2. pyproject.toml / setup.cfg / pytest.ini
   └── pytest → python -m pytest
3. go.mod
   └── Go test → go test ./...
4. Makefile / Cargo.toml / 其他
   └── 按框架惯例检测
5. 无法检测 → AskUserQuestion 询问用户

Test File Location

Locate test files via the path information in the test case document:

1. 03-test-cases*.md 中的测试文件路径
2. 代码中的 @testcase 标注（反向查找）
3. 测试框架约定路径（__tests__/、*.test.ts、*_test.go）

Layered Execution Strategy

Execution Order

UT（单元测试）→ IT（集成测试）→ E2E（端到端测试）

UT Full Failure Prompt: When all UTs fail, decide based on the calling context:

Standalone call (used directly by the user): AskUserQuestion whether to continue with IT/E2E
Called by dev-workflow (--trace): continue execution and collect all results

Execute by Feature Point

/devdocs-test-run F-001

1. 读取追溯矩阵
2. 查找 F-001 关联的所有 AC
3. 查找每个 AC 关联的测试用例（UT/IT/E2E）
4. 仅执行这些测试
5. 生成功能点维度的报告

Context Management

Segmented Writing

Process in segments by test layer: complete UT results → write to the UT section of the report → then process IT → write to the IT section → then process E2E. Avoid processing all results at once.

Integrity Verification

Verify after writing each layer:

Number of test entries in the report == actual number of entries output by the test framework
Number of failure detail entries == actual number of failures (no omissions)

Failure Detail Consistency

Use the details of the first failed test case as theformat anchor
Each subsequent failed test case must contain the same fields: file path, line number, associated AC, error message, suggestion
Do not omit any field because of a large number of failures

Traceability Verification (--trace)

Verification Rules

Check Item	Pass Condition	Failure Marker
AC Test Coverage	Each AC has at least 1 associated test	❌ Not Covered
Tests Pass	All tests associated with the AC pass	⚠️ Test Failed
Annotation Consistency	Code @verifies matches the document traceability matrix	⚠️ Annotation Inconsistency
Orphan Test	The test case has a corresponding AC association	ℹ️ Isolated test (information)

Traceability Report Format

## 追溯验证结果

| AC 编号 | 描述 | 关联测试 | 测试状态 | 覆盖状态 |
|---------|------|----------|----------|----------|
| AC-001 | 邮箱格式校验 | UT-001, IT-001 | ✅ 全部通过 | ✅ 已覆盖 |
| AC-002 | 密码强度校验 | UT-002 | ❌ 1/1 失败 | ⚠️ 测试失败 |
| AC-003 | 重复注册检测 | — | — | ❌ 未覆盖 |

Test Report

Output Path

docs/devdocs/05-test-report.md

Report Content

See templates/test-report-template.md

The report includes:

Executive summary (pass rate, coverage, execution time)
Layered results (separate statistics for UT/IT/E2E)
Failure details (file path, line number, error message, related AC)
[--trace] Traceability verification results
Recommendations (handling suggestions for uncovered ACs)

Skill Collaboration

Scenario	Collaborating Skill	Description
Test case source	`/devdocs-test-cases`	Precondition: provide UT/IT/E2E case lists and traceability matrix
Test quality standards	`/testing-guide`	Collaboration: coverage and assertion quality criteria
Invoked after development is complete	`/devdocs-dev-workflow`	Invoked: automatically trigger full testing after batch development is complete
Traceability update	`/devdocs-sync`	Follow-up: test results can trigger traceability matrix status updates

Constraints

Execution Constraints

A test framework must be detected before execution(ask the user if it cannot be detected)
Layered execution order: UT → IT → E2E(must not be changed)
A single test failure does not terminate subsequent tests(aggregate after collecting all results)
When all UTs fail, standalone invocation may prompt the user, while invoked execution continues
Timeout protection: single test suite timeout of 5 minutes (configurable)

Report Constraints

A test report must be generated(output to 05-test-report.md)
The report must include an executive summary and layered results
Failure details must include file path and line number
--trace mode must include traceability verification results
The number of report entries per layer must match the actual number executed (completeness check)
All failure detail fields must have consistent completeness (do not omit due to large quantity)

Traceability Constraints

Traceability verification must cover all ACs
Uncovered ACs must be clearly marked
Label inconsistencies must be warned(code vs documentation)
Traceability results do not modify source files(report only; modifications are handled by /devdocs-sync)

Sub-Agent Summary Format

When this Skill runs as a sub-agent, return the following structured summary:

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

Reference Materials

templates/test-report-template.md - Test report template