关于 frontend-testing-debugging
面向编码 Agent 的前端工作流技能，涵盖渲染界面的修改、测试与问题排查，并规定浏览器选择、验证步骤、回退规则和 QA 报告格式。
主要功能
- 01前端测试与调试流程
- 02浏览器选择及回退规则
- 03渲染界面验证清单
- 04QA 报告结构
适用场景
- 01测试本地应用交互
- 02排查渲染界面问题
- 03编辑后验证 UI 改动
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/frontend-testing-debugging确认已加载。
附带文件agents/openai.yaml
详细介绍
前端测试调试
调用约定
此技能应能响应普通用户提示词。不要要求用户明确说明 Browser 路由、截图、报告格式或回退策略。
当用户要求使用 Build Web Apps 插件、web dev 插件、frontend dev 插件或前端测试／调试技能来处理已渲染的前端改动、测试或 Bug 调查时，请使用此技能。
以下示例应触发完整工作流：
please make an improvement to the web dashboard transaction search area and use the web dev pluginuse the frontend dev plugin to polish this dashboarddebug this UI with the Build Web Apps plugintest this localhost app and fix the broken interaction
根据简短提示，从代码仓库、当前打开的应用／浏览器 URL、附近文件或正在运行的开发服务器中推断目标界面。如果目标 URL 不明确，请先检查代码仓库脚本和正在运行的本地端口，再向用户询问。
对于任何会改变已渲染前端界面的代码改动，默认执行以下验证循环：
- 确定目标流程。
- 选择下方的 Browser 路径。
- 进行最小且有效的修改。
- 验证渲染后的行为。
- 回复 QA 最终报告。
选择 Browser 路径
首先判断 Browser 是否可用：
- 可用：会话中列出了 Browser 插件和其
browser技能。执行任何浏览器操作前，先阅读并遵循该技能。 - 不可用：未列出 Browser 插件或
browser技能。使用常规 Playwright，并记录Browser plugin not available。 - 调用失败：Browser 看似可用，但技能／运行时、Node REPL JavaScript 设置、标签页获取或导航失败。将其视为 Browser 路径阻塞。
Browser 可用时，请勿先使用常规 Playwright、外部 Chrome 或 shell open。
仅当用户已允许回退，或任务明确允许使用非 Browser 验证时，才可从失败的 Browser 调用切换到常规 Playwright。在这种情况下，报告 Browser 的具体故障和回退决定。
目标流程
浏览器验证前，用一句话定义目标流程：
The flow under test is: [entry route] -> [user action or state] -> [expected rendered result].
如果用户要求进行一般性冒烟测试，请使用：
The flow under test is: app loads -> first meaningful screen renders -> primary visible controls respond without runtime errors.
Browser 插件循环
通过 Browser 技能所述的 Node REPL JavaScript 工具运行 Browser 命令。不要另行设置浏览器路径。除非 Browser 技能另有说明，否则请继续使用同一个标签页绑定。
必需步骤：
- 严格按照 Browser 技能的说明加载 Browser 运行时。
- 使用
agent.browser.nameSession("...")命名会话。 - 使用
agent.browser.tabs.selected()或agent.browser.tabs.new()获取标签页。 - 使用
tab.goto(url)导航。 - 执行所需检查。
- 使用作用域明确的
tab.playwright定位器或 Browser 技能的交互 API 进行操作。 - 修改后调用
await tab.reload()，然后重复检查和失败的交互。
对于每项会改变 UI 的操作，收集能够证明下一状态正确的最简证据：新的 DOM 快照、可见文本／状态、URL 变化、焦点控件、提示消息、模态框、截图或控制台日志。
必需的浏览器检查
在声称渲染后的应用正常运行之前，先执行以下检查：
- 页面身份：
await tab.url()和await tab.title()与预期页面一致。 - 页面非空：
await tab.playwright.domSnapshot()包含有意义的应用内容，而不是空壳。 - 没有框架错误覆盖层：快照或截图中没有显示 Next.js、Vite、Webpack 或框架错误覆盖层。
- 控制台状态正常：
await tab.dev.logs({ levels: ["error", "warn"], limit: 50 })中没有相关应用错误，或已解释每个相关错误。 - 截图证据：
await display(await tab.playwright.screenshot({ fullPage: false }))能够支持视觉方面的声明。 - 交互验证：至少执行一次目标流程交互，并随后检查状态。
对于视觉类工作，条件允许时，添加桌面和一种移动尺寸视口。对于有参考依据的工作，维护一份简短的差异记录：参考证据、渲染证据、修复或有意的偏差。
Playwright 测试循环
当 Browser 不可用，或用户允许在 Browser 调用失败后使用备用方案时，使用此流程。
按以下顺序操作：
- 在
package.json中查找脚本。 - 使用仓库的包管理器启动应用，并确保主机地址与要求完全一致。
- 如果存在仓库的端到端测试脚本，优先使用该脚本。
- 否则，如果已配置 Playwright，则运行
pnpm exec playwright test或对应包管理器命令。 - 如果项目没有 Playwright 工作流，则使用
pnpm exec playwright --version验证 Playwright，然后使用pnpm exec playwright screenshot <url> /tmp/frontend-check.png截图。 - 如需深入调试，在已提交源码之外创建一个小型临时 Playwright 脚本，用于打开 URL、捕获控制台错误、截图并执行目标交互。
- 修改后，重新运行相同的命令或脚本。
除非任务确有需要且用户允许更改依赖，否则不要安装新的浏览器依赖。
验证清单
- 确保主机地址与要求完全一致。
- 验证控件会更新真实的 UI 状态。
- 检查滚动前的首屏，以及条件允许时的桌面和一种移动尺寸视口。
- 检查内容裁切、重叠、文字难以辨认、换行、布局偏移、资源缺失、z-index 问题、滚动陷阱、加载状态陈旧和错误状态。
- 对于有参考依据的工作，对比渲染截图与参考内容，并维护一份简短的差异记录。
- 如果要求进行渲染验证，仅构建通过还不够。
QA 最终响应报告
对于任何非简单的渲染 UI 验证运行，请像 QA 工程师验证代码更改那样撰写最终响应。让用户或 PR 审核者轻松了解更改内容、测试内容、证明更改有效的证据，以及仍未测试的部分。
请采用以下结构：
- 摘要：用一到两条要点说明用户可见的更改，以及 QA 是否通过。
- 环境：URL、视口（一个或多个）、Browser 可用性分类；若使用了 Playwright，还需说明回退原因。
- 已验证的更改：列出更改的文件或界面，以及预期的具体用户可见行为。
- 检查项：用通过/失败表格列出页面身份、空白页面检查、框架覆盖层检查、控制台健康状况、截图证据和交互证明。
- 交互流程：说明已测试的确切交互路径，包括操作的控件或工作流，以及观察到的状态变化。
- 证据：在 QA 部分描述截图证据，然后在响应末尾连续展示实际截图。根据需要加入多张截图，以证明相关的更改前、更改后、交互、响应式、错误或修复状态。
- 命令 / Browser API：列出使用的关键命令和 Browser API 调用顺序，不要倾倒冗长的日志。
- 剩余风险：列出尚未测试的视口、流程、浏览器、数据状态或已知限制。
如果发现问题，请先列出问题发现，再写摘要。每个问题发现都应说明用户看到的内容、复现步骤、截图/DOM/控制台证据、可能的负责人或文件（如已知），以及已完成的修复或仍存在的阻碍。
如果要展示 Browser 截图供用户查看，请通过 Browser 运行时输出或显示截图，以便在聊天中引用。使用 Playwright 截图时，请保存到仓库之外，并在聊天中引用。若多张截图有助于验证不同状态或流程，请一并提供。
不要在文字报告中穿插截图。请在末尾添加简短的截图部分，以连续图片集的形式展示，每行一张图片。仅在有助于说明状态时添加简短标签，例如 Before、After、Filtered results、Empty state 或 Mobile。
默认情况下，不要创建单独的 HTML 报告。只有在用户明确要求时才创建独立报告文件；除非用户明确要求提交相关产物，否则请将文件写在仓库之外。
除非用户明确要求提交相关产物，否则不要在仓库中写入报告、截图、跟踪记录或临时脚本。
相关技能
- 任务涉及设计创作、重新设计或忠实还原已认可的设计方案时，使用
frontend-app-builder。 - 完成重要的 React/Next.js 组件修改后，使用
react-best-practices。 - 普通调试时不要调用 Image Gen。仅当任务需要创建或修改视觉素材，或
frontend-app-builder已在推动从设计概念到实现的还原流程时，才使用 Image Gen。
最终响应
使用上述 QA 最终响应报告格式。保持简洁，但需提供足够具体的证据，让 PR 审核者无需立即重跑验证也能信任结果。
如果 Browser 不可用而使用了 Playwright，请在结尾建议用户安装 Browser 插件，以便通过应用内导航、截图、DOM 快照、控制台日志和交互验证，获得更好的前端开发体验。