dogfood

Overview

What the dogfood skill does

dogfood skill 使用 agent-browser client 自動化 Web 應用程式的探索式測試。它會系統性地探索目標網站或 app，針對視覺介面、功能、UX、效能、console 與無障礙等面向尋找缺陷，並產出一份包含以下內容的 結構化 QA 報告：

• 清楚的 issue 標題與分類
• 嚴重程度（critical、high、medium、low）
• 任何一位同事都能依循的重現步驟
• 逐步對應的截圖
• 需要時針對互動問題錄製的重現影片

這讓 dogfood 在你被要求「dogfood 一下」、「幫忙 QA」、「做探索式測試」、「找 bug」或「測這個 app/site/platform」時特別實用，而且能產出可以直接交給工程師、設計師或產品經理的佐證資料。

Who dogfood is for

如果你是以下角色，適合使用 dogfood skill：

• QA 工程師與 SDET，希望有可重複執行的探索式測試與完整的重現證據。
• Frontend 與 Full‑stack 工程師，想在發佈前快速 sanity check 近期修改。
• 產品經理與設計師，需要快速取得具體範例的 UX / UI 回饋。
• 新創與小型團隊，沒有專職 QA，卻需要有系統地找出問題。

When dogfood is a good fit

以下情境特別適合使用 dogfood：

• 你的目標是 以瀏覽器為主的 Web app 或網站（公開網域或 localhost）。
• 你想要 端到端探索使用流程，而不是僅執行單一 Script 化測試。
• 你同樣重視 UX 與 UI 完整度，不只是在意功能是否壞掉。
• 你需要 可分享的輸出（截圖、影片與 markdown 報告），能直接接上既有工作流程。

以下情況則較不適合：

• 你的主要目標是 純後端 API，沒有任何瀏覽器介面。
• 你只需要 Unit test 或低階整合測試，而不是以使用者行為為主的檢查。
• 你需要 正式的壓力測試 或超出探索式互動所能揭露的合成效能指標。

How dogfood works at a high level

在 vercel-labs/agent-browser repository 中，dogfood 會以下列設定啟動 agent-browser client：

• 要在瀏覽器開啟的 target URL
• 可選的 session naming、scope 與 output directory
• 若需要登入時，額外的 authentication steps
• 用來維持發現結果一致性的參考 issue taxonomy（references/issue-taxonomy.md）
• 用來組織最終 QA 報告的 report template（templates/dogfood-report-template.md）

接著，skill 會驅動瀏覽器走過關鍵使用流程，在發現問題時擷取截圖與影片，並以一致的格式記錄下來。

How to Use

Prerequisites

要有效使用 dogfood，你應該先準備好：

• 從 vercel-labs/agent-browser repository 取得 agent-browser client 的存取權限
• 想要測試的 app 或網站 URL，例如 https://example.com 或 http://localhost:3000
• （選用）若 app 需要登入，準備好測試用帳號密碼

此 skill 是以上游文件中提到的 直接執行 agent-browser binary 為設計基礎，而不是 npx agent-browser，以確保你能使用效能更佳的 Rust client。

Installing the dogfood skill

在你的 agent skills 環境中安裝此 skill：

npx skills add https://github.com/vercel-labs/agent-browser --skill dogfood

此指令會從 vercel-labs/agent-browser repository 中的 skills/dogfood 目錄拉取 dogfood skill 定義，其中包含：

• SKILL.md – 主要說明與執行時預期
• references/issue-taxonomy.md – 如何一致地分類 issue
• templates/dogfood-report-template.md – 最終報告使用的 markdown 樣板

安裝完成後，請從 Files 分頁或本機檢出查看這些檔案，再進行第一次執行。

Core configuration: required and optional inputs

dogfood skill 提供合理預設值，讓你能快速開始測試。

必要參數

• Target URL – 你想要 dogfood 的 Web app 或網站
  範例：vercel.com、https://example.com、http://localhost:3000

有預設值的選用參數

• Session name
  預設值：由網域轉成 slug（例如 vercel.com → vercel-com）
  覆寫範例：--session my-first-dogfood-run

• Output directory
  預設值：./dogfood-output/
  覆寫範例：Output directory: /tmp/qa

• Scope
  預設值：整個 app
  覆寫範例：Focus on the billing page、Only test onboarding and settings、Ignore marketing pages

• Authentication
  預設值：無
  覆寫範例：Sign in to user@example.com（你再透過一般安全管道提供憑證）

當有人說「dogfood vercel.com」時，此 skill 的設計就是要 直接用預設值開始跑，除非需要登入但尚未提供帳密，否則不該停下來多問問題。

Typical dogfood workflow

你可以依照下列流程，作為每個 Web app 測試的固定起手式：

1. Initialize a dogfood session

先決定你想涵蓋的範圍以及結果要儲存在哪裡。例如你可以：

• 選擇一個 target URL（本機開發可用 http://localhost:3000，或使用 staging 網域）。
• 視需要指定 session name，方便區分不同執行。
• 視需要自訂 output directory，例如指定到共用資料夾。

啟動帶有 dogfood skill 的 agent，並依 SKILL.md 說明在 prompt 或設定中提供這些參數。

2. Authenticate if needed

如果你的 app 需要登入：

• 提供清楚指示，例如：Sign in to qa-user@example.com。
• 確保測試帳號與密碼能透過你慣用的安全機制存取。

dogfood skill 會把登入視為探索流程的一部分，讓它也能在登入後頁面發現問題。

3. Explore key user journeys

在選定的 scope 內，dogfood 會驅動瀏覽器走過具代表性的使用流程，例如：

• 新使用者 onboarding 或註冊流程
• 登入與帳號管理
• 產品核心操作（建立、編輯、刪除各種資料）
• 主要區塊之間的導覽
• 設定、帳單或個人資料頁面

在探索過程中，它會使用 references/issue-taxonomy.md 中的 issue taxonomy，以一致方式發現並分類問題。

4. Capture issues with evidence

對於每個 issue，dogfood 會盡量收集：

• 簡短又具描述性的 issue title
• Severity：critical、high、medium、low
• Category：visual、functional、ux、content、performance、console、accessibility
• 問題發生的 URL
• Repro video 路徑（互動型問題），或對於靜態顯示錯誤則標記為 N/A
• Step-by-step screenshots，讓任何人都能對照畫面重現

這個結構會對應到 templates/dogfood-report-template.md 的格式。

5. Generate the dogfood report

探索完成後，skill 會依照 templates/dogfood-report-template.md 輸出一份 markdown 報告：

• 一個按嚴重程度統計的 summary table
• 詳細的 Issues 區段，每個 issue 都包含說明與附有截圖標註的重現步驟

你可以把這份報告放在程式碼庫裡、附在 ticket 上，或直接分享給團隊。

Customizing dogfood for your workflow

雖然預設設定可直接使用，你仍可以調整 dogfood 來更貼近你的 QA 流程：

• 使用團隊專用的 output directory，例如 /tmp/qa 或共用網路磁碟。
• 縮小 scope，聚焦在高風險區域，例如帳單、結帳或新功能。
• 檢視並參考 references/issue-taxonomy.md，將嚴重程度與分類定義對齊你們內部 QA 標準。
• 將產生的 markdown 報告後處理匯入 bug tracker，可個別複製 issue 或直接附上整份報告。

Files worth reviewing in the repository

若想深入了解 dogfood skill，建議從以下檔案開始：

• SKILL.md – 關於 skill 行為以及可呼叫工具的權威說明。
• references/issue-taxonomy.md – 定義嚴重程度、分類，以及探索檢查清單，確保不同執行間的結果一致。
• templates/dogfood-report-template.md – 顯示最終報告中 issue 與 session 摘要的實際格式。

FAQ

Is dogfood a unit test or end-to-end test framework?

不是。dogfood skill 主要用於 Web 應用程式的 探索式、以使用者為中心的 QA。它透過 agent-browser 操控瀏覽器，模擬人工測試者探索流程並記錄附有佐證的缺陷。它不會取代 unit test、integration test 或程式層級框架，而是搭配使用，用來補強視覺、UX 與互動類問題的偵測。

What kinds of issues can dogfood detect?

dogfood 的設計是圍繞在 references/issue-taxonomy.md 中定義的 issue taxonomy，鼓勵你記錄下列問題：

• Visual / UI issues – 版面破版、文字重疊、RWD 問題、色彩對比不足、icon 或圖片顯示錯誤。
• Functional bugs – 失效連結、按鈕沒反應、表單送出失敗、錯誤導頁、狀態遺失、檔案上傳/下載問題。
• UX issues – 導覽動線混亂、缺乏操作回饋、標籤不清楚、互動遲緩或沒有反應。
• Content issues – 拼字錯誤、術語不一致、內容過時。
• Performance issues – 在探索過程中明顯感受到頁面或操作很慢。
• Console issues – 使用期間瀏覽器 console 出現的錯誤或警告。
• Accessibility issues – 缺少 alt text、鍵盤陷阱、焦點管理不佳等可觀察到的問題。

這套 taxonomy 會讓 dogfood session 更有系統，也能在不同執行間保持可比性。

How do I start a quick dogfood run against a new site?

當有人說「dogfood example.com」時，你可以這樣做：

1. 確認已從 vercel-labs/agent-browser 安裝好 dogfood skill。
2. 呼叫帶有 dogfood skill 的 agent，並只提供 Target URL 即可。
3. 除非你有特別需求，否則讓 skill 使用預設的 session name、scope（整個 app）與 output directory。

目標是能 立即開始測試，而不用花時間處理繁瑣設定。

Does dogfood require authentication to work?

不需要。dogfood 在不必登入的公開網站與行銷頁面上也能正常運作。

若你的 app 有重要流程需要登入，建議你：

• 先註明需要驗證（例如：Sign in to user@example.com）。
• 透過既有的安全管道提供登入憑證。

之後，skill 會把登入流程也納入 session 範圍內，一起探索登入後的頁面。

Where can I see how issues are categorized and reported?

在 vercel-labs/agent-browser repository 裡有兩個關鍵參考：

• references/issue-taxonomy.md – 說明 severity levels、issue categories，並提供 exploration checklist。
• templates/dogfood-report-template.md – 展示 Dogfood Report 的結構，包括 summary table，以及含有 Severity、Category、URL、Repro Video、Description 與附截圖 Repro Steps 等欄位的個別 issue 區塊。

在第一次執行前先閱讀這兩個檔案，有助於你理解並調整 dogfood skill 產生的報告。

When is dogfood not the right tool?

以下狀況下，dogfood skill 並不是理想工具：

• 你在測試 非瀏覽器系統（CLI 工具、桌面應用程式、後端服務），agent-browser 無法與之互動。
• 你需要的是 壓力測試 或超出主觀觀察之外的 合成效能指標。
• 你希望在 CI pipeline 中加入 細粒度、程式化的測試；這種情況下應搭配傳統測試框架，而不是只依賴 dogfood。

在這些情境中，請把 dogfood 視為一層著重於真實瀏覽器行為的補充工具，而不是其他測試工具的替代品。