devdocs-test-cases

Test Case Design

Design test cases based on the requirements document, and establish traceability between acceptance criteria and test cases.

Language Rules

• Support questions in Chinese and English
• Always reply in Chinese
• Generate documents in Chinese

Trigger Conditions

• The user has completed the requirements document
• The user requests test case design
• The user needs a test coverage strategy

Preconditions

• Requirements document:docs/devdocs/01-requirements.md
• System design document:docs/devdocs/02-system-design.md(When designing UT/IT, you need to understand the interface signatures and module division)
• If it does not exist, it is recommended to run the prerequisite phase first

Core Concepts

Source of Test Cases

功能点 (F-XXX)
    │
    └── 用户故事 (US-XXX)
            │
            └── 验收标准 (AC-XXX)
                    │
                    ├── 单元测试 (UT-XXX)  ← 验证内部逻辑
                    │
                    ├── 集成测试 (IT-XXX)  ← 验证组件协作
                    │
                    └── E2E 测试 (E2E-XXX) ← 验证用户场景

Key Principles：

• Test cases are derived from requirements, not from code
• Each acceptance criterion is covered by at least one test case
• The test type is selected according to the nature of the acceptance criterion

Test Type Selection

Acceptance Criterion Type	Recommended Test Type	Example
Input validation rules	Unit test	"Email format validation" → UT
Business logic rules	Unit test + integration test	"Password encrypted storage" → UT + IT
User interaction flow	E2E test	"Complete registration flow" → E2E
Collaboration between components	Integration test	"Send verification email" → IT

Numbering Specification

Type	Prefix	Format	Example
Unit test	UT	UT-XXX	UT-001, UT-002
Integration test	IT	IT-XXX	IT-001, IT-002
E2E test	E2E	E2E-XXX	E2E-001, E2E-002

Run Mode

/devdocs-test-cases              → 标准模式（逐步确认）
/devdocs-test-cases --fast       → 跳过逐步确认，直接生成，仅最终确认

--fast mode

• Skip the step-by-step confirmation of test type selection
• Automatically select the best test type according to the nature of the AC
• Keep only 1 confirmation before the final write
• Default behavior remains unchanged,--fast is opt-in

Workflow

1. 读取需求文档
   │
   ▼
2. 提取功能点、用户故事、验收标准
   │
   ▼
3. 为每个验收标准选择测试类型
   │
   ▼
4. 按功能点分批设计测试用例
   │  对每个功能点 (F-XXX)：
   │    ├── 设计该功能点的 UT
   │    ├── 设计该功能点的 IT
   │    ├── 设计该功能点的 E2E
   │    └── 质量一致性自检（与首批对比详细程度）
   │
   ▼
5. 生成追溯矩阵
   │
   ▼
6. 用户确认

Context Management

Batching Principle

Design in batches by feature point (F-XXX), completing all test cases for one feature point in each batch (UT + IT + E2E).

Quality Anchor

• The test cases for the first feature point serve as thequality anchor
• Before starting each new feature point, review the level of detail of the first batch of test cases (field completeness, scenario coverage, specificity of inputs and outputs)
• If the level of detail of the current batch is significantly lower than the anchor, supplement it immediately

Consistency Self-Check

After completing each feature point, compare and check:

• Whether the table fields are consistent with the first batch (no missing columns)
• Whether the inputs/outputs have specific values (not vague descriptions such as "normal input")
• Whether the scenario coverage includes normal + exception paths

Output Files

Main File：docs/devdocs/03-test-cases.md

Document Splitting Rules

Default SplittingIt is a main file + sub-file structure. Keep each sub-file within a reasonable size. The Agent writes only one sub-file at a time to reduce the context burden.

Splitting Method：

docs/devdocs/
├── 03-test-cases.md           # 大纲：策略、覆盖率、追溯矩阵、用例索引
├── 03-test-unit.md            # UT 详情
├── 03-test-integration.md     # IT 详情
└── 03-test-e2e.md             # E2E 详情

Content retained in the main document(Outline, no specific use cases):

• Test strategy description
• Coverage targets
• Complete traceability matrix (F → US → AC → test)
• Scope description of use cases in each subdocument

Small project exception: test cases ≤ 15and documents ≤ 200 lines, they may be merged into a single file 03-test-cases.md。

For detailed templates, see:

• templates/test-cases-template.md
• templates/unit-test-template.md
• templates/integration-test-template.md
• templates/e2e-test-template.md

Test case overview document structure

# 测试用例：<功能名称>

## 1. 测试策略
## 2. 覆盖率要求
## 3. 追溯矩阵
## 4. 测试用例索引

Traceability matrix

The traceability matrix is the core deliverable, showing the complete association between requirements, tests, and code.

Basic format (design phase)

| 功能点 | 用户故事 | 验收标准 | 单元测试 | 集成测试 | E2E测试 | 状态 |
|--------|----------|----------|----------|----------|---------|------|
| F-001 | US-001 | AC-001 | UT-001 | - | E2E-001 | ⏳ |
| F-001 | US-001 | AC-002 | UT-002 | - | E2E-001 | ⏳ |
| F-001 | US-002 | AC-004 | UT-003, UT-004 | IT-001 | - | ⏳ |

Full format (development phase, including code locations)

Code locations are automatically populated by /devdocs-sync , based on the @satisfies/@verifies annotations in the code.

| AC 编号 | 验收标准 | 测试编号 | 入口代码 | 测试代码 | 状态 |
|---------|----------|----------|----------|----------|------|
| AC-001 | 邮箱格式校验 | UT-001 | `src/user.ts:15` | `tests/user.test.ts:20` | ✅ |
| AC-002 | 密码强度校验 | UT-002 | `src/user.ts:15` | `tests/user.test.ts:35` | ✅ |
| AC-003 | 用户名唯一性 | UT-003 | `src/user.ts:15` | `tests/user.test.ts:50` | ⏳ |
| AC-004 | 发送验证邮件 | IT-001 | - | - | ❌ |

Code location field description

Field	Source	Description
Entry code	@satisfies AC-XXX annotation	Method location implementing the AC
Test code	@verifies AC-XXX annotation	Test location verifying the AC

Status description

Status	Meaning	Condition
✅	Complete coverage	Has test case + entry code + test code + tests pass
⏳	In progress	Has test case, code/test partially complete
⚠️	Partial coverage	Has code but lacks tests, or has tests but lacks code
❌	Not covered	No test case or no code implementation

Matrix maintenance process

设计阶段                    开发阶段                     同步阶段
    │                          │                           │
    ▼                          ▼                           ▼
生成基础矩阵          生成骨架代码（带标注）        /devdocs-sync
(AC → 测试编号)       (入口 + 测试)                      │
                                                        ▼
                                                 扫描代码标注
                                                        │
                                                        ▼
                                                 填充代码位置列
                                                        │
                                                        ▼
                                                 更新状态列

Test case format

Unit test cases

| 编号 | 验收标准 | 测试对象 | 场景 | 输入 | 预期输出 | 优先级 |
|------|----------|----------|------|------|----------|--------|
| UT-001 | AC-001 | validateEmail() | 有效邮箱 | "test@example.com" | true | P0 |
| UT-002 | AC-002 | validateEmail() | 无效格式 | "invalid" | false | P0 |

Integration test cases

| 编号 | 验收标准 | 测试场景 | 涉及组件 | 预期结果 | 优先级 |
|------|----------|----------|----------|----------|--------|
| IT-001 | AC-004 | 密码加密存储 | UserService + DB | 密码以 bcrypt 格式存储 | P0 |

E2E test cases

| 编号 | 用户故事 | 验收标准 | 操作步骤 | 预期结果 | 优先级 |
|------|----------|----------|----------|----------|--------|
| E2E-001 | US-001 | AC-001~AC-003 | 1. 打开注册页<br>2. 输入邮箱密码<br>3. 点击注册 | 注册成功，收到验证邮件 | P0 |

Coverage requirements

Test type	Coverage target	Coverage requirement
Unit test	Core business logic	Line coverage ≥ 80%, branch coverage ≥ 80%
Integration test	Component collaboration scenarios	At least 1 IT per feature point
E2E test	User stories	At least 1 E2E per P0 user story

Constraints

Phase boundary constraints (highest priority)

• This Skill only produces documents; it is strictly forbidden to write or generate any implementation code or test code files
• The Write tool is only used to write docs/devdocs/ Markdown documents under
• Test cases are described in document form (tables/text), and do not generate .test.ts/.spec.ts code files such as
• Coding and test writing are handled by /devdocs-dev-workflow , which this Skill does not cover

Traceability constraints

• Each acceptance criterion is covered by at least 1 test case
• A traceability matrix must be generated
• The traceability matrix must cover all ACs

Use case design constraints

• Test cases must be associated with acceptance criterion numbers
• Each use case must have a clear expected result
• Priority must be marked (P0/P1/P2)
• The level of detail of later batches of test cases must not be lower than that of the first batch (field completeness, specific values, scenario coverage)
• Perform a consistency self-check after completing each feature point

Coverage Constraints

• P0 acceptance criteria must have 100% test coverage
• P0 user stories must have E2E tests
• Unit test line coverage target ≥ 80%

Quality Constraints (Reference /testing-guide）

• Test names must describe the expected behavior
• Weak assertions are prohibited (toBeDefined, toBeTruthy cannot be the only assertion)
• Mocks are only used for external dependencies

Skill Collaboration

Scenario	Collaborating Skill	Description
Requirement Input	/devdocs-requirements	Prerequisite: provide F/US/AC as the basis for test design
New Feature Testing	/devdocs-feature	Called: new features require new test cases
Bug Regression Testing	/devdocs-bugfix	Called: bug fixes require supplementary regression tests
Improvement Testing	/devdocs-insights	Called: improvement suggestions may require test coverage
Traceability Update	/devdocs-sync	Collaboration: trace mode updates the code locations in the traceability matrix
Test Quality	/testing-guide	Collaboration: quality constraints when writing test code
Task Breakdown	/devdocs-dev-tasks	Follow-up: convert test cases into development tasks

Sub-Agent Summary Format

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

skill: devdocs-test-cases
mode: initial | incremental
new_ids:
  unit_tests: [UT-001~UT-012]
  integration_tests: [IT-001~IT-003]
  e2e_tests: [E2E-001~E2E-002]
traceability_matrix_updated: true
status: completed
output_files:
  - docs/devdocs/03-test-cases.md

Next Steps

After completion, it is recommended to run /devdocs-dev-tasks to perform development task breakdown.

Tip: when document changes are significant, it is recommended to run /agent-memory to synchronize the memory files.