visual-diff

Run a visual regression test by capturing baseline and current screenshots of the app, then comparing them with ImageMagick to find pixel-level differences.

Workflow

Prerequisites

• App running with KB_ENABLE_REMOTE_DEBUG=1 yarn desktop:start:hot
• ImageMagick installed (brew install imagemagick)

Option A: Automated Scripts (preferred)

# Baseline (on base branch, app running)
cd shared && node perf/visual-diff-take.js baseline

# Current (on feature branch, app restarted)
cd shared && node perf/visual-diff-take.js current

# Compare
cd shared && ./perf/visual-diff-compare.sh

Option B: Playwright MCP (manual)

1. Close the DevTools tab (browser_tabs action=close index=0), select the app tab.
2. Navigate to each tab (People, Chat, Files, Crypto, Teams, Git, Devices, Settings) via browser_snapshot + browser_click.
3. Take screenshots to /tmp/visual-diff/baseline/ or /tmp/visual-diff/current/.
4. Run cd shared && ./perf/visual-diff-compare.sh.

Viewing Results

After comparison, read the diff images to evaluate:

1. Resize each diff image for token efficiency:

   sips -Z 800 /tmp/visual-diff/diff/<tab>.png --out /tmp/visual-diff-resized/<tab>.png
   

2. Use the Read tool to display each resized diff image.

Interpreting Diffs

Red pixels indicate differences between baseline and current screenshots.

• Subpixel noise (<200px): Scattered faint red dots from font antialiasing. Safe to ignore.
• Dynamic content: Avatars, timestamps, badges change between runs. Safe to ignore.
• COLOR REGRESSION: Entire icons or text areas are solid red — colors changed (e.g. icon went blue → gray). Investigate.
• SIZE/POSITION REGRESSION: Red outlines or doubled shapes — something shifted. Common cause: Box2 adding alignSelf: 'center' where old code used <div>.
• Rule of thumb: Clean text labels + solid red icons = real bug, not noise.

Typical Session

1. User says "take baseline" → run the baseline capture step.
2. User makes code changes and restarts app.
3. User says "compare" or "take current" → run the current capture + comparison.
4. Display diff images and summarize findings: which tabs changed, whether changes look intentional or are regressions.