WebApp Testing Skill

概述

WebApp Testing Skill 是 Anthropic 官方发布的 Claude Skills 之一,旨在使用 Playwright 与本地 Web 应用程序交互和测试。此 Skill 提供全面的工具和模式,用于验证前端功能、调试 UI 行为、捕获浏览器截图和查看浏览器日志。

该 Skill 强调对动态 Web 应用程序的侦察后行动方法,以及自动管理服务器生命周期的辅助脚本,使编写专注的测试脚本变得容易,而无需担心基础设施。

核心功能

1. Playwright 自动化

使用 Playwright 完成浏览器自动化:

• 导航并与网页交互
• 点击按钮、填写表单、提交数据
• 等待元素和页面状态
• 捕获截图和页面内容
• 监控控制台日志和网络活动

2. 服务器生命周期管理

辅助脚本 (with_server.py) 处理:

• 单服务器: 启动一个开发服务器
• 多服务器: 同时启动后端 + 前端
• 端口管理: 自动端口可用性检测
• 自动清理: 测试后优雅的服务器关闭

3. 方法选择决策树

选择正确测试方法的明确指导:

• 静态 HTML: 直接读取文件,然后编写 Playwright 脚本
• 动态 Webapp: 使用服务器辅助 + 侦察模式
• 已经运行: 导航,等待 networkidle,然后交互

4. 侦察后行动模式

对于动态应用程序:

1. 导航并等待 networkidle
2. 截图或检查 DOM
3. 从渲染状态识别选择器
4. 使用发现的选择器执行操作

5. 示例脚本

常见模式的参考实现:

• element_discovery.py: 查找按钮、链接和输入
• static_html_automation.py: 对本地 HTML 使用 file:// URL
• console_logging.py: 在自动化期间捕获控制台日志

使用场景

• 前端测试: 验证 UI 功能和用户流程
• 回归测试: 确保更改不会破坏现有功能
• 跨浏览器测试: 跨 Chromium、Firefox、WebKit 测试
• 可视化测试: 捕获截图以进行视觉回归
• 集成测试: 测试前端-后端集成
• 调试: 调查 UI 问题和行为
• 演示录制: 捕获交互流程

技术实现

服务器管理

# 单服务器
python scripts/with_server.py --server "npm run dev" --port 5173 -- python test.py

# 多服务器(后端 + 前端)
python scripts/with_server.py \
  --server "cd backend && python server.py" --port 3000 \
  --server "cd frontend && npm run dev" --port 5173 \
  -- python test.py

Playwright 脚本结构

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()

选择器策略

使用描述性选择器以提高可靠性:

• text=: 按文本内容匹配
• role=: 按 ARIA 角色匹配
• CSS 选择器: 标准 CSS 选择
• ID: 最具体的选择

最佳实践

始终先运行 --help

在使用辅助脚本之前:

python scripts/with_server.py --help

这显示使用方法和可用选项,而无需读取大型���文件。

使用黑盒方法

辅助脚本设计为直接调用:

• 除非绝对必要,否则不要读取源代码
• 保持上下文窗口干净
• 脚本可靠地处理复杂的工作流程

等待 networkidle

对动态应用程序至关重要:

page.wait_for_load_state('networkidle')

在检查 DOM 或与元素交互之前等待。

使用 sync_playwright

用于同步测试脚本:

• 更易于编写和调试
• 清晰的顺序流程
• 更简单的错误处理

适当的浏览器清理

完成后始终关闭浏览器:

browser.close()

添加适当的等待

根据需要等待元素或超时:

page.wait_for_selector('#element-id')
page.wait_for_timeout(1000)  # 毫秒

决策树

用户任务 → 是静态 HTML 吗?
    ├─ 是 → 直接读取 HTML 文件以识别选择器
    │         ├─ 成功 → 使用选择器编写 Playwright 脚本
    │         └─ 失败/不完整 → 视为动态(下面)
    │
    └─ 否(动态 webapp) → 服务器已经在运行吗?
        ├─ 否 → 运行: python scripts/with_server.py --help
        │        然后使用辅助 + 编写简化的 Playwright 脚本
        │
        └─ 是 → 侦察后行动:
            1. 导航并等待 networkidle
            2. 截图或检查 DOM
            3. 从渲染状态识别选择器
            4. 使用发现的选择器执行操作

常见陷阱

不要在动态应用上等待 networkidle 之前检查 DOM:

# ❌ 错误
page.goto('http://localhost:3000')
page.content()  # 可能获得部分/不完整的内容

# ✅ 正确
page.goto('http://localhost:3000')
page.wait_for_load_state('networkidle')
page.content()  # 获得完整的渲染内容

参考文件

位于 examples/ 目录:

• element_discovery.py: 发现页面元素
• statichtmlautomation.py: 测试静态 HTML 文件
• console_logging.py: 捕获控制台输出

总结

WebApp Testing Skill 使 Claude 能够使用 Playwright 有效地测试本地 Web 应用程序并与之交互。通过服务器生命周期管理、侦察后行动模式和全面的示例,此 Skill 使编写可靠的自动化脚本变得容易,用于测试、调试和验证前端功能。