webapp-testing

用途

webapp-testing 用于测试本地 Web 应用，通过编写原生 Python Playwright 脚本来验证前端功能、调试 UI 行为、捕获浏览器截图或检查页面状态。

主要能力

使用 Python Playwright 编写自动化测试脚本。
提供辅助脚本 scripts/with_server.py，用于管理服务器生命周期，并支持同时管理多个服务器（例如后端 + 前端）。
支持静态 HTML 与动态 Web 应用两类测试路径。
支持截图、DOM 检查、控制台日志捕获等侦察手段。

使用方式

决策树：选择测试方法

用户任务 → 是否为静态 HTML？

是 → 直接读取 HTML 文件识别选择器
- 成功 → 使用选择器编写 Playwright 脚本
- 失败/不完整 → 按动态应用处理（见下）
否（动态 Web 应用）→ 服务器是否已在运行？
- 否 → 运行 python scripts/with_server.py --help，然后使用该辅助脚本并编写简化的 Playwright 脚本
- 是 → 先侦察后操作：
  1. 导航并等待 networkidle
  2. 截图或检查 DOM
  3. 从渲染状态识别选择器
  4. 使用发现的选择器执行操作

使用 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

创建自动化脚本时，只包含 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()

从检查结果中识别选择器，然后使用发现的选择器执行操作。

常见陷阱

❌ 不要在动态应用上未等待 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 - 在自动化过程中捕获控制台日志

适用场景

验证本地 Web 应用的前端功能。
调试 UI 行为。
捕获浏览器截图。
检查页面渲染状态与 DOM 结构。

限制

资料未提供关于收费、价格、平台支持范围、性能指标或效果保证的信息。