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 依赖安装
```bash
pip install pytest pytest-asyncio pytest-cov pytest-mock httpx
```

### 2.2 测试配置文件 pytest.ini
```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 环境变量
测试环境使用独立数据库配置：
```env
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
```python
@pytest.fixture
async def db_session():
    # 创建测试数据库会话
    # 测试结束后回滚
    yield session
    # 清理数据
```

### 5.2 用户Fixture
```python
@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
```python
@pytest.fixture
async def test_project(db_session, admin_user):
    # 创建测试项目
    return project
```

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

## 6. 运行测试

### 6.1 运行所有测试
```bash
cd backend
pytest tests/
```

### 6.2 运行特定测试文件
```bash
pytest tests/test_auth.py
```

### 6.3 运行特定测试用例
```bash
pytest tests/test_auth.py::test_login_success
```

### 6.4 生成覆盖率报告
```bash
pytest tests/ --cov=src --cov-report=html
```

### 6.5 运行集成测试
```bash
pytest tests/ -m integration
```

### 6.6 运行单元测试
```bash
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