Webapp testing

何时使用

• 需要真实驱动浏览器与本地 Web 应用交互：验证前端功能、调试 UI 行为、点击/填表/导航、截图、抓取浏览器控制台日志。
• 应用是动态前端（React/Vue/Vite 等需 JS 渲染）或静态 HTML，都适用；可一条命令拉起前后端多个服务再跑测试。
• 触发词：webapp testing、playwright、浏览器自动化、前端测试、UI 调试、网页截图、控制台日志、e2e、headless、本地起服务测试。

不该用的边界：

• 单元测试 / 接口（HTTP API）测试 / 后端逻辑断言 —— 用对应测试框架直接断言，无需开浏览器。
• 对生产线上站点做压测、爬取、负载测试 —— 本技能面向本地开发态验证。
• 纯静态视觉/设计评审、不需要真实渲染 —— 直接读 HTML 即可。
• 远程 CI 已有 e2e 流水线、只想看结果 —— 不在此范围。

步骤 / 指令

先决策再动手（决策树）：

任务 → 是静态 HTML 吗？
  ├─ 是 → 直接读 HTML 文件，定位选择器
  │        ├─ 能定位 → 用 file:// URL 写 Playwright 脚本
  │        └─ 读不全/含动态 JS → 按动态应用处理（见下）
  └─ 否（动态应用）→ 服务是否已在跑？
      ├─ 否 → 先 `python scripts/with_server.py --help`，用它托管服务 + 写精简脚本
      └─ 是 → 侦察后行动：
              1) 导航并等 networkidle
              2) 截图 / 抓 DOM
              3) 从渲染后状态识别选择器
              4) 用选出的选择器执行操作

核心规则：

1. 脚本当黑盒用：scripts/with_server.py 等先跑 --help 看用法再直接调用；不要把脚本源码读进上下文（很长，会污染上下文窗口），仅当确需定制时才读。
2. 服务交给 with_server.py 托管：它会拉起一个或多个服务、轮询端口直到就绪、运行你的命令、结束后清理。你的自动化脚本里只写 Playwright 逻辑，不要自己起服务。
3. chromium 一律 headless 启动，用完务必 browser.close()。
4. 动态应用先等 networkidle 再检查 DOM（关键约束，见注意事项）。
5. 选择器优先用语义化的：text=、role=、CSS、#id；必要时加等待 wait_for_selector() / wait_for_timeout()。

示例

用 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)   # 始终 headless
    page = browser.new_page()
    page.goto('http://localhost:5173')           # 服务已就绪
    page.wait_for_load_state('networkidle')       # 关键：等 JS 执行完
    # ...交互逻辑
    browser.close()                               # 用完务必关闭

侦察后行动（识别选择器）：

page.screenshot(path='/tmp/inspect.png', full_page=True)
content = page.content()
buttons = page.locator('button').all()

抓控制台日志：

page.on("console", lambda msg: console_logs.append(f"[{msg.type}] {msg.text}"))

静态 HTML 用 file:// 直接测：

import os
file_url = f"file://{os.path.abspath('path/to/file.html')}"
page.goto(file_url)               # 静态文件无需起服务，也无需等 networkidle
page.fill('#email', '[email protected]')
page.click('button[type="submit"]')

注意事项

• 动态应用必须先 page.wait_for_load_state('networkidle') 再检查 DOM/截图；过早检查会拿到未渲染的空壳，是最常见的坑。静态 file:// 页面通常不需要。
• chromium 始终 headless，脚本结束务必关闭浏览器，避免残留进程占端口。
• with_server.py 的 --server 与 --port 数量必须一一对应；默认每个服务就绪超时 30 秒，可用 --timeout 调整；命令分隔符 -- 之后才是要运行的命令。
• 截图/日志输出路径用绝对路径；示例里的 /tmp、/mnt/user-data/outputs 按你的环境替换为可写目录（Windows 用 C:\... 或临时目录）。
• 选择器要稳定且具描述性，避免依赖易变的下标顺序；交互后用显式等待而非裸 sleep。
• 源技能为 Apache-2.0，本条目为适配重写；脚本（如 with_server.py、examples/）随源仓库分发，按需调用。

互见

• requires：无。
• related：frontend-design（产出前端界面，本技能负责对其做浏览器层面的功能验证与调试）、web-artifacts-builder（构建 Web 工件后可用本技能跑交互验证）。
• combines_with：code-reviewer（前端改动先静态审查、再用本技能起浏览器实测，形成"审查 + 运行验证"闭环）。