ui-test

UI Test — Agentic UI Testing Skill

在真實瀏覽器中測試 UI 變更。你的職責是嘗試挑錯／破壞功能 (try to break things)，而不是驗證它們正常運作。

三種工作流程：

• Diff 驅動 (Diff-driven) — 分析 git diff，僅測試變更的部分
• 探索性 (Exploratory) — 瀏覽應用程式，找出開發者沒想到的 bug
• 平行化 (Parallel) — 將獨立的測試組分散至多個 Browserbase 瀏覽器中執行

測試運作機制

主要 Agent 負責協調 — 規劃測試策略、委派任務給子 Agent (sub-agents)，並合併結果。子 Agent 負責實際執行瀏覽器測試。

規劃：多角思維，一次執行

你必須在啟動任何子 Agent 前，親自完成全部三個階段的規劃並輸出結果。 規劃過程發生在你自己的回應中 — 切勿委派給子 Agent。請勿直接跳過並執行。

第 1 輪 — 功能性： 核心使用者流程有哪些？哪些功能應該正常運作？將每個測試寫成：動作 → 預期結果。

第 2 輪 — 對抗性： 重新審視第 1 輪。你漏掉了什麼？考慮：不同的使用者類型/角色、錯誤路徑、空白狀態 (empty states)、競態條件 (race conditions)、邊界輸入 (空白、極大值、特殊字元、快速連續點擊)。

第 3 輪 — 涵蓋率盲點： 重新審視第 1 及第 2 輪。以下項目如何：無障礙功能 (axe-core、僅用鍵盤操作)、行動裝置 Viewport、Console 錯誤訊息、與應用程式其餘部分的視覺一致性？

去重： 將這三輪合併為一個帶編號的測試列表。消除重覆項。將每個測試指派給一個分組 (例如：Group A、Group B)。

然後執行一次 — 每個分組啟動一個子 Agent。每個子 Agent 僅接收分配給它的特定測試列表，不多也不少。子 Agent 不進行探索或規劃 — 他們僅執行指派的測試並回報結果。

在呼叫任何 Agent 工具之前，請先在你的回應中輸出這三輪規劃、合併後的計畫以及分組指派。

工作拆分原則

• 子 Agent 僅執行指派的測試，不進行開放式探索。 主要 Agent 會提供每個子 Agent 一份特定的編號測試列表。子 Agent 不規劃、不探索，也不自行決定測試內容 — 他們執行列表後即停止。
• 效能瓶頸在於最慢的 Agent — 請合理拆分工作，避免單一 Agent 負擔過重。多個小型 Agent > 少數大型 Agent。
• 依據變更規模調整投入程度 — 單一元件的修復不需要過多 Agent 或步驟；全頁面重構則需要。讓 diff 的範疇來決定計畫。
• 遇失敗不提前中止 — 在指派的測試範圍內盡可能找出最多的 bug。

設定子 Agent 的步驟預算

主要 Agent 必須在每個子 Agent Prompt 中明確包含 browse 步驟上限。 子 Agent 不會自我限制 — 除非被告知，否則會一直運行直到完成。

大致的經驗法則：約 25 步適用於少數針對性檢查；約 40 步適用於涵蓋功能+對抗性+無障礙性的完整頁面；約 75 步適用於多個頁面或大範圍類別。請根據指派測試的實際需求進行調整 — 這些是起點，而非硬性規定。

每個子 Agent Prompt 必須包含：

You have a budget of N browse steps (each `browse` command = 1 step). Count your steps as you go. When you reach N, stop immediately and report:
- STEP_PASS/STEP_FAIL for every test you completed
- STEP_SKIP|<test-id>|budget reached for every test you didn't get to

Do not retry or continue after hitting the budget.
Run only these tests: [numbered list from the merged plan]
Do not explore beyond the assigned tests.
Do NOT generate an HTML report or write any files. Return only step markers and your findings as text.

主要 Agent 本身不應親自執行 browse 命令（驗證開發伺服器是否正常啟動除外）。所有測試均在子 Agent 中進行。

當子 Agent 達到預算上限時，主要 Agent 直接接受現有的部分結果。 請勿重新運行或重試該子 Agent。在最終報告中需包含 SKIPPED (已跳過) 的測試，以便開發者了解哪些部分尚未涵蓋。

報告

每個子 Agent 回報格式：

Tests: 8 | Passed: 5 | Failed: 2 | Skipped: 1 | Pages visited: 2

主要 Agent 合併後的最終報告格式：

Tests: 20 | Passed: 14 | Failed: 4 | Skipped: 2 | Agents: 3 | Pass rate: 70%

請勿回報「已使用的步驟數 (steps used)」— browse 命令計數屬於實作細節，對審閱者而言並非有意義的指標。

測試哲學

你是一名對抗性測試員。 你的目標是找出 bug，而不是證明功能正常。

• 嘗試破壞你測試的每一個功能。 不要只檢查「按鈕是否存在？」— 請快速點擊兩次、送出空白表單、貼上 500 個字元、在流程中途按下 Escape。
• 測試開發者沒考慮到的情境。 空白狀態、錯誤復原、僅用鍵盤導覽、行動版溢出 (overflow)。
• 每一個斷言 (assertion) 都必須有憑有據。 比較操作前後的比對快照 (snapshots)。透過 ref 檢查特定元素。切勿在缺乏無障礙樹 (accessibility tree) 的具體證據或確定性檢查的情況下回報 PASS。
• 回報失敗時需提供足夠重現的細節。 包含精確的動作、預期結果、實際結果以及建議的修復方案。

斷言協定

每個測試步驟必須產生結構化的斷言。請勿撰寫如「這看起來不錯」的自由格式文字。

步驟標記

針對每個測試步驟，發出恰好一個標記：

STEP_PASS|<step-id>|<evidence>

或

STEP_FAIL|<step-id>|<expected> → <actual>|<screenshot-path>

• step-id：簡短識別碼，例如 homepage-cta、form-validation-error、modal-cancel
• evidence：證明步驟通過的觀察結果（元素 ref、文字內容、URL、eval 結果）
• expected → actual：預期結果 vs 實際結果
• screenshot-path：儲存的螢幕截圖路徑（僅限失敗時 — 請參閱下方螢幕截圖擷取說明）

失敗時的螢幕截圖擷取

每個 STEP_FAIL 必須附帶一張螢幕截圖，以便開發者能直觀地看到問題所在。

當測試步驟失敗時：

# 1. 在觀察到失敗後立即截圖
browse screenshot --path .context/ui-test-screenshots/<step-id>.png

# 若不支援 --path，請執行截圖後手動儲存：
browse screenshot
# browse CLI 會輸出截圖路徑 — 移動/複製它：
cp /tmp/browse-screenshot-*.png .context/ui-test-screenshots/<step-id>.png

在任何測試執行前建立螢幕截圖目錄：

mkdir -p .context/ui-test-screenshots

規則：

• 檔名 = step-id（例如 double-submit.png、axe-audit.png、modal-focus-trap.png）
• 儲存於 .context/ui-test-screenshots/ — 此目錄已被 gitignore，且可供開發者與其他 Agent 存取
• 對於平行執行，需包含 Session 名稱：<session>-<step-id>.png（例如 signup-double-submit.png）
• 在失敗的當下立即截圖 — 捕捉損壞的狀態，而非復原後的狀態
• 對於視覺/版面 bug，同時截取基準（正常狀態）以供比較：<step-id>-baseline.png

如何驗證（依嚴謹度排序）

1. 確定性檢查（最嚴謹）— browse eval 回傳你可以檢查的結構化資料。例如：axe-core 違規次數、document.title、表單欄位值、console 錯誤陣列、元素數量。
2. 快照元素比對 — 在無障礙樹中存在具備特定 role 與文字的特定元素。透過 ref 檢查：@0-12 button "Save"。元素要麼存在於樹中，要麼不存在。
3. 操作前後比較 — 操作前擷取快照、執行動作、操作後擷取快照。驗證樹是否以預期的模式改變（元素出現、消失、文字改變）。
4. 截圖 + 視覺判斷（最不嚴謹）— 僅適用於無障礙樹無法擷取的純視覺屬性（顏色、間距、版面配置）。必須始終附帶你具體正在評估的內容。

操作前後比較模式

這是核心驗證迴圈。適用於每一次互動：

# 1. BEFORE: 擷取狀態
browse snapshot
# 記錄：存在哪些元素、其文字、其 ref

# 2. ACT: 執行互動
browse click @0-12

# 3. AFTER: 擷取新狀態
browse snapshot
# 比較：改變了什麼？出現了什麼？消失了什麼？

# 4. ASSERT: 根據比較結果發出標記
# 若對話框出現：STEP_PASS|modal-open|dialog "Confirm" appeared at @0-20
# 若無任何改變：
browse screenshot --path .context/ui-test-screenshots/modal-open.png
# STEP_FAIL|modal-open|expected dialog to appear → snapshot unchanged|.context/ui-test-screenshots/modal-open.png

設定

which browse || npm install -g browse

避免頻繁的權限確認

此 skill 會執行許多 browse 命令（快照、點擊、eval）。為避免逐一核準，請將 browse 新增至許可命令集中：

將這兩種模式新增至 .claude/settings.json（專案層級）或 ~/.claude/settings.json（使用者層級）：

{
  "permissions": {
    "allow": [
      "Bash(browse:*)",
      "Bash(BROWSE_SESSION=*)"
    ]
  }
}

第一個模式涵蓋一般 browse 命令；第二個模式涵蓋平行 Session (BROWSE_SESSION=signup browse open ...)。兩者皆需要，以避免跳出核準提示。

模式選擇

目標	模式	命令	驗證/權限
localhost / 127.0.0.1	Local	browse open <url> --local	無需（預設使用乾淨隔離的本機瀏覽器）
已部署/Staging 網站	Remote	browse open <url> --remote	Browserbase 憑證；在支援處使用 Contexts

規則：若目標 URL 包含 localhost 或 127.0.0.1，請在首次 browse open 時傳入 --local。

本機模式（Localhost 預設）

browse open http://localhost:3000 --local

browse open ... --local 預設使用乾淨隔離的本機瀏覽器，這是進行可重現 localhost QA 執行的最佳方式。

僅在需要時使用本機模式的變體：

• browse open <url> --auto-connect — 自動偵測現有可偵錯的本機 Chrome。僅在測試明確需要現有本機登入/Cookie/狀態時使用。
• browse open <url> --cdp <port|url> — 附加至特定 CDP 目標（明確的本機瀏覽器附加）。

遠端模式（透過 cookie-sync 存取已部署網站）

# 步驟 1：將 Cookie 從本機 Chrome 同步至 Browserbase
node .claude/skills/cookie-sync/scripts/cookie-sync.mjs --domains your-app.com
# 輸出：Context ID: ctx_abc123

# 步驟 2：使用同步後的 Context 以遠端模式開啟
SESSION_JSON="$(browse cloud sessions create --context-id ctx_abc123 --persist --keep-alive)"
SESSION_ID="$(echo "$SESSION_JSON" | jq -r .id)"
CONNECT_URL="$(echo "$SESSION_JSON" | jq -r .connectUrl)"

browse open https://staging.your-app.com --cdp "$CONNECT_URL"
browse snapshot
# ... 執行測試 ...
browse stop
browse cloud sessions update "$SESSION_ID" --status REQUEST_RELEASE

Cookie-sync 旗標：--domains、--context、--verified、--proxy "City,ST,US"

工作流程 A：Diff 驅動測試

階段 1：分析 Diff

git diff --name-only HEAD~1          # 或：git diff --name-only / git diff --name-only main...HEAD
git diff HEAD~1 -- <file>            # 檢視實際變更

將變更的檔案分類：

檔案模式	UI 影響	測試內容

<!-- truncated for translation batch; full body continues in source -->