dogfood

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dogfood

Systematically explore a web application, find issues, and produce a report with full reproduction evidence for every finding.

系统性地探索Web应用，发现问题，并为每个发现生成一份包含完整复现证据的报告。

Setup

配置说明

Only the Target URL is required. Everything else has sensible defaults -- use them unless the user explicitly provides an override.

Parameter	Default	Example override
Target URL	(required)	`vercel.com` , `http://localhost:3000`
Session name	Slugified domain (e.g., `vercel.com` -> `vercel-com` )	`--session my-session`
Output directory	`./dogfood-output/`	`Output directory: /tmp/qa`
Scope	Full app	`Focus on the billing page`
Authentication	None	`Sign in to user@example.com`

If the user says something like "dogfood vercel.com", start immediately with defaults. Do not ask clarifying questions unless authentication is mentioned but credentials are missing.

Always use

agent-browser

directly -- never

npx agent-browser

. The direct binary uses the fast Rust client.

npx

routes through Node.js and is significantly slower.

仅需目标URL即可。其余参数均有合理默认值——除非用户明确提供覆盖值，否则使用默认值。

参数	默认值	示例覆盖值
目标URL	（必填）	`vercel.com` , `http://localhost:3000`
会话名称	域名转短横线格式（例如： `vercel.com` -> `vercel-com` ）	`--session my-session`
输出目录	`./dogfood-output/`	`Output directory: /tmp/qa`
测试范围	整个应用	`Focus on the billing page`
身份验证	无	`Sign in to user@example.com`

如果用户输入类似“dogfood vercel.com”的指令，请立即使用默认值启动测试。除非提到身份验证但未提供凭据，否则无需询问澄清问题。

请直接使用

agent-browser

——切勿使用

npx agent-browser

。直接调用二进制文件会使用快速的Rust客户端，而

npx

会通过Node.js路由，速度明显更慢。

Workflow

工作流程

1. Initialize    Set up session, output dirs, report file
2. Authenticate  Sign in if needed, save state
3. Orient        Navigate to starting point, take initial snapshot
4. Explore       Systematically visit pages and test features
5. Document      Screenshot + record each issue as found
6. Wrap up       Update summary counts, close session

1. 初始化    设置会话、输出目录、报告文件
2. 身份验证  如需登录则完成登录，保存状态
3. 环境熟悉  导航至起始页面，拍摄初始快照
4. 探索测试  系统性地访问页面并测试功能
5. 问题记录  发现问题时立即截图+录制相关内容
6. 收尾工作  更新摘要统计，关闭会话

1. Initialize

1. 初始化

bash

mkdir -p {OUTPUT_DIR}/screenshots {OUTPUT_DIR}/videos

Copy the report template into the output directory and fill in the header fields:

bash

cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md

Start a named session:

bash

agent-browser --session {SESSION} open {TARGET_URL}
agent-browser --session {SESSION} wait --load networkidle

bash

mkdir -p {OUTPUT_DIR}/screenshots {OUTPUT_DIR}/videos

将报告模板复制到输出目录并填写头部字段：

bash

cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md

启动命名会话：

bash

agent-browser --session {SESSION} open {TARGET_URL}
agent-browser --session {SESSION} wait --load networkidle

2. Authenticate

2. 身份验证

If the app requires login:

bash

agent-browser --session {SESSION} snapshot -i

如果应用需要登录：

bash

agent-browser --session {SESSION} snapshot -i

Identify login form refs, fill credentials

识别登录表单元素，填写凭据

agent-browser --session {SESSION} fill @e1 "{EMAIL}" agent-browser --session {SESSION} fill @e2 "{PASSWORD}" agent-browser --session {SESSION} click @e3 agent-browser --session {SESSION} wait --load networkidle


For OTP/email codes: ask the user, wait for their response, then enter the code.

After successful login, save state for potential reuse:

```bash
agent-browser --session {SESSION} state save {OUTPUT_DIR}/auth-state.json


对于OTP/邮箱验证码：向用户询问，等待回复后输入验证码。

登录成功后，保存状态以备后续复用：

```bash
agent-browser --session {SESSION} state save {OUTPUT_DIR}/auth-state.json

3. Orient

3. 环境熟悉

Take an initial annotated screenshot and snapshot to understand the app structure:

bash

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/initial.png
agent-browser --session {SESSION} snapshot -i

Identify the main navigation elements and map out the sections to visit.

拍摄初始带注释的截图和快照，以了解应用结构：

bash

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/initial.png
agent-browser --session {SESSION} snapshot -i

识别主导航元素，规划需要访问的板块。

4. Explore

4. 探索测试

Read references/issue-taxonomy.md for the full list of what to look for and the exploration checklist.

Strategy -- work through the app systematically:

Start from the main navigation. Visit each top-level section.
Within each section, test interactive elements: click buttons, fill forms, open dropdowns/modals.
Check edge cases: empty states, error handling, boundary inputs.
Try realistic end-to-end workflows (create, edit, delete flows).
Check the browser console for errors periodically.

At each page:

bash

agent-browser --session {SESSION} snapshot -i
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/{page-name}.png
agent-browser --session {SESSION} errors
agent-browser --session {SESSION} console

Use your judgment on how deep to go. Spend more time on core features and less on peripheral pages. If you find a cluster of issues in one area, investigate deeper.

阅读references/issue-taxonomy.md以查看完整的检查清单和需关注的问题类型。

策略——系统性地遍历应用：

从主导航开始，访问每个顶级板块。
在每个板块内，测试交互元素：点击按钮、填写表单、打开下拉菜单/弹窗。
检查边缘情况：空状态、错误处理、边界输入值。
尝试真实的端到端工作流（创建、编辑、删除流程）。
定期检查浏览器控制台是否有错误。

在每个页面执行：

bash

agent-browser --session {SESSION} snapshot -i
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/{page-name}.png
agent-browser --session {SESSION} errors
agent-browser --session {SESSION} console

自行判断测试深度。在核心功能上投入更多时间，对边缘页面减少投入。如果在某个区域发现多个问题，可深入调查。

5. Document Issues (Repro-First)

5. 问题记录（优先复现）

Steps 4 and 5 happen together -- explore and document in a single pass. When you find an issue, stop exploring and document it immediately before moving on. Do not explore the whole app first and document later.

Every issue must be reproducible. When you find something wrong, do not just note it -- prove it with evidence. The goal is that someone reading the report can see exactly what happened and replay it.

Choose the right level of evidence for the issue:

步骤4和5同步进行——在单次流程中完成探索和记录。发现问题时，停止探索并立即记录，然后再继续。切勿先遍历整个应用再统一记录问题。

每个问题必须可复现。发现问题时，不要仅做记录——要用证据证明。目标是让阅读报告的人能清楚看到发生了什么并复现问题。

根据问题类型选择合适的证据级别：

Interactive / behavioral issues (functional, ux, console errors on action)

交互/行为类问题（功能、UX、操作触发的控制台错误）

These require user interaction to reproduce -- use full repro with video and step-by-step screenshots:

Start a repro video before reproducing:

bash

agent-browser --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.webm

Walk through the steps at human pace. Pause 1-2 seconds between actions so the video is watchable. Take a screenshot at each step:

bash

agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png
sleep 1

这类问题需要用户交互才能复现——需使用完整的复现视频和分步截图：

在复现前启动录制视频：

bash

agent-browser --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.webm

以人类操作速度执行步骤。操作间暂停1-2秒，确保视频可观看。为每个步骤截图：

bash

agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png
sleep 1

Perform action (click, fill, etc.)

执行操作（点击、填写等）

sleep 1 agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png sleep 1

...continue until the issue manifests

...继续操作直至问题出现


3. **Capture the broken state.** Pause so the viewer can see it, then take an annotated screenshot:

```bash
sleep 2
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}-result.png

Stop the video:

bash

agent-browser --session {SESSION} record stop

Write numbered repro steps in the report, each referencing its screenshot.


3. **捕获异常状态**。暂停以便查看者看清，然后拍摄带注释的截图：

```bash
sleep 2
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}-result.png

停止录制视频：

bash

agent-browser --session {SESSION} record stop

在报告中编写编号的复现步骤，每个步骤对应其截图。

Static / visible-on-load issues (typos, placeholder text, clipped text, misalignment, console errors on load)

静态/加载可见类问题（拼写错误、占位文本、文本截断、排版错位、加载时的控制台错误）

These are visible without interaction -- a single annotated screenshot is sufficient. No video, no multi-step repro:

bash

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}.png

Write a brief description and reference the screenshot in the report. Set Repro Video to

N/A

For all issues:

Append to the report immediately. Do not batch issues for later. Write each one as you find it so nothing is lost if the session is interrupted.
Increment the issue counter (ISSUE-001, ISSUE-002, ...).

这类问题无需交互即可看到——仅需一张带注释的截图即可。无需视频或多步复现：

bash

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}.png

在报告中编写简短描述并引用该截图。将复现视频设为

N/A

。

所有问题需遵循：

立即追加到报告中。切勿批量记录问题。发现一个就记录一个，避免会话中断导致数据丢失。
递增问题计数器（ISSUE-001, ISSUE-002, ...）。

6. Wrap Up

6. 收尾工作

Aim to find 5-10 well-documented issues, then wrap up. Depth of evidence matters more than total count -- 5 issues with full repro beats 20 with vague descriptions.

After exploring:

Re-read the report and update the summary severity counts so they match the actual issues. Every
```
### ISSUE-
```
block must be reflected in the totals.
Close the session:

bash

agent-browser --session {SESSION} close

Tell the user the report is ready and summarize findings: total issues, breakdown by severity, and the most critical items.

目标是找到5-10个记录完善的问题，然后收尾。证据的详实程度比数量更重要——5个带完整复现信息的问题胜过20个描述模糊的问题。

探索完成后：

重新阅读报告并更新摘要中的严重程度统计，使其与实际问题匹配。每个
```
### ISSUE-
```
块都必须体现在总数中。
关闭会话：

bash

agent-browser --session {SESSION} close

告知用户报告已准备就绪，并总结发现：问题总数、按严重程度分类的明细，以及最关键的问题。

Guidance

指导原则

Repro is everything. Every issue needs proof -- but match the evidence to the issue. Interactive bugs need video and step-by-step screenshots. Static bugs (typos, placeholder text, visual glitches visible on load) only need a single annotated screenshot.
Don't record video for static issues. A typo or clipped text doesn't benefit from a video. Save video for issues that involve user interaction, timing, or state changes.
For interactive issues, screenshot each step. Capture the before, the action, and the after -- so someone can see the full sequence.
Write repro steps that map to screenshots. Each numbered step in the report should reference its corresponding screenshot. A reader should be able to follow the steps visually without touching a browser.
Be thorough but use judgment. You are not following a test script -- you are exploring like a real user would. If something feels off, investigate.
Write findings incrementally. Append each issue to the report as you discover it. If the session is interrupted, findings are preserved. Never batch all issues for the end.
Never delete output files. Do not
```
rm
```
screenshots, videos, or the report mid-session. Do not close the session and restart. Work forward, not backward.
Never read the target app's source code. You are testing as a user, not auditing code. Do not read HTML, JS, or config files of the app under test. All findings must come from what you observe in the browser.
Check the console. Many issues are invisible in the UI but show up as JS errors or failed requests.
Test like a user, not a robot. Try common workflows end-to-end. Click things a real user would click. Enter realistic data.
Type like a human. When filling form fields during video recording, use
```
type
```
instead of
```
fill
```
-- it types character-by-character. Use
```
fill
```
only outside of video recording when speed matters.
Pace repro videos for humans. Add
```
sleep 1
```
between actions and
```
sleep 2
```
before the final result screenshot. Videos should be watchable at 1x speed -- a human reviewing the report needs to see what happened, not a blur of instant state changes.
Be efficient with commands. Batch multiple
```
agent-browser
```
commands in a single shell call when they are independent (e.g.,
```
agent-browser ... screenshot ... && agent-browser ... console
```
). Use
```
agent-browser --session {SESSION} scroll down 300
```
for scrolling -- do not use
```
key
```
or
```
evaluate
```
to scroll.

复现是核心。每个问题都需要证据——但要根据问题类型匹配证据。交互类Bug需要视频和分步截图。静态Bug（拼写错误、占位文本、加载时可见的视觉故障）仅需一张带注释的截图。
不为静态问题录制视频。拼写错误或文本截断不需要视频。仅为涉及用户交互、时序或状态变化的问题录制视频。
对于交互类问题，为每个步骤截图。捕获操作前、操作中、操作后的状态——以便他人查看完整流程。
编写与截图对应的复现步骤。报告中的每个编号步骤都应引用对应的截图。阅读者无需打开浏览器，即可通过视觉跟随步骤复现问题。
全面但需灵活判断。你无需遵循测试脚本——要像真实用户一样探索。如果感觉有问题，就深入调查。
逐步记录发现。发现问题后立即追加到报告中。如果会话中断，已有的发现也能保留。切勿将所有问题留到最后统一记录。
切勿删除输出文件。会话过程中不要删除截图、视频或报告文件。不要关闭会话后重新启动。按流程推进，不要回溯。
切勿阅读目标应用的源代码。你是作为用户进行测试，而非审计代码。不要查看被测应用的HTML、JS或配置文件。所有发现必须来自你在浏览器中的观察。
检查控制台。许多问题在UI中不可见，但会以JS错误或请求失败的形式出现在控制台中。
像用户一样测试，而非机器人。尝试常见的端到端工作流。点击真实用户会点击的内容。输入真实的数据。
以人类的速度输入。录制视频时填写表单字段，使用
```
type
```
而非
```
fill
```
——它会逐字符输入。仅在追求速度的非录制场景中使用
```
fill
```
。
为人类调整复现视频的节奏。操作间添加
```
sleep 1
```
，最终结果截图前添加
```
sleep 2
```
。视频应以1倍速可观看——阅读报告的人需要看清发生了什么，而非快速闪过的状态变化。
高效使用命令。当多个
```
agent-browser
```
命令相互独立时，在单个shell调用中批量执行（例如：
```
agent-browser ... screenshot ... && agent-browser ... console
```
）。使用
```
agent-browser --session {SESSION} scroll down 300
```
进行滚动——不要使用
```
key
```
或
```
evaluate
```
来滚动。

References

参考资料

Reference	When to Read
references/issue-taxonomy.md	Start of session -- calibrate what to look for, severity levels, exploration checklist

参考文档	阅读时机
references/issue-taxonomy.md	会话开始时——明确需关注的问题类型、严重程度级别和探索检查清单

Templates

模板

Template	Purpose
templates/dogfood-report-template.md	Copy into output directory as the report file

模板	用途
templates/dogfood-report-template.md	复制到输出目录作为报告文件