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. 依赖包已安装

安装依赖

cd e2e_tests
pip install -r requirements.txt

环境配置

复制 .env.example 为 .env 并根据实际情况修改配置：

cp .env.example .env

运行所有测试

cd e2e_tests
pytest

测试分类执行

按模块运行

# 认证测试
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

按标记运行

# 冒烟测试
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

运行特定测试用例

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

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

测试报告

生成覆盖率报告

pytest --cov=. --cov-report=html

覆盖率报告将生成在 htmlcov/index.html

生成Allure报告

pytest --alluredir=allure-results
allure serve allure-results

并发执行

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

# 指定worker数量
pytest -n 4

调试模式

详细输出

pytest -v -s

只运行失败的测试

pytest --lf

停在第一个失败处

pytest -x

显示本地变量

pytest -l

测试配置

pytest.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' 解决:

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 示例

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