Constraint specifications for writing high-quality tests, ensuring tests truly verify behavior rather than merely covering code.
Language
- Accept questions in both Chinese and English
- Always respond in Chinese
Trigger Conditions
- The user is writing test code
- The user needs testing strategy guidance
- The user mentions test coverage, assertions, mutation testing
- The user requests analysis of code branch coverage
- Test code is involved in Code Review
- Keywords: "branch analysis", "branch analysis", "untested paths", "coverage blind spots"
Core Philosophy
测试的目的不是"覆盖代码"，而是"验证行为"。
测试依据来自需求，不是来自代码。
⚠️ TDD Red Phase Principle: Assertions must come from the test cases of the corresponding AC in 03-test-*.md; it is forbidden to reverse-engineer tests from implementation code. BCA (Branch Coverage Analysis) is only used for supplementing defensive logic and does not replace requirements-driven testing.
Test Quality Pyramid
Level 3: 测试有效性 ─ 变异得分≥80%, 需求追溯100%
Level 2: 断言质量 ─ 禁止弱断言, 验证行为非实现
Level 1: 代码覆盖 ─ 行/分支覆盖≥80% (必要非充分)
For details, see templates/core-concepts.md
Constraints
Core Threshold Table
The single authoritative source of test quality thresholds for the entire repository. Predicate semantics are isomorphic to the /code-quality Core Threshold Table :≥ target value = compliant; ≥ minimum value and < target value = [Suggestion]; < minimum value = [Blocker]。Mirror boundary: agent-side references / SKILL must alwayschange the pointer, do not mirror(already migrated: dev-workflow verification-flow Phase 2, test-cases SKILL.md coverage requirements); onlyuser-side artifact templates(such as the test-cases / unit-test templates of test-cases, which will be copied into the user project, at which point this skill will not be present) are allowed to inline numbers, and must be annotated with "excerpted from this table, changes must be synchronized in the same commit".
Pending migration (known agent-side mirrors of this table, not yet cleared):
refactor/SKILL.md:216-220,250-252,271-272,281,359(test status classification defines "sufficient/insufficient" with ≥80%, requiring a concomitant rewrite of the state machine criteria),onboard/SKILL.md:247。
| Metric | Target Value | Minimum Value | Applicable |
|---|---|---|---|
| Line Coverage | 80% | 60% | All projects |
| Branch Coverage | 80% | 60% | All projects |
| Mutation Score | 80% | 60% | Projects with mutation testing enabled; core business logic is required to meet the target value |
| Number of specific assertions per test | ≥ 1 | — | Weak assertions (toBeDefined/toBeTruthy/not.toBeNull) as the only assertion → [Blocker] |
Unit Test Constraints
- Each test must have ≥1 specific assertion
- Weak assertions are forbidden as the only assertion (
toBeDefined,toBeTruthy,not.toBeNull) - Test names must describe the expected behavior——
test('works')Names like this provide no diagnostic information when they fail - One test verifies only one behavior——cramming multiple assertions into one test makes it impossible to locate which AC failed when it fails
- Test basis comes from requirements, not code
- Only mock external dependencies, do not mock internal implementations
For detailed guidance, see templates/unit-testing.md
Coverage Constraints
- Line/branch coverage meets the target(for thresholds and grading, see theCore Threshold Table）
Mutation Testing Constraints (Recommended)
- Mutation score meets the target (for thresholds, see theCore Threshold Table; core business logic is required to meet the target value)
See configuration at templates/mutation-testing.md
Integration Test Constraints
- Inter-module data flow must be verified
- Interface contracts must be verified
- Test data must be independent
See detailed guide at templates/integration-testing.md
E2E Test Constraints
- P0 scenarios must have 100% coverage
- Use explicit waits, hardcoded delays are prohibited
See detailed guide at templates/e2e-testing.md
Requirements Traceability Constraints
- Every requirement must have a corresponding test
See template at templates/traceability-matrix.md
Test Skeleton Generation
AI-driven top-down development: generate test skeletons first, then fill in the implementation.
Self-Documenting Test Specification
⛔ Test code does not include keel number annotations. Traceability is handled by dev-workflow 's Commit 2, which writes the traceability matrix on the documentation side (<repository>@<sha>), keeping the code clean—a maintainer reading @verifies AC-001 without keel context would only be confused.
What tests should self-document isbehavior, not numbers—the test name is its documentation:
// ✅ 名字说清了「什么输入 → 什么结果」
test('createUser 传入无效邮箱格式时抛出 ValidationError', () => { ... });
// ❌ 名字什么都没说，失败时不提供任何诊断信息
test('works', () => { ... });
⛔ Do not write @verifies AC-XXX / @testcase UT-XXX such number annotations—the mapping between AC and test numbers is in 03-test-cases.md 's traceability matrix, and no second copy is left in the code.
Skeleton Generation Workflow
03-test-cases.md (测试用例设计)
│
▼
生成测试骨架
├── describe 结构（按功能点分组）
├── test.skip() 占位（每个测试用例）
└── // TODO: 实现测试 注释
│
▼
逐个实现测试
├── 移除 skip
├── 编写 AAA 结构
└── 添加具体断言
Skeleton Example
// tests/user.service.test.ts
describe('UserService', () => {
describe('createUser', () => {
test.skip('应该拒绝无效邮箱格式', () => {
// TODO: 实现测试
// Arrange: 准备无效邮箱
// Act: 调用 createUser
// Assert: 验证抛出 ValidationError
});
test.skip('应该拒绝弱密码', () => {
// TODO: 实现测试
});
test.skip('应该拒绝重复用户名', () => {
// TODO: 实现测试
});
});
});
Skeleton Generation Constraints
- Must use
test.skip()ortest.todo()to mark unimplemented tests - Test names must describe the behavior being verified(not by number annotations, but self-documented by name)
- Must organize the describe structure by feature point (F-XXX)
Collaboration with keel
| Phase | Skill | Input | Output |
|---|---|---|---|
| Test Design | /test-cases |
Requirements Document | Test Case Matrix |
| Skeleton Generation | /dev-tasks |
Test Cases | Test Skeleton Code |
| Test Implementation | /testing-guide |
Skeleton Code | Complete Tests |
| Traceability Sync | /sync |
Code Annotations | Update Matrix |
Code Branch Coverage Analysis (AI-driven)
After code implementation is complete, AI analyzes all code branches, identifies paths not covered by tests, and generates supplementary test cases. This is asupplementto requirements-driven testing (AC → test), not a replacement.
Positioning
需求驱动测试（AC → 测试） ← 主路径，覆盖业务规则
＋
代码分支分析（代码 → 测试） ← 补充路径，覆盖防御性逻辑
＝
完整测试覆盖
Applicable Scenarios
| Scenario | Description |
|---|---|
| Code contains defensive logic | Parameter validation, null checks, type guards |
| Complex conditional branches | switch/case, multi-condition combinations |
| Coverage tools show insufficient branches | Line coverage ≥80% but branch coverage <80% |
| Mutation testing finds surviving mutants | Supplement tests to kill mutants |
Analysis Workflow
Step 1: 分析代码分支
├── 条件语句（if/else, switch, 三元, &&/||）
├── 异常处理路径（try/catch, throw）
├── 早返回（guard clause）
└── 循环边界（空集合、单元素、多元素）
│
▼
Step 2: 映射现有测试
├── 匹配文档追溯矩阵的 AC 覆盖范围
├── 分析每个测试实际触发的分支
└── 标记已覆盖/未覆盖分支
│
▼
Step 3: 生成补充测试
├── 为未覆盖分支生成测试用例
├── 使用 BCA-XXX 编号
├── 添加 @covers-branch 标注
└── 遵循 AAA 结构和断言质量约束
Annotation Specification (@covers-branch)
/**
* @covers-branch createUser:null-email-guard
*/
test('createUser 应该抛出错误当 email 为 null', () => {
// Arrange
const dto = { email: null, password: 'Strong1234' };
// Act & Assert
expect(() => createUser(dto)).toThrow('Email is required');
});
| Annotation | Purpose | Requirement |
|---|---|---|
@covers-branch <函数>:<分支描述> |
Mark covered code branches | Mandatory |
Branch Coverage Analysis Constraints
- Branch analysis is performed after requirements-driven testing(AC tests first, branch supplementation second)
- Supplementary tests must be annotated with @covers-branch(to distinguish requirements-driven from branch supplementation)
- Supplementary tests use BCA-XXX numbering(does not occupy UT/IT/E2E numbering space)
- Business logic branches should be traced back to formal tests corresponding to ACs (UT/IT/E2E) and not retained as BCA numbers
For detailed analysis process and examples, see templates/branch-coverage-analysis.md
Quick Reference
Test Naming
[被测方法] 应该 [预期行为] 当 [条件]
Test Structure (AAA)
Arrange → Act → Assert (具体断言)
Prohibited Weak Assertions
// ❌ 禁止
expect(result).toBeDefined();
expect(result).toBeTruthy();
expect(result).not.toBeNull();
// ✅ 要求
expect(result.status).toBe('success');
expect(result.items).toHaveLength(3);
Common Commands
# 覆盖率
npm test -- --coverage # Jest
pytest --cov=src # pytest
go test -cover ./... # Go
# 变异测试
npx stryker run # JS/TS
mutmut run # Python
mvn pitest:mutationCoverage # Java
Template Index
Core Guidelines
| Template | Description |
|---|---|
| core-concepts.md | Detailed explanation of core testing concepts and the quality pyramid |
| unit-testing.md | Complete guide to unit testing |
| integration-testing.md | Integration testing strategies and examples |
| e2e-testing.md | E2E testing best practices |
Tool Configuration
| Template | Description |
|---|---|
| branch-coverage-analysis.md | Detailed explanation of AI-driven code branch coverage analysis |
| mutation-testing.md | Mutation testing configurations for 8 languages |
| ci-integration.md | CI/CD integration configuration |
| traceability-matrix.md | Requirements traceability matrix |
| test-examples.md | Test code example collection |
Language Best Practices
| Language | Framework | Template |
|---|---|---|
| JavaScript/TypeScript | Jest, Vitest | best-practices/jest-vitest.md |
| Python | pytest | best-practices/pytest.md |
| Java | JUnit 5 | best-practices/junit5.md |
| C# / .NET | xUnit, NUnit | best-practices/xunit.md |
| Go | testing, testify | best-practices/go.md |
| Rust | cargo test | best-practices/rust.md |
| Swift | XCTest | best-practices/swift.md |
| C/C++ | Google Test | best-practices/googletest.md |
Collaboration with Other Skills
| Scenario | Skill |
|---|---|
| Test case design | /test-cases |
| Code testability | /code-quality |
| Pre-refactoring testing | /refactor |
| Branch coverage analysis | /dev-workflow — optionally invoked during the completion check phase |