FrameTour-RenderWorker/tests/README.md

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. 安装测试依赖

pip install -r requirements-test.txt

2. 运行测试

使用测试运行器脚本：

# 运行所有测试
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：

# 运行所有测试
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 未找到

   # 安装 FFmpeg
   sudo apt-get install ffmpeg  # Ubuntu/Debian
   brew install ffmpeg          # macOS
   

2. 测试视频创建失败

   # 手动创建测试视频
   python run_tests.py setup
   

3. 覆盖率过低

   • 检查是否有未测试的代码路径
   • 添加边界条件测试
   • 验证测试是否实际运行

4. 集成测试超时

   • 增加超时时间：--timeout=600
   • 使用更小的测试文件
   • 检查系统资源使用情况

调试技巧

1. 查看详细输出：

   pytest tests/ -v -s
   

2. 只运行失败的测试：

   pytest tests/ --lf
   

3. 停在第一个失败：

   pytest tests/ -x
   

4. 查看覆盖率详情：

   pytest tests/ --cov=entity --cov-report=term-missing
   

贡献指南

添加新测试

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

测试最佳实践

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

代码质量

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