AmElmo/proofshot

UI 功能視覺驗證工具。在建立或修改任何 UI 元件、頁面或視覺功能後使用。啟動包含錄影與錯誤捕捉的驗證會話，隨後驅動瀏覽器進行測試，最後停止並將驗證成果打包提供給人類審查。

proofshot 是什麼？

ProofShot 是一個專為 AI 代理（如 Claude Code、Cursor 等）設計的 UI 視覺驗證工作流程工具。在開發者修改 UI 元件、頁面或修復視覺錯誤後，該技能提供一個結構化流程，讓代理自動化記錄測試過程、執行互動驗證，並產出包含影片、螢幕截圖和錯誤報告的摘要（SUMMARY.md）。它支援通過 `proofshot exec` 驅動無頭瀏覽器進行點擊、填寫表單等操作，並利用 `proofshot pr` 將驗證成果（影片與截圖）直接附加到 GitHub Pull Request 上。本質上，它將傳統的人工視覺回歸測試轉變為可重複的、由 AI 驅動的驗證工序，確保每次 UI 變更皆有視覺證明。

相容平台~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/AmElmo/proofshot/tree/HEAD/test/fixtures/sample-app/.claude/skills/proofshot

說明文件

ProofShot — 視覺驗證工作流程

使用時機

在以下情況使用 ProofShot：

建立新的 UI 功能或頁面
修改現有 UI 元件
修復視覺錯誤
任何影響使用者所見內容的變更

工作流程（請務必遵循以下 3 個步驟）

步驟 1：啟動會話

proofshot start --description "您即將驗證的內容"

這將啟動開發伺服器、開啟無頭瀏覽器，並開始錄製。描述會出現在驗證報告中，供人類檢視。

步驟 2：驅動瀏覽器並測試

使用 proofshot exec 進行導覽、互動和驗證：

proofshot exec snapshot -i                                    # 檢視可互動元素
proofshot exec open http://localhost:PORT/page                # 導覽至頁面
proofshot exec click @e3                                      # 點擊按鈕
proofshot exec fill @e2 "[email protected]"                    # 填寫表單欄位
proofshot exec screenshot step-NAME.png                       # 捕捉關鍵時刻

在重要時刻擷取螢幕截圖——這些將成為視覺證明。透過閱讀快照輸出，驗證您預期看到的內容。

步驟 3：停止並打包驗證成果

proofshot stop

這將停止錄製、收集主控台與伺服器錯誤，並產生包含影片、螢幕截圖和錯誤報告的 SUMMARY.md。

步驟 4（可選）：將驗證成果張貼到 PR

proofshot pr              # 從目前分支自動偵測 PR
proofshot pr 42           # 指定特定 PR 編號

這會將螢幕截圖和影片上傳至 GitHub，並在 PR 上張貼格式化留言。預設使用官方 GitHub 內容 API 上傳到 proofshot-artifacts 分支。如果您特別想使用 GitHub 附件 URL，請使用 --upload-provider github-web-attachments。

提示

務必包含有意義的 --description，以便人類知道測試了什麼
在關鍵動作前後皆擷取螢幕截圖（例如表單提交前、重新導向後）
如果在驗證過程中發現錯誤，請修正後重新執行工作流程
停止後使用 proofshot pr 將驗證成果直接附加到 Pull Request 上