life-echo/.cursor/rules/backend-testing-strategy.mdc

---
description: Backend testing strategy for meaningful business coverage
globs: api/**/*
alwaysApply: false
---

# Backend Testing Strategy

- 测试必须服务真实业务场景，禁止为了覆盖率、形式化 TDD 或“顺手测一下”而堆低价值用例。
- 自动化优先覆盖：核心用户流程、鉴权/权限/配额/幂等、关键状态写入后的持久化结果、前端依赖的稳定 HTTP 契约。
- 不优先覆盖：第三方库自身行为、纯实现细节、脆弱的调用顺序断言、低价值 getter/常量映射。
- 默认优先写 HTTP 场景测试，而不是先写大量细碎单元测试。

## Test Infrastructure

- 不要直接 import `api/main.py` 跑测试；避免把 `.env`、startup/shutdown、Redis、模型预热等副作用带进测试。
- 优先使用最小 `FastAPI()` 测试 app，按需挂载目标 router。
- 用 `app.dependency_overrides` 替换数据库和外部依赖。
- 用 `httpx.AsyncClient` + `ASGITransport` 进行异步 HTTP 测试。
- `api/tests/conftest.py` 和 `api/tests/factories.py` 只提供通用基础设施，不要把具体业务测试硬编码进去。

## HTTP 错误契约

- 失败响应断言 **`error_code` + `message`**（及可选 `request_id`），不要断言 FastAPI 旧格式 `{ detail }`。
- OpenAPI / router 级 smoke：参考 `tests/test_http_router_error_contract.py`、`tests/test_openapi_error_response.py`。
- Auth / payment / SMS 等 feature 码：断言具体 `error_code`（如 `INVALID_SMS_CODE`、`REFRESH_TOKEN_REUSE`），不只测 status code。

## 配置 / TOML 测试

- TOML 加载测试用 `CONFIG_DIR` 指向 fixture 目录，或 `reload_app_config()`；见 `tests/test_app_config_loader.py`。
- **不要**用 `os.environ["OTEL_ENABLED"]` 等已迁出 Settings 的 env 键驱动应用行为（运行时已读 TOML）。
- 新增 TOML 默认值时，若影响产品行为，更新 `tests/test_default_toml_legacy_parity.py` 或明确 overlay 意图。

## Test Layering

- HTTP 场景测试：注册、登录、刷新、登出、受保护资源访问、关键资源 CRUD、重要失败分支。
- 纯单元测试：纯函数、规则计算、序列化、适配器错误分支与格式转换。
- Service / 事务边界测试：仅当保护明确业务承诺（如 refresh rotation、SMS 回滚、幂等 ingest）且 HTTP 层难以稳定复现时允许；参考 `tests/test_auth_refresh_rotation.py`、`tests/test_db_transactional.py`。
- 手工 / E2E：WebSocket 多轮对话、真实短信、Celery + Redis + LLM 编排、支付/对象存储/ASR/图像生成联调。

## Decision Filter

新增测试前先问自己：

1. 这个测试保护的是哪条业务承诺？
2. 失败后能否快速定位问题边界？
3. 这个测试是否比只测内部函数更接近真实用户行为？

如果答不上来 2 个以上，通常不该立刻写这个测试。