Heygem自动化测试框架搭建：确保每次更新不破坏核心功能-平芜编程栈

Heygem自动化测试框架搭建：确保每次更新不破坏核心功能

1. 引言

1.1 项目背景与业务需求

HeyGem 数字人视频生成系统是一款基于 AI 技术的音视频合成工具，支持将音频与人物视频结合，生成口型同步的高质量数字人视频。该系统已广泛应用于批量内容创作场景，其 WebUI 版本由开发者“科哥”进行二次开发并优化为批量处理模式，显著提升了多任务处理效率。

随着系统的持续迭代和功能扩展，手动验证核心流程（如音频上传、视频合成、结果导出等）的成本急剧上升。任何一次代码提交都可能无意中引入回归问题，例如：

音频无法正确加载
视频预览异常
批量生成任务卡顿或失败
下载包缺失文件

为保障系统稳定性，亟需构建一套可重复执行、覆盖关键路径、易于维护的自动化测试框架。

1.2 自动化测试的价值定位

本文将围绕 HeyGem 系统的实际使用场景，设计并实现一个端到端（End-to-End, E2E）自动化测试解决方案，目标是：

✅ 每次代码更新后自动运行核心功能检测
✅ 快速发现界面交互或后端服务异常
✅ 减少人工回归测试时间成本
✅ 提供可追溯的测试报告用于质量分析

最终实现“提交即测、失败即知”的持续集成闭环。

2. 技术选型与架构设计

2.1 测试类型选择：为什么采用 E2E 而非单元测试？

尽管单元测试能有效验证模型推理逻辑，但 HeyGem 的主要交互集中在前端 WebUI 层，且用户操作路径复杂（拖拽上传、分页管理、打包下载等），因此更适配端到端测试来模拟真实用户行为。

测试类型	适用层级	HeyGem 适配性
单元测试	函数/模块	低（前端为主）
接口测试	API 调用	中（部分可用）
E2E 测试	用户界面	高（推荐方案）

我们选择Playwright + Python作为核心技术栈，理由如下：

支持多浏览器自动化（Chromium、Firefox、WebKit）
原生支持文件上传、拖放操作（关键！）
强大的等待机制，避免因异步加载导致误判
与 pytest 深度集成，便于组织测试用例
可生成视频录制和截图，便于故障排查

2.2 整体测试架构设计

+------------------+ +---------------------+ | Git 代码仓库 | --> | CI/CD Pipeline | +------------------+ +----------+----------+ | +---------------v------------------+ | Playwright Test Runner (Python) | | - 启动本地服务 | | - 执行 UI 操作 | | - 断言输出结果 | +---------------+-------------------+ | +---------------v------------------+ | 测试资源目录 | | - test_audio.mp3 | | - test_video.mp4 | | - expected_output_checksums.txt | +------------------------------------+

测试流程包括： 1. 拉取最新代码 2. 启动start_app.sh服务 3. 使用 Playwright 控制浏览器完成全流程操作 4. 验证输出文件完整性 5. 清理环境并生成报告

3. 核心测试用例实现

3.1 环境准备与依赖安装

首先配置 Python 虚拟环境并安装必要依赖：

python -m venv .venv source .venv/bin/activate pip install playwright pytest pytest-html playwright install chromium

创建项目结构：

tests/ ├── conftest.py # 全局 fixture ├── test_batch_mode.py # 批量模式测试 ├── test_single_mode.py # 单个模式测试 └── utils/ └── helpers.py # 工具函数 resources/ ├── test_audio.mp3 └── test_video.mp4

3.2 启动服务与页面初始化

在conftest.py中定义共享 fixture：

# conftest.py import subprocess import time import pytest from playwright.sync_api import sync_playwright @pytest.fixture(scope="session") def browser(): with sync_playwright() as p: browser = p.chromium.launch(headless=True) yield browser browser.close() @pytest.fixture(scope="session") def server(): # 启动应用服务 process = subprocess.Popen(["bash", "start_app.sh"]) time.sleep(10) # 等待服务启动 yield process.terminate()

3.3 批量处理模式全流程测试

# test_batch_mode.py import os from playwright.sync_api import expect def test_batch_processing_e2e(browser, server): page = browser.new_page() # 访问本地服务 page.goto("http://localhost:7860") expect(page.locator("h1")).to_contain_text("HeyGem") # 步骤1：上传音频文件 audio_upload = page.locator("input[type='file']").first audio_upload.set_input_files("../resources/test_audio.mp3") page.wait_for_timeout(2000) # 预览播放按钮应出现 play_button = page.locator("button:has-text('▶')") expect(play_button).to_be_visible() # 步骤2：添加视频文件（模拟拖放） drop_zone = page.locator(".upload-video-area") video_path = os.path.abspath("../resources/test_video.mp4") with page.expect_file_chooser() as fc_info: drop_zone.click() file_chooser = fc_info.value file_chooser.set_files(video_path) page.wait_for_timeout(3000) # 视频应在左侧列表中显示 video_item = page.locator("li.video-item").first expect(video_item).to_have_count(1) # 步骤3：开始批量生成 start_btn = page.locator("button:has-text('开始批量生成')") start_btn.click() # 监控进度条至完成 progress_bar = page.locator(".progress-bar") expect(progress_bar).to_have_attribute("aria-valuenow", "100", timeout=120000) # 步骤4：检查生成结果 result_items = page.locator(".result-item") expect(result_items).to_have_count(1) # 步骤5：触发一键打包下载 zip_btn = page.locator("text=📦 一键打包下载") zip_btn.click() # 监听下载事件 with page.expect_download() as download_info: page.locator("text=点击打包后下载").click() download = download_info.value # 保存到本地 download.save_as("./outputs/latest_batch.zip") assert os.path.exists("./outputs/latest_batch.zip") assert os.path.getsize("./outputs/latest_batch.zip") > 0 page.close()

关键点说明： - 使用expect_file_chooser模拟文件选择器 -wait_for_timeout避免因网络延迟导致断言失败 - 下载监听确保 ZIP 包成功生成

3.4 单个处理模式测试简略版

# test_single_mode.py def test_single_mode_processing(browser, server): page = browser.new_page() page.goto("http://localhost:7860") # 切换到单个模式标签 page.locator("button:has-text('单个处理模式')").click() # 分别上传音频和视频 audio_input = page.locator("input[type='file']").nth(1) video_input = page.locator("input[type='file']").nth(2) audio_input.set_input_files("../resources/test_audio.mp3") video_input.set_input_files("../resources/test_video.mp4") page.wait_for_timeout(3000) # 开始生成 page.locator("button:has-text('开始生成')").click() expect(page.locator(".result-video")).to_be_visible(timeout=90000) # 结果视频可播放 video_player = page.locator("video") expect(video_player).to_have_count(1)

4. 测试优化与工程化建议

4.1 失败重试与超时控制

为提高测试稳定性，添加重试机制：

# 在 pytest.ini 中配置 [tool:pytest] addopts = --reruns 2 --timeout=300

同时设置全局等待策略：

page.set_default_timeout(30000) # 全局超时 page.set_default_navigation_timeout(60000)

4.2 日志与证据留存

启用 Playwright 的跟踪功能，便于调试：

context = browser.new_context() context.tracing.start(screenshots=True, snapshots=True) # ...执行操作... context.tracing.stop(path="trace.zip")

结合日志文件监控：

# 实时捕获错误日志 tail -f /root/workspace/运行实时日志.log | grep -i "error\|fail"

4.3 集成 CI/CD 流程

在.github/workflows/test.yml中配置 GitHub Actions：

name: Run E2E Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest container: nvidia/cuda:12.1.1-runtime-ubuntu22.04 services: docker: image: docker:dind privileged: true steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 with: python-version: '3.10' - name: Install dependencies run: | pip install playwright pytest playwright install chromium - name: Start App & Run Tests run: | bash start_app.sh & sleep 60 python -m pytest tests/ --html=report.html --self-contained-html - name: Upload Report uses: actions/upload-artifact@v3 with: path: report.html