agent-browser-visual

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

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

---

绝不

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

---

用例决策树

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

---

视觉回归工作流

# Step 1: Capture baseline (run once before changes)
agent-browser open <url>
agent-browser wait --load networkidle
agent-browser screenshot --full baseline.png

# Step 2: After changes, compare
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)
agent-browser diff screenshot --baseline baseline.png -s "#main-content"

# Step 4: Compare two environments (snapshot + optionally screenshots)
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 ——适用于动态内容区域的宽松模式

---

视频录制工作流

# 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
# ... perform actions ...
agent-browser record stop

# Record from a fresh 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

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

---

带注释的截图

agent-browser screenshot --annotate step1.png

输出：叠加了编号标签的截图，以及将每个编号映射到其元素名称的图例。

适用于：Bug 报告、文档编写，以及与非技术审核者分享上下文。与光标叠加相比，注释标签在截图压缩后仍更清晰。

---

HAR 录制（完整网络跟踪）

# 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
# Or: https://har.tech (online analyzer)

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

---

DOM 快照差异

# Compare current DOM vs last snapshot in this session
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

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

---

故障恢复模式

故障	恢复方法
差异始终显示有变化（动画 / 加载）	wait --load networkidle，并添加 wait 500 以等待 CSS 过渡完成
差异过于敏感（抗锯齿噪点）	增大 --threshold 0.2
差异未能发现真实回归	减小 --threshold 0.05
视频文件过大	将录制范围限制为较短的流程；对于静态证据，使用 screenshot --full
HAR 缺少早期请求	重新开始：必须在 open 之前调用 network har start
record 丢失身份验证状态	始终先执行 open 和 wait，然后再执行 record start（不带 URL 参数）

---

易犯错误

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