novalon-manage-system/api_integration_tests/TEST_EXECUTION_GUIDE.md

# E2E测试执行指南

## 快速开始

### 前置条件
1. 后端API服务运行在 `http://localhost:8080`
2. PostgreSQL数据库运行在 `localhost:55432`
3. Python 3.9+ 已安装
4. 依赖包已安装

### 安装依赖
```bash
cd e2e_tests
pip install -r requirements.txt
```

### 环境配置
复制 `.env.example` 为 `.env` 并根据实际情况修改配置：
```bash
cp .env.example .env
```

### 运行所有测试
```bash
cd e2e_tests
pytest
```

## 测试分类执行

### 按模块运行
```bash
# 认证测试
pytest tests/test_auth.py

# 用户管理测试
pytest tests/test_user.py

# 角色管理测试
pytest tests/test_role.py

# 字典管理测试
pytest tests/test_dictionary.py

# 系统配置测试
pytest tests/test_config.py

# 通知公告测试
pytest tests/test_notice.py

# 审计日志测试
pytest tests/test_audit.py

# 文件管理测试
pytest tests/test_file.py

# OAuth2客户端测试
pytest tests/test_oauth2.py
```

### 按标记运行
```bash
# 冒烟测试
pytest -m smoke

# 回归测试
pytest -m regression

# 认证测试
pytest -m auth

# 用户管理测试
pytest -m user

# 角色管理测试
pytest -m role

# 字典管理测试
pytest -m dictionary

# 系统配置测试
pytest -m config

# 审计日志测试
pytest -m audit

# 通知公告测试
pytest -m notice

# 文件管理测试
pytest -m file

# OAuth2测试
pytest -m oauth2
```

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

# 运行特定测试类
pytest tests/test_auth.py::TestAuth
```

## 测试报告

### 生成覆盖率报告
```bash
pytest --cov=. --cov-report=html
```
覆盖率报告将生成在 `htmlcov/index.html`

### 生成Allure报告
```bash
pytest --alluredir=allure-results
allure serve allure-results
```

### 并发执行
```bash
# 使用多进程并发执行测试
pytest -n auto

# 指定worker数量
pytest -n 4
```

## 调试模式

### 详细输出
```bash
pytest -v -s
```

### 只运行失败的测试
```bash
pytest --lf
```

### 停在第一个失败处
```bash
pytest -x
```

### 显示本地变量
```bash
pytest -l
```

## 测试配置

### pytest.ini 配置说明
```ini
[pytest]
testpaths = tests                    # 测试文件路径
python_files = test_*.py            # 测试文件匹配模式
python_classes = Test*               # 测试类匹配模式
python_functions = test_*            # 测试函数匹配模式
pythonpath = .                      # Python路径
addopts = 
    -v                              # 详细输出
    --strict-markers                # 严格标记检查
    --tb=short                     # 短格式的traceback
    --cov=.                        # 覆盖率检查
    --cov-report=html               # HTML覆盖率报告
    --cov-report=term-missing       # 终端覆盖率报告
    --alluredir=allure-results      # Allure结果目录

markers =
    auth: 认证相关测试
    user: 用户管理测试
    role: 角色管理测试
    dictionary: 字典管理测试
    dict: 字典管理测试
    config: 系统配置测试
    audit: 审计日志测试
    notice: 通知公告测试
    file: 文件管理测试
    oauth2: OAuth2相关测试
    smoke: 冒烟测试
    regression: 回归测试
    slow: 慢速测试

asyncio_mode = auto                 # 异步测试模式
```

## 常见问题

### 1. 导入错误
**问题**: `ModuleNotFoundError: No module named 'xxx'`
**解决**: 
```bash
pip install -r requirements.txt
```

### 2. 数据库连接失败
**问题**: `Connection refused` 或 `Authentication failed`
**解决**:
- 检查数据库是否运行
- 验证 `.env` 中的数据库配置
- 确认数据库用户名和密码正确

### 3. API连接失败
**问题**: `Connection refused` 或 `Timeout`
**解决**:
- 确认后端API服务是否运行
- 检查API端口配置（默认8080）
- 验证防火墙设置

### 4. 认证失败
**问题**: `401 Unauthorized`
**解决**:
- 检查测试用户凭证是否正确
- 验证JWT Token生成和验证机制
- 确认SecurityConfig配置

### 5. 测试数据冲突
**问题**: `Duplicate key` 或 `Unique constraint violation`
**解决**:
- 使用时间戳生成唯一数据
- 每个测试用例使用不同的数据
- 确保测试数据正确清理

## CI/CD集成

### GitHub Actions 示例
```yaml
name: E2E Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_DB: manage_system
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
        ports:
          - 55432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.13'
      
      - name: Install dependencies
        run: |
          cd e2e_tests
          pip install -r requirements.txt
      
      - name: Run tests
        run: |
          cd e2e_tests
          pytest --cov=. --cov-report=xml
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage.xml
```

## 最佳实践

### 1. 测试隔离
- 每个测试用例应该独立运行
- 使用fixture自动创建和清理测试数据
- 避免测试用例之间的依赖关系

### 2. 测试数据管理
- 使用随机数据生成器（Faker）
- 为每个测试用例创建唯一数据
- 确保测试数据在测试后正确清理

### 3. 断言清晰
- 使用有意义的断言消息
- 验证业务逻辑而非实现细节
- 使用专门的断言方法

### 4. 测试命名规范
- 使用描述性的测试名称
- 格式：`test_[功能]_[场景]_[预期结果]`
- 示例：`test_login_success_with_valid_credentials`

### 5. 测试文档
- 为复杂测试添加文档字符串
- 说明测试目的和预期行为
- 记录已知的限制和问题

## 性能优化

### 减少测试执行时间
1. 使用并发执行：`pytest -n auto`
2. 跳过慢速测试：`pytest -m "not slow"`
3. 使用Mock减少外部依赖
4. 实现测试数据缓存

### 提高测试稳定性
1. 使用合理的超时设置
2. 实现重试机制
3. 添加等待策略（而非固定sleep）
4. 使用稳定的测试环境

## 联系方式

如有问题或建议，请联系：
- **作者**: 张翔
- **角色**: 全栈质量保障与效能工程师
- **项目**: Novalon管理系统

---

**文档版本**: 1.0
**最后更新**: 2026-03-11