用途
本工具包用于与本地 Web 应用进行交互和测试，基于 Playwright 实现。它面向需要验证前端功能、调试 UI 行为、捕获控制台日志等场景，通过编写原生 Python Playwright 脚本来完成自动化测试。
主要能力
- 验证前端功能与 UI 行为
- 调试 UI 行为
- 捕获控制台日志
- 管理本地服务器生命周期（支持同时管理多个服务器）
- 提供辅助脚本 scripts/with_server.py 用于启动服务器并运行自动化脚本
使用方式
辅助脚本
工具包提供 scripts/with_server.py 用于管理服务器生命周期，支持多个服务器。使用前应先运行 --help 查看用法，不要直接阅读源码，因为这些脚本可能很大，会污染上下文窗口。它们被设计为黑盒脚本直接调用。
单服务器示例：
python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py
多服务器示例（例如后端 + 前端）：
python scripts/with_server.py \
--server "cd backend && python server.py" --port 3000 \
--server "cd frontend && npm run dev" --port 5173 \
-- python your_automation.py
决策树：选择方法
用户任务 → 是否为静态 HTML？
- 是 → 直接读取 HTML 文件识别选择器
- 成功 → 使用选择器编写 Playwright 脚本
- 失败/不完整 → 按动态应用处理（见下）
- 否（动态 Web 应用）→ 服务器是否已在运行？
- 否 → 运行：python scripts/with_server.py --help，然后使用辅助脚本并编写简化的 Playwright 脚本
- 是 → 先侦察后操作：
- 导航并等待 networkidle
- 截图或检查 DOM
- 从渲染状态识别选择器
- 使用发现的选择器执行操作
自动化脚本写法
创建自动化脚本时，只包含 Playwright 逻辑（服务器由辅助脚本自动管理）：
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(headless=True) # 始终以无头模式启动 chromium
page = browser.new_page()
page.goto('http://localhost:5173') # 服务器已运行并就绪
page.wait_for_load_state('networkidle') # 关键：等待 JS 执行
# ... 你的自动化逻辑
browser.close()
先侦察后操作模式
检查渲染后的 DOM：
page.screenshot(path='/tmp/inspect.png', full_page=True)
content = page.content()
page.locator('button').all()
从检查结果中识别选择器，然后使用发现的选择器执行操作。
适用场景
- 本地 Web 应用的前端功能验证
- UI 行为调试
- 控制台日志捕获
- 需要启动本地服务器并进行端到端自动化测试的场景
- 静态 HTML 页面的自动化测试
限制与注意事项
- 常见陷阱：不要在动态应用上未等待 networkidle 就检查 DOM；应先执行 page.wait_for_load_state('networkidle') 再检查。
- 最佳实践：
- 将捆绑脚本作为黑盒使用，考虑 scripts/ 中的脚本能否帮助完成任务，这些脚本可靠地处理常见复杂工作流，且不会使上下文窗口混乱。使用 --help 查看用法后直接调用。
- 使用 sync_playwright() 编写同步脚本。
- 完成后始终关闭浏览器。
- 使用描述性选择器：text=、role=、CSS 选择器或 ID。
- 添加适当的等待：page.wait_for_selector() 或 page.wait_for_timeout()。
参考文件
examples/ 目录包含常见模式示例：
- element_discovery.py - 发现页面上的按钮、链接和输入框
- static_html_automation.py - 使用 file:// URL 处理本地 HTML
- console_logging.py - 在自动化过程中捕获控制台日志