ocean_project_manager/backend/tests/TEST_GUIDE.md

后端测试文档

1. 测试概述

1.1 测试目标

• 确保API接口功能正确
• 验证业务逻辑准确性
• 保证代码质量和稳定性
• 测试覆盖率达到80%以上

1.2 测试范围

• 单元测试：测试各个模块的独立功能
• 集成测试：测试API接口的端到端功能
• 性能测试：测试API响应时间（可选）

1.3 测试技术栈

技术	说明
测试框架	pytest
异步测试	pytest-asyncio
HTTP测试	httpx / TestClient
数据库测试	pytest-postgresql（可选）
覆盖率	pytest-cov
Mock	pytest-mock

1.4 测试目录结构

backend/tests/
├── __init__.py
├── conftest.py              # pytest配置和fixture
├── test_auth.py             # 认证模块测试
├── test_users.py            # 用户管理模块测试
├── test_projects.py         # 项目管理模块测试
├── test_statistics.py       # 统计功能测试
└── fixtures/                # 测试数据fixture
    ├── __init__.py
    └── test_data.py

2. 测试环境配置

2.1 依赖安装

pip install pytest pytest-asyncio pytest-cov pytest-mock httpx

2.2 测试配置文件 pytest.ini

[pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts =
    -v
    --strict-markers
    --cov=src
    --cov-report=term-missing
    --cov-report=html
asyncio_mode = auto
markers =
    unit: 单元测试
    integration: 集成测试
    slow: 慢速测试

2.3 环境变量

测试环境使用独立数据库配置：

TEST_DB_HOST=localhost
TEST_DB_NAME=project_manager_test
TEST_DB_USER=test_user
TEST_DB_PASSWORD=test_password

3. 测试策略

3.1 单元测试

• 测试各个Service层方法
• 测试工具函数
• 不涉及数据库和网络调用
• 使用Mock隔离外部依赖

3.2 集成测试

• 测试完整的API端点
• 使用测试数据库
• 验证请求/响应格式
• 测试权限控制

3.3 测试数据管理

• 使用pytest fixture创建测试数据
• 每个测试独立运行，互不影响
• 测试后清理数据

4. 测试用例设计

4.1 认证模块测试 (test_auth.py)

4.1.1 用户登录测试

测试用例	描述	预期结果
test_login_success	正确的用户名和密码	返回token和用户信息
test_login_wrong_username	错误的用户名	返回401错误
test_login_wrong_password	错误的密码	返回401错误
test_login_missing_fields	缺少必填字段	返回400错误

4.1.2 Token验证测试

测试用例	描述	预期结果
test_get_current_user_success	有效token	返回用户信息
test_get_current_user_invalid_token	无效token	返回401错误
test_get_current_user_expired_token	过期token	返回401错误
test_logout_success	有效token登出	返回成功

4.2 用户管理模块测试 (test_users.py)

4.2.1 创建用户测试

测试用例	描述	预期结果
test_create_user_admin_success	管理员创建用户	返回创建的用户
test_create_user_market_forbidden	非管理员创建用户	返回403错误
test_create_user_duplicate_username	重复的用户名	返回409错误
test_create_user_invalid_role	无效的角色	返回400错误

4.2.2 获取用户列表测试

测试用例	描述	预期结果
test_get_users_admin_success	管理员获取用户列表	返回用户列表
test_get_users_market_forbidden	非管理员获取用户列表	返回403错误
test_get_users_with_pagination	测试分页	返回正确的分页数据
test_get_users_with_filter	测试筛选	返回筛选后的数据

4.2.3 更新用户测试

测试用例	描述	预期结果
test_update_user_admin_success	管理员更新用户	返回更新后的用户
test_update_user_market_forbidden	非管理员更新用户	返回403错误
test_update_user_not_found	更新不存在的用户	返回404错误

4.2.4 删除用户测试

测试用例	描述	预期结果
test_delete_user_admin_success	管理员删除用户	返回成功
test_delete_user_market_forbidden	非管理员删除用户	返回403错误
test_delete_user_not_found	删除不存在的用户	返回404错误

4.2.5 重置密码测试

测试用例	描述	预期结果
test_reset_password_admin_success	管理员重置密码	返回成功
test_reset_password_market_forbidden	非管理员重置密码	返回403错误
test_reset_password_invalid_password	无效的密码格式	返回400错误

4.3 项目管理模块测试 (test_projects.py)

4.3.1 获取项目列表测试

测试用例	描述	预期结果
test_get_projects_all_users_success	所有用户获取项目列表	返回项目列表
test_get_projects_with_pagination	测试分页	返回正确的分页数据
test_get_projects_with_filters	测试组合筛选	返回筛选后的数据
test_get_projects_sort_by_contract_amount	按合同金额排序	返回排序后的数据

4.3.2 创建项目测试

测试用例	描述	预期结果
test_create_project_admin_success	管理员创建项目	返回创建的项目
test_create_project_market_success	市场部用户创建项目	返回创建的项目
test_create_project_other_forbidden	其他部门用户创建项目	返回403错误
test_create_project_duplicate_project_no	重复的项目编号	返回409错误
test_create_project_missing_required_fields	缺少必填字段	返回400错误

4.3.3 更新项目测试

测试用例	描述	预期结果
test_update_project_admin_success	管理员更新项目	返回更新后的项目
test_update_project_market_own_project	市场部更新自己的项目	返回更新后的项目
test_update_project_market_other_project	市场部更新其他人的项目	返回403错误
test_update_project_other_financial_info	其他部门更新财务信息	返回更新后的项目
test_update_project_other_basic_info	其他部门更新基础信息	返回403错误
test_update_project_not_found	更新不存在的项目	返回404错误

4.3.4 删除项目测试

测试用例	描述	预期结果
test_delete_project_admin_success	管理员删除项目	返回成功
test_delete_project_market_own_project	市场部删除自己的项目	返回成功
test_delete_project_market_other_project	市场部删除其他人的项目	返回403错误
test_delete_project_other_forbidden	其他部门删除项目	返回403错误
test_delete_project_not_found	删除不存在的项目	返回404错误

4.4 统计功能测试 (test_statistics.py)

4.4.1 基础统计测试

测试用例	描述	预期结果
test_get_statistics_all_users_success	所有用户获取统计	返回统计数据
test_get_statistics_with_filters	测试筛选条件	返回筛选后的统计
test_get_statistics_empty_data	无数据时统计	返回零值统计

4.4.2 分组统计测试

测试用例	描述	预期结果
test_get_group_statistics_by_engineering_type	按工程类别分组	返回分组统计
test_get_group_statistics_by_department	按项目部分组	返回分组统计
test_get_group_statistics_with_date_filter	带日期筛选的分组统计	返回分组统计

4.4.3 时间维度统计测试

测试用例	描述	预期结果
test_get_timeline_statistics_by_month	按月统计	返回时间维度统计
test_get_timeline_statistics_by_year	按年统计	返回时间维度统计
test_get_timeline_statistics_with_filter	带筛选的时间统计	返回时间维度统计

5. 测试Fixture

5.1 数据库Fixture

@pytest.fixture
async def db_session():
    # 创建测试数据库会话
    # 测试结束后回滚
    yield session
    # 清理数据

5.2 用户Fixture

@pytest.fixture
async def admin_user(db_session):
    # 创建管理员用户
    return user

@pytest.fixture
async def market_user(db_session):
    # 创建市场部用户
    return user

@pytest.fixture
async def other_user(db_session):
    # 创建其他部门用户
    return user

5.3 项目Fixture

@pytest.fixture
async def test_project(db_session, admin_user):
    # 创建测试项目
    return project

5.4 Token Fixture

@pytest.fixture
async def admin_token(client, admin_user):
    # 获取管理员token
    return token

6. 运行测试

6.1 运行所有测试

cd backend
pytest tests/

6.2 运行特定测试文件

pytest tests/test_auth.py

6.3 运行特定测试用例

pytest tests/test_auth.py::test_login_success

6.4 生成覆盖率报告

pytest tests/ --cov=src --cov-report=html

6.5 运行集成测试

pytest tests/ -m integration

6.6 运行单元测试

pytest tests/ -m unit

7. 持续集成

7.1 测试流程

1. 提交代码前运行单元测试
2. CI/CD流水线运行完整测试套件
3. 生成覆盖率报告
4. 测试通过才能合并代码

7.2 测试覆盖率要求

• 单元测试覆盖率 > 80%
• 关键业务逻辑覆盖率 > 90%
• API接口覆盖率 100%

8. 测试最佳实践

8.1 测试命名规范

• 测试文件: test_<模块名>.py
• 测试类: Test<功能名>
• 测试方法: test_<功能>_<场景>

8.2 测试编写原则

• 每个测试只验证一个功能点
• 测试之间相互独立
• 使用描述性的测试名称
• 遵循AAA模式：Arrange, Act, Assert

8.3 Mock使用

• Mock外部依赖（数据库、网络等）
• 不要Mock被测试的代码
• 保持Mock的行为真实

9. 常见问题

9.1 数据库连接失败

检查测试数据库配置，确保测试数据库已创建。

9.2 测试数据冲突

使用pytest fixture和scope控制测试数据的生命周期。

9.3 异步测试失败

使用pytest-asyncio，确保测试函数使用async def定义。

---

文档维护: 后端程序员 更新时间: 2026-01-25