Back to Details

devdocs-test-cases

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

测试用例设计

Test Case Design

基于需求文档设计测试用例，建立验收标准与测试用例的追溯关系。
Design test cases based on requirement documents, and establish traceability between acceptance criteria and test cases.

语言规则

Language Rules

  • 支持中英文提问
  • 统一中文回复
  • 使用中文生成文档
  • Support questions in Chinese and English
  • Respond uniformly in Chinese
  • Generate documents in Chinese

触发条件

Trigger Conditions

  • 用户已完成需求文档
  • 用户要求设计测试用例
  • 用户需要测试覆盖策略
  • User has completed the requirement document
  • User requests test case design
  • User needs test coverage strategy

前置条件

Preconditions

  • 需求文档：
    docs/devdocs/01-requirements.md
  • 系统设计文档：
    docs/devdocs/02-system-design.md
    （设计 UT/IT 时需要了解接口签名和模块划分）
  • 如不存在，建议先运行前置阶段
  • Requirement document: 
    docs/devdocs/01-requirements.md
  • System design document: 
    docs/devdocs/02-system-design.md
    (Required to understand interface signatures and module division when designing UT/IT)
  • If not present, it is recommended to run the pre-phase first

核心理念

Core Concepts

测试用例来源

Test Case Sources

功能点 (F-XXX)
    │
    └── 用户故事 (US-XXX)
            │
            └── 验收标准 (AC-XXX)
                    │
                    ├── 单元测试 (UT-XXX)  ← 验证内部逻辑
                    │
                    ├── 集成测试 (IT-XXX)  ← 验证组件协作
                    │
                    └── E2E 测试 (E2E-XXX) ← 验证用户场景
关键原则：
  • 测试用例从需求推导，不是从代码推导
  • 每个验收标准至少有一个测试用例覆盖
  • 测试类型根据验收标准的性质选择
Feature Point (F-XXX)
    │
    └── User Story (US-XXX)
            │
            └── Acceptance Criterion (AC-XXX)
                    │
                    ├── Unit Test (UT-XXX)  ← Verify internal logic
                    │
                    ├── Integration Test (IT-XXX)  ← Verify component collaboration
                    │
                    └── E2E Test (E2E-XXX) ← Verify user scenarios
Key Principles:
  • Test cases are derived from requirements, not from code
  • Each acceptance criterion must be covered by at least one test case
  • Test type is selected based on the nature of the acceptance criterion

测试类型选择

Test Type Selection

验收标准类型推荐测试类型示例
输入验证规则单元测试"邮箱格式校验" → UT
业务逻辑规则单元测试 + 集成测试"密码加密存储" → UT + IT
用户交互流程E2E 测试"完成注册流程" → E2E
组件间协作集成测试"发送验证邮件" → IT
Acceptance Criterion TypeRecommended Test TypeExample
Input validation rulesUnit Test"Email format validation" → UT
Business logic rulesUnit Test + Integration Test"Password encrypted storage" → UT + IT
User interaction flowE2E Test"Complete registration process" → E2E
Inter-component collaborationIntegration Test"Send verification email" → IT

编号规范

Naming Convention

类型前缀格式示例
单元测试UTUT-XXXUT-001, UT-002
集成测试ITIT-XXXIT-001, IT-002
E2E 测试E2EE2E-XXXE2E-001, E2E-002
Test TypePrefixFormatExample
Unit TestUTUT-XXXUT-001, UT-002
Integration TestITIT-XXXIT-001, IT-002
E2E TestE2EE2E-XXXE2E-001, E2E-002

工作流程

Workflow

1. 读取需求文档
   │
   ▼
2. 提取功能点、用户故事、验收标准
   │
   ▼
3. 为每个验收标准选择测试类型
   │
   ▼
4. 设计单元测试用例 (UT-XXX)
   │
   ▼
5. 设计集成测试用例 (IT-XXX)
   │
   ▼
6. 设计 E2E 测试用例 (E2E-XXX)
   │
   ▼
7. 生成追溯矩阵
   │
   ▼
8. 用户确认
1. Read requirement document
   │
   ▼
2. Extract feature points, user stories, and acceptance criteria
   │
   ▼
3. Select test type for each acceptance criterion
   │
   ▼
4. Design unit test cases (UT-XXX)
   │
   ▼
5. Design integration test cases (IT-XXX)
   │
   ▼
6. Design E2E test cases (E2E-XXX)
   │
   ▼
7. Generate traceability matrix
   │
   ▼
8. User confirmation

输出文件

Output Files

主文件：
docs/devdocs/03-test-cases.md
Main File: 
docs/devdocs/03-test-cases.md

文档拆分规则

Document Splitting Rules

当满足以下条件时，应拆分文档：
  • 测试用例总数超过 30 个
  • 文档超过 300 行
  • 单一测试类型用例超过 15 个
拆分方式：
docs/devdocs/
├── 03-test-cases.md           # 主文档：测试策略、覆盖率要求、追溯矩阵
├── 03-test-unit.md            # 单元测试用例（UT-XXX）
├── 03-test-integration.md     # 集成测试用例（IT-XXX）
└── 03-test-e2e.md             # E2E 测试用例（E2E-XXX）
拆分内容分配：
文件包含内容
03-test-cases.md测试策略、覆盖率要求、追溯矩阵、测试用例汇总
03-test-unit.md所有单元测试用例详情（UT-001 ~ UT-XXX）
03-test-integration.md所有集成测试用例详情（IT-001 ~ IT-XXX）
03-test-e2e.md所有 E2E 测试用例详情（E2E-001 ~ E2E-XXX）
主文档保留内容：
  • 测试策略说明
  • 覆盖率目标
  • 完整追溯矩阵（F → US → AC → 测试）
  • 各子文档的用例范围说明
小型项目：如测试用例较少（< 30 个），可合并为单一文件 
03-test-cases.md
。
详细模板参见：
  • templates/test-cases-template.md
  • templates/unit-test-template.md
  • templates/integration-test-template.md
  • templates/e2e-test-template.md
Split the document when any of the following conditions are met:
  • Total number of test cases exceeds 30
  • Document exceeds 300 lines
  • Number of test cases for a single test type exceeds 15
Splitting Method:
docs/devdocs/
├── 03-test-cases.md           # Main document: Test strategy, coverage requirements, traceability matrix
├── 03-test-unit.md            # Unit test cases (UT-XXX)
├── 03-test-integration.md     # Integration test cases (IT-XXX)
└── 03-test-e2e.md             # E2E test cases (E2E-XXX)
Content Allocation After Splitting:
FileContent Included
03-test-cases.mdTest strategy, coverage requirements, traceability matrix, test case summary
03-test-unit.mdDetails of all unit test cases (UT-001 ~ UT-XXX)
03-test-integration.mdDetails of all integration test cases (IT-001 ~ IT-XXX)
03-test-e2e.mdDetails of all E2E test cases (E2E-001 ~ E2E-XXX)
Content Retained in Main Document:
  • Test strategy description
  • Coverage targets
  • Complete traceability matrix (F → US → AC → Tests)
  • Description of test case scope for each sub-document
Small Projects: If the number of test cases is small (<30), they can be merged into a single file 
03-test-cases.md
.
For detailed templates, refer to:
  • 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

markdown
undefined
markdown
undefined

测试用例：<功能名称>

Test Cases: <Feature Name>

1. 测试策略

1. Test Strategy

2. 覆盖率要求

2. Coverage Requirements

3. 追溯矩阵

3. Traceability Matrix

4. 测试用例汇总

4. Test Case Summary

undefined
undefined

追溯矩阵

Traceability Matrix

追溯矩阵是核心产出，展示需求与测试、代码的完整关联。
The traceability matrix is the core deliverable, showing the complete association between requirements, tests, and code.

基础格式（设计阶段）

Basic Format (Design Phase)

markdown
| 功能点 | 用户故事 | 验收标准 | 单元测试 | 集成测试 | 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 | - | ⏳ |
markdown
| Feature Point | User Story | Acceptance Criterion | Unit Test | Integration Test | E2E Test | Status |
|---------------|------------|----------------------|-----------|------------------|----------|--------|
| 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 | - | ⏳ |

完整格式（开发阶段，含代码位置）

Complete Format (Development Phase, Including Code Locations)

代码位置由 
/devdocs-sync --trace
自动填充，基于代码中的 
@satisfies
/
@verifies
标注扫描。
markdown
| 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 locations are automatically populated by 
/devdocs-sync --trace
, based on scanning 
@satisfies
/
@verifies
annotations in the code.
markdown
| AC ID | Acceptance Criterion | Test ID | Entry Code | Test Code | Status |
|-------|----------------------|---------|------------|-----------|--------|
| AC-001 | Email format validation | UT-001 | `src/user.ts:15` | `tests/user.test.ts:20` | ✅ |
| AC-002 | Password strength validation | UT-002 | `src/user.ts:15` | `tests/user.test.ts:35` | ✅ |
| AC-003 | Username uniqueness | UT-003 | `src/user.ts:15` | `tests/user.test.ts:50` | ⏳ |
| AC-004 | Send verification email | IT-001 | - | - | ❌ |

代码位置字段说明

Code Location Field Description

字段来源说明
入口代码
@satisfies AC-XXX
标注		实现该 AC 的方法位置
测试代码
@verifies AC-XXX
标注		验证该 AC 的测试位置
FieldSourceDescription
Entry Code
@satisfies AC-XXX
annotation		Location of the method implementing this AC
Test Code
@verifies AC-XXX
annotation		Location of the test verifying this AC

状态说明

Status Description

状态含义条件
✅完整覆盖有测试用例 + 入口代码 + 测试代码 + 测试通过
⏳进行中有测试用例，代码/测试部分完成
⚠️部分覆盖有代码但缺测试，或有测试但缺代码
❌未覆盖无测试用例或无代码实现
StatusMeaningCondition
✅Fully CoveredHas test case + entry code + test code + test passed
⏳In ProgressHas test case, code/test partially completed
⚠️Partially CoveredHas code but lacks test, or has test but lacks code
❌Not CoveredNo test case or no code implementation

矩阵维护流程

Matrix Maintenance Process

设计阶段                    开发阶段                     同步阶段
    │                          │                           │
    ▼                          ▼                           ▼
生成基础矩阵          生成骨架代码（带标注）        /devdocs-sync --trace
(AC → 测试编号)       (入口 + 测试)                      │
                                                        ▼
                                                 扫描代码标注
                                                        │
                                                        ▼
                                                 填充代码位置列
                                                        │
                                                        ▼
                                                 更新状态列
Design Phase                Development Phase          Sync Phase
    │                          │                           │
    ▼                          ▼                           ▼
Generate Basic Matrix    Generate skeleton code (with annotations)   /devdocs-sync --trace
(AC → Test IDs)          (Entry + Test)                      │
                                                        ▼
                                                 Scan code annotations
                                                        │
                                                        ▼
                                                 Populate code location column
                                                        │
                                                        ▼
                                                 Update status column

测试用例格式

Test Case Format

单元测试用例

Unit Test Case

markdown
| 编号 | 验收标准 | 测试对象 | 场景 | 输入 | 预期输出 | 优先级 |
|------|----------|----------|------|------|----------|--------|
| UT-001 | AC-001 | validateEmail() | 有效邮箱 | "test@example.com" | true | P0 |
| UT-002 | AC-002 | validateEmail() | 无效格式 | "invalid" | false | P0 |
markdown
| ID | Acceptance Criterion | Test Object | Scenario | Input | Expected Output | Priority |
|----|----------------------|-------------|----------|-------|-----------------|----------|
| UT-001 | AC-001 | validateEmail() | Valid email | "test@example.com" | true | P0 |
| UT-002 | AC-002 | validateEmail() | Invalid format | "invalid" | false | P0 |

集成测试用例

Integration Test Case

markdown
| 编号 | 验收标准 | 测试场景 | 涉及组件 | 预期结果 | 优先级 |
|------|----------|----------|----------|----------|--------|
| IT-001 | AC-004 | 密码加密存储 | UserService + DB | 密码以 bcrypt 格式存储 | P0 |
markdown
| ID | Acceptance Criterion | Test Scenario | Involved Components | Expected Result | Priority |
|----|----------------------|---------------|---------------------|-----------------|----------|
| IT-001 | AC-004 | Password encrypted storage | UserService + DB | Password stored in bcrypt format | P0 |

E2E 测试用例

E2E Test Case

markdown
| 编号 | 用户故事 | 验收标准 | 操作步骤 | 预期结果 | 优先级 |
|------|----------|----------|----------|----------|--------|
| E2E-001 | US-001 | AC-001~AC-003 | 1. 打开注册页<br>2. 输入邮箱密码<br>3. 点击注册 | 注册成功，收到验证邮件 | P0 |
markdown
| ID | User Story | Acceptance Criterion | Operation Steps | Expected Result | Priority |
|----|------------|----------------------|-----------------|-----------------|----------|
| E2E-001 | US-001 | AC-001~AC-003 | 1. Open registration page<br>2. Enter email and password<br>3. Click register | Registration successful, verification email received | P0 |

覆盖率要求

Coverage Requirements

测试类型覆盖目标覆盖要求
单元测试核心业务逻辑行覆盖率 ≥ 80%，分支覆盖率 ≥ 80%
集成测试组件协作场景每个功能点至少 1 个 IT
E2E 测试用户故事每个 P0 用户故事至少 1 个 E2E
Test TypeCoverage TargetCoverage Requirement
Unit TestCore business logicLine coverage ≥ 80%, branch coverage ≥ 80%
Integration TestComponent collaboration scenariosAt least 1 IT per feature point
E2E TestUser storiesAt least 1 E2E per P0 user story

约束

Constraints

追溯约束

Traceability Constraints

  • 每个验收标准至少有 1 个测试用例覆盖
  • 必须生成追溯矩阵
  • 追溯矩阵必须覆盖所有 AC
  • Each acceptance criterion must be covered by at least 1 test case
  • Must generate a traceability matrix
  • The traceability matrix must cover all ACs

用例设计约束

Test Case Design Constraints

  • 测试用例必须关联验收标准编号
  • 每个用例必须有明确的预期结果
  • 优先级必须标注 (P0/P1/P2)
  • Test cases must be associated with acceptance criterion IDs
  • Each test case must have a clear expected result
  • Priority must be marked (P0/P1/P2)

覆盖约束

Coverage Constraints

  • P0 验收标准必须 100% 测试覆盖
  • P0 用户故事必须有 E2E 测试
  • 单元测试行覆盖率目标 ≥ 80%
  • 100% test coverage must be achieved for P0 acceptance criteria
  • P0 user stories must have E2E tests
  • Unit test line coverage target ≥ 80%

质量约束（参考 
/testing-guide
）

Quality Constraints (Refer to 
/testing-guide
)

  • 测试名称必须描述预期行为
  • 禁止弱断言（toBeDefined, toBeTruthy 不能作为唯一断言）
  • Mock 只用于外部依赖
  • Test names must describe expected behavior
  • Weak assertions are prohibited (toBeDefined, toBeTruthy cannot be used as the only assertion)
  • Mocks are only used for external dependencies

Skill 协作

Skill Collaboration

场景协作 Skill说明
需求输入
/devdocs-requirements
前置：提供 F/US/AC 作为测试设计依据
新功能测试
/devdocs-feature
被调用：新功能需要新增测试用例
Bug 回归测试
/devdocs-bugfix
被调用：Bug 修复需要补充回归测试
改进测试
/devdocs-insights
被调用：改进建议可能需要测试覆盖
追溯更新
/devdocs-sync
协作：trace 模式更新追溯矩阵代码位置
测试质量
/testing-guide
协作：编写测试代码时的质量约束
任务拆分
/devdocs-dev-tasks
后续：测试用例转化为开发任务
ScenarioCollaborating SkillDescription
Requirement Input
/devdocs-requirements
Pre-requisite: Provide F/US/AC as the basis for test design
New Feature Testing
/devdocs-feature
Called: New features require additional test cases
Bug Regression Testing
/devdocs-bugfix
Called: Bug fixes require supplementary regression tests
Test Improvement
/devdocs-insights
Called: Improvement suggestions may require test coverage
Traceability Update
/devdocs-sync
Collaboration: Trace mode updates code locations in the traceability matrix
Test Quality
/testing-guide
Collaboration: Quality constraints when writing test code
Task Splitting
/devdocs-dev-tasks
Follow-up: Convert test cases into development tasks

下一步

Next Steps

完成后建议运行 
/devdocs-dev-tasks
进行开发任务拆分。
After completion, it is recommended to run 
/devdocs-dev-tasks
for development task splitting.