# RenderWorker 测试文档

本目录包含 RenderWorker 项目的完整测试套件，用于验证特效参数生成和 FFmpeg 渲染功能。

## 目录结构

```
tests/
├── conftest.py                     # pytest 配置和公共 fixtures
├── test_data/                      # 测试数据
│   ├── videos/                     # 测试视频文件
│   ├── templates/                  # 测试模板数据
│   └── expected_outputs/           # 预期输出结果
├── test_effects/                   # 特效单元测试
│   ├── test_base.py               # 基础类测试
│   ├── test_zoom_effect.py        # 缩放特效测试
│   ├── test_speed_effect.py       # 变速特效测试
│   └── ...                        # 其他特效测试
├── test_ffmpeg_builder/            # FFmpeg 命令构建测试
│   └── test_ffmpeg_command_builder.py
├── test_integration/               # 集成测试
│   └── test_ffmpeg_execution.py   # FFmpeg 执行测试
└── utils/                          # 测试工具
    └── test_helpers.py            # 测试辅助函数
```

## 快速开始

### 1. 安装测试依赖

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

### 2. 运行测试

使用测试运行器脚本：

```bash
# 运行所有测试
python run_tests.py all --coverage

# 只运行单元测试
python run_tests.py unit --coverage --html-report

# 只运行集成测试
python run_tests.py integration

# 运行特定特效测试
python run_tests.py effects --effect zoom

# 运行压力测试
python run_tests.py stress
```

或直接使用 pytest：

```bash
# 运行所有测试
pytest tests/ -v --cov=entity --cov=services

# 只运行单元测试
pytest tests/test_effects/ tests/test_ffmpeg_builder/ -v

# 只运行集成测试
pytest tests/test_integration/ -v -m integration

# 生成覆盖率报告
pytest tests/ --cov=entity --cov=services --cov-report=html
```

## 测试类型说明

### 单元测试 (Unit Tests)

位置：`tests/test_effects/`, `tests/test_ffmpeg_builder/`

测试内容：
- 各个特效处理器的参数验证
- FFmpeg 滤镜参数生成
- 特效注册表功能
- FFmpeg 命令构建逻辑

特点：
- 运行速度快
- 不依赖外部工具
- 测试覆盖率高

### 集成测试 (Integration Tests)

位置：`tests/test_integration/`

测试内容：
- 实际 FFmpeg 命令执行
- 视频文件处理验证
- 特效组合效果测试
- 错误处理验证

依赖：
- 需要系统安装 FFmpeg
- 需要测试视频文件

### 压力测试 (Stress Tests)

测试内容：
- 大量特效链处理
- 长时间运行稳定性
- 资源使用情况

运行条件：
- 设置环境变量 `RUN_STRESS_TESTS=1`
- 较长的超时时间

## 测试配置

### pytest 配置

在 `pytest.ini` 中配置：
- 测试路径和文件模式
- 覆盖率设置
- 标记定义
- 输出格式

### 环境变量

- `RUN_STRESS_TESTS`: 启用压力测试
- `FFMPEG_PATH`: 自定义 FFmpeg 路径

## 特效测试详解

### 缩放特效 (ZoomEffect)

测试用例：
- 有效参数验证：`"0,2.0,3.0"`（开始时间，缩放因子，持续时间）
- 无效参数处理：负值、非数字、参数不足
- 静态缩放：持续时间为 0
- 动态缩放：指定时间段内的缩放
- 位置 JSON 解析：自定义缩放中心点

生成滤镜格式：
```
# 静态缩放
[0:v]trim=start=0,zoompan=z=2.0:x=iw/2:y=ih/2:d=1[v_eff1]

# 动态缩放
[0:v]zoompan=z=if(between(t\,0\,3.0)\,2.0\,1):x=iw/2:y=ih/2:d=1[v_eff1]
```

### 变速特效 (SpeedEffect)

测试用例：
- 加速效果：`"2.0"`（2倍速）
- 减速效果：`"0.5"`（0.5倍速）
- 无效参数：零值、负值、非数字
- 默认处理：空参数或 1.0 倍速

生成滤镜格式：
```
[0:v]setpts=2.0*PTS[v_eff1]
```

## FFmpeg 命令构建测试

### 测试场景

1. **单文件复制**：直接复制无需编码
2. **多文件拼接**：使用 concat 滤镜
3. **特效处理**：复杂滤镜链构建
4. **错误处理**：缺失文件、无效参数

### 命令验证

使用 `FFmpegValidator` 验证：
- 命令结构完整性
- 输入输出文件存在
- 滤镜语法正确性
- 流标识符格式

## 集成测试详解

### 真实 FFmpeg 执行

测试流程：
1. 创建测试视频文件
2. 构建 FFmpeg 命令
3. 执行命令并检查返回码
4. 验证输出文件存在且有效

### 测试用例

- 简单复制操作
- 单特效处理
- 多特效组合
- 视频拼接
- 错误情况处理

### 性能测试

监控指标：
- 执行时间
- 内存使用
- 文件大小
- 处理速度

## 代码覆盖率

目标覆盖率：≥ 70%

覆盖范围：
- `entity/` 目录下的所有模块
- `services/` 目录下的所有模块

报告格式：
- XML 格式：用于 Jenkins CI/CD
- HTML 格式：用于本地查看
- 终端输出：实时查看缺失覆盖

## CI/CD 集成

### Jenkins Pipeline

配置文件：`Jenkinsfile`

阶段：
1. 环境准备
2. 代码质量检查
3. 单元测试
4. 集成测试
5. 完整测试套件
6. 性能测试

报告生成：
- JUnit XML 测试报告
- Cobertura 覆盖率报告
- HTML 测试和覆盖率报告

### 自动化触发

- 代码提交时运行单元测试
- PR 创建时运行完整测试
- 主分支更新时运行包含性能测试的完整套件

## 故障排除

### 常见问题

1. **FFmpeg 未找到**
   ```bash
   # 安装 FFmpeg
   sudo apt-get install ffmpeg  # Ubuntu/Debian
   brew install ffmpeg          # macOS
   ```

2. **测试视频创建失败**
   ```bash
   # 手动创建测试视频
   python run_tests.py setup
   ```

3. **覆盖率过低**
   - 检查是否有未测试的代码路径
   - 添加边界条件测试
   - 验证测试是否实际运行

4. **集成测试超时**
   - 增加超时时间：`--timeout=600`
   - 使用更小的测试文件
   - 检查系统资源使用情况

### 调试技巧

1. **查看详细输出**：
   ```bash
   pytest tests/ -v -s
   ```

2. **只运行失败的测试**：
   ```bash
   pytest tests/ --lf
   ```

3. **停在第一个失败**：
   ```bash
   pytest tests/ -x
   ```

4. **查看覆盖率详情**：
   ```bash
   pytest tests/ --cov=entity --cov-report=term-missing
   ```

## 贡献指南

### 添加新测试

1. 在相应目录创建测试文件
2. 使用描述性的测试函数名
3. 添加适当的测试标记
4. 更新文档说明

### 测试最佳实践

1. **独立性**：每个测试应该独立运行
2. **可重复性**：测试结果应该一致
3. **清晰性**：测试意图应该明确
4. **完整性**：覆盖正常和异常情况

### 代码质量

- 遵循 PEP 8 代码风格
- 使用类型注解
- 添加适当的文档字符串
- 使用有意义的变量名