docs/v1.0/server/changelogs/2026-01-28-testing-standards-enhancement.md

测试规范文档重大更新

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

更新概述

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

新增内容

1. 扩展测试标记系统

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

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

使用场景：

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

运行特定标记：

# 仅运行外部服务测试
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）：

# 排除慢速和外部服务测试
docker exec jointo-server-app pytest -m "not slow and not external"

完整测试（发布前）：

# 运行所有测试
docker exec jointo-server-app pytest

外部服务测试（定期运行）：

# 仅运行外部服务测试
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 共享数据

示例代码：

# ❌ 错误：测试之间相互依赖
@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. 第三方服务异常测试

   • 网络超时
   • 服务不可用
   • 返回错误响应

测试清单模板：

@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 测试代码质量

相关文档

• 测试规范文档
• pytest 官方文档
• pytest-asyncio 文档