# Novalon Website E2E 测试框架

基于 Playwright 和 Python 的端到端测试解决方案，为 Novalon Website 提供全面的自动化测试覆盖。

## 目录

- [特性](#特性)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [测试运行](#测试运行)
- [CI/CD 集成](#cicd-集成)
- [测试标记](#测试标记)
- [配置说明](#配置说明)
- [最佳实践](#最佳实践)

## 特性

- **模块化设计**: 采用 Page Object Model (POM) 设计模式
- **跨浏览器测试**: 支持 Chrome、Firefox、WebKit
- **响应式测试**: 覆盖多端（移动端、平板、桌面）
- **性能测试**: 页面加载性能指标监控
- **多格式报告**: HTML、JSON、Markdown 报告生成
- **完整测试数据**: 自动生成测试数据（中文/英文）
- **详细日志**: 彩色日志输出，便于问题定位

## 技术栈

| 技术 | 用途 |
|------|------|
| Python 3.9+ | 编程语言 |
| Playwright | 浏览器自动化框架 |
| pytest | 测试框架 |
| pytest-html | HTML 报告 |
| pytest-cov | 代码覆盖率 |
| Jinja2 | 报告模板 |

## 项目结构

```
e2e-tests/
├── config/
│   ├── __init__.py
│   ├── settings.py          # 应用配置
│   └── browsers.py          # 浏览器配置
├── pages/
│   ├── __init__.py
│   ├── base_page.py         # 页面基类
│   ├── home_page.py         # 首页对象
│   └── contact_page.py      # 联系页面对象
├── tests/
│   ├── __init__.py
│   ├── conftest.py          # pytest 配置和 fixture
│   ├── test_home_page.py    # 首页测试
│   ├── test_contact_form.py # 联系表单测试
│   ├── test_navigation.py   # 导航测试
│   ├── test_performance.py  # 性能测试
│   └── test_responsive.py   # 响应式测试
├── utils/
│   ├── __init__.py
│   ├── helpers.py           # 辅助工具函数
│   ├── logger.py            # 日志配置
│   ├── data_generator.py    # 测试数据生成
│   └── report_generator.py  # 报告生成器
├── scripts/
│   ├── run_tests.py         # 测试运行脚本
│   └── ci_test.py           # CI/CD 测试脚本
├── reports/                 # 测试报告目录
├── screenshots/             # 失败截图目录
├── videos/                  # 测试视频目录
├── requirements.txt         # Python 依赖
├── pyproject.toml           # pytest 配置
├── pytest.ini               # pytest 配置
├── .env.example             # 环境变量模板
└── README.md                # 本文档
```

## 快速开始

### 1. 环境准备

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
.\venv\Scripts\activate   # Windows

# 安装依赖
pip install -r requirements.txt

# 安装 Playwright 浏览器
playwright install
```

### 2. 环境配置

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件
# BASE_URL=http://localhost:3000
# 默认开发环境: http://localhost:3000
```

### 3. 运行测试

```bash
# 运行所有测试
python scripts/run_tests.py

# 运行冒烟测试
python scripts/run_tests.py -m smoke

# 运行特定测试
python scripts/run_tests.py tests/test_home_page.py

# 使用关键字过滤
python scripts/run_tests.py -k home

# 多浏览器测试
python scripts/run_tests.py -b all
```

## 测试运行

### 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-b, --browser` | 浏览器 (chromium/firefox/webkit/all) | chromium |
| `-h, --headless` | 无头模式 | False |
| `-m, --marker` | 运行指定标记的测试 | - |
| `-k, --keyword` | 关键字过滤 | - |
| `-v, --verbose` | 详细输出 | False |
| `--html` | 生成 HTML 报告 | False |
| `--video` | 录制测试视频 | False |
| `--screenshot` | 失败时截图 | False |
| `--parallel` | 并行执行 | False |
| `--workers` | 并行工作数 | 4 |
| `--env` | 测试环境 | development |

### 示例命令

```bash
# 冒烟测试
python scripts/run_tests.py -m smoke -v

# 性能测试
python scripts/run_tests.py -m performance

# 响应式测试
python scripts/run_tests.py -m responsive

# 完整回归测试
python scripts/run_tests.py -m regression -v --html

# 无头模式运行
python scripts/run_tests.py -h --parallel

# 跨浏览器测试
python scripts/run_tests.py -b all --html
```

## CI/CD 集成

### GitHub Actions 示例

```yaml
name: E2E Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  e2e-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
          
      - name: Install dependencies
        run: |
          python -m venv venv
          source venv/bin/activate
          pip install -r e2e-tests/requirements.txt
          playwright install --with-deps chromium
          
      - name: Run E2E Tests
        run: |
          source venv/bin/activate
          cp e2e-tests/.env.example e2e-tests/.env
          python e2e-tests/scripts/run_tests.py -m smoke --html
        env:
          BASE_URL: ${{ secrets.BASE_URL }}
          
      - name: Upload Test Report
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: test-report
          path: e2e-tests/reports/
```

### CI 测试脚本

```bash
# 运行冒烟测试
python scripts/ci_test.py --test-type smoke

# 运行回归测试
python scripts/ci_test.py --test-type regression

# 运行性能测试
python scripts/ci_test.py --test-type performance

# 跨浏览器测试
python scripts/ci_test.py --test-type cross_browser

# 完整测试套件
python scripts/ci_test.py --test-type full
```

## 测试标记

| 标记 | 说明 | 用例数量 |
|------|------|---------|
| `@pytest.mark.smoke` | 冒烟测试，快速验证核心功能 | 关键路径 |
| `@pytest.mark.regression` | 回归测试，完整功能验证 | 功能测试 |
| `@pytest.mark.performance` | 性能测试，页面加载和响应时间 | 性能指标 |
| `@pytest.mark.responsive` | 响应式测试，不同屏幕尺寸 | 布局适配 |
| `@pytest.mark.cross_browser` | 跨浏览器测试 | 兼容性 |
| `@pytest.mark.form` | 表单相关测试 | 表单验证 |
| `@pytest.mark.navigation` | 导航测试 | 页面跳转 |
| `@pytest.mark.interactive` | 用户交互测试 | 交互功能 |

### 运行特定标记的测试

```bash
# 只运行冒烟测试
pytest -m smoke

# 运行冒烟和性能测试
pytest -m "smoke or performance"

# 运行冒烟但排除性能测试
pytest -m "smoke and not performance"
```

## 配置说明

### 环境变量 (.env)

```env
# 网站基础URL
BASE_URL=http://localhost:3000

# 测试环境
ENVIRONMENT=development

# 默认浏览器
DEFAULT_BROWSER=chromium

# 无头模式
HEADLESS_MODE=false

# 页面加载超时
PAGE_LOAD_TIMEOUT=30000

# 元素等待超时
ELEMENT_TIMEOUT=10000

# 报告标题
REPORT_TITLE=Novalon Website E2E 测试报告

# 报告描述
REPORT_DESCRIPTION=自动化端到端测试结果
```

### 测试配置 (pytest.ini)

```ini
[pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts =
    -v
    --tb=short
    --strict-markers
    --disable-warnings
filterwarnings =
    ignore::DeprecationWarning
```

### 浏览器配置 (config/browsers.py)

```python
# 支持的浏览器配置
BROWSER_CONFIG = {
    "chromium": {
        "headless": False,
        "viewport": {"width": 1920, "height": 1080},
        "args": ["--start-maximized"]
    },
    "firefox": {
        "headless": False,
        "viewport": {"width": 1920, "height": 1080}
    },
    "webkit": {
        "headless": False,
        "viewport": {"width": 1920, "height": 1080}
    }
}
```

## 最佳实践

### 1. 页面对象模式

每个页面都应该有对应的 Page Object 类：

```python
from pages.base_page import BasePage

class HomePage(BasePage):
    def __init__(self, page):
        super().__init__(page)
        self.path = "/"
        self.selectors = {
            "hero_title": "#home h1",
            "cta_button": ".cta-button"
        }
    
    def verify_hero_title(self):
        self.assert_element_visible("hero_title")
        return self
```

### 2. 测试数据管理

使用数据生成器创建测试数据：

```python
from utils.data_generator import get_test_data_generator

def test_contact_form(test_data_generator):
    data = test_data_generator.generate_contact_form_data()
    page.fill_contact_form(data)
```

### 3. 断言辅助

使用断言助手进行验证：

```python
def test_example(page):
    assert_(page).title_contains("首页")
    assert_(page).element_visible("#main")
```

### 4. 截图和日志

测试失败时自动截图，并记录详细日志：

```python
def test_with_logging(page):
    logger = get_logger()
    logger.log_action("执行测试步骤")
    # 测试代码
```

### 5. 性能监控

使用内置的性能监控：

```python
def test_performance(page):
    performance = page.verify_page_performance()
    assert performance["pageLoadTime"] < 5000
```

## 报告示例

测试完成后，报告将保存在 `reports/` 目录：

```
reports/
├── html/
│   └── test_report.html     # HTML 格式报告
├── json/
│   └── test_results.json    # JSON 格式结果
└── screenshots/
    └── test_failed.png      # 失败截图
```

## 故障排除

### 常见问题

**1. 浏览器安装失败**

```bash
playwright install --with-deps
```

**2. 依赖安装失败**

```bash
pip install --upgrade pip
pip install -r requirements.txt
```

**3. 测试超时**

检查 `.env` 中的 `PAGE_LOAD_TIMEOUT` 设置

**4. 页面元素定位失败**

使用开发者工具检查元素选择器是否正确

### 获取帮助

- 查看详细日志: 运行 `python scripts/run_tests.py -v`
- 查看 Playwright 文档: https://playwright.dev/python/
- 查看 pytest 文档: https://docs.pytest.org/

## 许可证

本测试框架基于 MIT 许可证开源。