端到端浏览器自动化测试

本项目提供两种端到端测试方案：AI 智能体驱动（JSON 测试用例）和编程式自动化（pytest + Playwright）。

目录结构

auto_test/
├── test_modules/              # JSON 测试用例（AI 智能体驱动）
│   ├── index.json             # 模块索引（含依赖关系）
│   └── *.json                 # 15 个模块的测试用例
├── e2e/                       # 编程式 E2E 测试（pytest + Playwright）
│   ├── conftest.py            # 核心 fixtures
│   ├── pytest.ini             # pytest 配置
│   ├── helpers/
│   │   ├── api_client.py      # httpx 异步 API 客户端
│   │   ├── editor_helpers.py  # 编辑器辅助函数
│   │   └── page_objects.py    # Page Object 基类
│   ├── test_auth.py           # 认证模块（3 个 P0）
│   ├── test_session.py        # 会话管理（5 个 P0）
│   ├── test_world.py          # 世界 CRUD（5 个 P0）
│   ├── test_character.py      # 角色 CRUD（4 个 P0）
│   ├── test_location.py       # 场景 CRUD（5 个 P0）
│   ├── test_workflow.py       # 工作流 CRUD（5 个测试，未标记 p0）
│   ├── test_workflow_page.py  # 工作流前端页面（3 个测试，未标记 p0）
│   ├── test_workflow_list.py  # 工作流列表页
│   ├── test_audio.py          # 音频模块（4 个测试，未标记 p0）
│   ├── test_script_writer.py  # 剧本编辑器页面（10 个 P0）
│   ├── test_script_writer_api.py  # 剧本编辑器 API
│   ├── test_script_split.py   # 剧本增量拆分
│   ├── test_marketing_agent.py# 营销智能体页面（6 个 P0）
│   ├── test_marketing_agent_api.py # 营销智能体 API
│   ├── test_admin.py          # 管理后台（9 个 P0）
│   ├── test_admin_api.py      # 管理后台 API
│   ├── test_node_operations.py # 节点操作
│   ├── test_grid_image.py     # 宫格图片生成
│   ├── test_shot_frame_video.py # 分镜节点视频生成
│   ├── test_shot_group_video.py # 分镜组视频生成
│   ├── test_camera_control.py # 镜头控制
│   ├── test_timeline.py       # 视频时间轴
│   ├── test_error_handling.py # 错误处理
│   ├── test_computing_power_logs.py # 算力日志
│   └── test_external_recharge.py # 外部充值
├── test_assets/               # 测试资源文件
├── test_config.json           # 测试配置文件
└── test_sessions/             # 测试会话记录

快速开始

1. 安装依赖

pip install playwright pytest-html pytest-timeout pytest-asyncio
playwright install chromium

2. 配置

复制 test_config.example.json 为 test_config.json，填写：

base_url: 服务器地址（当前默认 http://localhost:8000，即本地服务）
credentials.primary: 测试账号（见内部保密清单）
test_assets: 测试资源文件路径

3. 准备测试资产

E2E 需要两类资产，作用不同，不能混用：

资产类别	位置	谁使用	用途
输入资产	`auto_test/test_assets/`，由 `auto_test/test_config.json` 引用	测试用例	上传图片、视频、音频作为用户输入
测试模式输出资产	`auto_test/samples/` -> `upload/mock/`	后端测试模式	代替外部生成接口返回本地样本文件

3.1 输入资产

auto_test/test_config.json 默认需要：

配置项	默认路径	要求
`test_assets.test_image`	`auto_test/test_assets/test_image.jpg`	普通 jpg/png 图片
`test_assets.test_video`	`auto_test/test_assets/test.mp4`	可播放 mp4
`test_assets.test_voice`	`auto_test/test_assets/test.wav`	可读 wav 音频

这些文件是"测试上传用"的输入素材。例如测试图片上传、视频上传、声音上传时会读取它们。

3.2 测试模式输出资产

当需要跑带媒体生成链路的 E2E 时，系统提供测试模式：开启后，媒体生成相关接口返回本地样本文件。先把样本文件放到 auto_test/samples/（覆盖文生图、图编、四宫格拼图、多角度图、图生视频、文生视频、数字人、人脸遮盖、TTS、角色音频及世界导入样本等类型，文件名见仓库内现有清单），再执行：

python scripts/prepare_mock_assets.py

脚本会复制到 upload/mock/。临时本地验证时，普通图片类可以复用同一张图，视频类可以复用同一个短 mp4，音频类可以复用同一个 mp3。只有四宫格文件建议单独准备真实的 2x2 拼图（下游会拆成 4 张）。

4. 启用测试模式

系统提供测试模式，可在配置中开启，媒体生成相关 E2E 建议全局开启：

$env:comfyui_env="prod"  # 按实际测试环境设置；不设置时默认写入 dev
$env:E2E_TEST_USER_ID="<测试账号 user_id>"
python scripts/enable_test_mode.py

脚本执行后会：

开启测试模式（媒体生成接口返回本地样本文件）
将测试账号算力设置为可用值（仅测试用途）

注意：

数据库必须可连；配置按 comfyui_env 分环境写入，跑 prod 环境 E2E 前必须设置 $env:comfyui_env="prod"。
开启后建议重启后端服务，避免服务进程读到旧缓存。
auto_test/e2e/conftest.py 也提供了 mock_mode fixture，但现有 E2E 用例尚未统一声明它；跑现有全量测试时仍推荐先执行上面的全局脚本。

5. 启动后端服务

auto_test/test_config.json 默认指向 http://localhost:8000（本地服务）。Windows 开发环境常用：

uv run scripts/launchers/start_windows.py

或直接运行：

start.bat

启动后可先检查：

Invoke-WebRequest http://localhost/api/config/upload
Invoke-WebRequest http://localhost/upload/mock/e2e_text_to_image.png

6. 运行测试

cd auto_test/e2e

# 运行所有 P0 测试
python -m pytest -v -m p0

# 运行指定模块
python -m pytest -v -m auth
python -m pytest -v -m session
python -m pytest -v -m world

# 运行所有测试
python -m pytest -v

# 生成 HTML 报告
python -m pytest -v --html=reports/report.html --self-contained-html

建议第一次不要直接跑全量，先跑无生成链路和小范围生成链路：

cd auto_test/e2e
python -m pytest test_auth.py test_world.py -v
python -m pytest test_audio.py test_grid_image.py -v

E2E 运行前检查清单

[ ] auto_test/test_config.json 的 base_url 指向当前后端服务。

[ ] auto_test/test_assets/test_image.jpg 存在。

[ ] auto_test/test_assets/test.mp4 存在。

[ ] auto_test/test_assets/test.wav 存在。

[ ] auto_test/samples/ 下已准备测试模式所需的样本文件。

[ ] 已运行 python scripts/prepare_mock_assets.py，upload/mock/ 下文件存在。

[ ] 已运行 python scripts/enable_test_mode.py 开启测试模式。

[ ] 开启测试模式后已重启后端服务，或至少等待配置缓存过期。

[ ] 测试账号可登录，且 E2E_TEST_USER_ID 与该账号一致。

[ ] Playwright Chromium 已安装。

[ ] 时间轴相关测试所需 ffmpeg/ffprobe 可用。

常见问题

`mock_mode` 和 `enable_test_mode.py` 的区别

mock_mode 是 pytest fixture，适合新写的 E2E 用例显式声明依赖。
enable_test_mode.py 是全局准备脚本，适合跑现有 E2E 或手工调试。

现有 E2E 用例没有统一声明 mock_mode，所以跑现有用例时优先使用 enable_test_mode.py。

`test_config.json` 里为什么只有图片、视频、音频 3 个资产？

因为它们是测试输入资产，由测试用例主动上传。

文生图、图生视频、TTS 等结果样本是测试模式输出资产，由后端测试模式配置读取，不写在 test_config.json 里。

媒体任务仍然访问真实外部服务

通常是以下原因：

没有执行 enable_test_mode.py
执行后没有重启后端服务，进程缓存仍是旧值
样本文件 URL 没有写入测试模式配置
E2E 用例没有声明 mock_mode，又没有使用全局脚本

四宫格任务完成但角色/场景/道具没有参考图

检查 upload/mock/e2e_grid_2x2.png 是否是真实 2x2 拼图。四宫格测试模式会强制落盘并拆图，如果文件不是有效图片或不是 2x2 布局，下游效果会不可靠。

登录失败或测试账号准备失败

确认：

后端服务和数据库可用。
auto_test/test_config.json 中账号密码正确。
E2E_TEST_USER_ID 是同一个测试账号的 user_id。

Fixture 架构

e2e_config (session) ─── 读取 test_config.json
├── auth_token (session) ─── API 登录获取 token
├── user_id (session) ─── 登录返回的 user_id
├── auth_headers (session) ─── Authorization + X-User-Id
├── browser (session) ─── Playwright chromium 实例
│   └── browser_context (function) ─── 注入 localStorage 认证
│       └── page (function) ─── 独立页面实例
└── api_client (function) ─── httpx.Client
    ├── test_world (function) ─── 创建测试世界，yield 后清理
    │   ├── test_character (function) ─── 创建测试角色
    │   └── test_location (function) ─── 创建测试场景
    ├── test_workflow (function) ─── 创建测试工作流
    └── test_session_id (function) ─── 创建测试会话

关键设计

认证跳过 UI：通过 API 登录获取 token，注入 localStorage，避免反复 UI 登录
API 客户端：使用 httpx.Client（同步），不阻塞服务端事件循环
测试数据工厂：test_world、test_workflow 等 fixture 自动创建和清理测试数据

测试标记

标记	说明
`p0`	P0 核心功能（必须通过）
`p1`	P1 重要功能（应该通过）
`p2`	P2 次要功能（可选通过）
`auth`	认证模块
`session`	会话管理模块
`world`	世界管理模块
`character`	角色管理模块
`location`	场景管理模块
`workflow`	工作流 CRUD 模块
`workflow_page`	工作流前端页面模块
`audio`	音频模块
`script_writer`	剧本编辑器模块
`marketing_agent`	营销智能体模块
`admin`	管理后台模块

模块依赖关系

auth (无依赖)
├── workflow_list
├── world_management
│   ├── location_management
│   └── character_management
├── workflow_editor
│   ├── node_operations
│   │   ├── shot_frame_video
│   │   ├── shot_group_video
│   │   └── camera_control
│   ├── timeline
│   ├── grid_image_generation
│   └── audio
├── error_handling
└── marketing_agent

两种测试方案对比

维度	JSON 测试 (AI 智能体)	pytest E2E (编程式)
驱动方式	AI 解读 JSON，调用 MCP 工具	编程式 Playwright API
执行速度	慢（AI 推理 + MCP 通信）	快（直接 API 调用）
稳定性	受 AI 理解准确性影响	确定性高
适合场景	探索性测试、新功能验证	回归测试、CI/CD
维护方式	JSON 文件编辑	Python 代码

添加新测试

在 e2e/ 目录创建 test_<模块名>.py
使用 conftest.py 中的 fixtures
添加 pytest markers：@pytest.mark.<模块名> 和 @pytest.mark.p0
使用 Page Object 模式操作浏览器页面
更新本文档