# Backend Tests 测试指引

本文件适用于 backend/tests/ 下的测试和测试脚本。

## 测试入口

- pytest.ini 指定默认测试目录为 backend/tests，并设置后端覆盖率门槛为 90%。
- run_tests.py 提供 unit、integration、simulate、all 几种快捷入口。
- 默认优先使用 pytest 跑窄测试；只有在需要脚本封装参数时再用 run_tests.py。

## 测试分布

- test_main_endpoints.py：主 API 路由行为
- test_main_cancel.py：补全取消和任务生命周期
- test_prompt.py、test_prompt_extended.py：Prompt 上下文与规则
- test_llm.py、test_llm_extended.py：LLM 包装层
- test_geoip.py：GeoIP 逻辑
- test_tts_asr_*.py：TTS 相关与历史 TTS/ASR 面
- simulate_macos.py：历史模拟脚本
- quick_verify.py、verify_cross.py、play_audio.py：人工验证或辅助脚本

## 常用命令

- pytest
- pytest backend/tests/test_main_endpoints.py -v
- pytest backend/tests/test_main_cancel.py -v
- pytest backend/tests/test_prompt.py -v
- pytest backend/tests/test_llm.py -v
- python backend/tests/run_tests.py unit
- python backend/tests/run_tests.py integration --url http://localhost:8001 --key your-secret-key-here

## 测试原则

- 优先跑与改动直接对应的窄测试，不要动不动全量跑。
- 单元测试尽量 mock 掉外部依赖，不要直连真实 Ollama。
- 涉及 main.py 时，优先用 monkeypatch 或 fake 对象替代：
	- call_ollama
	- call_vlm_ocr
	- MarkItDown
	- GeoIP 查询
	- TTS 模型加载
- 测试要保持确定性，不依赖全局状态、环境顺序或人工输入。

## 容易误判的点

- 覆盖率门槛是针对多个 backend 模块一起算的，改核心文件时，即使单测通过也可能因为覆盖率不够失败。
- htmlcov、.pytest_cache、api_performance_report.md 属于生成产物，不是需要维护的源码。
- 这一目录里有一批 TTS/ASR 测试和说明明显继承自旧实现；当它们与当前 backend/tts_asr.py 冲突时，不要默认代码错了，先确认目标产品面。
- integration 脚本通常假设本地服务在 http://localhost:8001，且默认 API Key 还是占位值。

## 改动定位建议

- 路由返回值不对：先看 test_main_endpoints.py 和 test_main_cancel.py
- Prompt 规则不对：先看 test_prompt.py 和 test_prompt_extended.py
- Ollama 调用包装不对：先看 test_llm.py 和 test_llm_extended.py
- TTS 面变化：先确认当前 backend/tts_asr.py 是不是仍然以旧文档描述为目标，再决定修测试还是修实现

## 维护原则

- 新增后端行为时，优先给对应模块补测试，不要只依赖全量回归。
- 如果变更的是历史 TTS/ASR 面，先把“当前规范是什么”确定下来，再批量修测试。
- 如果覆盖率策略变化，记得同步这个文件，而不是只改 pytest.ini。