Help us improve
Share bugs, ideas, or general feedback.
From ddd-workflow
Debug E2E test failures using agent-browser CLI in a DDD workflow. Guides step-by-step from failure to root cause with browser inspection commands.
npx claudepluginhub applepig/ddd-workflowHow this skill is triggered — by the user, by Claude, or both
Slash command
/ddd-workflow:ddd.agent-browserThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
在 DDD 工作流的開發階段(`/ddd.work`),當 Playwright E2E 測試失敗或需要視覺驗證時,
Automates E2E web app tests using agent-browser CLI with accessibility tree snapshots and ref system for stable interactions like clicks, fills, navigation, and visual checks in bash scripts.
Tests local web applications using Playwright: verifies frontend functionality, debugs UI behavior, captures screenshots, views logs. Mandatory before declaring implementation complete.
Automates headless browser via agent-browser CLI: open/navigate sites, snapshot interactive elements for refs, click/fill forms, verify UI, scrape data, e2e test web apps.
Share bugs, ideas, or general feedback.
在 DDD 工作流的開發階段(/ddd.work),當 Playwright E2E 測試失敗或需要視覺驗證時,
用 agent-browser CLI 直接操作瀏覽器來定位問題。
與 /ddd.e2e 的分工:/ddd.e2e 規劃與撰寫 E2E 測試案例;本 skill 是測試失敗後的除錯工具。
測試跑不過 → 先用本 skill 除錯定位原因;需要新增或修改測試 → 用 /ddd.e2e。
這份說明書不是瀏覽器自動化教學,而是除錯流程指南——幫你從「測試掛了」走到「找到根因」。
測試失敗 → 前置檢查 → 重現場景 → 觀察狀態 → 定位根因 → 修正 → 驗證
每一步都有對應的 agent-browser 指令,按順序走就對了。
不要用 which agent-browser 檢查安裝——npm 全域安裝的工具不一定在 which 的搜尋路徑中。改用 agent-browser tab 一次完成兩件事:確認 CLI 可用、確認瀏覽器連線狀態。
# 確認 CLI 可用 + 瀏覽器已連線 + 查看現有 tab
agent-browser tab
先把瀏覽器帶到測試失敗的那個畫面。
⚠️ 避免用
agent-browser open開新頁面:open會建立隱藏(背景)tab,導致後續截圖抓到空白畫面。優先重用 Step 0 看到的前景 tab。
# ✅ 正確:用 open 在「現有前景 tab」中導航(tab 已存在時 open 是安全的)
agent-browser tab # 確認有前景 tab
agent-browser open http://localhost:3000/target-page # 在當前 tab 導航
# ✅ 正確:如果沒有任何 tab,用 tab new 建立可見 tab
agent-browser tab new http://localhost:3000/target-page
agent-browser tab 0 # 確保切到該 tab
# ❌ 錯誤:沒有 tab 時直接 open(會建立隱藏 tab)
agent-browser open http://localhost:3000/target-page # → 截圖會失敗
導航後等頁面載入、拿 ref:
agent-browser wait --load networkidle
agent-browser snapshot -i
如果測試需要登入狀態,用 session 持久化避免重複登入:
# 首次登入並儲存狀態
agent-browser tab # 確認前景 tab 存在
agent-browser open http://localhost:3000/login
agent-browser snapshot -i
agent-browser fill @e1 "test@example.com"
agent-browser fill @e2 "password"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
# 之後的除錯直接載入狀態
agent-browser --session-name debug open http://localhost:3000/target-page
根據失敗類型選擇觀察方式。
# 互動元素快照(最常用)
agent-browser snapshot -i
# 限定範圍——只看特定區塊
agent-browser snapshot -s "#form-container"
# 取得特定元素的文字內容
agent-browser get text @e1
# 取得元素的 HTML
agent-browser get html @e1
# 檢查元素狀態
agent-browser is visible @e1
agent-browser is enabled @e2
agent-browser is checked @e3
# 截圖——快速確認畫面長什麼樣
agent-browser screenshot
# 整頁截圖(含捲動區域)
agent-browser screenshot --full
# 標註互動元素的截圖——看元素位置和佈局
agent-browser screenshot --annotate
# 比對兩個 URL 的畫面差異
agent-browser diff url http://localhost:3000/page http://staging.example.com/page
# 查看 console 訊息(log, error, warn, info)
agent-browser console
# 只看未捕獲的 JS 例外
agent-browser errors
# 在瀏覽器中執行 JS 檢查狀態
agent-browser eval 'document.querySelectorAll(".error-message").length'
# 複雜的 JS 用 stdin 避免 shell 跳脫問題
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify({
url: location.href,
errors: document.querySelectorAll(".error").length,
formData: Object.fromEntries(new FormData(document.querySelector("form")))
})
EVALEOF
# 列出所有網路請求
agent-browser network requests
# 過濾特定 API 請求
agent-browser network requests --filter "/api/"
# 攔截請求(模擬 API 失敗)
agent-browser network route "/api/submit" --abort
agent-browser network route "/api/data" --body '{"error": "mocked failure"}'
# 移除攔截
agent-browser network unroute "/api/submit"
模擬使用者操作來重現失敗路徑。
# 填表單
agent-browser fill @e1 "test input"
agent-browser select @e2 "option-value"
agent-browser check @e3
# 按鍵操作
agent-browser press Tab
agent-browser press Enter
agent-browser keyboard type "search query"
# 點擊並等待結果
agent-browser click @e5
agent-browser wait --load networkidle
# 重要:操作後一定要重新拿 snapshot
agent-browser snapshot -i
@e1、@e2 這些 ref 在頁面變動後會失效。以下操作後必須重新 snapshot:
agent-browser click @e5 # 觸發頁面變動
agent-browser snapshot -i # 必須重新拿 ref
agent-browser click @e1 # 用新的 ref
錄影(record)、Playwright Trace(trace)、效能分析(profiler)、元素高亮(highlight)等進階工具詳見 references/agent-browser-advanced.md。
當 snapshot ref 不穩定或元素沒有好的選擇器時,用語義定位:
agent-browser find text "送出" click
agent-browser find label "電子郵件" fill "test@example.com"
agent-browser find role button click --name "Submit"
agent-browser find placeholder "搜尋" type "query"
agent-browser find testid "submit-btn" click
# 1. 確認頁面載入完成
agent-browser wait --load networkidle
# 2. 用 snapshot 檢查元素是否存在
agent-browser snapshot -i
# 3. 如果不在互動快照中,看完整 DOM
agent-browser snapshot
# 4. 可能在 iframe 或 shadow DOM 中
agent-browser eval 'document.querySelectorAll("iframe").length'
# 5. 可能被 CSS 隱藏
agent-browser is visible "your-selector"
# 1. 確認元素可見且可用
agent-browser is visible @e1
agent-browser is enabled @e1
# 2. 捲動到元素位置
agent-browser scrollintoview @e1
# 3. 檢查是否有覆蓋層擋住
agent-browser screenshot --annotate
# 4. 試用語義定位器
agent-browser find role button click --name "Submit"
# 1. 填完表單後截圖看驗證訊息
agent-browser screenshot
# 2. 檢查錯誤訊息元素
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify(
Array.from(document.querySelectorAll("[class*='error'], [class*='invalid'], .field-error"))
.map(el => ({ text: el.textContent.trim(), visible: el.offsetParent !== null }))
)
EVALEOF
# 3. 檢查表單欄位的 validity 狀態
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify(
Array.from(document.querySelectorAll("input, select, textarea"))
.map(el => ({ name: el.name, valid: el.validity.valid, message: el.validationMessage }))
)
EVALEOF
# 1. 列出 API 請求
agent-browser network requests --filter "/api/"
# 2. 模擬不同的 API 回應來驗證前端處理
agent-browser network route "/api/data" --body '{"items": []}'
# 3. 模擬網路錯誤
agent-browser network route "/api/data" --abort
# 4. 清除攔截後恢復正常
agent-browser network unroute
# 設定 viewport
agent-browser set viewport 375 812
# 模擬裝置
agent-browser set device "iPhone 14"
# 截圖比對
agent-browser screenshot mobile.png
# 恢復桌面尺寸
agent-browser set viewport 1920 1080
# 1. 檢查 cookies
agent-browser cookies
# 2. 檢查 localStorage
agent-browser storage local
# 3. 驗證 token
agent-browser eval "localStorage.getItem('token')"
# 4. 檢查 sessionStorage
agent-browser storage session
# 5. 清除登入狀態重新測試
agent-browser cookies clear
agent-browser eval "localStorage.clear()"
/ddd.work TDD 循環中使用works.md