PlexPlaylistSync/tests/UI_TEST_MIGRATION_GUIDE.md

UI测试迁移指南

概述

本文档说明了UI测试从旧版本迁移到新React前端的主要变更。

主要变更

1. 输出目录变更

旧版本:

dockerapp/test_playlists/{playlist_name}/

新版本:

output_playlists/{playlist_name}/

2. 服务器端口变更

旧版本:

• 测试服务器: http://localhost:8000

新版本:

• Docker映射端口: http://localhost:8888
• 容器内端口: 8080

3. UI架构变更

旧版本:

• 传统的HTML模板 (Jinja2)
• 选择器: #addRuleBtn, select[name='mode'], input[name='pattern']

新版本:

• React + TypeScript + Vite
• 策略选择器: 中间位置的圆形按钮下拉菜单
• 正则规则在StrategySelector组件中管理
• 选择器: button[title='Add Rule'], input[placeholder='Regex Pattern']

4. 测试文件修改

conftest_ui.py

• 更新BASE_URL为http://localhost:8888
• 修改server fixture为仅验证服务器运行状态
• 要求手动启动Docker Compose服务

test_ui_case_mix.py

• 添加SyncStrategy枚举类
• 实现_open_strategy_selector()和_close_strategy_selector()辅助函数
• 更新策略选择逻辑以适配React UI
• 更新正则规则添加逻辑
• 修改输出路径为output_playlists/case_mix/

test_ui_regex_rules.py

• 完全重写所有测试用例以适配React UI
• 添加辅助方法_open_strategy_selector()和_close_strategy_selector()
• 更新所有选择器以匹配新UI结构
• 适配Toast通知验证

运行测试

前提条件

1. 启动Docker Compose服务:

   docker compose up -d
   

2. 验证服务运行:

   # 在浏览器中访问
   # http://localhost:8888
   

3. 安装测试依赖:

   pip install pytest-playwright requests
   playwright install
   

运行测试

显示浏览器模式 (调试用):

pytest tests/test_ui_case_mix.py --headed
pytest tests/test_ui_regex_rules.py --headed

无头模式 (CI/CD):

pytest tests/test_ui_case_mix.py
pytest tests/test_ui_regex_rules.py

运行所有UI测试:

pytest tests/test_ui_*.py --headed

新UI元素定位

策略选择器

• 触发按钮: button with SVG icon (圆形按钮)
• 下拉菜单: div.absolute.top-14
• 策略选项: div:has-text('{strategy_label}') with SVG

正则规则

• 添加按钮: button[title='Add Rule'] 或 button:has-text('Add Rule')
• 删除按钮: button[title='Delete Rule']
• 模式输入: input[placeholder='Regex Pattern']
• 替换输入: input[placeholder='Replacement']
• 保存按钮: button:has-text('Save Changes')
• 重置按钮: button:has-text('Revert')

Toast通知

• 成功通知: div:has-text('Regex preprocessing rules have been saved')
• 策略保存: div:has-text('Selected strategy "{label}" has been saved')

策略映射

UI显示名称	SyncStrategy枚举	旧版mode值	预期输出文件
Local Overwrite	LOCAL_OVERWRITE	local_force	case_mix_local_force.m3u
Cloud Overwrite	CLOUD_OVERWRITE	remote_force	case_mix_remote_force.m3u
Two-way Merge (Local Priority)	MERGE_LOCAL	merge_local_primary	case_mix_merge_local_primary.m3u
Two-way Merge (Cloud Priority)	MERGE_CLOUD	merge_remote_primary	case_mix_merge_remote_primary.m3u

已知问题和注意事项

1. 同步触发: 新UI需要通过API显式触发同步操作。测试中使用 POST /api/sync 端点:

   import requests
   sync_response = requests.post(
       f"{BASE_URL}/api/sync",
       json={"mode": None}  # 使用当前配置的策略
   )
   

2. Toast通知: Toast通知有动画效果，需要适当的等待时间 (300-500ms)。

3. 下拉菜单: 策略选择器的下拉菜单需要通过ESC键关闭，或点击外部区域。

4. 测试隔离: 每个测试应该清理自己添加的规则，避免影响后续测试。

故障排除

服务器未运行

错误: 无法连接到测试服务器: http://localhost:8888
解决: docker compose up -d

元素未找到

错误: Timeout waiting for locator('button[title="Add Rule"]')
解决: 检查策略选择器是否已打开，确保调用了_open_strategy_selector()

输出文件未生成

错误: AssertionError: {strategy_label}: local_result.m3u8 未生成
解决: 
1. 检查output_playlists/case_mix/目录是否存在
2. 验证Docker volume映射配置
3. 检查后端日志: docker compose logs

更新日期

2024-11-29 - 初始迁移完成