前言¶
改完前端样式或交互之后，最常见的验证方式是：手动打开浏览器，看一眼页面，再打开 DevTools 扫控制台和 Network。流程不复杂，但一来回就要离开编辑器，改一轮验一轮，容易漏掉布局错位、 hydration 报错或接口 4xx。
Cursor 的 Agent 自带浏览器能力，可以通过内置的 cursor-ide-browser MCP 打开页面、截图、读控制台、查网络请求。社区仓库 spencerpauly/awesome-cursor-skills 里的 visual-qa-testing Skill，把这套检查写成固定工作流，让 Agent 在改完 UI 后按步骤做一轮视觉 QA，而不必你反复切换窗口。
本文基于该 Skill 的 SKILL.md 原文，以及 Cursor 官方 Browser / Agent Skills 文档整理，说明它是什么、怎么装、怎么用。
这是什么¶
visual-qa-testing 是一份面向 Agent 的视觉 QA 操作说明。官方描述是：在 Cursor 内置浏览器中启动 Web 应用，截图、检查控制台错误，并审计网络请求；适合在做出 UI 改动之后，验证页面是否看起来正确。
它收录在社区维护的 Skill 合集 awesome-cursor-skills 的 resources/visual-qa-testing/ 目录下，本身只有一个 SKILL.md 文件，没有额外脚本。Skill 并不替代 Playwright、Cypress 这类自动化测试框架，而是把「打开页面 → 看图 → 看日志 → 看请求」这条人工检查路径，固化成 Agent 可执行的步骤。
Agent Skills 是开放标准。Cursor 会从项目级或用户级的 skills 目录自动发现 SKILL.md；同一套格式也可放到 Claude Code、Codex 等兼容目录。需要注意的是：本 Skill 明确依赖 Cursor 的内置浏览器工具，在其他环境若没有等价的 browser MCP，完整流程可能无法按原文执行。
核心能力¶
根据 SKILL.md，这套流程主要做以下几件事：
-
确认开发服务已启动
Agent 会先检查是否已有终端在跑 dev server；没有则在后台执行npm run dev，并等待输出里出现 ready 或 localhost 地址。 -
导航到目标页面并截图
使用browser_navigate打开本地地址（例如http://localhost:3000），可顺带截图；再用browser_take_screenshot（可设fullPage: true）抓取整页，用于检查布局断裂、内容缺失、颜色不对、元素错位等问题。 -
检查控制台
通过browser_console_messages读取控制台信息，重点关注TypeError、ReferenceError、失败的 import，以及 React hydration mismatch 等。 -
审计网络请求
通过browser_network_requests查看请求，关注 4xx/5xx、CORS 错误、异常大的响应，以及不必要的重复请求。 -
按需交互后再验一次
若改动涉及按钮、表单、弹窗等，可用browser_click、browser_fill、browser_hover操作，再截图确认结果。 -
汇总报告
最后从界面是否正常、控制台是否干净、网络是否健康三方面给出结论。
Cursor 官方 Browser 文档也确认：Agent 可以导航、点击、输入、截图、读取控制台与网络流量，并且会尽量识别已有的开发服务端口，避免重复启动。这与该 Skill 的设计是对齐的。
安装与启用¶
用 npx skills 安装¶
skills.sh 与 vercel-labs 的 skills CLI 提供的安装命令如下：
npx skills add https://github.com/spencerpauly/awesome-cursor-skills --skill visual-qa-testing
若目标是 Claude Code，社区镜像页也给出过带 --agent claude-code 的写法，会安装到项目的 .claude/skills/。以你实际使用的 Agent 与 CLI 帮助信息为准。
手动放到 Cursor 的 skills 目录¶
按 Cursor Agent Skills 文档，Skill 会被自动加载的位置包括：
| 位置 | 作用范围 |
|---|---|
.agents/skills/ |
项目级 |
.cursor/skills/ |
项目级 |
~/.agents/skills/ |
用户级（全局） |
~/.cursor/skills/ |
用户级（全局） |
为兼容其他工具，Cursor 也会从 .claude/skills/、.codex/skills/ 以及对应的用户级目录加载。每个 Skill 是一个包含 SKILL.md 的文件夹，例如：
.cursor/skills/visual-qa-testing/SKILL.md
你也可以在 Cursor 侧边栏 Customize → Rules 中选择 Remote Rule (Github)，填入仓库地址导入（文档说明 Skills 可通过 GitHub 仓库链接安装）。
安装后，在 Agent 聊天里输入 /，搜索 visual-qa-testing 可手动调用；Agent 也可能根据上下文在改 UI 后自动选用相关 Skill。
典型用法¶
改完某个页面后，可以直接对 Agent 说类似：
我刚改了 /settings 页的布局，用 visual-qa-testing 做一轮视觉 QA。
或显式输入 /visual-qa-testing。按官方 SKILL.md，Agent 大致会按下面顺序执行。
1. 启动或复用开发服务
npm run dev
等待终端出现 ready 或 localhost URL。若项目启动命令不是 npm run dev，应在提示里写明实际命令（例如 pnpm dev、vite）。
2. 打开页面
Tool: browser_navigate
Arguments: { "url": "http://localhost:3000/settings", "take_screenshot_afterwards": true }
端口和路由按你的项目调整。文档建议可用 position: "side"，让浏览器面板开在代码旁边。
3. 全页截图
Tool: browser_take_screenshot
Arguments: { "fullPage": true }
4. 读控制台与网络
Tool: browser_console_messages
Tool: browser_network_requests
5. 需要点击前先 snapshot
Skill 注明：点击元素前应先用 browser_snapshot 取得正确的 element ref；做响应式检查可用 browser_resize 切换视口尺寸。
6. 看报告
期望输出会覆盖：截图上 UI 是否正常、控制台有无错误、网络请求有无失败。
适用场景与注意事项¶
适合的情况大致是：
- 刚改完前端样式、布局或组件交互，想快速肉眼级回归；
- 希望 Agent 顺带扫一遍控制台与接口失败，而不是只说「看起来没问题」；
- 本地已有可访问的 Web 前端（常见是 localhost 上的 SPA / SSR 应用）。
使用前注意几点：
-
依赖 Cursor 内置浏览器
Skill 写明依赖cursor-ide-browser。需在 Cursor 中启用 Browser / Browser Automation（Settings → Tools & MCP），且浏览器工具处于可用状态。社区反馈里也有过工具未连接、需重启或开关 Browser Automation 的情况。 -
它是流程说明，不是测试框架
没有断言 DSL、没有稳定的 CI 报告格式；复杂回归仍建议保留 Playwright 等专用方案。它更适合「改完马上验一眼」的开发中反馈环。 -
启动命令与端口要因项目调整
原文示例是npm run dev与localhost:3000。非 Node 前端或端口不同时，应在对话里写清楚，避免 Agent 猜错。 -
权限与安全
Cursor 官方说明：浏览器工具默认需要你审批操作；企业环境还可能受 MCP / Origin Allowlist 限制。对未信任站点不要随意开 auto-run。 -
跨工具可移植性有限
SKILL.md文件格式可放到 Claude Code、Codex 目录，但本 Skill 的工具名与「Cursor 内置浏览器」绑定；在其他 Agent 上需确认是否具备同等 browser 能力。
小结¶
visual-qa-testing 把「截图看界面 + 查控制台 + 查网络」写成 Agent 可跟随的步骤，把视觉 QA 嵌进 Cursor 的编码闭环里，很适合前端改完立刻验收。它来自社区仓库 awesome-cursor-skills，能力本身建立在 Cursor 官方 Browser 工具之上。
官方地址：
- Skill 目录：https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/visual-qa-testing
- Cursor Skills 文档：https://cursor.com/docs/skills
- Cursor Browser 文档：https://cursor.com/docs/agent/tools/browser
