agent-browser-visual

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Visual Evidence & Regression — Execution Protocol

视觉证据与回归测试 — 执行协议

Internal template. Entry point:
agent-browser
skill.

内部模板。入口：
agent-browser
技能。

NEVER

禁止操作

NEVER compare screenshots before `wait --load networkidle` — animation frames cause false diffs
NEVER use default diff threshold for pixel-perfect checks — set --threshold 0.05 or lower
NEVER skip baseline update after intentional UI changes — stale baseline = false positives forever
NEVER start `network har start` after navigation — HAR must begin before the requests you want to capture
NEVER start `record start` before opening the page — start after `open` + `wait` to preserve auth state

NEVER compare screenshots before `wait --load networkidle` — 动画帧会导致误判差异
NEVER use default diff threshold for pixel-perfect checks — 设置--threshold 0.05或更低
NEVER skip baseline update after intentional UI changes — 过时的基准线会永远导致误报
NEVER start `network har start` after navigation — HAR必须在你想要捕获的请求开始前启动
NEVER start `record start` before opening the page — 在`open` + `wait`之后启动以保留认证状态

Use Case Decision Tree

用例决策树

Goal	Command
Catch visual regression (before/after deploy)	`diff screenshot --baseline`
Compare staging vs production side by side	`diff url`
Detect DOM structure changes	`diff snapshot`
Create shareable demo / bug report video	`record start` → actions → `record stop`
Annotated screenshot for docs / ticket	`screenshot --annotate`
Capture full network trace for perf/debug	`network har start` → actions → `network har stop`

目标	命令
捕获部署前后的视觉回归	`diff screenshot --baseline`
并排对比预发布与生产环境	`diff url`
检测DOM结构变化	`diff snapshot`
创建可分享的演示/ bug报告视频	`record start` → 执行操作 → `record stop`
用于文档/工单的带注释截图	`screenshot --annotate`
捕获完整网络轨迹用于性能分析/调试	`network har start` → 执行操作 → `network har stop`

Visual Regression Workflow

视觉回归测试流程

bash

undefined

bash

undefined

Step 1: Capture baseline (run once before changes)

步骤1：捕获基准线（变更前执行一次）

agent-browser open <url> agent-browser wait --load networkidle agent-browser screenshot --full baseline.png

Step 2: After changes, compare

步骤2：变更后进行对比

agent-browser open <url> agent-browser wait --load networkidle agent-browser diff screenshot --baseline baseline.png --output diff.png --threshold 0.1

Step 3: Scope to specific element (reduces noise from unrelated areas)

步骤3：限定到特定元素（减少无关区域的干扰）

agent-browser diff screenshot --baseline baseline.png -s "#main-content"

Step 4: Compare two environments (snapshot + optionally screenshots)

步骤4：对比两个环境（快照 + 可选截图）

agent-browser diff url https://staging.example.com https://prod.example.com agent-browser diff url https://staging.example.com https://prod.example.com --screenshot --full


**Threshold guide:**
- `0.1` (default) — tolerates antialiasing, minor rendering differences
- `0.05` — catches subtle color/font changes
- `0.01` — pixel-perfect (sensitive to any rendering difference)
- `0.2` — forgiving mode for dynamic content areas

---

agent-browser diff url https://staging.example.com https://prod.example.com agent-browser diff url https://staging.example.com https://prod.example.com --screenshot --full


**阈值指南：**
- `0.1`（默认）—— 容忍抗锯齿、轻微渲染差异
- `0.05`—— 捕获细微的颜色/字体变化
- `0.01`—— 像素级完美（对任何渲染差异都敏感）
- `0.2`—— 动态内容区域的宽松模式

---

Video Recording Workflow

视频录制流程

bash

undefined

bash

undefined

Best practice: open page first, then start recording (preserves auth state)

最佳实践：先打开页面，再开始录制（保留认证状态）

agent-browser open <url> agent-browser wait --load networkidle agent-browser snapshot -i # explore first, plan your actions agent-browser record start ./demo.webm

agent-browser open <url> agent-browser wait --load networkidle agent-browser snapshot -i # 先探索，规划操作 agent-browser record start ./demo.webm

... perform actions ...

... 执行操作 ...

agent-browser record stop

Record from a fresh URL

从全新URL开始录制

agent-browser record start ./onboarding.webm https://app.example.com/signup

Restart (stop current recording, start new — useful for retakes)

重新录制（停止当前录制，开始新录制 — 适合重拍）

agent-browser record restart ./take2.webm


> To convert WebM → GIF: `ffmpeg -i demo.webm -vf "fps=10,scale=800:-1:flags=lanczos" demo.gif`

---

agent-browser record restart ./take2.webm


> 转换WebM为GIF：`ffmpeg -i demo.webm -vf "fps=10,scale=800:-1:flags=lanczos" demo.gif`

---

Annotated Screenshot

带注释的截图

bash

agent-browser screenshot --annotate step1.png

Output: screenshot with numbered labels overlaid + a legend mapping each number to its element name.

Ideal for: bug reports, documentation, sharing context with non-technical reviewers. The annotation labels survive screenshot compression better than cursor overlays.

bash

agent-browser screenshot --annotate step1.png

输出：带有编号标签叠加层的截图 + 映射每个编号到对应元素名称的图例。

适用场景：bug报告、文档撰写、与非技术评审人员共享上下文。注释标签比光标叠加层更能在截图压缩后保留清晰性。

HAR Recording (full network trace)

HAR录制（完整网络轨迹）

bash

undefined

bash

undefined

Must start BEFORE navigation to capture all requests

必须在导航前启动以捕获所有请求

agent-browser network har start ./trace.har agent-browser open <url> agent-browser wait --load networkidle

... perform actions you want to trace ...

... 执行你想要追踪的操作 ...

agent-browser network har stop

View: open in browser DevTools → Network tab → Import HAR

查看方式：在浏览器开发者工具 → 网络标签 → 导入HAR

Or: https://har.tech (online analyzer)

或使用在线分析工具：https://har.tech


Use when: diagnosing slow pages, verifying API calls, auditing third-party requests.

---


适用场景：诊断页面加载缓慢问题、验证API调用、审计第三方请求。

---

DOM Snapshot Diff

DOM快照对比

bash

undefined

bash

undefined

Compare current DOM vs last snapshot in this session

对比当前DOM与本次会话中的上一个快照

agent-browser diff snapshot

Compare against a saved snapshot file

与保存的快照文件对比

agent-browser diff snapshot --baseline before.txt

Scope to a specific section

限定到特定区域

agent-browser diff snapshot -s ".sidebar" -c

Combined: compact + depth-limited scope

组合使用：紧凑模式 + 限定深度

agent-browser diff snapshot -s "#app" -c -d 4


Use when: verifying a code change didn't silently alter DOM structure, or checking that a UI component renders identically across environments.

---

agent-browser diff snapshot -s "#app" -c -d 4


适用场景：验证代码变更未悄然改变DOM结构，或检查UI组件在不同环境中的渲染一致性。

---

Recovery Patterns

故障恢复方案

Failure	Recovery
Diff always shows changes (animation/loading)	`wait --load networkidle` + add `wait 500` for CSS transitions
Diff too sensitive (antialiasing noise)	Increase `--threshold 0.2`
Diff misses real regression	Decrease `--threshold 0.05`
Video file too large	Scope recording to shorter flow; use `screenshot --full` for static evidence
HAR missing early requests	Restart: `network har start` must be called before `open`
`record` loses auth state	Always `open` + `wait` first, then `record start` (no URL arg)

故障	恢复方法
对比始终显示变化（动画/加载中）	`wait --load networkidle` + 添加 `wait 500` 等待CSS过渡完成
对比过于敏感（抗锯齿噪点）	提高阈值至 `--threshold 0.2`
对比遗漏真实回归	降低阈值至 `--threshold 0.05`
视频文件过大	将录制范围限定为更短的流程；使用 `screenshot --full` 获取静态证据
HAR缺失早期请求	重新开始： `network har start` 必须在 `open` 之前调用
`record` 丢失认证状态	始终先执行 `open` + `wait` ，再启动 `record start` （不使用URL参数）

Pitfalls

常见误区

Mistake	Fix
Screenshot before page is stable	`wait --load networkidle` before any capture
Baseline not updated after intentional design change	Delete old baseline, re-capture: `screenshot --full baseline.png`
`diff screenshot` without `--baseline`	`--baseline <file>` is required
HAR started after XHR calls already fired	`network har start` must come before `open` or `reload`
`record start` before page open loses auth	Open page + wait first, then start recording

错误操作	修复方法
页面未稳定时截图	在任何捕获操作前执行 `wait --load networkidle`
有意修改设计后未更新基准线	删除旧基准线，重新捕获： `screenshot --full baseline.png`
使用 `diff screenshot` 时未加 `--baseline`	必须指定 `--baseline <file>`
XHR请求已触发后才启动HAR	`network har start` 必须在 `open` 或 `reload` 之前执行
打开页面前启动 `record start` 导致丢失认证	先打开页面并等待，再启动录制