Geruyang/agent-skills-library

前端測試與除錯

呼叫契約

此技能應能從一般的使用者提示中正常運作。無需要求使用者詳細說明瀏覽器路由、螢幕截圖、報告格式或降級策略。

當使用者要求使用「建構網頁應用程式」外掛程式、網頁開發外掛程式、前端開發外掛程式，或前端測試/除錯技能來進行渲染前端變更、測試或錯誤調查時，請使用此技能。

應觸發此完整工作流程的範例：

• 請對網頁儀表板的交易搜尋區域進行改善，並使用網頁開發外掛程式
• 使用前端開發外掛程式來打磨這個儀表板
• 使用「建構網頁應用程式」外掛程式來除錯此 UI
• 測試此 localhost 應用程式並修復壞掉的互動

從簡短的提示中，根據儲存庫、當前開啟的應用程式/瀏覽器 URL、附近的檔案或正在執行的開發伺服器來推斷目標表面。如果目標 URL 不清楚，請先檢查儲存庫的腳本和正在執行的本機連接埠，然後再詢問使用者。

對於任何對渲染前端表面進行的程式碼變更，預設執行驗證循環：

1. 識別目標流程。
2. 選擇下方的瀏覽器路徑。
3. 進行最小的有用編輯。
4. 驗證渲染行為。
5. 回覆 QA 最終回應報告。

選擇瀏覽器路徑

首先分類瀏覽器的可用性：

• 可用：瀏覽器外掛程式及其 browser 技能已列在對話中。在執行任何瀏覽器操作之前，先閱讀並遵循該技能。
• 不存在：瀏覽器外掛程式或 browser 技能未列出。使用一般的 Playwright 並記錄 Browser plugin not available。
• 呼叫失敗：瀏覽器看似可用，但技能/執行環境、Node REPL JavaScript 設定、取得分頁或導航失敗。將此視為瀏覽器路徑的阻礙。

當瀏覽器可用時，不要優先使用一般的 Playwright、外部 Chrome 或 shell open。

僅在使用者已允許降級，或任務明確允許非瀏覽器驗證的情況下，才從失敗的瀏覽器呼叫切換到一般的 Playwright。在這種情況下，請報告確切的瀏覽器失敗原因和降級決策。

目標流程

在進行瀏覽器驗證之前，用一句話定義目標流程：

正在測試的流程是：[進入路由] -> [使用者操作或狀態] -> [預期的渲染結果]。

如果使用者要求的是通用冒煙測試，請使用：

正在測試的流程是：應用程式載入 -> 第一個有意義的畫面渲染 -> 主要可見控制項回應而無執行時期錯誤。

瀏覽器外掛程式循環

透過瀏覽器技能描述的 Node REPL JavaScript 工具來執行瀏覽器命令。請勿發明單獨的瀏覽器設定路徑。除非瀏覽器技能另有說明，否則繼續使用相同分頁的綁定。

必要的順序：

1. 完全按照瀏覽器技能的指示載入瀏覽器執行環境。
2. 使用 agent.browser.nameSession("...") 為工作階段命名。
3. 使用 agent.browser.tabs.selected() 或 agent.browser.tabs.new() 取得分頁。
4. 使用 tab.goto(url) 進行導航。
5. 執行下方所需的檢查。
6. 使用限定範圍的 tab.playwright 定位器或瀏覽器技能互動 API 進行互動。
7. 編輯後，呼叫 await tab.reload()，然後重複檢查和失敗的互動。

對於每個改變 UI 的操作，收集最簡單的證據來證明下一個狀態是正確的：新的 DOM 快照、可見的文字/狀態、URL 變更、聚焦的控制項、提示訊息、模態框、螢幕截圖或主控台日誌。

必要的瀏覽器檢查

在聲明渲染的應用程式正常運作之前，執行這些檢查：

1. 頁面身分：await tab.url() 和 await tab.title() 符合預期頁面。
2. 非空白：await tab.playwright.domSnapshot() 包含有意義的應用程式內容，而非空殼。
3. 無框架覆蓋層：快照或螢幕截圖未顯示 Next.js、Vite、Webpack 或框架錯誤覆蓋層。
4. 主控台健康狀況：await tab.dev.logs({ levels: ["error", "warn"], limit: 50 }) 沒有相關的應用程式錯誤，或者每個相關錯誤都有解釋。
5. 螢幕截圖證據：await display(await tab.playwright.screenshot({ fullPage: false })) 支援視覺化主張。
6. 互動證明：至少執行一次目標流程的互動，並隨後進行狀態檢查。

對於視覺化工作，在可行時加入桌上型電腦和一個行動裝置大小的視窗。對於參考驅動的工作，保留一個簡短的差異清單：參考證據、渲染證據、修正或故意偏離。

Playwright 循環

當瀏覽器不可用，或使用者已在瀏覽器呼叫失敗後允許降級時，使用此分支。

使用此順序：

1. 在 package.json 中尋找腳本。
2. 使用儲存庫的套件管理器啟動應用程式，並保持請求的主機精確。
3. 如果存在，優先使用儲存庫的 e2e 腳本。
4. 否則，當 Playwright 已設定時，執行 pnpm exec playwright test 或等效的套件管理器命令。
5. 如果沒有專案的 Playwright 工作流程，請使用 pnpm exec playwright --version 驗證 Playwright，然後使用 pnpm exec playwright screenshot <url> /tmp/frontend-check.png 擷取螢幕截圖。
6. 對於更深入的除錯，在已提交的原始碼之外建立一個小的臨時 Playwright 腳本，該腳本會開啟 URL、擷取主控台錯誤、螢幕截圖並執行目標互動。
7. 編輯後，重新執行相同的命令或腳本。

除非任務需要且使用者允許相依性變更，否則不要安裝新的瀏覽器相依性。

驗證檢查清單

• 保持請求的主機精確。
• 驗證控制項會更新真實的 UI 狀態。
• 在滾動前檢查第一個視口，並在可行時檢查桌上型電腦和一個行動裝置大小的視口。
• 尋找裁剪、重疊、不可讀的文字、換行、版面配置偏移、遺失的資源、z-index 問題、滾動陷阱、過時的載入和損壞的狀態。
• 對於參考驅動的工作，將渲染的螢幕截圖與參考進行比較，並保留一個簡短的差異清單。
• 當請求渲染驗證時，建置通過是不夠的。

QA 最終回應報告

對於任何非平凡的渲染 UI 驗證執行，請像 QA 工程師驗證程式碼變更一樣撰寫最終回應。回應應讓使用者或 PR 審查者易於理解變更了什麼、測試了什麼、什麼證據證明了它，以及還有什麼未測試。

使用此格式：

• 摘要：一兩個要點，解釋使用者可見的變更以及 QA 是否通過。
• 環境：URL、視口、瀏覽器可用性分類，以及如果使用了 Playwright 的降級原因。
• 已驗證的變更：已變更的檔案或表面，以及預期的使用者面向行為。
• 檢查：頁面身分、空白頁面檢查、框架覆蓋層檢查、主控台健康狀況、螢幕截圖證據和互動證明的通過/失敗表格。
• 互動循環：測試的準確互動路徑，包括已執行的控制項或工作流程，以及觀察到的狀態變更。
• 證據：在 QA 部分描述螢幕截圖證據，然後將實際的螢幕截圖放在回應的最後，作為連續的圖片。包含足夠有用的螢幕截圖，以證明相關的前後狀態、互動、響應式、錯誤或已修復的狀態。
• 命令 / 瀏覽器 API：列出所使用的關鍵命令和瀏覽器 API 順序，不要傾倒雜亂的日誌。
• 剩餘風險：未測試的視口、流程、瀏覽器、資料狀態或已知的限制。

如果發現問題，請在摘要之前先以 發現 開頭。每個發現應包含使用者看到的內容、重現步驟、螢幕截圖/DOM/主控台證據、已知的負責人或檔案（如果知道），以及已做的修復或剩餘的阻礙。

當使用應向使用者顯示的瀏覽器螢幕截圖時，請透過瀏覽器執行環境發出或顯示螢幕截圖，以便在聊天中引用。當使用 Playwright 螢幕截圖時，請將它們儲存在儲存庫之外，並在聊天中引用。當多張螢幕截圖有助於驗證不同的狀態或流程時，請包含它們。

請勿在書面報告中穿插螢幕截圖。在報告的最後放置一個簡短的 螢幕截圖 部分，並使其成為一個連續的圖片庫，每行一張圖片。僅在標籤能釐清狀態時才加入簡短標籤，例如 Before、After、Filtered results、Empty state 或 Mobile。

預設情況下，不要建立單獨的 HTML 報告。僅在使用者明確要求時才建立獨立的報告檔案，並將其寫在儲存庫之外，除非使用者明確要求提交的工件。

除非使用者明確要求提交的工件，否則不要將報告、螢幕截圖、追蹤或臨時腳本寫入儲存庫。

相關技能

• 當任務是設計創作、重新設計或忠於已接受的概念時，使用 frontend-app-builder。
• 在進行有意義的 React/Next.js 元件編輯後，使用 react-best-practices。
• 不要為一般的除錯呼叫影像生成。僅在任務需要建立或修改視覺資產時，或當 frontend-app-builder 已在驅動概念到實作的忠實度循環時，才使用它。

最終回應

使用上述的 QA 最終回應報告格式。保持簡潔，但包含足夠的具體證據，以便 PR 審查者可以信任驗證結果，而無需立即重新執行。

如果瀏覽器不存在且使用了 Playwright，請在結束時建議使用者安裝瀏覽器外掛程式，以獲得更好的前端開發體驗，包括應用程式內導航、螢幕截圖、DOM 快照、主控台日誌和互動驗證。