8.3 KiB

Raw Permalink Blame History

测试规范文档重大更新

日期: 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 端点应该测试的场景：

正常流程测试
- 有效的输入参数
- 正确的响应格式
- 业务逻辑正确执行
参数验证测试
- 缺失必填参数
- 参数类型错误
- 参数格式错误
- 参数边界值（最小值、最大值）
认证与权限测试
- 未登录访问受保护资源
- 无效的 token
- 过期的 token
- 权限不足
业务逻辑异常测试
- 资源不存在
- 重复创建
- 业务规则违反
- 余额不足、库存不足等
第三方服务异常测试
- 网络超时
- 服务不可用
- 返回错误响应

测试清单模板：

@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. 测试代码最佳实践

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

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

修改文件

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

文档结构

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

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

价值

这次更新将帮助团队：

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

后续计划

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

8.3 KiB Raw Permalink Blame History