browser-tester

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

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

---

Phase 0: 前置檢查

0.1 設定 playwright-cli

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
export PWCLI="$CODEX_HOME/skills/playwright/scripts/playwright_cli.sh"
"$PWCLI" --version

如果 $PWCLI --version 失敗 → 輸出以下訊息並中斷所有操作：

playwright-cli 不可用。請確認：
1. Node.js / npm 已安裝
2. npx 在 PATH 中

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)。Playwright 錄影解析度跟隨 viewport，因此第 2 步的 resize 1920 1080 是強制規範，不可省略也不可降低——它直接決定了錄影畫質。若未來 playwright-cli 提供 video-start 的解析度參數，仍須鎖定 1920x1080。

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

# 2. 統一視窗解析度為 1920x1080（決定錄影畫質為 1080P，必做）
"$PWCLI" resize 1920 1080

# 3. 開始錄影（必須在所有操作之前；錄影畫質 = 1920x1080 = 1080P）
"$PWCLI" video-start

# 4. 取得頁面元素參考
"$PWCLI" snapshot

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

# 6. 截圖重點時刻（見 3.3 截圖指引）
"$PWCLI" screenshot

# 7. 檢查 console 錯誤
"$PWCLI" console warning

# 8. 檢查網路請求
"$PWCLI" network

# 9. 停止錄影並儲存
"$PWCLI" video-stop --filename "output/playwright/browser-test/videos/${scenario_name}.webm"

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 頁面	頁面上變更的區域（使用元素截圖 screenshot <ref>）
UI 組件	頁面上顯示該變更組件的區域（使用元素截圖 screenshot <ref>）

截圖儲存：

"$PWCLI" screenshot          # 全頁截圖（備用）
"$PWCLI" screenshot e15      # 元素截圖（優先）
# 截圖自動儲存到當前目錄，手動移至：
# output/playwright/browser-test/screenshots/{scenario}-{step}.png

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/

---

錯誤處理

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