前言¶
改完前端樣式或交互之後，最常見的驗證方式是：手動打開瀏覽器，看一眼頁面，再打開 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
