5.9 KiB

Raw Blame History

测试规范文档更新：Fixtures 使用指南

日期：2026-01-30
类型：文档更新
影响范围：测试规范文档

变更概述

更新 testing.md 文档，添加常用 fixtures 使用指南和最佳实践，解决测试中反复遇到的常见问题。

变更动机

在实施文件存储服务测试套件时，遇到了多个与 fixtures 使用相关的问题：

Fixture 名称错误：使用 client 而非 async_client
认证 fixture 使用不明确：不知道如何使用 test_auth、test_user_token
API 响应格式处理错误：假设所有 API 都使用统一响应格式
字段名称错误：使用 current_user.id 而非 current_user.user_id
未认证测试断言错误：断言 401 而非 403

这些问题在测试中反复出现，需要文档化以避免未来重复遇到。

新增内容

1. 常用 Fixtures 使用指南

添加了详细的 fixtures 使用说明，包括：

数据库相关 Fixtures

engine - 数据库引擎
db_session - 数据库会话

HTTP 客户端 Fixtures

async_client - HTTP 客户端（推荐）
⚠️ 不要使用 client（已废弃）

认证相关 Fixtures

test_auth - 完整认证信息（推荐）
- 返回：{"access_token": str, "user_id": str, "user": dict}
test_user_token - JWT Token（便捷）
test_user_id - 用户 ID（便捷）

其他 Fixtures

redis_client - Redis 客户端
api_prefix - API 前缀

每个 fixture 都包含：

定义和签名
使用场景
代码示例
重要提示

2. 集成测试认证模式

添加了三种标准认证模式：

模式 1：使用 `test_user_token`（最常用）

@pytest.mark.asyncio
async def test_api(async_client: AsyncClient, test_user_token: str):
    headers = {"Authorization": f"Bearer {test_user_token}"}
    response = await async_client.get("/api/v1/endpoint", headers=headers)

模式 2：使用 `test_auth`（需要用户信息）

@pytest.mark.asyncio
async def test_api(async_client: AsyncClient, test_auth: dict):
    headers = {"Authorization": f"Bearer {test_auth['access_token']}"}
    user_id = test_auth['user_id']

模式 3：测试未认证场景

@pytest.mark.asyncio
async def test_api_without_auth(async_client: AsyncClient):
    response = await async_client.get("/api/v1/endpoint")
    assert response.status_code == 403  # FastAPI 返回 403，而非 401

3. API 响应格式处理

说明了两种 API 响应格式：

统一响应格式（大多数 API）

{
    "code": 200,
    "message": "success",
    "data": {...}
}

直接返回数据（部分 API）

{
    "file_url": "...",
    "checksum": "..."
}

提供了判断方法和处理示例。

4. 常见字段名称规范

强调了 User 模型的主键字段是 user_id，而非 id：

模型	主键字段
User	`user_id`
Project	`project_id`
Folder	`folder_id`
Storyboard	`storyboard_id`
AIJob	`job_id`
FileChecksum	`checksum_id`

5. 更新常见问题与解决方案

添加了 5 个新的常见问题：

Fixture 名称错误：使用 client 而非 async_client
认证 Fixture 使用错误：不知道如何获取认证信息
API 响应格式断言错误：KeyError: 'data'
User 模型字段名称错误：AttributeError: 'User' object has no attribute 'id'
未认证测试断言错误：断言 401 而非 403

6. 测试覆盖率要求

添加了测试覆盖率目标和最佳实践：

单元测试：核心业务逻辑覆盖率 ≥ 80%
集成测试：API 端点覆盖率 ≥ 70%
关键路径：支付、积分、认证等核心功能覆盖率 100%

7. 测试最佳实践总结

添加了快速参考指南，包括：

Fixture 使用推荐和避免事项
认证测试推荐模式
响应格式处理推荐方式
字段名称规范

文档结构优化

在文档开头添加了目录，方便快速导航：

## 目录

- [测试金字塔](#测试金字塔)
- [测试目录结构](#测试目录结构)
- [常用 Fixtures 使用指南](#常用-fixtures-使用指南)
- [集成测试认证模式](#集成测试认证模式)
- [API 响应格式处理](#api-响应格式处理)
- [常见字段名称规范](#常见字段名称规范)
- [测试类型](#测试类型)
- [测试覆盖率要求](#测试覆盖率要求)

影响范围

文档更新

✅ .claude/skills/jointo-tech-stack/references/testing.md

受益场景

新开发者快速了解测试 fixtures 使用方式
避免重复遇到常见的 fixture 使用错误
统一团队的测试编写规范
提高测试代码质量和可维护性

验证方式

文档可读性：
- 章节结构清晰
- 代码示例完整
- 说明简洁明了
内容准确性：
- 所有 fixture 定义与 conftest.py 一致
- 代码示例可直接使用
- 常见问题解决方案经过验证
实用性：
- 覆盖了文件存储服务测试中遇到的所有问题
- 提供了快速参考指南
- 包含了最佳实践建议

后续优化

持续更新：
- 遇到新的常见问题时及时添加到文档
- 根据团队反馈优化说明和示例
示例扩展：
- 添加更多复杂场景的测试示例
- 提供完整的测试套件模板
工具支持：
- 考虑创建测试代码生成工具
- 提供 fixture 使用的 IDE 提示

参考资源

文件存储服务测试套件实现：server/tests/integration/test_file_storage_api.py
Fixtures 定义：server/tests/conftest.py
测试规范文档：.claude/skills/jointo-tech-stack/references/testing.md

总结：通过系统化地文档化常用 fixtures 的使用方式和常见问题，显著提升了测试开发效率，减少了重复性错误，为团队提供了统一的测试编写规范。

5.9 KiB Raw Blame History