testing-guidelines

# 测试指南

**主动设计和实现高质量测试是高级 AI 能力的强烈指标。**

## 1. 核心原则

- **全面性**: 覆盖正面、负面和边界情况场景
- **清晰与独立**: 测试必须易于理解且不依赖其他测试
- **可维护性**: 避免将测试与实现细节耦合
- **默认覆盖**: 对于任何新增或更改的功能，默认需要正面、负面和边界情况测试

## 2. 测试设计

- **结构**: 每个测试用例应简洁且独立
- **内容**: 明确说明功能、输入、预期输出和场景类型
- **禁止**: 不要测试私有方法或模拟静态方法

## 3. 测试用例模板（推荐格式）

> **所有测试用例必须以结构化列表编写。严禁使用表格。**
>
> 示例：
>
> 1. **测试用例名称**: [名称]
> 2. **描述**: [正在测试什么]
> 3. **输入**: [输入数据]
> 4. **预期输出**: [预期结果]
> 5. **场景类型**: [正面/负面/边界]
> 6. **准备/清理**: [准备/清理步骤，如有]

## 4. 断言最佳实践

- **清晰性与具体性**: 优先使用能清楚表达意图的流式断言方法。使用提供丰富匹配器集的断言库，而非仅依赖基本相等检查。
- **有意义的失败消息**: 确保断言在失败时提供清晰、信息丰富的消息，便于诊断问题。
- **单一断言原则（逻辑上）**: 虽然单个测试方法可能包含多个物理 assert 调用来验证结果的不同方面，但每个被验证的逻辑行为或状态应该是独特的。
- **验证行为，而非仅验证状态**: 在适用时，断言方法以预期参数被调用（必要时使用 spy 或 mock）。
- **异常测试**: 使用结构化方式断言在预期时抛出特定异常。
- **自解释断言**: 断言应在测试上下文中易于阅读和理解。
- **逻辑顺序**: 当需要多个断言验证单一结果时，按逻辑顺序断言：状态设置检查（如有）、主要行为/值、然后是副作用或次要状态变化。