team/docs/测试-单元.md

单元测试规范

文档版本: 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. 测试执行命令

# 运行所有单元测试
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): 初始化模板