# 单元测试规范

**文档版本**: 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): 初始化模板