webapp-testing 是一个基于 Playwright 的本地 Web 应用测试工具包。它可以帮助你验证前端功能、调试 UI 行为、捕获浏览器截图以及查看浏览器日志。通过提供辅助脚本和标准化的测试流程，它简化了与本地 Web 应用交互和自动化测试的过程。

使用场景

• 验证本地开发服务器的前端功能是否正常
• 调试动态页面的 UI 渲染行为
• 捕获页面截图用于视觉检查或文档记录
• 查看浏览器控制台日志，排查前端报错
• 对静态 HTML 文件进行自动化交互测试

使用方法

1. 安装/获取工具包：通过 Clone 或 Skill 管理工具添加该 Skill 到你的环境中。

2. 查看辅助脚本用法：所有脚本都应先运行 --help 查看用法，不要直接阅读源码（脚本可能很大，会污染上下文窗口）。

   python scripts/with_server.py --help
   

3. 管理服务器生命周期：如果目标应用尚未运行，使用 with_server.py 自动启动服务器并运行你的自动化脚本。

   单服务器示例：

   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
   

4. 编写 Playwright 测试脚本：只需包含 Playwright 逻辑，服务器已由辅助脚本管理。务必启动 Chromium 无头模式，并等待 networkidle。

   from playwright.sync_api import sync_playwright
   
   with sync_playwright() as p:
       browser = p.chromium.launch(headless=True)
       page = browser.new_page()
       page.goto('http://localhost:5173')
       page.wait_for_load_state('networkidle')
       # 你的自动化逻辑
       browser.close()
   

5. 非动态页面：如果是静态 HTML，可直接读取 HTML 文件来确定选择器，无需启动服务器。

注意事项

• 动态应用必须等待 networkidle 后再检查 DOM，否则可能获取到未完全渲染的内容。
• 尽量使用描述性选择器（如 text=、role=、CSS 或 ID），并适当添加等待。
• 使用 sync_playwright() 编写同步脚本，结束时务必关闭浏览器。
• 优先将辅助脚本作为黑盒调用，仅在必要时才自定义实现。