dogfood

Overview

What the dogfood skill does

Kỹ năng dogfood giúp tự động hóa kiểm thử khám phá (exploratory testing) cho ứng dụng web bằng client agent-browser. Nó sẽ có hệ thống khám phá site hoặc app mục tiêu, tìm lỗi trên nhiều khía cạnh như giao diện (UI), chức năng, UX, hiệu năng, console và khả năng truy cập (accessibility), rồi tạo ra một báo cáo QA có cấu trúc với:

• Tiêu đề và phân loại vấn đề rõ ràng
• Mức độ nghiêm trọng (critical, high, medium, low)
• Các bước tái hiện lỗi mà đồng đội có thể dễ dàng làm theo
• Ảnh chụp màn hình theo từng bước
• Video tái hiện cho các vấn đề tương tác khi cần

Điều này khiến dogfood đặc biệt hữu ích khi bạn được yêu cầu “dogfood”, “QA”, “exploratory test”, “bug hunt” hoặc “test app/site/platform này” và cần bằng chứng có thể chuyển thẳng cho kỹ sư, nhà thiết kế hoặc product manager.

Who dogfood is for

Hãy sử dụng kỹ năng dogfood nếu bạn là:

• QA engineer hoặc SDET muốn có các lượt chạy exploratory lặp lại được, kèm bằng chứng tái hiện lỗi phong phú.
• Kỹ sư frontend hoặc full‑stack muốn sanity-check các thay đổi trước khi phát hành.
• Product manager và designer cần phản hồi nhanh về UX và UI với ví dụ cụ thể.
• Startup và các nhóm nhỏ chưa có đội QA riêng nhưng vẫn cần cách có hệ thống để tìm vấn đề.

When dogfood is a good fit

Dogfood phù hợp khi:

• Mục tiêu của bạn là web app hoặc website chạy trên browser (public domain hoặc localhost).
• Bạn muốn khám phá luồng end-to-end thay vì chỉ chạy một bài test kịch bản đơn lẻ.
• Bạn quan tâm đến độ chỉn chu về UX và UI không kém gì lỗi chức năng.
• Bạn cần kết quả dễ chia sẻ (screenshot, video và báo cáo markdown) có thể tích hợp vào quy trình hiện tại.

Dogfood kém phù hợp hơn khi:

• Mục tiêu chính của bạn là API backend thuần túy không có giao diện browser.
• Bạn chỉ cần unit test hoặc integration test mức thấp thay vì kiểm tra hành vi hướng người dùng.
• Bạn yêu cầu kiểm thử tải (load test) chính thức hoặc benchmark hiệu năng synthetic vượt quá những gì tương tác khám phá có thể cho thấy.

How dogfood works at a high level

Từ repository vercel-labs/agent-browser, dogfood cấu hình client agent-browser với:

• Một target URL để mở trong browser
• Tùy chọn tên session, scope và output directory
• Tùy chọn bước xác thực khi cần đăng nhập
• Một issue taxonomy tham chiếu (references/issue-taxonomy.md) để giữ các phát hiện nhất quán
• Một report template (templates/dogfood-report-template.md) để cấu trúc báo cáo QA cuối cùng

Sau đó, kỹ năng này điều khiển browser đi qua các user flow chính, chụp screenshot và video khi phát hiện vấn đề, đồng thời ghi nhận lại theo một định dạng nhất quán.

How to Use

Prerequisites

Để sử dụng dogfood hiệu quả, bạn nên có:

• Quyền truy cập client agent-browser từ repository vercel-labs/agent-browser
• URL của app hoặc site bạn muốn test, ví dụ https://example.com hoặc http://localhost:3000
• (Tuỳ chọn) Tài khoản test nếu app yêu cầu đăng nhập

Kỹ năng này được thiết kế xoay quanh binary agent-browser chạy trực tiếp được đề cập trong tài liệu upstream, không phải npx agent-browser. Nhờ đó bạn tận dụng được client Rust nhanh hơn.

Installing the dogfood skill

Cài kỹ năng vào môi trường agent skills của bạn với:

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

Lệnh này sẽ kéo định nghĩa kỹ năng dogfood từ skills/dogfood trong repository vercel-labs/agent-browser, bao gồm:

• SKILL.md – mô tả chính và kỳ vọng khi runtime
• references/issue-taxonomy.md – cách phân loại vấn đề nhất quán
• templates/dogfood-report-template.md – mẫu markdown cho báo cáo cuối cùng

Sau khi cài đặt, mở tab Files hoặc bản checkout local để xem lại các file này trước lần chạy đầu tiên.

Core configuration: required and optional inputs

Kỹ năng dogfood được thiết kế để khởi động nhanh với các giá trị mặc định hợp lý, giúp bạn bắt đầu test ngay.

Tham số bắt buộc

• Target URL – web app hoặc website bạn muốn dogfood
  Ví dụ: vercel.com, https://example.com, http://localhost:3000

Tham số tuỳ chọn với giá trị mặc định

• Session name
  Mặc định: slugified domain (ví dụ vercel.com → vercel-com)
  Ví dụ override: --session my-first-dogfood-run

• Output directory
  Mặc định: ./dogfood-output/
  Ví dụ override: Output directory: /tmp/qa

• Scope
  Mặc định: toàn bộ app
  Ví dụ override: Focus on the billing page, Only test onboarding and settings, Ignore marketing pages

• Authentication
  Mặc định: không có
  Ví dụ override: Sign in to user@example.com (sau đó bạn cung cấp credential qua kênh bảo mật như thường lệ)

Nếu ai đó nói “dogfood vercel.com”, kỹ năng này được thiết kế để khởi chạy ngay với mặc định. Nó sẽ không dừng lại để hỏi thêm trừ khi cần đăng nhập nhưng chưa có credential.

Typical dogfood workflow

Hãy dùng trình tự sau như một điểm xuất phát đáng tin cậy cho mỗi web app bạn test:

1. Initialize a dogfood session

Quyết định phạm vi muốn cover và nơi lưu kết quả. Ví dụ, bạn có thể:

• Chọn một target URL (http://localhost:3000 cho môi trường local, hoặc domain staging).
• Tuỳ chọn chọn session name để phân biệt các lượt chạy.
• Tuỳ chọn tùy chỉnh output directory nếu muốn lưu kết quả vào thư mục dùng chung.

Chạy agent của bạn với kỹ năng dogfood được bật và cung cấp các tham số này trong prompt hoặc cấu hình như mô tả trong SKILL.md.

2. Authenticate if needed

Nếu app của bạn yêu cầu đăng nhập:

• Cung cấp hướng dẫn rõ ràng như: Sign in to qa-user@example.com.
• Đảm bảo credential test sẵn sàng qua quy trình bảo mật nội bộ.

Kỹ năng dogfood sẽ coi bước xác thực là một phần của luồng khám phá, để có thể tìm vấn đề trên cả các trang yêu cầu đăng nhập.

3. Explore key user journeys

Trong phạm vi đã chọn, dogfood điều khiển browser đi qua các flow tiêu biểu, ví dụ:

• Onboarding hoặc đăng ký người dùng mới
• Đăng nhập và quản lý tài khoản
• Các hành động cốt lõi của sản phẩm (tạo, sửa, xóa entity)
• Điều hướng qua các khu vực chính
• Trang cài đặt, billing hoặc hồ sơ người dùng

Trong quá trình khám phá, nó sử dụng issue taxonomy từ references/issue-taxonomy.md để phát hiện và phân loại vấn đề một cách nhất quán.

4. Capture issues with evidence

Với mỗi vấn đề, dogfood cố gắng thu thập:

• Một tiêu đề vấn đề ngắn gọn, mô tả rõ
• Mức độ nghiêm trọng: critical, high, medium, low
• Category: visual, functional, ux, content, performance, console, accessibility
• URL nơi xảy ra vấn đề
• Đường dẫn Repro video (cho vấn đề tương tác) hoặc N/A với lỗi tĩnh
• Screenshot theo từng bước để bất kỳ ai cũng có thể theo dõi trực quan

Cấu trúc này phản chiếu định dạng trong templates/dogfood-report-template.md.

5. Generate the dogfood report

Khi quá trình khám phá hoàn tất, kỹ năng sẽ xuất một báo cáo markdown theo templates/dogfood-report-template.md:

• Một bảng tóm tắt với số lượng issue theo từng mức độ nghiêm trọng
• Phần Issues chi tiết, trong đó mỗi issue có mô tả và bước tái hiện được chú thích kèm screenshot

Bạn có thể lưu báo cáo này cùng với codebase, đính kèm vào ticket, hoặc chia sẻ trực tiếp với nhóm.

Customizing dogfood for your workflow

Dù mặc định hoạt động tốt ngay từ đầu, bạn có thể tùy chỉnh dogfood để phù hợp hơn với quy trình QA của mình:

• Dùng output directory dành riêng cho team, ví dụ /tmp/qa hoặc ổ mạng chia sẻ.
• Thu hẹp scope để tập trung vào khu vực rủi ro cao như billing, checkout hoặc tính năng mới.
• Điều chỉnh định nghĩa mức độ nghiêm trọng và category cho khớp với tiêu chuẩn QA nội bộ bằng cách xem và tham chiếu references/issue-taxonomy.md.
• Hậu xử lý báo cáo markdown đã tạo để đưa vào bug tracker bằng cách copy từng issue hoặc đính kèm toàn bộ báo cáo.

Files worth reviewing in the repository

Để hiểu sâu về kỹ năng dogfood, hãy bắt đầu với:

• SKILL.md – mô tả chuẩn về cách kỹ năng hoạt động và những tool nó có thể gọi.
• references/issue-taxonomy.md – định nghĩa mức độ nghiêm trọng, category và checklist khám phá để kết quả nhất quán giữa các lượt chạy.
• templates/dogfood-report-template.md – cho thấy chính xác cách định dạng issue và tóm tắt session trong báo cáo cuối cùng.

FAQ

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

Không. Kỹ năng dogfood chủ yếu dùng cho QA khám phá, lấy người dùng làm trung tâm cho ứng dụng web. Nó điều khiển browser qua agent-browser để hành xử như một tester thực thụ, khám phá các flow và ghi log lỗi kèm bằng chứng. Nó không thay thế unit test, integration test hoặc các framework ở tầng code; thay vào đó, nó bổ trợ bằng cách bắt các vấn đề về giao diện, UX và tương tác.

What kinds of issues can dogfood detect?

Dogfood được thiết kế xoay quanh một issue taxonomy được định nghĩa trong references/issue-taxonomy.md. Nó khuyến khích bạn ghi nhận các vấn đề như:

• Visual / UI issues – vỡ layout, chữ đè nhau, lỗi responsive, độ tương phản màu, icon hoặc hình ảnh bị lỗi.
• Functional bugs – link hỏng, nút không hoạt động, form lỗi, redirect sai, mất state, lỗi upload/download file.
• UX issues – điều hướng khó hiểu, thiếu phản hồi, nhãn không rõ ràng, tương tác chậm hoặc không phản hồi.
• Content issues – lỗi chính tả, thuật ngữ không nhất quán, nội dung lỗi thời.
• Performance issues – trang hoặc thao tác chậm thấy rõ trong quá trình khám phá.
• Console issues – error hoặc warning trong browser console khi sử dụng.
• Accessibility issues – thiếu alt text, bẫy phím (keyboard trap), xử lý focus kém và các vấn đề quan sát được tương tự.

Taxonomy này giúp các session dogfood có tính hệ thống và dễ so sánh giữa các lần chạy.

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

Khi có người yêu cầu “dogfood example.com”, bạn có thể:

1. Đảm bảo kỹ năng dogfood đã được cài từ vercel-labs/agent-browser.
2. Gọi agent của bạn với kỹ năng dogfood và chỉ cần cung cấp Target URL.
3. Để kỹ năng dùng giá trị mặc định cho tên session, scope (toàn bộ app) và output directory trừ khi bạn có nhu cầu override cụ thể.

Mục tiêu là bắt đầu test ngay lập tức, không cần một pha cấu hình dài dòng.

Does dogfood require authentication to work?

Không. Dogfood hoạt động tốt trên site/public page hoặc marketing page không yêu cầu đăng nhập.

Nếu app của bạn cần đăng nhập cho các flow quan trọng, bạn nên:

• Nêu rõ là cần authentication (ví dụ: Sign in to user@example.com).
• Cung cấp credential qua kênh bảo mật nội bộ như thường lệ.

Kỹ năng sau đó sẽ coi đăng nhập là một phần của session để có thể khám phá cả khu vực yêu cầu xác thực.

Where can I see how issues are categorized and reported?

Có hai tài liệu tham chiếu quan trọng trong repository vercel-labs/agent-browser thể hiện điều này:

• references/issue-taxonomy.md – giải thích mức độ nghiêm trọng, category của issue và cung cấp exploration checklist.
• templates/dogfood-report-template.md – thể hiện cấu trúc Dogfood Report, bao gồm bảng tóm tắt và từng block issue riêng lẻ với các field như Severity, Category, URL, Repro Video, Description và Repro Steps kèm screenshot.

Xem trước các file này trước lần chạy đầu tiên sẽ giúp bạn hiểu và tùy chỉnh báo cáo do kỹ năng dogfood tạo ra.

When is dogfood not the right tool?

Kỹ năng dogfood không phù hợp trong các trường hợp:

• Bạn đang test hệ thống không chạy trên browser (tool CLI, app desktop, dịch vụ backend) mà agent-browser không tương tác được.
• Bạn cần load testing hoặc chỉ số hiệu năng synthetic vượt ra ngoài quan sát định tính.
• Bạn muốn bài test được code chi tiết và nhúng chặt vào CI pipeline; khi đó hãy dùng thêm các test framework truyền thống bên cạnh dogfood.

Trong những kịch bản đó, hãy xem dogfood như một lớp bổ sung, tập trung vào hành vi thực tế trên browser, chứ không phải thay thế cho các công cụ kiểm thử khác.