Visual Verify 是做什麼的?
版本:1.1.0。1.0.0 之前的版本未在此儲存庫中追蹤。
在無頭瀏覽器中檢視真實運行的應用,並如實報告所見。 兩種模式:
- 驗證(預設)— 擷取當前狀態的一張(或幾張)螢幕截圖,並由您自己讀取以確認某個功能是否正確渲染、某個修復是否生效,或特定寬度下的版面是否正確。
- 前後對比— 針對視覺變更,先關閉再開啟該變更,生成一張標有「之前/之後」的並排合成圖。
- 觸控(iOS / Android)— 模擬手機,用手指點擊和拖曳,並審查觸控目標尺寸。請參閱下方的手機觸控檢查。
根據使用者的要求選擇模式。如果使用者問「這樣看起來對嗎?/能用嗎?/在手機寬度下顯示給我看」,請使用「驗證」模式。如果使用者問「之前和之後/這個修復在視覺上有效嗎」,請使用「前後對比」模式。
當使用者提出要求時,請照做
當使用者要求您視覺驗證某個東西(或要求截圖/檢查外觀)時,該要求的本身就是您的行動指令 — 請自行執行完整的檢查:擷取、讀取圖片,並直接說明是否正確。不要只是提出建議然後停下。
請不要在每次變更後主動、未經要求地執行此操作 — 因為這會驅動瀏覽器並讀取圖片,消耗令牌。在未經要求的視覺變更後,您可以提議執行(例如「想要一個前後對比圖嗎 — 手機、桌面,或兩者都要?」),並讓使用者決定。
每次都顯示您驗證的結果 — 每次
使用者必須能夠看到結果,而無需開啟檔案。在報告工作的回覆中,為您驗證的每個功能顯示「之後」的圖片 — 每個功能一張圖片,因此檢查三個東西意味著至少三張圖片。將每張圖片放在一行簡短說明旁邊,說明其內容以及是否正確(例如:「刪除確認,手機寬度 — 焦點在『取消』」)。
- 使用 Markdown 的絕對路徑內嵌顯示圖片,格式為
,以便客戶端渲染。否則請附加檔案(例如使用 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。
工作流程 — 驗證模式
- 確保應用正在運行,並且您知道它的 URL(按照該專案的運行方式啟動它 — 請參閱下方的運行應用程式)。執行
mkdir -p visual-checks。 - 擷取要檢查的狀態,如有需要,可使用
--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來進行桌面檢查。 - 讀取每一張圖片並直接報告是否正確。如果正在驗證一個修復,請確認有問題的部分確實消失了;如果是一個功能,請確認它確實被渲染出來了。
- 在您的回覆中顯示相關的截圖 — 每個功能一張(請參閱顯示您驗證的結果)。
工作流程 — 前後對比模式
- 確認範圍和視口。執行
mkdir -p visual-checks。選擇共同的<change>前綴。 - 擷取「之後」 — 工作目錄已包含變更:
對於桌面,移除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後綴。 - 擷取「之前」 — 暫時僅撤銷視覺變更,截圖到
<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)。
- 未提交的變更:
- 合成 — 相同前綴,使用
-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" - 讀取合成圖,確認它顯示了您所聲稱的內容,然後在您的回覆中顯示它。
- 還原「之前」的切換。 在完成之前,永遠不要提交或部署仍帶有臨時「之前」變更的狀態 — 請重新檢查
git status/git diff。
手機觸控檢查
(…此處因原文截斷而省略)
