novalon-manage-system/tests_suite/README.md

# Tests Suite - 统一测试套件

## 概述

tests_suite 是 Novalon 管理系统的统一测试套件项目，包含所有非单元测试：

- **集成测试**：API集成测试、数据库集成测试、WebSocket集成测试
- **E2E测试**：Web UI测试、API E2E测试、业务流程测试
- **性能测试**：负载测试、压力测试、尖峰测试
- **安全测试**：认证测试、授权测试、注入测试

## 项目结构

```
tests_suite/
├── README.md                    # 本文档
├── pytest.ini                   # Pytest配置
├── pyproject.toml              # 项目配置
├── requirements.txt            # Python依赖
├── .env.example               # 环境变量示例
├── conftest.py               # 全局fixtures和配置
│
├── config/                   # 配置管理
│   ├── __init__.py
│   └── settings.py          # 应用配置
│
├── tests/                    # 测试用例（按类型分层）
│   ├── integration/         # 集成测试
│   │   ├── api/            # API集成测试
│   │   ├── database/       # 数据库集成测试
│   │   └── websocket/      # WebSocket集成测试
│   ├── e2e/               # E2E测试
│   │   ├── web/           # Web UI测试
│   │   ├── api/           # API E2E测试
│   │   └── business/      # 业务流程测试
│   ├── performance/       # 性能测试
│   └── security/         # 安全测试
│
├── test_utils/            # 测试工具和辅助函数
│   ├── api_client/       # API客户端封装
│   ├── ui_helpers/       # UI辅助函数
│   ├── data_manager/     # 测试数据管理
│   ├── assertions/       # 自定义断言
│   ├── logger.py         # 日志工具
│   └── data_generator.py # 数据生成器
│
├── fixtures/             # Pytest fixtures
│   ├── api_fixtures.py  # API相关fixtures
│   ├── db_fixtures.py   # 数据库fixtures
│   ├── ui_fixtures.py   # UI相关fixtures
│   └── data_fixtures.py # 测试数据fixtures
│
├── test_data/            # 测试数据文件
└── reports/             # 测试报告
    ├── html/
    ├── performance/
    └── coverage/
```

## 快速开始

### 环境准备

1. **安装Python依赖**
```bash
cd tests_suite
pip install -r requirements.txt
```

2. **安装Playwright浏览器**
```bash
playwright install
```

3. **配置环境变量**
```bash
cp .env.example .env
# 编辑.env文件，配置相关环境变量
```

### 运行测试

#### 运行所有测试
```bash
pytest tests/ -v
```

#### 按类型运行测试

**集成测试**
```bash
# 运行所有集成测试
pytest tests/integration/ -v

# 运行API集成测试
pytest tests/integration/api/ -v

# 运行数据库集成测试
pytest tests/integration/database/ -v

# 运行WebSocket集成测试
pytest tests/integration/websocket/ -v
```

**E2E测试**
```bash
# 运行所有E2E测试
pytest tests/e2e/ -v

# 运行Web UI测试
pytest tests/e2e/web/ -v

# 运行API E2E测试
pytest tests/e2e/api/ -v

# 运行业务流程测试
pytest tests/e2e/business/ -v
```

**性能测试**
```bash
# 运行所有性能测试
pytest tests/performance/ -v

# 运行负载测试
pytest tests/performance/test_load_testing.py -v

# 运行压力测试
pytest tests/performance/test_stress_testing.py -v

# 运行尖峰测试
pytest tests/performance/test_spike_testing.py -v
```

**安全测试**
```bash
# 运行所有安全测试
pytest tests/security/ -v
```

#### 按标记运行测试

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

# 运行E2E测试
pytest tests/ -v -m e2e

# 运行性能测试
pytest tests/ -v -m performance

# 运行安全测试
pytest tests/ -v -m security

# 运行冒烟测试
pytest tests/ -v -m smoke

# 运行回归测试
pytest tests/ -v -m regression
```

#### 运行特定测试

```bash
# 运行单个测试文件
pytest tests/integration/api/test_user_api.py -v

# 运行单个测试函数
pytest tests/integration/api/test_user_api.py::test_create_user_success -v

# 运行单个测试类
pytest tests/integration/api/test_user_api.py::TestUserAPI -v
```

### 生成测试报告

#### HTML测试报告
```bash
pytest tests/ --html=reports/html/test_report.html --self-contained-html
```

#### 覆盖率报告
```bash
pytest tests/ --cov=test_utils --cov-report=html --cov-report=term-missing
```

#### Allure测试报告
```bash
pytest tests/ --alluredir=allure-results
allure generate allure-results -o allure-report
allure open allure-report
```

## 配置说明

### 环境变量配置

在`.env`文件中配置以下环境变量：

```env
ENVIRONMENT=dev

API_BASE_URL=http://localhost:8080
WEB_BASE_URL=http://localhost:3003

DB_HOST=localhost
DB_PORT=5432
DB_NAME=manage_system
DB_USERNAME=postgres
DB_PASSWORD=postgres

TEST_USERNAME=admin
TEST_PASSWORD=admin123

HEADLESS_BROWSER=true
BROWSER_TYPE=chromium
REQUEST_TIMEOUT=30000
```

### Pytest配置

主要配置项在`pytest.ini`中：

```ini
[pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts = 
    -v
    --strict-markers
    --tb=short
    --cov=test_utils
    --cov-report=html
    --cov-report=term-missing
    --alluredir=allure-results
```

## 测试分层说明

### 集成测试

**目标**：测试模块间的交互和API端点

**特点**：
- 使用真实数据库
- 测试API契约
- 验证数据持久化

**工具**：pytest + httpx + testcontainers

**示例**：
```python
@pytest.mark.integration
def test_create_user_api(api_client: Client, test_user_data: dict):
    response = api_client.post("/api/users", json=test_user_data)
    assert response.status_code == 201
    assert response.json()["username"] == test_user_data["username"]
```

### E2E测试

**目标**：从用户视角验证完整业务流程

**特点**：
- 使用真实浏览器
- 模拟用户操作
- 验证端到端流程

**工具**：pytest + playwright

**示例**：
```python
@pytest.mark.e2e
def test_complete_user_lifecycle(page: Page, web_base_url: str):
    page.goto(f"{web_base_url}/login")
    page.fill("input[name='username']", "admin")
    page.fill("input[name='password']", "admin123")
    page.click("button[type='submit']")
    # ... 完整的用户操作流程
```

### 性能测试

**目标**：验证系统性能指标

**特点**：
- 模拟真实负载
- 监控性能指标
- 发现性能瓶颈

**工具**：pytest + locust/k6

**示例**：
```python
@pytest.mark.performance
def test_load_testing():
    # 性能测试逻辑
    pass
```

### 安全测试

**目标**：发现安全漏洞

**特点**：
- 测试认证授权
- 检测注入攻击
- 验证安全配置

**工具**：pytest + 安全工具

**示例**：
```python
@pytest.mark.security
def test_sql_injection_protection(api_client: Client):
    malicious_input = "' OR '1'='1"
    response = api_client.post("/api/auth/login", json={
        "username": malicious_input,
        "password": "test"
    })
    assert response.status_code == 401
```

## CI/CD集成

tests_suite 集成到项目的 CI/CD 流水线中：

### 快速反馈（提交时）
```yaml
# 单元测试在各自业务项目中运行
# tests_suite不参与此阶段
```

### 全面验证（合并前）
```yaml
# 运行集成测试
pytest tests/integration/ -v --tb=short

# 运行E2E测试
pytest tests/e2e/ -v --tb=short
```

### 生产验证（部署前）
```yaml
# 运行性能测试
pytest tests/performance/ -v

# 运行安全测试
pytest tests/security/ -v
```

## 测试数据管理

### 数据工厂模式

使用`test_utils/data_manager/data_generator.py`中的数据工厂生成测试数据：

```python
from test_utils.data_manager.data_generator import UserDataFactory

# 生成用户数据
user_data = UserDataFactory.create_user_data()

# 自定义数据
custom_user = UserDataFactory.create_user_data({
    "username": "test_user",
    "email": "test@example.com"
})
```

### 测试数据清理

使用fixtures自动清理测试数据：

```python
@pytest.mark.integration
def test_create_user(api_client: Client, test_user_data: dict, clean_test_data):
    # clean_test_data fixture会在测试后自动清理数据
    response = api_client.post("/api/users", json=test_user_data)
    assert response.status_code == 201
```

## 调试技巧

### 查看详细输出
```bash
pytest tests/ -v -s
```

### 显示更详细的traceback
```bash
pytest tests/ -v --tb=long
```

### 在第一个失败时停止
```bash
pytest tests/ -v -x
```

### 进入pdb调试器
```bash
pytest tests/ -v --pdb
```

### 非headless模式调试
```bash
HEADLESS_BROWSER=false pytest tests/e2e/web/ -v
```

## 常见问题

### 1. 测试超时

**问题**：测试执行超时

**解决方案**：
- 增加请求超时时间：修改`.env`中的`REQUEST_TIMEOUT`
- 增加页面默认超时时间：`page.set_default_timeout(60000)`
- 增加特定操作的等待时间

### 2. 405 Method Not Allowed错误

**问题**：API端点返回405错误

**解决方案**：
- 检查API端点的HTTP方法是否正确
- 检查路由配置是否正确
- 检查Handler方法的HTTP方法注解

### 3. 前后端数据不一致

**问题**：前端显示的数据与API返回的数据不一致

**解决方案**：
- 检查前端是否正确调用API
- 检查API返回的数据格式
- 检查前端数据渲染逻辑

### 4. Playwright浏览器未安装

**问题**：运行E2E测试时报错浏览器未安装

**解决方案**：
```bash
playwright install
```

## 最佳实践

### 1. 测试命名规范

- 测试文件：`test_*.py`
- 测试类：`Test*`
- 测试函数：`test_*`

### 2. 使用标记

为测试添加适当的标记：

```python
@pytest.mark.integration
@pytest.mark.smoke
def test_create_user_api():
    pass
```

### 3. 使用fixtures

充分利用fixtures减少重复代码：

```python
def test_create_user(api_client: Client, auth_headers: dict, test_user_data: dict):
    response = api_client.post("/api/users", 
                              json=test_user_data,
                              headers=auth_headers)
    assert response.status_code == 201
```

### 4. 数据隔离

每个测试应该独立运行，不依赖其他测试：

```python
@pytest.mark.integration
def test_create_user(api_client: Client, test_user_data: dict, clean_test_data):
    # clean_test_data fixture确保测试数据清理
    response = api_client.post("/api/users", json=test_user_data)
    assert response.status_code == 201
```

### 5. 断言清晰

使用清晰的断言消息：

```python
assert response.status_code == 201, f"Expected 201, got {response.status_code}"
assert "username" in response.json(), "Response should contain username"
```

## 参考资料

- [Pytest官方文档](https://docs.pytest.org/)
- [Playwright官方文档](https://playwright.dev/python/)
- [Httpx官方文档](https://www.python-httpx.org/)
- [测试金字塔](https://martinfowler.com/articles/practical-test-pyramid.html)

## 维护者

- **张翔**（全栈质量保障与研发效能工程师）

## 版本历史

| 版本 | 日期 | 变更说明 |
|-----|------|---------|
| 1.0.0 | 2026-03-14 | 初始版本，完成测试架构重构 |

---

**最后更新时间**: 2026-03-14