agent-browser

差异比较

通过可访问性树快照进行结构化比较，或通过像素对比进行视觉比较，亦或在两个不同网址之间进行比较。

Verify an action changed the page
$ agent-browser snapshot -i
$ agent-browser fill @e3 "[email protected]"
$ agent-browser click @e4
$ agent-browser diff snapshot
heading "Sign Up" [ref=e1]
text "Create your account" [ref=e2]
- textbox "Email" [ref=e3]
+ textbox "Email" [ref=e3]: "[email protected]"
- button "Submit" [ref=e4]
+ button "Submit" [ref=e4] [disabled]
+ status "Sending..." [ref=e7]
link "Already have an account?" [ref=e5]
3 additions, 2 removals, 3 unchanged
Catch a visual regression
$ agent-browser diff screenshot --baseline before-deploy.png
✗ 2.37% pixels differ
Diff image: ~/.agent-browser/tmp/diffs/diff-1708473621.png
1,137 different / 48,000 total pixels
Baseline
Submit
Current
Submit
Diff
Submit

命令

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

快照差异比较

使用逐行文本差异比较两个时间点之间的可访问性树。

# 与本会话中上一次拍摄的快照进行比较
agent-browser diff snapshot

# 与一个保存的基线文件进行比较
agent-browser diff snapshot --baseline before.txt

# 限定到页面的特定部分
agent-browser diff snapshot --selector "#main" --compact

未指定 --baseline 时，该命令会自动与当前会话中最近一次拍摄的快照进行比较。这是代理验证某个操作是否达到预期效果的主要用例。

选项

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

输出

差异输出使用 + 表示新增行，- 表示删除行，类似于统一差异格式。末尾会显示添加、删除和未更改行的数量摘要。

- button "提交" [ref=e2]
+ button "提交" [ref=e2] [disabled]
  3 个新增，2 个删除，41 个未更改

截图差异比较

在像素级别上将当前页面截图与基线图像进行比较。生成一张高亮更改像素为红色的差异图像。

# 基础视觉差异比较
agent-browser diff screenshot --baseline before.png

# 将差异图像保存到指定路径
agent-browser diff screenshot --baseline before.png --output diff.png

# 调整阈值并限定到特定元素
agent-browser diff screenshot --baseline before.png --threshold 0.2 --selector "#hero"

选项

标志描述
-b, --baseline <file>用于对比的基线 PNG/JPEG 图像（必需）
-o, --output <file>生成的差异图像路径（默认：临时目录）
-t, --threshold <0-1>颜色距离阈值（默认：0.1）。数值越高，容忍度越高
-s, --selector <sel>将当前截图范围限定到一个元素
--full截取完整页面截图

输出

报告差异图像路径、不同像素数量以及不匹配百分比。差异图像中未更改的像素会变暗，更改的像素以红色高亮显示。

如果基线图像与当前图像尺寸不同，命令将报告尺寸不匹配，而非尝试进行像素级比较。

URL 差异比较

通过依次导航至每个网址并比较结果来对比两个页面。

# 比较两个网址（快照差异）
agent-browser diff url https://staging.example.com https://prod.example.com

# 包含视觉比较
agent-browser diff url https://v1.example.com https://v2.example.com --screenshot

# 完整页面截图比较
agent-browser diff url https://v1.example.com https://v2.example.com --screenshot --full

该命令会先导航到第一个网址，捕获状态；然后导航到第二个网址并再次捕获。始终包含快照差异比较。截图差异比较需要 --screenshot 标志。

完成操作后，浏览器将停留在第二个网址。

选项

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

使用场景

验证代理操作

最常见的用例：确认某个操作（点击、填写、提交）是否按预期改变了页面。

agent-browser snapshot -i          # 拍摄仅交互部分的快照（作为基线）
agent-browser fill @e3 "[email protected]"
agent-browser diff snapshot        # 将当前快照与基线进行比较

监控变更

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

# 保存基线
agent-browser open https://example.com && agent-browser snapshot > baseline.txt

# 后续检查变更
agent-browser open https://example.com && agent-browser diff snapshot --baseline baseline.txt

视觉回归测试

在部署前后对比截图，以捕捉意外的视觉变化。

agent-browser open https://staging.example.com && agent-browser screenshot baseline.png
# ... 执行部署 ...
agent-browser open https://staging.example.com && agent-browser diff screenshot --baseline baseline.png

对比环境

将预发布环境与生产环境进行对比，以验证一致性。

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