瀏覽器測試 Skill

使用目前執行環境（harness）中最優質且已核准的瀏覽器驅動程序（browser driver），針對 PR 或分支所影響的頁面執行端對端（E2E）瀏覽器測試。

模式

手動模式 (Manual，預設)： 由使用者自行控制開發伺服器（dev server）。當備用驅動程序為 agent-browser 時，系統會詢問要以有頭（headed，顯示視窗）還是無頭（headless，背景執行）模式執行。
Pipeline 模式 (mode:pipeline)： 由 LFG 或其他自動化執行工具（runner）呼叫。此模式為無人值守（unattended）執行——切勿停下來等待使用者回答問題。請讀取並遵循本 Skill 目錄下的 references/pipeline-orchestration.md；該檔案會覆寫可用連接埠掃描（步驟 4）、開發伺服器啟動（步驟 5）以及可視性提示詢問（步驟 6），但仍會使用步驟 4 計算出的偏好連接埠。

瀏覽器驅動程序策略

在執行第一個瀏覽器操作前選擇驅動程序：

優先使用宿主原生（Host-native）整合瀏覽器。 當目前執行環境內建或直接掌控的瀏覽器控制介面支援導覽至本機 URL、檢查渲染與互動狀態、點擊/填寫/按壓按鍵、擷取螢幕截圖以及檢查 Console 錯誤時，請優先採用。額外設定的瀏覽器擴充功能或整合機制不屬於宿主原生。在開工前，請先載入並遵循該整合功能自身的指示。
否則退回（fall back）至 agent-browser。 執行任何命令前，請先閱讀 references/agent-browser-driver.md。
切勿引進第三套瀏覽器工具鏈（browser stack）。 絕不安裝或替換成獨立的 Playwright、Puppeteer、額外設定的瀏覽器擴充功能或 MCP，或其他臨時（ad hoc）瀏覽器自動化工具。若在所選的宿主原生瀏覽器中暴露出 Playwright API，它仍屬於宿主原生的一部分，而非獨立的 Playwright。

整趟測試請全程使用同一套驅動程序。只有在第一個路由測試前初始化失敗時，所選的宿主原生驅動程序才可以退回到 agent-browser。一旦測試開始，切勿混用驅動程序工作階段（sessions）、元素引用（element references）、螢幕截圖或身份驗證狀態。

工作流程

1. 選擇瀏覽器驅動程序

套用上述「瀏覽器驅動程序策略」並記錄所選的驅動程序。此步驟同時需要一個含有待測變更的 git 儲存庫。

2. 確定測試範圍

若提供了 PR 編號：

gh pr view [number] --json files -q '.files[].path'

若傳入 'current' 或留空：

git diff --name-only main...HEAD

若提供了分支名稱：

git diff --name-only main...[branch]

3. 將變更檔案對映至路由

將每個變更的檔案對映至渲染它的路由，進而建立待測試的 URL 清單。下表為常見模式的起步參考，非排他性硬性規則——請依專案實際的架構靈活判斷：

檔案模式	路由
`app/views/users/*`	`/users`, `/users/:id`, `/users/new`
`app/controllers/settings_controller.rb`	`/settings`
`app/javascript/controllers/*_controller.js`	使用該 Stimulus controller 的頁面
`app/components/*_component.rb`	渲染該元件的頁面
`app/views/layouts/*`	所有頁面（至少測試首頁）
`app/assets/stylesheets/*`	關鍵頁面的視覺迴歸測試 (Visual regression)
`app/helpers/*_helper.rb`	使用該 helper 的頁面
`src/app/*` (Next.js)	對應的路由
`src/components/*`	使用這些元件的頁面

4. 確定開發伺服器連接埠

依下列優先順序確定偏好的連接埠（Port）：

明確參數 — 若使用者傳入了 --port 5000，直接採用該值。
上下文中的專案指示 — 若已在上下文中的專案指示明確載明了開發伺服器連接埠，直接採用。不要在指示檔案中 grep 尋找 Port：散文中提到的內容（如文件、範例、疑難排解）不可靠且容易誤判，設定檔與 .env 才是可靠來源。
package.json — 檢查 dev/start 腳本中是否有 --port 標記。
環境變數檔案 — 檢查 .env、.env.local、.env.development 中的 PORT=。
預設值 — 退回使用 3000。

# 若上下文中的專案指示已指定開發伺服器連接埠，先設定 EXPLICIT_PORT。
PORT="${EXPLICIT_PORT:-}"
if [ -z "$PORT" ]; then
  PORT=$(grep -Eo '\-\-port[= ]+[0-9]{4,5}' package.json 2>/dev/null | grep -Eo '[0-9]{4,5}' | head -1)
fi
if [ -z "$PORT" ]; then
  PORT=$(grep -h '^PORT=' .env .env.local .env.development 2>/dev/null | tail -1 | cut -d= -f2)
fi
PORT="${PORT:-3000}"
echo "Preferred dev server port: $PORT"

手動模式會直接照原樣使用此偏好的連接埠——使用者自行控管伺服器，因此請勿掃描其他替代連接埠。在 Pipeline 模式下，references/pipeline-orchestration.md 會讀取此處印出的偏好連接埠值，並向上掃描直到找到真正未被佔用的連接埠。

5. 確認開發伺服器正在執行

在詢問有頭/無頭模式問題之前，先確認伺服器已正常啟動——若手動執行且未啟動伺服器，流程會在此處中止，先詢問問題只會浪費該次提問。

if lsof -i ":${PORT}" -sTCP:LISTEN -t >/dev/null 2>&1; then
  echo "Server running on port ${PORT}";
else
  echo "Server not running on port ${PORT}";
  echo "Start your dev server, then re-run:";
  echo "  Rails: bin/dev  or  rails server -p ${PORT}";
  echo "  Node/Next.js: npm run dev";
  echo "  Custom port: run this skill again with --port <your-port>";
  exit 0;
fi

在 Pipeline 模式下，請勿在此處中止——references/pipeline-orchestration.md 會改為在背景自動啟動伺服器。

6. 設定瀏覽器可視性並驗證根路由

可視性設定與無人值守執行彼此獨立：

宿主原生整合瀏覽器： 保持其正常的整合介面可見且不阻礙操作，方便使用者在需要時觀看進度。切勿隨著路由切換而頻繁強行搶奪焦點（steal focus）。此原則在手動模式與 Pipeline 模式下均適用。
agent-browser 備用方案，Pipeline 模式： 直接以無頭（headless）模式執行，不進行詢問。
agent-browser 備用方案，手動模式： 使用平台的阻塞式提問工具詢問使用者要以有頭（headed）還是無頭（headless）模式執行：Claude Code 中使用 AskUserQuestion（若未載入其 schema，先呼叫 ToolSearch 帶上 select:AskUserQuestion）、Codex 中使用 request_user_input、Antigravity CLI (agy) 中使用 ask_question、Pi 中使用 ask_user（需安裝 pi-ask-user 擴充功能）。僅當執行環境中不存在阻塞式工具或呼叫出錯時，才退回到在聊天中列出選項。切勿默默跳過此提問：
```
Do you want to watch the browser tests run?

1. Headed (watch) - Opens a visible browser window
2. Headless (faster) - Runs without a visible window
```

接著使用所選的驅動程序導覽至 http://localhost:<port>，擷取其渲染或互動狀態，並在迭代測試前確認根路由成功提供服務。

7. 測試每個受影響的頁面

針對每個受影響的路由，使用所選的驅動程序進行導覽，並擷取最新的渲染或互動狀態。

驗證關鍵元素：

頁面標題/標頭存在
主要內容已渲染
無可見的錯誤訊息
表單包含預期的欄位
無歸因於測試流程的全新 Console 錯誤

測試關鍵互動： 根據所選驅動程序最新的檢查狀態推導出定位器（locators）或元素引用，執行點擊/填寫/按壓按鍵操作，然後檢查產生的新狀態。切勿盲目猜測選擇器（selectors）或重複使用過期的引用。

拍攝螢幕截圖： 當所選驅動程序支援時，擷取視埠（viewport）與全頁面的佐證截圖。當後續工作流程或報告需要檔案路徑時，請將截圖實體化為本機產物（artifacts）；否則應用程式內的佐證即已足夠。

8. 人工驗證（需要時）

當測試觸及需要外部互動的流程時，暫停並等待人工輸入。Pipeline 模式： 切勿暫停——將此類流程記錄為 Skip（跳過）並註明原因後繼續執行。

流程類型	詢問內容
OAuth	"Please sign in with [provider] and confirm it works"
Email	"Check your inbox for the test email and confirm receipt"
Payments	"Complete a test purchase in sandbox mode"
SMS	"Verify you received the SMS code"
External APIs	"Confirm the [service] integration is working"

詢問使用者（使用平台的提問工具，或展示具編號的選項並等待）：

Human Verification Needed

This test touches [flow type]. Please:
1. [Action to take]
2. [What to verify]

Did it work correctly?
1. Yes - continue testing
2. No - describe the issue

9. 處理失敗

當測試失敗時（Pipeline 模式： 切勿詢問如何處置——擷取錯誤截圖與重現步驟、記錄失敗狀況後繼續）：

記錄失敗資訊：
- 使用所選的驅動程序擷取錯誤狀態的螢幕截圖
- 記錄確切的重現步驟

詢問使用者如何處理：

Test Failed: [route]

Issue: [description]
Console errors: [if any]

How to proceed?
1. Fix now - debug and fix the failing test
2. Skip - continue testing other pages

若選擇 "Fix now"（立即修復）： 排查原因、提出修復方案、套用修復並重新執行失敗的測試
若選擇 "Skip"（跳過）： 記錄為已跳過並繼續

10. 測試總結

所有測試完成後，呈遞總結報告：

## Browser Test Results

**Test Scope:** PR #[number] / [branch name]
**Server:** http://localhost:${PORT}

### Pages Tested: [count]

| Route | Status | Notes |
|-------|--------|-------|
| `/users` | Pass | |
| `/settings` | Pass | |
| `/dashboard` | Fail | Console error: [msg] |
| `/checkout` | Skip | Requires payment credentials |

### Console Errors: [count]
- [List any errors found]

### Human Verifications: [count]
- OAuth flow: Confirmed
- Email delivery: Confirmed

### Failures: [count]
- `/dashboard` - [issue description]

### Result: [PASS / FAIL / PARTIAL]

快速使用範例

# 測試目前分支的變更（自動偵測連接埠）
/ce-test-browser

# 測試指定 PR
/ce-test-browser 847

# 測試指定分支
/ce-test-browser feature/new-dashboard

# 在指定連接埠上測試
/ce-test-browser --port 5000

驅動程序參考

當選擇 agent-browser 作為備用方案時，在執行其命令前，請先閱讀本 Skill 目錄下的 references/agent-browser-driver.md。宿主原生驅動程序則遵循其執行環境提供的指示。

ce-test-browser

相關技能