wehub-resource-sync
195 lines
4.6 KiB
Markdown
195 lines
4.6 KiB
Markdown
# 测试规范与工作流
|
||
|
||
本文档用于指导 Yuxi 后续如何创建测试文件、修改测试文件，以及如何验证项目功能。目标是务实、稳定、可执行，不追求过度设计。
|
||
|
||
## 1. 测试分层
|
||
|
||
当前测试统一分为三层：
|
||
|
||
- `backend/test/unit`
|
||
- 纯单元测试
|
||
- 不依赖运行中的 Docker 服务
|
||
- 优先使用 `monkeypatch`、fake repo、stub、`tmp_path`
|
||
|
||
- `backend/test/integration`
|
||
- 真实 API 集成测试
|
||
- 依赖 `docker compose up -d` 后的运行环境
|
||
- 统一通过真实 HTTP 接口验证认证、权限、参数和副作用
|
||
|
||
- `backend/test/e2e`
|
||
- 关键链路端到端测试
|
||
- 覆盖 run、viewer、附件、文件落盘等完整流程
|
||
- 默认数量少、执行更慢
|
||
|
||
## 2. 新增测试时怎么选目录
|
||
|
||
新增测试前先判断：
|
||
|
||
1. 只测 Python 逻辑，不需要真实服务
|
||
放到 `unit`
|
||
|
||
2. 需要请求真实接口
|
||
放到 `integration/api`
|
||
|
||
3. 需要验证从入口到最终结果的完整链路
|
||
放到 `e2e`
|
||
|
||
不要再默认把测试直接丢到 `backend/test/` 根目录。
|
||
|
||
## 3. 文件和命名规范
|
||
|
||
文件名：
|
||
|
||
- 使用 `test_<domain>_<target>.py`
|
||
- 一个文件只测一个明确主题
|
||
|
||
函数名：
|
||
|
||
- 使用 `test_<行为>_<预期结果>`
|
||
- 名称直接表达业务语义
|
||
|
||
示例：
|
||
|
||
- `test_create_agent_run_commits_before_enqueue`
|
||
- `test_viewer_download_returns_attachment_response`
|
||
- `test_agent_bubble_sort_run_creates_expected_artifacts`
|
||
|
||
## 4. 写测试的基本要求
|
||
|
||
每个测试尽量保持三段式：
|
||
|
||
1. Arrange：准备数据、打桩、创建资源
|
||
2. Act：调用被测行为
|
||
3. Assert：断言结果
|
||
|
||
要求：
|
||
|
||
- 不要只断言 `status_code == 200`
|
||
- 要断言关键业务字段和副作用
|
||
- 失败信息要能帮助定位问题
|
||
|
||
## 5. fixture 规范
|
||
|
||
原则：
|
||
|
||
- 同一个文件内复用，优先写本地 helper
|
||
- 多个文件复用，再提取到对应层级的 `conftest.py`
|
||
- 根 `backend/test/conftest.py` 只保留通用 marker，不绑定真实环境
|
||
|
||
当前约定：
|
||
|
||
- `backend/test/integration/conftest.py`
|
||
- 管理 `test_client`、`admin_headers`、`standard_user`、`knowledge_database`
|
||
|
||
- `backend/test/e2e/conftest.py`
|
||
- 管理 `e2e_client`、`e2e_headers`、`e2e_agent_context`
|
||
|
||
## 6. 允许与禁止
|
||
|
||
允许：
|
||
|
||
- 在单元测试里使用 `monkeypatch`
|
||
- 在集成测试里通过 fixture 创建测试资源
|
||
- 在 E2E 中使用轮询等待最终状态
|
||
|
||
禁止：
|
||
|
||
- 在测试文件里硬编码真实账号密码
|
||
- 在单元测试里请求真实 HTTP 服务
|
||
- 在根 `conftest.py` 里继续添加重环境依赖
|
||
- 写 `if __name__ == "__main__":` 作为测试入口
|
||
- 用 `print` 作为通过/失败判断手段
|
||
- 因为系统里没有默认数据就直接 `skip`
|
||
|
||
## 7. skip 的使用规则
|
||
|
||
只在下面两类场景允许 `pytest.skip`：
|
||
|
||
1. 外部可选能力不可用
|
||
例如 OCR 服务、外部模型服务未启动
|
||
|
||
2. E2E 环境变量未配置
|
||
例如没有配置专用测试账号
|
||
|
||
不允许把“系统里没有 agent / config / 预置数据”当成正常 skip 条件。
|
||
这类情况应优先改为 fixture 显式准备资源，或者直接 fail 暴露环境问题。
|
||
|
||
## 8. 修改测试文件时的规则
|
||
|
||
如果是修 bug：
|
||
|
||
1. 先补一个能稳定复现 bug 的测试
|
||
2. 再修代码
|
||
3. 先跑最小相关测试集
|
||
4. 再跑相关层级回归
|
||
|
||
如果是改已有功能：
|
||
|
||
- 行为变了，就更新断言
|
||
- 文件职责混乱，就顺手拆分或迁移目录
|
||
- 依赖现成系统状态的测试，优先改成 fixture 建资源
|
||
|
||
## 9. 运行方式
|
||
|
||
启动环境：
|
||
|
||
```bash
|
||
docker compose up -d
|
||
docker ps
|
||
docker logs api-dev --tail 100
|
||
```
|
||
|
||
运行单元测试：
|
||
|
||
```bash
|
||
docker compose exec api uv run --group test pytest test/unit -m "not slow"
|
||
```
|
||
|
||
运行集成测试：
|
||
|
||
```bash
|
||
docker compose exec api uv run --group test pytest test/integration
|
||
```
|
||
|
||
运行 E2E：
|
||
|
||
```bash
|
||
docker compose exec api uv run --group test pytest test/e2e -m e2e
|
||
```
|
||
|
||
运行全部测试：
|
||
|
||
```bash
|
||
docker compose exec api uv run --group test pytest test
|
||
```
|
||
|
||
也可以使用：
|
||
|
||
```bash
|
||
backend/test/run_tests.sh unit
|
||
backend/test/run_tests.sh integration
|
||
backend/test/run_tests.sh e2e
|
||
backend/test/run_tests.sh all
|
||
```
|
||
|
||
## 10. 推荐的日常开发流程
|
||
|
||
建议顺序：
|
||
|
||
1. 本地改代码
|
||
2. 先跑相关单元测试
|
||
3. 涉及接口时跑相关集成测试
|
||
4. 涉及关键主链路时补跑对应 E2E
|
||
5. 提交前至少完成“检查 -> 测试 -> Lint”
|
||
|
||
## 11. 当前落地原则
|
||
|
||
这套规范的重点不是一步到位重写所有旧测试，而是：
|
||
|
||
- 新增测试必须按新目录落位
|
||
- 改到旧测试时顺手迁移
|
||
- 优先保持测试可执行和可信
|
||
- 优先减少假绿和环境耦合
|
||
|
||
对当前 Yuxi 来说，这就是最务实、也最容易持续执行的测试标准。
|