# 测试规范文档重大更新

**日期**: 2026-01-28  
**类型**: Documentation  
**影响范围**: 测试规范和最佳实践

## 更新概述

对测试规范文档进行了全面的增强和扩展，新增了多个关键章节，提供更完整的测试指导。

## 新增内容

### 1. 扩展测试标记系统

新增 `external` 标记，用于区分第三方服务集成测试：

```ini
markers =
    integration: HTTP API 集成测试
    unit: 单元测试（使用 Mock）
    external: 外部服务集成测试（第三方 SDK）
    slow: 慢速测试
```

**使用场景**：
- `integration` - HTTP API 端到端测试
- `unit` - 单元测试（Mock 外部依赖）
- `external` - 第三方服务测试（阿里云短信、微信登录等）
- `slow` - 运行时间超过 1 秒的测试

**运行特定标记**：
```bash
# 仅运行外部服务测试
docker exec jointo-server-app pytest -m external

# 排除外部服务测试（加快 CI/CD）
docker exec jointo-server-app pytest -m "not external"
```

### 1.1 标记组合策略 ⭐ 新增

提供了详细的标记组合使用策略：

**快速反馈（CI/CD Pull Request）**：
```bash
# 排除慢速和外部服务测试
docker exec jointo-server-app pytest -m "not slow and not external"
```

**完整测试（发布前）**：
```bash
# 运行所有测试
docker exec jointo-server-app pytest
```

**外部服务测试（定期运行）**：
```bash
# 仅运行外部服务测试
docker exec jointo-server-app pytest -m external
```

### 1.2 CI/CD 配置示例 ⭐ 新增

提供了完整的 CI/CD 配置示例：

**GitHub Actions 示例**：
- 快速测试（PR 触发）- 排除 slow 和 external
- 完整测试（push 到主分支）- 运行所有测试
- 外部服务测试（定时任务）- 仅运行 external 标记

**GitLab CI 示例**：
- 快速测试（每次提交）
- 完整测试（主分支）
- 外部服务测试（定时任务）

**CI/CD 分层策略表**：

| 阶段 | 触发条件 | 运行测试 | 目标 |
|------|---------|---------|------|
| PR 检查 | Pull Request | `not slow and not external` | 快速反馈（< 2 分钟） |
| 主分支 | Push to main/develop | 所有测试 | 完整验证（< 10 分钟） |
| 定时任务 | 每日/每周 | `external` 或 `slow` | 验证外部依赖 |
| 发布前 | 手动触发 | 所有测试 + 覆盖率报告 | 质量保证 |

### 1.3 标记使用最佳实践 ⭐ 新增

- 合理标记测试的示例
- 本地开发建议
- 标记命名规范
- 避免的反模式

### 2. 测试隔离原则

明确了测试隔离的重要性，并提供了详细的示例：

**关键原则**：
- ✅ 每个测试使用独立的事务，测试结束后自动回滚
- ✅ 不依赖其他测试生成的数据
- ✅ 不修改全局状态
- ❌ 不要使用 session 或 module 级别的 fixture 共享数据

**示例代码**：
```python
# ❌ 错误：测试之间相互依赖
@pytest.mark.asyncio
async def test_create_user(db_session):
    user = User(username="test_user")
    db_session.add(user)
    await db_session.commit()
    # 数据会被回滚，下一个测试无法访问

# ✅ 正确：每个测试独立创建数据
@pytest.mark.asyncio
async def test_create_user(db_session):
    user = User(username="test_user")
    db_session.add(user)
    await db_session.commit()
    
    # 在同一个测试中验证
    result = await db_session.get(User, user.user_id)
    assert result is not None
```

### 3. 测试覆盖率原则

新增测试覆盖率指导，强调质量优于数量：

**推荐目标**：
- ✅ 核心业务流程 100% 覆盖
- ✅ 关键业务逻辑 100% 覆盖
- ✅ API 端点覆盖率 > 80%
- ⚠️ 代码覆盖率 > 70%（参考指标，不是硬性要求）

**不追求覆盖率的场景**：
- ❌ 简单的 CRUD 操作（集成测试已覆盖）
- ❌ 数据模型定义（SQLModel 自动验证）
- ❌ 配置文件、常量定义
- ❌ 第三方库的封装（除非有复杂逻辑）

### 4. Mock vs 真实调用决策指南

新增详细的决策指南，帮助开发者选择合适的测试方式：

**何时使用 Mock**：
- ✅ 单元测试中隔离外部依赖
- ✅ 第三方服务不稳定或有调用限制
- ✅ 测试异常情况（如网络超时、服务错误）
- ✅ 需要快速反馈的 CI/CD 流程
- ✅ 测试成本高（如付费 API）

**何时使用真实调用**：
- ✅ 集成测试验证端到端流程
- ✅ 验证与第三方服务的集成正确性
- ✅ 测试环境有测试账号或沙箱环境
- ✅ 关键业务流程的冒烟测试

**决策流程图**：
```
是否是单元测试？
├─ 是 → 使用 Mock
└─ 否 → 是否有测试环境/沙箱？
    ├─ 是 → 使用真实调用
    └─ 否 → 是否关键业务流程？
        ├─ 是 → 使用真实调用（定期运行）
        └─ 否 → 使用 Mock
```

### 5. 异常与边界测试清单

新增完整的测试场景清单，确保测试完整性：

**每个 API 端点应该测试的场景**：

1. **正常流程测试**
   - 有效的输入参数
   - 正确的响应格式
   - 业务逻辑正确执行

2. **参数验证测试**
   - 缺失必填参数
   - 参数类型错误
   - 参数格式错误
   - 参数边界值（最小值、最大值）

3. **认证与权限测试**
   - 未登录访问受保护资源
   - 无效的 token
   - 过期的 token
   - 权限不足

4. **业务逻辑异常测试**
   - 资源不存在
   - 重复创建
   - 业务规则违反
   - 余额不足、库存不足等

5. **第三方服务异常测试**
   - 网络超时
   - 服务不可用
   - 返回错误响应

**测试清单模板**：
```python
@pytest.mark.integration
class TestUserAPI:
    """用户 API 测试"""
    
    # 1. 正常流程
    async def test_create_user_success(self): pass
    
    # 2. 参数验证
    async def test_create_user_missing_params(self): pass
    async def test_create_user_invalid_email(self): pass
    
    # 3. 认证与权限
    async def test_get_user_without_token(self): pass
    async def test_get_user_with_invalid_token(self): pass
    
    # 4. 业务逻辑异常
    async def test_get_nonexistent_user(self): pass
    async def test_create_duplicate_user(self): pass
    
    # 5. 边界情况
    async def test_username_max_length(self): pass
```

### 6. 测试代码最佳实践

新增完整的测试代码最佳实践章节：

1. **提取测试常量** - 避免硬编码，统一管理测试数据
2. **封装重复的断言逻辑** - 遵循 DRY 原则
3. **安全的 JSON 解析** - 避免测试因解析错误而崩溃
4. **使用 Fixture 提供共享资源** - 减少重复代码
5. **辅助函数 vs Fixture** - 明确何时使用哪种方式
6. **完整示例** - 结合所有最佳实践的实际代码
7. **测试数据管理** - 提及 Factory 模式作为未来扩展方向

## 修改文件

- `.claude/skills/jointo-tech-stack/references/testing.md` - 测试规范文档
- `server/pytest.ini` - 添加 `external` 标记

## 文档结构

更新后的测试规范文档包含以下章节：

1. 测试金字塔
2. 测试目录结构
3. 测试类型（集成测试、单元测试）
4. 测试策略
   - 测试覆盖原则 ⭐ 新增
   - 测试覆盖率目标 ⭐ 新增
   - Mock vs 真实调用决策指南 ⭐ 新增
   - 异常与边界测试清单 ⭐ 新增
5. 测试命名规范
6. 运行测试
7. 测试标记（扩展了 `external` 标记）
8. 共享 Fixtures（新增测试隔离原则）
9. 测试环境
10. 最佳实践
11. 测试代码最佳实践 ⭐ 新增
12. 常见问题与解决方案
13. 故障排查
14. 持续集成
15. 相关文档

## 价值

这次更新将帮助团队：

1. **更清晰的测试分类** - 通过 `external` 标记区分第三方服务测试
2. **更完整的测试覆盖** - 提供异常与边界测试清单
3. **更好的决策指导** - Mock vs 真实调用的明确指导
4. **更高的代码质量** - 测试代码最佳实践
5. **更强的测试隔离** - 明确的测试隔离原则
6. **更合理的覆盖率目标** - 强调质量而非数字

## 后续计划

1. 根据实际使用情况，持续优化测试规范
2. 考虑引入 Factory 模式（pytest-factoryboy）管理复杂测试数据
3. 建立测试覆盖率监控和报告机制
4. 定期 review 测试代码质量

## 相关文档

- [测试规范文档](.claude/skills/jointo-tech-stack/references/testing.md)
- [pytest 官方文档](https://docs.pytest.org/)
- [pytest-asyncio 文档](https://pytest-asyncio.readthedocs.io/)