Community程式設計與開發github.com

Visual Verify

使用 Playwright 驅動真實的無頭瀏覽器(Docker 環境下運行於 Playwright 映像)截取運行中 Web 應用在指定裝置視口下的螢幕截圖,查看結果並確認內容正確顯示,或生成標註了「之前/之後」的比對圖。

Visual Verify 是什麼?

Visual Verify 是一個專為 AI 代理(如 Claude Code 或 Cursor)設計的技能,用於自動驅動 Playwright 對真實運行的 Web 應用進行視覺驗證。它支援三種模式:預設的「驗證」模式用於獨立確認功能正確渲染;「前後對比」模式可自動切換變更與否,生成標籤化的「之前/之後」合成圖;以及「觸控」模式,用於模擬手機瀏覽器並檢測觸控目標尺寸。該技能明確排除任何 MCP 伺服器,而是透過獨立的 Node.js 腳本與 Playwright 庫互動。它會自動判斷可用的瀏覽器後端(優先使用 Docker 中的 Playwright 映像,否則使用本地瀏覽器),遵循嚴格的視口計算規則(從使用者提供的螢幕截圖推導 CSS 寬度),並透過擷取前/後條件(使用選擇器或 JavaScript 表達式)來確保穩定渲染。完成驗證後,代理必須內嵌顯示每張螢幕截圖或合成圖,並附上一行文字說明,以便使用者無需打開檔案即可查看結果。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/conorjwryan/skills/tree/main/visual-verify

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

預覽

來自技能 README

說明

說明文件

Visual Verify 是做什麼的?

版本:1.1.0。1.0.0 之前的版本未在此儲存庫中追蹤。

在無頭瀏覽器中檢視真實運行的應用,並如實報告所見。 兩種模式:

  • 驗證(預設)— 擷取當前狀態的一張(或幾張)螢幕截圖,並由您自己讀取以確認某個功能是否正確渲染、某個修復是否生效,或特定寬度下的版面是否正確。
  • 前後對比— 針對視覺變更,先關閉再開啟該變更,生成一張標有「之前/之後」的並排合成圖。
  • 觸控(iOS / Android)— 模擬手機,用手指點擊和拖曳,並審查觸控目標尺寸。請參閱下方的手機觸控檢查。

根據使用者的要求選擇模式。如果使用者問「這樣看起來對嗎?/能用嗎?/在手機寬度下顯示給我看」,請使用「驗證」模式。如果使用者問「之前和之後/這個修復在視覺上有效嗎」,請使用「前後對比」模式。

當使用者提出要求時,請照做

當使用者要求您視覺驗證某個東西(或要求截圖/檢查外觀)時,該要求的本身就是您的行動指令 — 請自行執行完整的檢查:擷取、讀取圖片,並直接說明是否正確。不要只是提出建議然後停下。

請不要在每次變更後主動、未經要求地執行此操作 — 因為這會驅動瀏覽器並讀取圖片,消耗令牌。在未經要求的視覺變更後,您可以提議執行(例如「想要一個前後對比圖嗎 — 手機、桌面,或兩者都要?」),並讓使用者決定。

每次都顯示您驗證的結果 — 每次

使用者必須能夠看到結果,而無需開啟檔案。在報告工作的回覆中,為您驗證的每個功能顯示「之後」的圖片 — 每個功能一張圖片,因此檢查三個東西意味著至少三張圖片。將每張圖片放在一行簡短說明旁邊,說明其內容以及是否正確(例如:「刪除確認,手機寬度 — 焦點在『取消』」)。

  • 使用 Markdown 的絕對路徑內嵌顯示圖片,格式為 ![說明](/abs/path/to/image.png),以便客戶端渲染。否則請附加檔案(例如使用 SendUserFile)。始終同時提供路徑。
  • 選擇最清晰的截圖:如果全頁會把功能淹沒,請裁切或裁剪到該功能。
  • 對於前後對比圖,請顯示合成圖。
  • 如果某個部分無法如實顯示(例如系統 UI、安全區域),請直接說明,而不是顯示誤導性的圖片。

始終檢視您擷取的內容

螢幕截圖本身不是最終交付物 — 您的驗證判斷才是。在報告前,請讀取您擷取的每一張圖片;在發送合成圖前,請確認它確實顯示了您所聲稱的內容。如果圖片沒有顯示您預期的結果,請進行調查;不要根據未經檢視的截圖就報告成功。

選擇正確的視口 — 這點很重要

響應式錯誤通常只在特定寬度下才會重現。匹配使用者的裝置。 如果使用者傳送了螢幕截圖,請推導出其 CSS 寬度:

css_width = screenshot_pixel_width / devicePixelRatio

現代 iPhone 的 DPR 為 3(例如,1320px 寬的截圖 ⇒ 440 CSS px;Pro Max 等級)。 常見 Android 的 DPR 約為 2.6–3。如果不確定,請掃描幾個寬度(例如 320、360、390、440)— 截圖腳本讓這個操作成本很低。傳遞 --mobile 以進行觸控/手機模擬。對於適用於所有寬度的通用設計變更,請同時檢查桌面和手機。

腳本(使用 Bash 執行;沒有 MCP)

請不要尋找 browser_* / Playwright MCP 工具 — 它沒有被安裝。所有操作都透過純 Node 腳本執行。解析包含此已安裝 SKILL.md 的絕對目錄,然後在您的 shell 中將 VISUAL_VERIFY_DIR 設定為該目錄。這可能是專案安裝或全域安裝;請使用您正在閱讀此說明的那份副本,而不是一個硬編碼的全域路徑。將工作目錄保留在應用程式專案根目錄。在每個 shell 命令中重複使用此變數(如果 shell 狀態未被保留,則重新設定):

VISUAL_VERIFY_DIR="/absolute/path/to/installed/visual-verify"

隨附的腳本如下:

"$VISUAL_VERIFY_DIR/scripts/screenshot.mjs"   # 擷取 URL → png
"$VISUAL_VERIFY_DIR/scripts/composite.mjs"     # 兩個 png → 標籤化的前後對比圖
"$VISUAL_VERIFY_DIR/scripts/touch.mjs"         # 手機觸控:點擊、拖曳、目標審查

執行環境和瀏覽器設定。 此技能擁有精確的 Playwright 依賴項和鎖定檔案。它永遠不會解析全域或專案的 Playwright 套件。請在安裝或更新此技能後,明確執行安裝程式;正常檢查永遠不會下載套件、圖片或瀏覽器。

瀏覽器運行位置。 當 Docker 可用時,每次啟動都會從完全匹配且已安裝的 Playwright 映像建立一個新的容器。Docker 會分配一個唯一的 loopback 連接埠;輔助程式會驗證其容器身份並連接到該端點。此技能已安裝的 Node 依賴項會以唯讀方式掛載,因此伺服器無需下載套件。Playwright 會將 loopback 請求轉發給客戶端,允許在沒有主機網路的情況下使用本地應用程式 URL。正常關閉、啟動失敗和已處理的終止只會清理該次運行的容器。強制終止或主機崩潰可能會留下一個標記的容器;在明確清理前請檢查所有權。不會取代或停止任何既有的容器。Docker Desktop/macOS 網路功能仍需單獨驗證;請勿根據 Linux 檢查結果進行斷言。

如果沒有 Docker,輔助程式會使用已安裝的本地瀏覽器二進位檔。設定 VISUAL_VERIFY_DOCKER=0 以強制使用本地模式;啟動 API 也接受明確的後端。JSON 輸出會命名實際的後端和版本。

專案腳本支援的啟動器

// 解析此匯入路徑為已安裝技能目錄的相對路徑。
const { launchBrowser } = await import("<installed-skill>/scripts/load-playwright.mjs");
const { browser, where } = await launchBrowser("chromium", {
  backend: "auto", // auto, docker, local
  timeout: 30000,
  launchOptions: { headless: true },
});
try {
  // 使用 browser.newContext() 等。在報告證據時一併報告 `where`。
} finally {
  await browser.close();
}

launchOptions 會傳遞給本地的 launch 方法或固定的 Docker 伺服器瀏覽器啟動請求。完整的 Playwright 伺服器會啟用請求的客戶端 loopback 轉發;Docker 擁有伺服器主機和連接埠;主機特定的執行檔路徑和其他機器特定的選項由呼叫者負責。現有的 loadChromium() 和 loadBrowser(name) 匯出仍然是僅限本地的相容性 API:它們既不會啟動 Docker,也不會修復缺失的瀏覽器。請有意識地遷移呼叫者,而不是假設設定會改變他們的行為。

Docker 啟動會為每個呼叫使用一個全新的、唯一命名的伺服器容器。Docker 會原子性地分配一個 loopback 連接埠;客戶端會驗證容器元資料並連接到其報告的 WebSocket 路徑。Playwright 會轉發客戶端的 loopback 流量,從而在沒有主機網路的情況下保留對本地開發應用程式的存取權限。容器會在關閉、啟動失敗和已處理的終止時被移除。這種做法以犧牲暖伺服器重用為代價,換取端點隔離;較舊的共享連接埠容器不會受到影響。強制終止或 Docker 故障可能會留下孤立容器。請檢查 doctor 輸出並在明確移除前驗證確切容器的所有權;永遠不要停止所有匹配的程序/容器。跨平台 Docker 行為仍需獨立驗證。

screenshot.mjs 標誌:--url --out [--width 390] [--height 844] [--dpr 2] [--mobile] [--wait 2000] [--click "Text or selector"] [--scroll-bottom "sel"] [--eval "js"] [--clip x,y,w,h] [--full]。--click 是可重複的,會先匹配按鈕的無障礙名稱,然後匹配 CSS 選擇器 — 用於到達某個標籤、選單或對話方塊後方的狀態。

一次性安裝(每台機器)

bash "$VISUAL_VERIFY_DIR/scripts/install.sh"

將鎖定的依賴項安裝到此技能自己的 node_modules 中。預設的 auto 設定會在有 Docker 可用時拉取對應的 Docker 映像;否則會安裝本地 Chromium。傳遞 docker 或 local 給安裝程式以明確選擇。此命令不安裝本地 WebKit。不會更改任何全域 npm 套件或系統套件。

檢查先決條件,無需啟動瀏覽器、拉取映像或更改容器:

node "$VISUAL_VERIFY_DIR/scripts/doctor.mjs"

Doctor 會報告技能/執行時版本、執行時路徑、本地執行檔是否存在、Docker 映像的可用性以及活動的 Visual Verify 容器/端點(包括舊名稱)。其退出狀態會檢查所選預設後端的 Chromium 先決條件;它不會證明瀏覽器啟動或 WebKit 的可用性。安裝檔案和成功啟動瀏覽器是分開的證據。

使用以下指令進行驗證:

node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
  --url https://example.com --out /tmp/_vv_check.png --width 390 --height 844

檢查圖片和後端 JSON,以確認此煙霧測試已成功。

等待正在檢查的狀態

截圖和觸控指令支援以下操作後選項:

  • --ready-selector "<selector>":等待第一個匹配的元素變為可見。
  • --ready-js "<expression>":輪詢直到頁面表達式(包括 promise)為真。
  • --ready-timeout 10000:正的就緒超時時間(毫秒);由選擇器和謂詞等待共用。同時也分別限制了 --eval 和 --report 的評估。
  • --settle 0:可選的非負延遲,用於在就緒後等待動畫完成。

這些條件在所有點擊/觸摸、滾動、評估和拖曳之後、審查和擷取之前執行。當兩個條件都提供時,兩者都必須通過。失敗時會以非零退出,並且不會寫入新的成功截圖(不會移除現有的輸出檔案)。請選擇唯一的輸出路徑。--wait 保留其舊有的操作前延遲功能;固定的點擊/拖曳延遲仍然是相容性穩定措施,而非就緒證據。請說明所選條件證明了什麼。

node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
  --url "<local-app-url>" --out visual-checks/search-desktop.png \
  --click "Search" --ready-selector "[data-search-results]" \
  --ready-js "document.querySelectorAll('[data-result]').length > 0"

使用一個特定於預期新狀態的條件,而不是一個已經存在於頁面上的過時元素。對於需要非同步結果的中間步驟,請使用啟動 API 和 Playwright 定位器,並在操作之間使用斷言。如果需要等待回應,請在觸發其請求之前註冊等待,然後斷言渲染後的狀態;僅有回應並不能證明渲染完成。對於有反彈(debounce)的應用程式,不要將任意的延遲或網路空閒視為完成的保證。

輸出位置

將生成的圖片寫入儲存庫根目錄下一個被 .gitignore 忽略的 visual-checks/ 目錄(mkdir -p visual-checks)。如果您不在一個儲存庫中,或不想將檔案添加到其中,請改用一個臨時目錄。在將檔案發送給使用者時,請參考穩定的路徑。

為同一次運行中的每張圖片提供一個共同的 <change> 前綴來描述其內容(例如 import-export-tab、header-nav)— 而不是通用的 before.png/after.png — 這樣看一眼目錄就能知道某個檔案屬於哪次運行:

visual-checks/<change>-<viewport>.png                 # 驗證模式:單張截圖
visual-checks/<change>-<viewport>-before.png          # 前後對比模式
visual-checks/<change>-<viewport>-after.png
visual-checks/<change>-<viewport>-before-after.png    # 合成圖

其中 <viewport> 是 mobile 或 desktop。

工作流程 — 驗證模式

  1. 確保應用正在運行,並且您知道它的 URL(按照該專案的運行方式啟動它 — 請參閱下方的運行應用程式)。執行 mkdir -p visual-checks。
  2. 擷取要檢查的狀態,如有需要,可使用 --click / --eval / --scroll-bottom 達到該狀態:
    node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
      --url "<running app url>" --out visual-checks/<change>-mobile.png \
      --width 440 --height 800 --mobile --wait 2000
    
    掃描幾個寬度,或根據需要移除 --mobile 並使用例如 --width 1280 --height 800 來進行桌面檢查。
  3. 讀取每一張圖片並直接報告是否正確。如果正在驗證一個修復,請確認有問題的部分確實消失了;如果是一個功能,請確認它確實被渲染出來了。
  4. 在您的回覆中顯示相關的截圖 — 每個功能一張(請參閱顯示您驗證的結果)。

工作流程 — 前後對比模式

  1. 確認範圍和視口。執行 mkdir -p visual-checks。選擇共同的 <change> 前綴。
  2. 擷取「之後」 — 工作目錄已包含變更:
    node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
      --url "<running app url>" --out visual-checks/<change>-mobile-after.png \
      --width 440 --height 800 --mobile --wait 2000
    
    對於桌面,移除 --mobile,使用例如 --width 1280 --height 800,並使用 -desktop-after.png 後綴。
  3. 擷取「之前」 — 暫時僅撤銷視覺變更,截圖到 <change>-<viewport>-before.png,然後還原。建議使用 git,這樣就不會忘記還原:
    • 未提交的變更:git stash push -- <file> → 截圖 → git stash pop
    • 已提交的變更:git show HEAD~1:<path> > <path>(或 git checkout <parent> -- <file>)→ 截圖 → git checkout -- <file> 在切換和截圖之間等待開發伺服器進行熱重載(使用 --wait)。
  4. 合成 — 相同前綴,使用 -before-after.png 後綴:
    node "$VISUAL_VERIFY_DIR/scripts/composite.mjs" \
      --before visual-checks/<change>-mobile-before.png --after visual-checks/<change>-mobile-after.png \
      --out visual-checks/<change>-mobile-before-after.png \
      --title "Header at 440px (iPhone width)" \
      --before-label "BEFORE — title squished" \
      --after-label  "AFTER — title full width"
    
  5. 讀取合成圖,確認它顯示了您所聲稱的內容,然後在您的回覆中顯示它。
  6. 還原「之前」的切換。 在完成之前,永遠不要提交或部署仍帶有臨時「之前」變更的狀態 — 請重新檢查 git status / git diff。

手機觸控檢查

(…此處因原文截斷而省略)

相關技能