CloudyWing/browser-smoke

Browser Smoke Verification

此 Skill 用於完成前端或 Web UI 變更後的低成本瀏覽器驗證。它不是完整 E2E 測試框架，不負責新增可重跑的測試案例；若使用者要求建立正式測試，改依專案既有 Playwright、Cypress、Vitest 或其他測試架構處理。

啟動條件

符合任一條件時套用：

• 使用者明確要求「用瀏覽器驗證」、「打開頁面檢查」、「看 console error」、「確認畫面是否正常」。
• 本次修改影響 Web UI、路由、表單、互動、樣式、響應式版面或前端狀態管理。
• SDD、一般直接修改或 Debug 完成前端變更後，需要快速確認主要畫面可用。

以下情境不強制套用：

• 只修改後端純邏輯、文件、CLI、資料庫 migration 或非 UI 設定。
• 專案已有明確的 CI E2E 測試，且本輪只需執行該測試。

驗證流程

1. 確認驗證目標：
   • 若使用者提供 URL 或頁面路徑，直接使用該目標。
   • 若未提供，從本次 diff、路由設定或 README 找出受影響頁面。
   • 若無法判斷入口頁，回報需要使用者提供 URL 或啟動方式。
2. 啟動或沿用本機服務：
   • 優先沿用已執行的 dev server。
   • 若需啟動服務，使用專案既有 script，例如 npm run dev、pnpm dev、yarn dev、dotnet run。
   • 不新增套件、不改 .env，也不讀取 .env 內容。若缺少帳號、測試資料或外部服務，明確回報阻塞條件。
3. 使用瀏覽器檢查頁面：
   • 優先使用當前環境提供的 Browser / browser-use / in-app browser 工具。
   • 若無 Browser 工具，但專案已有 Playwright 或 Cypress 指令，可執行既有 smoke / e2e 測試。
   • 若兩者皆不可用，回報無法完成瀏覽器驗證，改提供可手動確認的步驟。
4. 檢查基礎健康狀態：
   • 頁面可載入，沒有空白畫面、錯誤頁或無限 loading。
   • Console 沒有與本次變更直接相關的 error。
   • Network 沒有與主要功能相關的 4xx / 5xx 或資源載入失敗。
   • 路由切換不會導向錯誤頁或卡住。
5. 操作主要流程：
   • 走完本次修改相關的完整使用者流程，例如填寫表單 → 送出 → 確認結果畫面顯示正確的資料，而非只點一下按鈕就結束。
   • 涵蓋正常、邊界與錯誤情境：合法輸入預期成功；必填漏填或格式錯誤預期顯示驗證訊息；邊界值能正常處理。
   • 狀態變更後畫面有合理回饋（loading、成功、失敗、停用），且回饋內容與實際結果一致。
6. 驗證寫入與持久化（操作會寫入資料時）：
   • 操作後查詢資料來源，確認資料確實寫入且關鍵欄位值正確。
   • 重新整理頁面或重新進入該頁，確認寫入的資料正確載回，篩選、分頁等前端狀態行為正常。
7. 檢查版面與響應式：
   • 文字不重疊、不被截斷，按鈕與卡片內容不溢出。
   • 本次修改影響響應式版面時，至少檢查一個桌面 viewport 與一個手機 viewport。
   • 若畫面問題難以文字描述，截圖並用具體位置說明。

登入與測試帳號

需要登入才能進入受影響頁面時：

• 使用者已提供測試帳號：直接使用。
• 未提供帳號：依序嘗試專案既有的測試資料來源，例如 seed data、開發環境固定測試帳號、README 或文件記載的測試帳號。
• 都無法取得時：回報缺少測試帳號為阻塞條件，請使用者提供，不自行猜測或建立帳號。
• 登入成功後沿用該 session 繼續後續檢查，不重複登入。

共用規範

以 integration-verify 為單一來源的共用規範（行為基準、結果驗證原則、主動詢問規範、步驟二判定執行環境、步驟六寫入回查 gate、資料異動安全規範、修正迴圈）：由 integration-verify 路由進入時已套用；獨立執行本 skill 時，先讀取上述各節並套用。

修正迴圈

修正迴圈規範以 integration-verify §修正迴圈 為單一來源，由 integration-verify 路由進入時已套用；獨立執行本 skill 時，先讀取並套用。本 skill 重跑驗證時的標的為「同一組瀏覽器驗證」。

停止時回報（本 skill 領域專屬延伸）：

• 失敗頁面或操作。
• 觀察到的 console / network / 畫面現象。
• 已修正的項目。
• 尚未解決的原因或需要使用者補充的條件。

收尾清理

驗證結束後（成功或中止皆適用）：

• 關閉本流程自行開啟的瀏覽器分頁或實例。沿用的既有瀏覽器工作階段不關閉。
• dev server 若為本流程啟動，可保留供使用者繼續開發，但須在報告中註明仍在執行。
• 刪除驗證過程產生的臨時檔案。用於說明問題的截圖除外，存入 <work-root>/.local/ai-sessions/screenshots/ 保留並於報告中引用。

驗證報告格式

完成後用精簡格式回報：

瀏覽器驗證：
- URL / 頁面：
- 檢查項目：
- 結果：
- 修正迴圈：
- 未解決項目：

若沒有問題，未解決項目 可省略。若未能執行瀏覽器驗證，必須說明缺少的工具、服務或資料條件。

有未解項目或阻塞條件時的檔案輸出：

• 本流程由 integration-verify 呼叫時，未解項目交回由其統一輸出，不自行寫檔。
• 本流程為獨立執行時，將未解項目與阻塞條件寫入 <work-root>/.local/ai-sessions/verify-pending.md（覆寫模式）。
• 全部通過時不寫檔；若該檔先前已存在，刪除它。