用途
Playwright Screenshot Inspector 是一个由 LLM 驱动的视觉测试专家技能，面向使用 Playwright 进行自动化截图捕获、分析与 UI 验证的场景。其核心理念是：传统视觉测试比较像素，而 LLM 驱动的视觉测试理解语义。它不再只报告“这 50 个像素变了”，而是回答“内容是否真的渲染了”“主题切换是否正确”“交互元素是否可见且样式正确”“哪些是损坏、哪些只是不同”。
主要能力
该技能围绕“截图检查循环”展开，包含四个步骤：
- 捕获（Playwright）：等待 React 水合，而不仅仅是网络空闲。
- 读取（Claude 视觉）：将截图连同具体问题传给 LLM。
- 分析（结构化响应）：提取内容是否存在、主题是否正确、是否有错误等信息。
- 行动（条件逻辑）：基于语义理解判定通过或失败。
它提供多种 LLM 截图分析模式：
- 内容验证：判断主内容是否渲染（非空白/加载中）、可见的主要 UI 元素、是否存在错误状态或布局损坏，并给出内容完整度评级（FULL / PARTIAL / EMPTY）。
- 主题合规：验证背景色是否符合预期主题、文字对比度是否足够、交互元素是否可见且样式正确、是否存在主题泄漏。
- 对比分析：比较前后两张截图，识别变化内容、判断变化是预期（如主题切换）还是缺陷、检查“之后”版本是否缺失内容，并给出相似度评级（IDENTICAL / MINOR_DIFF / MAJOR_DIFF / BROKEN）。
- 可访问性检查：评估文字可读性、交互元素可识别性、视觉层级，以及是否存在可能不满足 WCAG 对比度要求的元素。
使用方式
该技能通过激活触发词启用，包括：“screenshot test”“visual test”“screenshot inspection”“playwright headless”“playwright screenshot”“UI verification”“visual regression”“theme compliance test”“dark mode test”“light mode test”“automated screenshot”“capture and analyze”“compare screenshots”“visual diff”。
使用中强调几个关键实践：
- 等待实际内容：截图前应等待 React 挂载。反模式是仅等待 networkidle，可能导致截图空白。正确做法是先等待 domcontentloaded 和 networkidle，再留出 React 水合缓冲时间，然后等待实际内容选择器可见，并验证 body 文本长度。
- 无头模式：始终使用 headless=True 以防止浏览器窗口弹出。
- 主题测试：在 page 上调用 emulate_media(color_scheme='dark'/'light')，而非在 context 上，然后重新加载并等待内容。
- 完整测试脚本模板：技能附带一个 Python 脚本模板，定义待测页面列表、基础 URL、截图目录，包含等待内容函数、主题截图捕获函数和测试运行函数，并收集控制台错误、输出通过统计。
技能还提供 MCP 与原生 Playwright 的决策树：交互式调试/探索用 Playwright MCP；自动化测试套件、CI/CD 流水线、供 LLM 分析的截图捕获用原生 Python Playwright（无头）；一次性检查两者皆可。
适用场景
- 自动化视觉测试套件
- CI/CD 流水线中的 UI 验证
- 深色/浅色主题合规测试
- 截图前后对比与视觉回归的语义分析
- 供 LLM 进行语义分析的截图捕获
限制
该技能明确不适用于：
- 简单的一次性截图（应使用浏览器 DevTools）
- 无需 AI 的像素级精确对比（应使用原生 Playwright 的 toHaveScreenshot）
- 非 Web UI 测试（应使用平台特定工具）
- 性能测试（应使用 Lighthouse/WebPageTest）
常见失败与修复包括：空白截图（原因：React 水合前截图；修复：等待内容选择器并加水合缓冲）、出现“Reconnecting...”徽章（原因：HMR/WebSocket 未连接，测试中通常无碍）、主题未应用（原因：在 context 而非 page 上调用 emulate_media；修复：使用 page.emulate_media）、浏览器窗口弹出（原因：headless=False 或使用 MCP；修复：使用 headless=True）、内容超时（原因：选择器错误或页面确实损坏；修复：验证选择器存在并检查控制台错误）。
版本历史
2026-01-23：初始技能创建，研究多模态 LLM 截图分析最佳实践，记录 React 水合等待模式，添加无头模式要求，创建完整测试脚本模板。
核心洞见：无用与有用的截图测试之间的区别在于等待内容，而不仅仅是网络。LLM 可以分析语义，但前提是确实有内容可供分析。