Geruyang/agent-skills-library

前端测试与调试

调用约定

该技能应响应用户的正常提示。不要要求用户明确指定浏览器路由、截图、报告格式或回退策略。

当用户要求使用“构建 Web 应用”插件、Web 开发插件、前端开发插件或前端测试/调试技能来处理渲染后的前端变更、测试或 bug 调查时，使用此技能。

应触发完整工作流的示例：

• 请对 Web 仪表板的交易搜索区域进行改进，并使用 Web 开发插件
• 使用前端开发插件打磨这个仪表板
• 使用“构建 Web 应用”插件调试此 UI
• 测试此 localhost 应用并修复损坏的交互

根据简短的提示，从仓库、当前打开的应用程序/浏览器 URL、附近文件或正在运行的开发服务器推断目标页面。如果目标 URL 不明确，请在询问用户之前先检查仓库脚本和正在运行的本地端口。

对于对渲染的前端界面所做的任何代码更改，默认执行验证循环：

1. 确定目标流。
2. 选择下面的浏览器路径。
3. 进行最小有效的编辑。
4. 验证渲染行为。
5. 回复 QA 最终响应报告。

选择浏览器路径

首先对浏览器可用性进行分类：

• 可用：会话中列出了浏览器插件及其 browser 技能。在进行任何浏览器操作之前，先阅读并遵循该技能。
• 不可用：未列出浏览器插件或 browser 技能。使用常规 Playwright 并记录 浏览器插件不可用。
• 调用失败：浏览器似乎可用，但技能/运行时、Node REPL JavaScript 设置、选项卡获取或导航失败。将此视为浏览器路径阻塞器。

当浏览器可用时，不要首先使用常规 Playwright、外部 Chrome 或 shell open。

仅当用户已允许回退或任务明确允许非浏览器验证时，才从失败的浏览器调用切换到常规 Playwright。在这种情况下，报告确切的浏览器失败和回退决策。

目标流

在进行浏览器验证之前，用一句话定义目标流：

测试中的流是：[入口路由] -> [用户操作或状态] -> [预期的渲染结果].

如果用户要求进行一般的冒烟测试，则使用：

测试中的流是：应用加载 -> 第一个有意义的屏幕渲染 -> 主要可见控件无运行时错误地响应.

浏览器插件循环

通过浏览器技能描述的 Node REPL JavaScript 工具运行浏览器命令。不要发明单独的浏览器设置路径。除非浏览器技能另有说明，否则继续使用相同的选项卡绑定。

必需的顺序：

1. 完全按照浏览器技能的指示加载浏览器运行时。
2. 使用 agent.browser.nameSession("...") 命名会话。
3. 使用 agent.browser.tabs.selected() 或 agent.browser.tabs.new() 获取选项卡。
4. 使用 tab.goto(url) 导航。
5. 运行下面所需的检查。
6. 使用作用域内的 tab.playwright 定位器或浏览器技能交互 API 进行交互。
7. 编辑后，调用 await tab.reload()，然后重复检查和有问题的交互。

对于每个更改 UI 的操作，收集最便宜的证明来证明下一个状态是正确的：最新的 DOM 快照、可见文本/状态、URL 更改、焦点的控件、toast、模态框、截图或控制台日志。

必需的浏览器检查

在声称渲染的应用正常工作之前，请运行这些检查：

1. 页面身份：await tab.url() 和 await tab.title() 与预期页面匹配。
2. 非空白：await tab.playwright.domSnapshot() 包含有意义的应用内容，而不是空壳。
3. 无框架覆盖：快照或截图不显示 Next.js、Vite、Webpack 或框架错误覆盖。
4. 控制台健康：await tab.dev.logs({ levels: ["error", "warn"], limit: 50 }) 没有相关的应用错误，或者每个相关错误都有解释。
5. 截图证据：await display(await tab.playwright.screenshot({ fullPage: false })) 支持视觉声明。
6. 交互证明：至少执行了一个目标流交互，并随后进行了状态检查。

对于视觉工作，在可行时添加桌面视图和一个移动尺寸视图。对于基于参考的工作，维护一个简短的差异记录：参考证据、渲染证据、修复或有意的偏差。

Playwright 循环

当浏览器不可用时，或者在浏览器调用失败后用户允许回退时，使用此分支。

按此顺序操作：

1. 在 package.json 中查找脚本。
2. 使用仓库的包管理器启动应用，并保持请求的主机准确。
3. 如果存在，优先使用仓库的 e2e 脚本。
4. 否则，当 Playwright 已配置时，运行 pnpm exec playwright test 或等效于包管理器的命令。
5. 如果没有项目 Playwright 工作流，使用 pnpm exec playwright --version 验证 Playwright，然后使用 pnpm exec playwright screenshot <url> /tmp/frontend-check.png 捕获截图。
6. 对于更深入的调试，在提交的源代码之外创建一个小的临时 Playwright 脚本，该脚本打开 URL、捕获控制台错误、截图并运行目标交互。
7. 编辑后，重新运行相同的命令或脚本。

除非任务需要并且用户允许依赖项更改，否则不要安装新的浏览器依赖项。

验证检查清单

• 保持请求的主机准确。
• 验证控件更新真实的 UI 状态。
• 在滚动前检查第一个视口，并在可行时检查桌面视图和一个移动尺寸视口。
• 查找裁剪、重叠、不可读文本、换行、布局偏移、丢失的资源、z-index 问题、滚动陷阱、过时的加载和损坏的状态。
• 对于基于参考的工作，将渲染的截图与参考进行比较，并维护一个简短的差异记录。
• 当请求了渲染验证时，仅仅构建通过是不够的。

QA 最终响应报告

对于任何非平凡的渲染 UI 验证运行，请像 QA 工程师验证代码更改一样编写最终响应。该响应应使用户或 PR 审阅者轻松了解更改了什么、测试了什么、什么证据证明了它以及什么尚未测试。

使用此格式：

• 摘要：一两个要点解释用户可见的更改以及 QA 是否通过。
• 环境：URL、视口、浏览器可用性分类以及如果使用 Playwright 时的回退原因。
• 已验证的更改：更改的文件或页面，以及预期的面向用户的行为。
• 检查：页面身份、空白页检查、框架覆盖检查、控制台健康、截图证据和交互证明的通过/失败表。
• 交互循环：测试的确切交互路径，包括执行的控件或工作流以及观察到的状态更改。
• 证据：在 QA 部分描述截图证据，然后将实际截图作为连续图像放在响应的末尾。包含尽可能多的有用截图来证明相关的之前、之后、交互、响应式、错误或修复状态。
• 命令/浏览器 API：列出使用的关键命令和浏览器 API 序列，无需转储嘈杂的日志。
• 剩余风险：未测试的视口、流程、浏览器、数据状态或已知限制。

如果发现问题，请在摘要之前以发现开头。每个发现应包括用户看到的内容、重现步骤、截图/DOM/控制台证据、已知时的所有者或文件，以及所做的修复或剩余的阻塞器。

当使用应显示给用户的浏览器截图时，通过浏览器运行时发出或显示截图，以便可以在聊天中引用。当使用 Playwright 截图时，将它们保存在仓库外部并在聊天中引用。当它们有助于验证不同的状态或流程时，包括多个截图。

不要在整个书面报告中穿插截图。在末尾放置一个简短的截图部分，并将其设为连续图片库，每行一张图片。仅在需要澄清状态时添加简短标签，例如 之前、之后、过滤结果、空状态 或 移动端。

默认情况下不要创建单独的 HTML 报告。仅当用户明确要求时才创建独立的报告文件，并将其写在仓库外部，除非用户明确要求提交工件。

除非用户明确要求提交工件，否则不要将报告、截图、跟踪或临时脚本写入仓库。

相关技能

• 当任务是设计创作、重新设计或对已接受概念保真时，使用 frontend-app-builder。
• 在进行有意义的 React/Next.js 组件编辑后，使用 react-best-practices。
• 不要为普通的调试调用图像生成。仅当任务需要创建或修改视觉资源，或者 frontend-app-builder 已经在驱动从概念到实现的保真循环时，才使用它。

最终响应

使用上面的 QA 最终响应报告格式。保持简洁，但包含足够的具体证据，以便 PR 审阅者在不立即重新运行的情况下可以信任验证。

如果浏览器不可用并且使用了 Playwright，最后建议用户安装浏览器插件以获得更好的前端开发体验，包括应用内导航、截图、DOM 快照、控制台日志和交互验证。