mcpField
B
browser-screenshot-diff

browser-screenshot-diff

github.com/ruvnetTesting & quality80.0k696 installsUpdated today
Repository

About browser-screenshot-diff

browser-screenshot-diff compares recorded browser sessions step by step for UI regression testing and flow verification. It pairs screenshots and accessibility snapshots by step-id, then saves replayable findings.

Key features

  1. 01Pair steps by step-id
  2. 02Compare screenshot pixels
  3. 03Diff accessibility snapshot nodes
  4. 04Report divergence and similarity
  5. 05Save replayable diff findings

Use cases

  1. 01Check visual regressions after UI changes
  2. 02Verify browser-replay against its source session
  3. 03Compare A/B variants of a form flow

MCP support

The skill works with locally saved RVF artifacts and does not provide a browser_screenshot_diff MCP tool. It uses browser_eval only for live verification when needed.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/ruvnet/ruflo --skill browser-screenshot-diff

After installing, type/browser-screenshot-diffin Claude Code to confirm it loaded.

Details

From the project README

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 [email protected] rvf status <session-id-a>.rvf
npx -y [email protected] 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.

Comments

Markdown supported