PlexPlaylistSync/tests/UI_QUICKSTART.md

🎭 UI 集成测试快速开始

📦 安装

# 1. 安装 Python 依赖
pip install -r requirements.txt

# 2. 安装 Playwright 浏览器
playwright install chromium

# 或安装所有浏览器
playwright install

🚀 运行测试

启动服务器

# 终端 1: 启动应用
uvicorn app.main:app --reload --port 8000

运行 UI 测试

# 终端 2: 运行测试

# 无头模式（后台运行，快速）
pytest tests/test_ui_regex_rules.py -v

# 有头模式（显示浏览器，便于调试）
pytest tests/test_ui_regex_rules.py -v --headed

# 慢速模式（每个操作间隔 500ms，方便观察）
pytest tests/test_ui_regex_rules.py -v --headed --slowmo=500

📊 测试内容

✅ 基础交互 (8 个测试)

• 页面加载
• 添加/删除规则
• 保存规则
• 规则持久化
• 表单验证
• 规则顺序

✅ 复杂场景 (2 个测试)

• Windows → Linux 路径转换
• NAS 路径规范化

✅ 性能测试 (1 个测试)

• 添加 20 个规则性能

🎯 快速示例

# 运行单个测试（有头模式，便于观察）
pytest tests/test_ui_regex_rules.py::TestRegexRulesUI::test_add_single_rule -v --headed

# 运行 NAS 场景测试
pytest tests/test_ui_regex_rules.py::TestComplexScenarios::test_nas_path_normalization -v --headed

# 调试模式（带 Playwright Inspector）
PWDEBUG=1 pytest tests/test_ui_regex_rules.py::TestRegexRulesUI::test_add_single_rule

🐛 调试技巧

1. 截图调试

测试失败时会自动保存截图到 tests/screenshots/

2. 慢速观察

pytest tests/test_ui_regex_rules.py --headed --slowmo=1000 -v

3. 交互式调试

PWDEBUG=1 pytest tests/test_ui_regex_rules.py -k test_add_single_rule

4. 查看追踪

# 在测试中添加
context.tracing.start(screenshots=True, snapshots=True)
# ... 测试代码 ...
context.tracing.stop(path="trace.zip")

然后查看:

playwright show-trace trace.zip

📝 编写新测试

def test_my_feature(page: Page):
    """测试我的功能"""
    # 1. 与元素交互
    page.locator("#myButton").click()
    
    # 2. 填写表单
    page.locator("input[name='pattern']").fill("test")
    
    # 3. 验证结果
    expect(page.locator("#result")).to_have_text("Success")

🎨 选择器参考

# 通过 ID
page.locator("#addRuleBtn")

# 通过文本
page.locator("button:has-text('保存规则')")

# 通过 CSS 类
page.locator(".rule-row")

# 通过属性
page.locator("input[name='pattern']")

# 组合选择器
page.locator(".rule-row input[name='pattern']")

# 获取第一个/最后一个
page.locator(".rule-row").first
page.locator(".rule-row").last

# 获取第 N 个
page.locator(".rule-row").nth(2)

⚡ 常用命令

# 运行所有 UI 测试
pytest tests/test_ui_regex_rules.py -v

# 运行特定测试类
pytest tests/test_ui_regex_rules.py::TestRegexRulesUI -v

# 运行标记为 slow 的测试
pytest tests/test_ui_regex_rules.py -m slow -v

# 跳过 slow 测试
pytest tests/test_ui_regex_rules.py -m "not slow" -v

# 失败时进入调试器
pytest tests/test_ui_regex_rules.py --pdb

# 只运行失败的测试
pytest tests/test_ui_regex_rules.py --lf -v

📚 相关文档

• 详细指南: tests/UI_TESTING_GUIDE.md
• Playwright 文档: https://playwright.dev/python/
• pytest-playwright: https://github.com/microsoft/playwright-pytest

🎉 开始测试

# 一行命令开始
uvicorn app.main:app --port 8000 & \
sleep 3 && \
pytest tests/test_ui_regex_rules.py -v --headed