Web应用测试:Webapp Testing Skill

一、核心定义与定位

• 技能名称：webapp-testing
• 核心功能：使用 Python Playwright 脚本与本地 Web 应用进行交互。
• 主要能力：
• 验证前端功能（如按钮点击、表单提交）。
• 调试 UI 行为。
• 捕获浏览器截图与日志。
• 管理本地开发服务器的生命周期。

⚠️ 二、核心原则：黑盒调用策略

文档特别强调了一种“黑盒调用”的思维模式，这是使用该技能的关键：

• 原则：不要阅读脚本源代码，直接调用。
• 原因：Helper Scripts 通常很大，阅读它们会严重污染 AI 的上下文窗口（Context Window）。
• 操作指南：
1. 先运行脚本带 --help 参数查看用法。
2. 直接调用脚本执行任务。
3. 除非绝对必要，否则不要去阅读脚本源码。

🧭 三、决策树：如何选择测试路径

文档提供了一个清晰的决策逻辑，帮助确定如何处理不同的 Web 应用场景：

User task → Is it static HTML?    ├─ Yes → Read HTML file directly to identify selectors    │         ├─ Success → Write Playwright script using selectors    │         └─ Fails/Incomplete → Treat as dynamic (below)    │    └─ No (dynamic webapp) → Is the server already running?        ├─ No → Run: python scripts/with_server.py --help        │        Then use the helper + write simplified Playwright script        │        └─ Yes → Reconnaissance-then-action:            1. Navigate and wait for networkidle            2. Take screenshot or inspect DOM            3. Identify selectors from rendered state            4. Execute actions with discovered selectors

1. 任务类型判断：
• 静态 HTML：直接读取文件获取选择器 -> 编写 Playwright 脚本。
• 动态 Web 应用：进入服务器判断流程。
2. 服务器状态判断：
• 导航并等待网络空闲（networkidle）。
• 截图或检查 DOM。
• 从渲染状态中识别选择器。
• 使用发现的选择器执行操作。
• 服务器未运行：使用 scripts/with_server.py 启动服务器，然后编写简化的 Playwright 脚本。
• 服务器已运行：采用 Reconnaissance-then-Action（侦查后行动） 模式：

🛠️ 四、关键工具与实战代码

1. 核心工具：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

2. Playwright 脚本最佳实践

• 必须等待：在检查动态应用的 DOM 之前，必须等待 page.wait_for_load_state('networkidle')，以确保 JavaScript 执行完毕。
• 代码结构：仅包含 Playwright 逻辑，服务器由 Helper 管理。
  
  from playwright.sync_api import sync_playwrightwith sync_playwright() as p:    browser = p.chromium.launch(headless=True) # Always launch chromium in headless mode    page = browser.new_page()    page.goto('http://localhost:5173') # Server already running and ready    page.wait_for_load_state('networkidle') # CRITICAL: Wait for JS to execute    # ... your automation logic    browser.close()

💡 五、避坑指南与最佳实践

• 常见陷阱：在动态应用加载完成前检查 DOM。这会导致找不到元素或获取错误的静态内容。
• 最佳实践：
• 同步模式：使用 sync_playwright()。
• 资源清理：任务完成后务必关闭浏览器。
• 选择器策略：优先使用描述性选择器（如 text=, role=, CSS 选择器或 ID）。
• 等待机制：使用 page.wait_for_selector() 或 page.wait_for_timeout() 确保元素就绪。

📚 六、参考示例

文档提及 examples/ 目录下包含具体实现参考：

• element_discovery.py：页面元素（按钮、链接）发现。
• static_html_automation.py：本地 HTML 文件处理。
• console_logging.py：自动化过程中的控制台日志捕获。

总结：该文档不仅提供了工具，更定义了一套“AI 驱动的测试工程规范”，核心在于通过“黑盒调用”保持上下文精简，并通过严格的“等待-侦查-行动”流程来解决动态网页自动化测试的痛点。

开源资料：

https://github.com/anthropics/skills/tree/main/skills/webapp-testing