browser-tester

name	browser-tester
description	Git diff 驅動的瀏覽器模擬人工測試工作流程。分析程式碼變更、映射影響範圍、使用 agent-browser 執行瀏覽器測試、錄製影片截圖、產出測試報告。

/browser-tester — Diff 驅動瀏覽器模擬測試

根據 git diff 自動判斷受影響頁面，使用 agent-browser 模擬人類操作，錄製影片並截圖重點。

---

Phase 0: 前置檢查

0.1 偵測 agent-browser（唯一主工具）

agent-browser 為外部 CLI，非本 plugin 打包。偵測方式：

agent-browser --version

• 可用 → 若環境有 user-level agent-browser skill 則優先載入該 skill；否則直接下 CLI 指令（自助文件：agent-browser skills get core --full）。

• 未安裝（互動情境） → 提示用戶安裝並等其決定，不得靜默跳過或改用其他工具：

  npm install -g agent-browser   # 安裝 CLI
  agent-browser install          # 首次使用下載瀏覽器 binary
  

• 未安裝（CI 環境，GITHUB_ACTIONS=true） → 自動安裝後繼續：

  npm install -g agent-browser && agent-browser install
  

• 用戶拒裝 → 輸出「瀏覽器測試依賴缺失：請執行 npm install -g agent-browser && agent-browser install」並中斷所有操作。

agent-browser daemon 常駐，指令間 session 保留、可用 && 串接；headless 預設，本機除錯可加 --headed。後續 Phase 3 的指令一律以 agent-browser <verb> 具體形式執行。

0.2 偵測環境

IS_CI=$(printenv GITHUB_ACTIONS || echo "false")

記住 IS_CI 值，後續決定報告模式（本地 vs CI）。

0.3 決定測試目標 URL

按以下優先級取得 BASE_URL：

1. 用戶 prompt 中明確提供的 URL
2. 環境變數：依序檢查 APP_URL、SITE_URL、WP_URL、BASE_URL
3. 專案配置推斷：
   • .env 中的 URL 相關設定
   • package.json 的 scripts.dev / scripts.start 中的 port
   • .wp-env.json 中的設定（WordPress 項目）
   • docker-compose.yml 中的 port mapping
4. localhost 探測：嘗試 http://localhost:3000、:5173、:8080、:8888

如果無法確定 URL → 向用戶詢問，或中斷操作。

0.4 建立產出目錄

mkdir -p output/playwright/browser-test/videos
mkdir -p output/playwright/browser-test/screenshots

---

Phase 1: Diff 分析

1.1 取得變更檔案

# 取得預設分支名稱
DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
DEFAULT_BRANCH=${DEFAULT_BRANCH:-master}

# 取得變更檔案清單（含統計）
git diff "origin/${DEFAULT_BRANCH}...HEAD" --name-only --stat

1.2 分類變更檔案

將每個變更檔案歸入以下類別：

類別	特徵路徑模式	測試策略
API 變更	routes/ controllers/ services/ api/ endpoints/ rest-api/	導航到所有呼叫該 API 的頁面
UI 頁面變更	pages/ views/ screens/ templates/ admin/	導航到所有修改到的頁面
UI 組件變更	components/ widgets/ blocks/ partials/	導航到其中一個使用該組件的頁面
非前端變更	migrations/ config/ tests/ .github/ docs/ styles-only	跳過瀏覽器測試

1.3 無可測變更處理

如果所有變更都歸類為「非前端變更」：

測試結果：無瀏覽器可測變更
變更摘要：
- {列出變更檔案}
- 這些變更不涉及前端頁面或 API，無需瀏覽器測試

輸出此報告後結束。

---

Phase 2: 影響範圍映射

2.1 使用 Serena MCP（優先路徑）

如果 Serena MCP 可用：

1. 對每個變更的 API/元件，使用 find_referencing_symbols 找到引用它的程式碼
2. 追蹤引用鏈直到找到頁面級元件或路由定義
3. 從路由配置映射到實際 URL：
   • React Router：讀取 createBrowserRouter / <Route> 定義
   • WordPress：讀取 add_menu_page / add_submenu_page 註冊
   • Next.js：依照 pages/ 或 app/ 目錄結構推斷

2.2 啟發式映射（備援路徑）

Serena 不可用時：

1. 使用 grep 搜尋 import/require 語句找到引用檔案
2. 根據檔案路徑模式推斷頁面 URL：
   • pages/orders/index.tsx → /orders
   • admin/class-settings-page.php → /wp-admin/admin.php?page=settings
3. 搜尋路由配置檔案匹配元件名稱到 URL

2.3 測試範圍決策

變更類別	測試範圍
API 變更	導航到所有呼叫該 API 的頁面，逐一測試
UI 頁面變更	導航到所有被修改的頁面，逐一測試
UI 組件變更	導航到其中一個使用該組件的頁面測試

2.4 輸出測試計畫

在執行測試前，先整理出測試計畫：

## 測試計畫

### 變更摘要
- API 變更：{N} 個檔案
- UI 頁面變更：{N} 個檔案
- UI 組件變更：{N} 個檔案

### 測試目標
1. {URL} — {變更類型} — {預期行為}
2. {URL} — {變更類型} — {預期行為}
...

---

Phase 3: 測試執行

對測試計畫中的每個目標 URL 執行以下流程。

3.1 單頁測試流程

錄影畫質規範：所有錄影必須為 1080P (1920x1080)。agent-browser 錄影解析度跟隨 viewport，因此必須先 agent-browser set viewport 1920 1080 再 agent-browser record start（第 2 步的 set viewport 1920 1080 是強制規範），不可省略也不可降低——它直接決定了錄影畫質。若未來 agent-browser 提供 record start 的解析度參數，仍須鎖定 1920x1080。

# 1. 開啟頁面
agent-browser open "${BASE_URL}${path}" --headed

# 2. 統一視窗解析度為 1920x1080（決定錄影畫質為 1080P，必做，須在 record start 之前）
agent-browser set viewport 1920 1080

# 3. 開始錄影（必須在所有操作之前；輸出路徑於此指定；錄影畫質 = 1920x1080 = 1080P）
agent-browser record start "output/playwright/browser-test/videos/${scenario_name}.webm"

# 4. 取得頁面元素參考（-i 只列互動元素，回傳 @ref）
agent-browser snapshot -i

# 5. 執行測試操作（見 3.2 各類型操作指引）
# ...

# 6. 截圖重點時刻（見 3.3 截圖指引）
agent-browser screenshot --full

# 7. 檢查 console 錯誤（log/warn/error/info）
agent-browser console

# 8. 檢查網路請求
agent-browser network requests

# 9. 停止錄影並儲存
agent-browser record stop

3.2 各變更類型的測試操作

API 變更測試

1. 導航到呼叫該 API 的頁面
2. 觸發 API 呼叫的操作（填表單、點按鈕、切換篩選等）
3. 等待 API 回應
4. 驗證：頁面是否正確顯示回應結果（成功通知、資料更新、錯誤訊息）
5. 檢查 network 確認 API 請求狀態碼

UI 頁面變更測試

1. 導航到修改的頁面
2. 檢視頁面佈局和視覺呈現
3. 與頁面上的互動元素互動（按鈕、連結、表單）
4. 導航到相關子頁面
5. 驗證：頁面渲染正常、互動功能正確

UI 組件變更測試

1. 導航到包含該組件的頁面
2. 找到組件在頁面上的位置
3. 與組件互動（如果可互動）
4. 驗證：組件渲染正常、互動行為正確

3.3 截圖重點時刻

截圖只截重點部分，不截整頁：

變更類型	截圖重點
API 變更	API 發出後，成功的回應通知（toast / alert / 資料更新）
UI 頁面	頁面上變更的區域（使用元素截圖 agent-browser screenshot @ref）
UI 組件	頁面上顯示該變更組件的區域（使用元素截圖 agent-browser screenshot @ref）

截圖儲存：

agent-browser screenshot --full "output/playwright/browser-test/screenshots/{scenario}-{step}.png"   # 全頁截圖（備用）
agent-browser screenshot @e15 "output/playwright/browser-test/screenshots/{scenario}-{step}.png"     # 元素截圖（優先，@ref 來自 snapshot）
# agent-browser 支援 screenshot [selector] [path]，可直接指定輸出路徑，無需再手動搬移

3.4 Re-snapshot 時機

以下操作後必須重新 snapshot：

• 導航到新頁面
• 點擊引發 DOM 大幅變更的元素（modal、tab、accordion）
• 表單提交後頁面重載
• SPA 路由切換

3.5 測試結果判定

每個頁面測試結束後，判定結果：

結果	條件
通過	頁面正常渲染 + 無 console error + 無 network 失敗 + 互動行為正確
警告	有 console warning 但無 error，功能正常
失敗	console error / network 4xx-5xx / 頁面崩潰 / 互動異常

---

Phase 4: 報告生成

4.1 報告格式

所有模式（本地 + CI）均使用以下格式，並必須將報告寫入檔案：

# 所有測試完成後，用 Bash 工具將報告寫入此路徑（必做，不可省略）
cat > output/playwright/browser-test/test-report.md << 'REPORT_EOF'
# 瀏覽器模擬測試報告

## 測試摘要
- **測試日期**：{YYYY-MM-DD}
- **變更來源**：`git diff origin/{branch}...HEAD`
- **測試頁數**：{N} 頁
- **結果**：✅ {pass} 通過 / ⚠️ {warn} 警告 / ❌ {fail} 失敗

## 測試結果明細

### {N}. {頁面名稱} ({URL})
- **變更類型**：{API/頁面/組件}
- **結果**：✅/⚠️/❌
- **操作步驟**：
  1. {step}
  2. {step}
- **截圖**：
  - ![{截圖說明}](screenshots/{NN}-{name}.png)
- **影片**：
  - [▶️ 觀看影片](videos/{NN}-{name}.webm)
- **Console 錯誤**：{有/無}
- **Network 異常**：{有/無}
REPORT_EOF

⚠️ 重要：報告必須寫入磁碟（output/playwright/browser-test/test-report.md），不可只輸出到終端。

4.2 CI 模式報告

當 GITHUB_ACTIONS=true 時：

⚠️ 禁止使用 gh CLI 發佈 Issue Comment。 在此 CI 架構中，後續的 workflow steps 會自動讀取 test-report.md、上傳媒體到 CDN 並發佈 Issue Comment。 Agent 的職責只是確保 output/playwright/browser-test/test-report.md 正確寫入磁碟，其餘由 CI 處理。

CI 模式檢查清單：

• output/playwright/browser-test/test-report.md 已寫入
• 截圖在 output/playwright/browser-test/screenshots/
• 影片在 output/playwright/browser-test/videos/

---

錯誤處理

錯誤情境	處理方式
agent-browser 不可用（未安裝且用戶拒裝 / CI 自動安裝失敗）	輸出依賴缺失指引，中斷操作
測試 URL 不可達	輸出提示（啟動 dev server / 提供 URL），中斷操作
頁面載入超時	記錄為失敗，繼續測試下一個頁面
record start 失敗	記錄警告，改用連續截圖模式，繼續測試
元素參考過期	重新 snapshot，重試操作
無法映射 URL	記錄為「無法映射」，跳過該檔案
git diff 為空	輸出「無變更」報告，正常結束
Serena 不可用	降級到啟發式映射，繼續測試