effective-ui-testing skill
這頁整理 repo-local effective-ui-testing skill 的長期規則。它回答的是「UI 行為要怎麼驗證才可靠」，不是某個業務流程本身的權威。
適用時機
當任務需要測 UI flow、瀏覽器確認畫面行為、寫 UI 測試步驟、除錯 flaky browser/manual test，或需要判斷 UI 驗證要不要搭配 API/DB 檢查時，先照這頁走。
核心目標：用最短且可重複的瀏覽器路徑，搭配穩定測試資料與可見證據，驗證指定行為。
先凍結測試契約
進 browser 前先把測試契約釘住：
| 欄位 | 要寫清楚 |
|---|---|
| 行為 | 這次到底要驗哪條規則 |
| 入口 | URL / 頁面 / 角色 |
| 固定資料 | 客戶、權狀號、位置、prefill / application / notification id |
| 觸發 | 最小操作，例如按一個按鈕、改一個日期、送出一筆單 |
| 正向結果 | 具體可見文字、row count、狀態、日期、id、toast、modal 狀態 |
| 反向結果 | 不應出現的重複列、錯狀態、錯日期、禁用動作 |
資料未知時，先找或建一組可控 fixture，不要用隨機列硬測。
瀏覽器選擇順序
- 已開啟的 in-app browser。
- 專案 browser-testing tooling。
- API / DB probe 只用於 setup 或隱藏狀態驗證，不取代 UI 行為證據。
若 in-app browser 控制失敗，先做一次 recovery：重新連線、抓目前 tab、讀 URL / snapshot。若 tab read 或 snapshot 連續失敗但 localhost 仍活著，再明確改 fallback，並說清楚 fallback 和使用者可見 tab 的差異。
穩定測試資料
issue-driven flow 優先使用具名 fixture，並記錄：
- customer id / name
- product auth number / position
- 建出的 prefill / application / notification id
- 任何測試 remark
失敗或 submit 結果不明時，用 exact id 回查 UI list，確認到底有沒有建出資料。
UI 操作規則
| 情境 | 規則 |
|---|---|
| selector | 優先用 data-testid、stable href、最新 snapshot 裡的 exact button name |
| 導航後第一 click | 可能被 Nuxt hydration 吃掉；必要時等約 2 秒重點一次或確認 network 有 fired |
| text selector | 不用 includes('查詢') 這種寬匹配；要 scope 到內容區或用 exact text / attribute |
| modal 表單 | 不靠 placeholder 請輸入 找欄位，要用旁邊 label 判定 |
| text input | 不直接 click/type 到文字輸入框；用 accessibility form_input 或 DOM setter + input event，避免 password-manager extension overlay bricking tab |
| date filters | 查詢、通報、統計常預設 today；查不到前先切 all 或設明確日期範圍，且日期軸要對到該報表 |
證據標準
好的 UI 結果至少要有：
- 一個正向可見證據：指定列、日期、狀態、toast、欄位值。
- 一個反向可見證據：沒有重複列、錯狀態、錯日期或 forbidden action。
重複防呆類 bug 如果只靠 row count，filter 必須精確；否則補一個 focused API/DB check。
截圖只當 evidence file。狀態判斷優先用 JS innerText / DOM probe，因為 screenshot 在此 app 的 browser channels 曾有 timeout、blank frame、改 zoom 等不穩定問題。
上傳與完成關卡
必附文件要從申請單詳情頁「該文件名稱那一列」上傳，不能直接打 Media API；直接打 API 會落到其他附件，不滿足 required-doc status。
完成申請前按順序確認：
- item form data 已保存
- 會計審核通過
- 有金額時出納收款完成
- required docs 顯示 N/N 已上傳
- invoice status 符合 case
- target item 仍可完成
少前置 gate 時，最後完成錯誤常會看起來像下游問題；不要只信最後錯誤訊息。
專案固定事項
| 項目 | 值 |
|---|---|
| dev login | zzzzzz / zion1234 |
| CAPTCHA | 可空白或 0000 |
| 截圖 | 走專案 QA/browse skill path，不用 OS-level screenshot |
| query pages | 常預設 today，查 missing 前要改 all 或明確 range |
| create flows | 常有 data-testid，先 inspect 再靠 visible text |
回報格式
UI 測試報告要包含：
- 測了什麼。
- 使用了哪些 exact data / ids。
- 哪些 visible UI evidence 通過。
- 哪些 gate 被阻塞或未覆蓋。
- 是否使用 fallback browser/tool，以及原因。
不要只寫「看起來正常」；要留下 ids、filters 與 expected result。
相關
- GitHub issue source index：
content/sources/issues/index.md - issue249-fixture-scripts — issue #249 fixture preflight 與 required-doc upload helper