关于 python-testing-strategies
面向测试 FastAPI 类端点的开发者，提供编写和运行异步 Python 测试的速查指南，重点涵盖异步配置、端点覆盖和测试隔离。
主要功能
- 01pytest 异步配置
- 02使用 httpx AsyncClient 与 ASGITransport
- 03端点覆盖清单
- 04测试数据工厂建议
- 05常见异步测试陷阱
适用场景
- 01为 API 端点配置异步测试
- 02检查端点的成功与错误情形
- 03避免数据库状态在测试间泄漏
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/python-testing-strategies确认已加载。
附带文件examples.md
详细介绍
Python 测试策略 — 快速参考
设置（关键）
在 pyproject.toml 中设置 asyncio_mode = "auto"，以便自动检测异步测试，无需标记。（如果使用 @pytest.mark.asyncio 标记测试，默认的 "strict" 模式也可正常工作。）
完整的 conftest.py 和 pyproject.toml 设置请参阅 examples.md。
测试客户端
使用 httpx.AsyncClient + ASGITransport，异步测试中切勿使用 TestClient。
客户端 fixture 设置请参阅 examples.md。
每个端点所需的覆盖范围
- 正常流程（创建、读取、更新、删除）
- 未找到（404）
- 验证错误（422）
- 身份验证失败（401）——适用于受保护的端点
- 软删除——不返回已删除的记录
测试命名
async def test_create_item(): # Happy path
async def test_create_item_missing_name(): # Validation
async def test_get_item_not_found(): # 404
async def test_get_item_soft_deleted(): # Soft delete
测试数据工厂
使用默认值合理的简单工厂函数。只覆盖测试关注的部分。
工厂模式请参阅 examples.md。
运行测试
pytest # All tests
pytest tests/test_items.py # One file
pytest -k "test_create" # By name pattern
pytest --tb=short -q # Quiet output
注意事项
-
缺少
asyncio_mode = "auto"会导致所有内容悄无声息地出错。 测试看似通过（收集到 0 项），或无限期挂起。在编写任何异步测试之前，先将[tool.pytest.ini_options] asyncio_mode = "auto"添加到pyproject.toml。这是“我的测试无法运行”的头号原因。 -
TestClient和AsyncClient不能互换。TestClient（来自 Starlette）是同步的，会阻塞；AsyncClient（来自 httpx）是异步的，会使用事件循环。如果应用使用带有await的async def路由，就必须使用搭配ASGITransport的AsyncClient。使用TestClient可能会掩盖异步错误，因为它以同步方式运行。 -
没有正确清理时，数据库状态会在测试之间泄漏。 每个测试都需要一个干净的数据库。使用
autouse=Truefixture 来创建/删除表，或在测试之间清空数据。否则，测试顺序会影响结果，CI 中也会出现随机失败。 -
默认情况下，
response.json()返回的是 FastAPI 的 snake_case 格式。 如果 Pydantic 模型使用了alias_generator，JSON 键可能与 Python 字段名不同。断言时务必使用实际的 JSON 键，而非 Python 属性名。 -
在异步测试中忘记使用
await会导致令人困惑的错误。 如果测试输出中出现<coroutine object ...>，而不是实际数据，说明你漏写了await。每个client.get()、client.post()等调用都必须使用await。