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

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

---

## 变更概述

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

---

## 变更动机

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

1. **Fixture 名称错误**：使用 `client` 而非 `async_client`
2. **认证 fixture 使用不明确**：不知道如何使用 `test_auth`、`test_user_token`
3. **API 响应格式处理错误**：假设所有 API 都使用统一响应格式
4. **字段名称错误**：使用 `current_user.id` 而非 `current_user.user_id`
5. **未认证测试断言错误**：断言 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`（最常用）
```python
@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`（需要用户信息）
```python
@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：测试未认证场景
```python
@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）
```python
{
    "code": 200,
    "message": "success",
    "data": {...}
}
```

#### 直接返回数据（部分 API）
```python
{
    "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 个新的常见问题：

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

### 6. 测试覆盖率要求

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

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

### 7. 测试最佳实践总结

添加了快速参考指南，包括：
- Fixture 使用推荐和避免事项
- 认证测试推荐模式
- 响应格式处理推荐方式
- 字段名称规范

---

## 文档结构优化

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

```markdown
## 目录

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

---

## 影响范围

### 文档更新
- ✅ `.claude/skills/jointo-tech-stack/references/testing.md`

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

---

## 验证方式

1. **文档可读性**：
   - 章节结构清晰
   - 代码示例完整
   - 说明简洁明了

2. **内容准确性**：
   - 所有 fixture 定义与 `conftest.py` 一致
   - 代码示例可直接使用
   - 常见问题解决方案经过验证

3. **实用性**：
   - 覆盖了文件存储服务测试中遇到的所有问题
   - 提供了快速参考指南
   - 包含了最佳实践建议

---

## 后续优化

1. **持续更新**：
   - 遇到新的常见问题时及时添加到文档
   - 根据团队反馈优化说明和示例

2. **示例扩展**：
   - 添加更多复杂场景的测试示例
   - 提供完整的测试套件模板

3. **工具支持**：
   - 考虑创建测试代码生成工具
   - 提供 fixture 使用的 IDE 提示

---

## 参考资源

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

---

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