agent-browser

差异对比#

比较页面状态以检测变化，可通过可访问性树快照进行结构对比、通过像素比较进行视觉对比，或者直接比较两个不同 URL。

验证操作是否改变了页面
$ agent-browser snapshot -i
$ agent-browser fill @e3 "test@example.com"
$ agent-browser click @e4
$ agent-browser diff snapshot
heading "注册" [ref=e1]
text "创建你的账户" [ref=e2]
- textbox "邮箱" [ref=e3]
+ textbox "邮箱" [ref=e3]: "test@example.com"
- button "提交" [ref=e4]
+ button "提交" [ref=e4] [disabled]
+ status "发送中..." [ref=e7]
link "已经有账户？" [ref=e5]
3 处新增， 2 处删除， 3 处未变
捕获视觉回归
$ agent-browser diff screenshot --baseline before-deploy.png
✗ 2.37% 的像素不同
差异图像：~/.agent-browser/tmp/diffs/diff-1708473621.png
1,137 个不同 / 48,000 个总像素
基线
提交
当前
提交
差异
提交

命令#

命令描述
diff snapshot将当前快照与会话中的上一次快照进行比较
diff snapshot --baseline <file>将当前快照与已保存文件进行比较
diff screenshot --baseline <file>与基线图片进行像素级视觉 diff
diff url <url1> <url2>比较两个页面（快照 + 可选截图）

快照对比#

使用按行文本 diff 对比两个时间点之间的可访问性树。

bash
# Compare against the last snapshot taken in this session
agent-browser diff snapshot

# Compare against a saved baseline file
agent-browser diff snapshot --baseline before.txt

# Scope to a specific part of the page
agent-browser diff snapshot --selector "#main" --compact

如果不提供 --baseline，命令会自动与当前会话中最近一次快照进行比较。这是代理验证某个动作是否达到预期效果的主要用法。

选项#

标志描述
-b, --baseline <file>用于比较的已保存快照文件路径
-s, --selector <sel>将当前快照限定到 CSS 选择器或 @ref
-c, --compact使用紧凑快照格式
-d, --depth <n>限制快照树深度

输出#

diff 会使用 + 表示新增行、- 表示删除行，格式类似统一 diff。摘要行会显示新增、删除和未变化行的数量。

bash
- button "Submit" [ref=e2]
+ button "Submit" [ref=e2] [disabled]
  3 additions, 2 removals, 41 unchanged

截图对比#

在像素级别将当前页面截图与基线图片进行比较，并生成一张将变更像素标红的 diff 图。

bash
# Basic visual diff
agent-browser diff screenshot --baseline before.png

# Save diff image to a specific path
agent-browser diff screenshot --baseline before.png --output diff.png

# Adjust threshold and scope to element
agent-browser diff screenshot --baseline before.png --threshold 0.2 --selector "#hero"

选项#

标志描述
-b, --baseline <file>用于比较的基线 PNG/JPEG 图片（必填）
-o, --output <file>生成的 diff 图片保存路径（默认：临时目录）
-t, --threshold <0-1>颜色距离阈值（默认：0.1）。数值越高，容差越大
-s, --selector <sel>将当前截图限定到某个元素
--full截取整页截图

输出#

会报告 diff 图片路径、不同像素数量以及不匹配百分比。diff 图片会把未变化像素压暗，并把变更像素标红。

如果基线图和当前图尺寸不同，命令会报告尺寸不匹配，而不会尝试像素比较。

URL 对比#

通过依次导航到两个页面并对结果进行 diff 来比较它们。

bash
# Compare two URLs (snapshot diff)
agent-browser diff url https://staging.example.com https://prod.example.com

# Include visual comparison
agent-browser diff url https://v1.example.com https://v2.example.com --screenshot

# Full-page screenshot comparison
agent-browser diff url https://v1.example.com https://v2.example.com --screenshot --full

命令会先打开第一个 URL、捕获状态，然后再打开第二个 URL 并再次捕获。快照 diff 始终包含在内；截图 diff 需要 --screenshot 标志。

完成后，浏览器会停留在第二个 URL。

选项#

标志描述
--screenshot同时执行视觉截图比较
--full使用整页截图
--wait-until <strategy>导航等待策略：load、domcontentloaded、networkidle（默认：load）
-s, --selector <sel>将快照限定到 CSS 选择器或 @ref
-c, --compact使用紧凑快照格式
-d, --depth <n>限制快照树深度

使用场景#

验证代理动作#

最常见的场景：确认某个动作（click、fill、submit）是否按预期改变了页面。

bash
agent-browser snapshot -i          # Take interactive-only snapshot (baseline)
agent-browser fill @e3 "test@example.com"
agent-browser diff snapshot        # Compare current snapshot to the baseline

监控变化#

定期将页面与已保存的基线进行比较，以发现更新。

bash
# Save baseline
agent-browser open https://example.com && agent-browser snapshot > baseline.txt

# Later, check for changes
agent-browser open https://example.com && agent-browser diff snapshot --baseline baseline.txt

视觉回归测试#

比较部署前后的截图，以捕捉非预期的视觉变化。

bash
agent-browser open https://staging.example.com && agent-browser screenshot baseline.png
# ... deploy happens ...
agent-browser open https://staging.example.com && agent-browser diff screenshot --baseline baseline.png

比较环境#

对比 staging 与 production，以验证一致性。

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