90 lines
2.4 KiB
Markdown
90 lines
2.4 KiB
Markdown
# 单元测试规范
|
|
|
|
**文档版本**: 1.0.0
|
|
**最后更新**: 2026-04-19
|
|
|
|
---
|
|
|
|
## 1. 概述
|
|
|
|
本文档定义项目各模块的单元测试规范和测试清单，确保代码质量和功能正确性。测试按模块组织，与系统架构中的模块划分一致。
|
|
|
|
### 1.1 覆盖率目标
|
|
|
|
| 模块类别 | 覆盖率目标 | 适用范围 |
|
|
|----------|-----------|----------|
|
|
| <!-- 核心模块 --> | ><!-- % --> | <!-- 范围 --> |
|
|
| <!-- 其他模块 --> | ><!-- % --> | <!-- 范围 --> |
|
|
|
|
### 1.2 测试框架和工具
|
|
|
|
| 工具 | 用途 |
|
|
|------|------|
|
|
| **pytest** | 测试框架 |
|
|
| **pytest-cov** | 覆盖率报告 |
|
|
| **pytest-asyncio** | 异步测试支持 |
|
|
| **pytest-mock / unittest.mock** | Mock 和 Patch |
|
|
| **faker** | 测试数据生成 |
|
|
| **freezegun** | 时间冻结（测试时间相关逻辑） |
|
|
|
|
### 1.3 测试文件组织结构
|
|
|
|
```
|
|
apps/<!-- 模块 -->/
|
|
├── src/<!-- 模块名 -->/
|
|
│ ├── services/
|
|
│ ├── api/
|
|
│ └── ...
|
|
└── tests/
|
|
├── conftest.py # 公共 fixtures
|
|
├── unit/
|
|
│ ├── services/
|
|
│ │ └── <!-- test_*.py -->
|
|
│ └── api/
|
|
│ └── <!-- test_*.py -->
|
|
└── integration/
|
|
└── ...
|
|
```
|
|
|
|
### 1.4 通用 Mock 策略
|
|
|
|
| 策略 | 说明 |
|
|
|------|------|
|
|
| **数据库隔离** | 每个测试用例使用独立的内存 SQLite 数据库（`file::memory:`），测试结束自动销毁 |
|
|
| **文件系统隔离** | 使用 `tmp_path` fixture 创建临时目录，测试结束自动清理 |
|
|
| **网络隔离** | Mock 所有外部 HTTP 请求，禁止真实网络调用 |
|
|
| **时间控制** | 使用 `freezegun` 冻结时间，确保时间相关测试可重复 |
|
|
|
|
---
|
|
|
|
## 2. 模块测试文档索引
|
|
|
|
<!-- 按模块拆分为独立文件后在此列出索引 -->
|
|
|
|
| 文件 | 内容 | 子模块数 | 测试函数数 |
|
|
|------|------|----------|------------|
|
|
| <!-- 测试文件 --> | <!-- 说明 --> | <!-- 数 --> | <!-- 数 --> |
|
|
|
|
---
|
|
|
|
## 3. 测试执行命令
|
|
|
|
```bash
|
|
# 运行所有单元测试
|
|
uv run pytest tests/unit/ -v
|
|
|
|
# 运行指定模块测试
|
|
uv run pytest tests/unit/services/<!-- test_module -->.py -v
|
|
|
|
# 生成覆盖率报告
|
|
uv run pytest tests/unit/ --cov=src --cov-report=html
|
|
|
|
# 仅运行 P1 优先级测试
|
|
uv run pytest tests/unit/ -v -k "p1"
|
|
```
|
|
|
|
---
|
|
|
|
**版本历史**:
|
|
- v1.0.0 (2026-04-19): 初始化模板
|