chore: import upstream snapshot with attribution

docs/develop-guides/testing-guidelines.md

@@ -0,0 +1,194 @@
+# 测试规范与工作流
+
+本文档用于指导 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 来说，这就是最务实、也最容易持续执行的测试标准。