test-run

Test Execution

Execute the test suite and generate a test report, supporting full execution, layered execution by type, associated execution by feature point, and traceability verification.

Quick Start

One sentence: Execute the test suite and generate a test report.

Most common usage: /test-run(full),/test-run --ut(unit tests only)

Not suitable? Design test cases →/test-cases

Language Rules

Supports questions in Chinese and English
Unified Chinese responses

Trigger Conditions

The user needs to execute tests
The user needs to verify test coverage
The user needs traceability verification (whether ACs are covered by passing tests)
/dev-workflow After batch completionRecommendedcall (--trace), after single task completionmustcall (--affected) — based on dev-workflow full test verification constraints as the standard
Keywords: "execute tests", "run tests", "full tests", "regression tests", "run tests"

Run Modes

Syntax

/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  # 受影响的单元测试

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
`--affected`	Identify changed files based on git diff, and run only associated tests (can be combined with --ut/--it/--e2e)

Prerequisites

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

Execution Flow

Test commands are executed under each path in workspace_context.code_roots (inline is a single item whenpath = absolute path of the repository root,the caller does not branch). When there is more than one code root, execute each one and group by root in the report. Test reports are always written to <workspace_context.docs_dir>/devdocs/05-test-report.md. Code roots are taken from the handshake workspace_context（shared/constraints.md §3 task/workspace-context; when not passed in, use the inline default).

1. 读取测试用例文档
   ├── 扫描 docs/devdocs/03-test-cases*.md
   ├── 解析测试用例清单（UT/IT/E2E 编号）
   └── 解析追溯矩阵（AC → 测试映射）
           │
           ▼
1.5 [--affected] 变更范围识别
   ├── 确定比较基线（用户指定 base / 自动检测 merge-base / 不可判定时提示全量）
   ├── 执行 git diff --name-only <base> 获取变更文件
   ├── 在 03-test-cases.md 中匹配引用这些文件的测试用例
   ├── 在 04-dev-tasks.md 中匹配关联文件的任务，反查测试用例
   └── 无匹配时提示"建议运行全量"
           │
           ▼
2. 检测测试框架
   ├── 扫描 package.json / pyproject.toml / go.mod / Makefile
   ├── 识别测试框架（Jest/Vitest/pytest/Go test 等）
   └── 确定运行命令
           │
           ▼
3. 分层执行测试
   ├── 单元测试（UT-XXX）
   │   └── 运行命令 + 收集结果
   ├── 集成测试（IT-XXX）
   │   └── 运行命令 + 收集结果
   └── E2E 测试（E2E-XXX）
       └── 运行命令 + 收集结果
           │
           ▼
4. 收集测试结果
   ├── 通过/失败/跳过 统计
   ├── 覆盖率数据（如可用）
   └── 失败详情（文件:行号 + 错误信息）
           │
           ▼
5. [--trace] 追溯验证
   ├── 按测试文件与用例名匹配文档中的测试编号
   ├── 对比追溯矩阵（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 documentation:

1. 03-test-cases*.md 中的测试文件路径
2. 测试名与文档用例描述的匹配（反向查找）
3. 测试框架约定路径（__tests__/、*.test.ts、*_test.go）

Layered Execution Strategy

Execution order

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

UT total failure prompt: When all UTs fail, decide based on the calling context:

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

Execute by feature point

/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 check

Verify after each layer is written:

Number of test entries in the report == actual number of entries output by the test framework

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 just because there are many 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
Case coverage	Test numbers in the document have corresponding cases in the actual tests	⚠️ Case missing
Orphaned test	The test case has a corresponding AC association	ℹ️ Orphaned test (info)

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:

Execution summary (pass rate, coverage rate, execution time)
Layered results (statistics for UT/IT/E2E separately)
Failure details (file path, line number, error message, associated AC)
[--trace] Traceability verification results
Suggestions (handling suggestions for uncovered ACs)
[--affected] Coverage scope (mode, comparison baseline, changed files, matching tests, uncovered changes)

Skill collaboration

Scenario	Collaborating Skill	Description
Test case source	`/test-cases`	Prerequisite: provide UT/IT/E2E case list and traceability matrix
Test quality standards	`/testing-guide`	Collaboration: coverage and assertion quality judgment standards
Called after development is complete	`/dev-workflow`	Called: automatically trigger full testing after batch development is complete
Traceability update	`/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(cannot be changed)
A single test failure does not terminate subsequent tests(aggregate after collecting all results)
When all UTs fail, independent invocation may prompt the user, while invoked execution continues
Timeout protection: a single test suite times out after 5 minutes (configurable)

Report constraints

A test report must be generated(output to 05-test-report.md)
Failure details must include the file path and line number
--trace mode must include traceability verification results
All failure detail fields are equally complete (do not omit just because there are many)

Traceability constraints

Traceability verification must cover all ACs
⛔ Do not check CON-XXX— the scope of this skill istest suite. The CON's 档 = 可执行 verification method (guard script / command / benchmark) is directly executed by /dev-workflow in S5 red verification / S6 green verification,/verify --impl B1 re-check; only when a certain CON's verification methodreferences a test number(such as IT-012) does that test enter this skill's scope as an ordinary test case.This is an intentional boundary, not an omission.
Uncovered ACs must be explicitly marked
A warning must be issued when a documented test number has no corresponding actual test case
Traceability results do not modify source files(report only; modifications are handled by /sync)

Sub-Agent Summary Format

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

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"

Reference Materials

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