Skip to main content
AI/MLruvnet

browser-screenshot-diff

Visual + DOM diff between two recorded sessions at matching trajectory step ids; used for visual regression and replay verification

Stars
56,726
Source
ruvnet/claude-flow
Updated
2026-05-31
Slug
ruvnet--claude-flow--browser-screenshot-diff
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/ruvnet/claude-flow/HEAD/plugins/ruflo-browser/skills/browser-screenshot-diff/SKILL.md -o .claude/skills/browser-screenshot-diff.md

Drops the SKILL.md into .claude/skills/browser-screenshot-diff.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

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.

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.

Steps

  1. Locate both RVF containers:
    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".

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.