Back to Details

browser-screenshot-diff

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Browser Screenshot Diff

Browser Screenshot Diff

Compare two recorded sessions step-by-step. Pairs each step in session A to the same 
step-id
in session B, diffs the captured screenshot and accessibility snapshot, reports the first divergence and an aggregate similarity score.
逐步对比两个录制的会话。将会话A中的每个步骤与会话B中相同的
step-id
配对，对比捕获的截图和无障碍快照，报告首次差异点以及整体相似度得分。

When to use

使用场景

  • Visual regression after a UI change (record before, record after, diff).
  • Verifying a 
    browser-replay
    run matches the parent session within tolerance.
  • Comparing two A/B variants of the same form flow.
  • UI变更后的视觉回归测试（变更前录制、变更后录制、对比）。
  • 验证
    browser-replay
    运行结果与母会话在允许误差范围内匹配。
  • 对比同一表单流程的两个A/B变体。

Steps

操作步骤

  1. Locate both RVF containers:
    bash
    npx -y ruvector@0.2.25 rvf status <session-id-a>.rvf
npx -y ruvector@0.2.25 rvf status <session-id-b>.rvf
  2. Load both trajectories from 
    trajectory.ndjson
    . Build a 
    step-id → (screenshot_path, snapshot_path)
    map for each.
  3. Pair steps by 
    step-id
    . Steps that exist on only one side are flagged as 
    unmatched
    and contribute to the divergence score.
  4. Pixel diff (
    --mode pixel|both
    ): compare the two PNGs at each step. Report 
    mse
    , 
    psnr
    , and the bounding box of the largest diff cluster. Threshold default 
    0.02
    (2% of pixels).
  5. DOM diff (
    --mode dom|both
    ): compare the accessibility snapshots node-by-node. Report added / removed / changed nodes with their accessible names.
  6. Aggregate similarity: weighted average across matched steps, weighted by step duration. Verdict goes into a new 
    findings.md
    under a fresh RVF container so the diff itself is replayable.
  7. Persist the diff verdict in 
    browser-sessions
    under both source ids' tags so future searches surface "ran a diff against session X".
  1. 定位两个RVF容器:
    bash
    npx -y ruvector@0.2.25 rvf status <session-id-a>.rvf
npx -y ruvector@0.2.25 rvf status <session-id-b>.rvf
  2. 从
    trajectory.ndjson
    加载两个轨迹    。为每个会话构建
    step-id → (screenshot_path, snapshot_path)
    映射表。
  3. 按
    step-id
    配对步骤    。仅存在于一侧的步骤会被标记为
    unmatched
    （未匹配），并计入差异得分。
  4. 像素对比（
    --mode pixel|both
    ）：对比每个步骤的两张PNG图片。报告
    mse
    （均方误差）、
    psnr
    （峰值信噪比）以及最大差异簇的边界框。默认阈值为
    0.02
    （2%的像素）。
  5. DOM对比（
    --mode dom|both
    ）：逐节点对比无障碍快照。报告新增/移除/修改的节点及其无障碍名称。
  6. 整体相似度：对匹配步骤的结果按步骤时长进行加权平均。对比结果会存入新RVF容器下的
    findings.md
    文件，以便重放对比过程。
  7. 持久化存储：将对比结果存入
    browser-sessions
    中两个源会话ID的标签下，以便后续搜索时能显示“已与会话X进行对比”。

Caveats

注意事项

  • Pixel diff is sensitive to font hinting, antialiasing, and scrollbar position. Keep viewport pinned across both sessions.
  • DOM diff over Playwright's accessibility tree is more stable than HTML diff. Prefer it.
  • This skill does not handle dynamic content (clocks, ads); add ignore regions to the field map or pre-process snapshots before diffing.
  • The 
    browser_screenshot_diff
    MCP tool is not planned (ADR-0001 §7); the skill operates against locally-saved RVF artifacts and uses 
    browser_eval
    only for live verification.
  • 像素对比对字体微调、抗锯齿和滚动条位置敏感。需在两个会话中固定视口。
  • 基于Playwright无障碍树的DOM对比比HTML对比更稳定，建议优先使用。
  • 该功能不支持处理动态内容（如时钟、广告）；可在字段映射中添加忽略区域，或在对比前预处理快照。
  • 目前无计划开发
    browser_screenshot_diff
    MCP工具（ADR-0001 §7）；该功能基于本地保存的RVF工件运行，仅在实时验证时使用
    browser_eval
    。