browser-smoke

Files (1)

• SKILL.md

SKILL.md (first lines)

# Browser Smoke Verification

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

## 啟動條件

符合任一條件時套用：

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

以下情境不強制套用：

- 只修改後端純邏輯、文件、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。
   - 若畫面問題難以文字描述，截圖並用具體位置說明。
   - 涉及清單、表格、Dialog、iframe 內嵌或表單時，依下節「極端條件檢查」執行。

## 極端條件檢查

開發環境通常只有少量資料、單一視窗大小與正常長度的文字，下列問題在這些條件下不會出現。涉及清單、表格、Dialog、iframe 內嵌或表單的變更，逐項在極端條件下檢查實際行為。

不論預期由框架處理，例如共用 Layout、Dialog 元件或 iframe 宿主，一律以實際行為驗證，不以「應由框架負責」略過。老舊專案的框架不一定已處理這些情況。

| 條件 | 檢查 |
| --- | --- |
| 資料量 | 空、單筆、足以超過一屏的多筆各驗證一次。最後一筆可捲動到達，其後的操作區（分頁、新增、送出）可見可點。極多筆時未分頁的清單不卡頓 |
| 捲動 | 沒有雙捲軸。Dialog 與 iframe 內嵌頁的內容超過可視高度時，內容區可捲動，Dialog 的標題與動作列維持可見可點 |
| 文字長度 | 長名稱與無空白長字串不撐破版面，被截斷的文字可看到完整內容 |
| 視窗 | 矮視窗（高度 600 px 以下）與瀏覽器縮放 150% 下，固定高度與固定定位的元素不切掉內容 |
| 遮擋 | sticky 表頭與固定頁尾不蓋住最後一列與按鈕 |
| Dialog 行為 | 背景捲動、焦點與關閉方式（點背景、Esc）和同專案其他 Dialog 一致，已填資料不會非預期遺失 |

造出多筆資料屬寫入操作，依 `integration-verify` 的資料異動安全規範處理。

## 登入與測試帳號

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

- 使用者已提供測試帳號：直接使用。
- 未提供帳號：依序嘗試專案既有的測試資料來源，例如 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/` 保留並於報告中引用。

## 驗證報告格式

完成後用精簡格式回報：

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

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

獨立執行且需要寫入或刪除固定報告時，先從呼叫端取得 `LineContext`，驗證 `lineSlug` 符合 `^[a-z0-9]+(?:-[a-z0-9]+)*$`，並確認 `<work-root>/.local/ai-sessions/handoff/<lineSlug>/line.json` 的 `line-slug` 欄位相符。缺少有效 `LineContext` 或 manifest 時停止固定報告的寫入或刪除操作，不得改用預設值。

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

- 本流程由 `integration-verify` 呼叫時，未解項目交回由其統一輸出，不自行寫檔。

From CloudyWing/ai-dotfiles, MIT.

More from CloudyWing/ai-dotfiles