visual-mirror

Pixel diffs tell you something changed. Visual Mirror tells you what it means.

A CLI tool for visual regression testing powered by AI. It captures a screenshot of a live URL, diffs it pixel-by-pixel against a reference image, then uses Claude Vision to provide an intelligent, human-readable analysis of what changed — complete with actionable fix suggestions.

Install

npm install -g visual-mirror

Quick Start

# Option 1: Paste from clipboard — just copy a screenshot and run:
visual-mirror --url http://localhost:3000

# Option 2: Provide a reference file:
visual-mirror --ref ./reference.png --url http://localhost:3000

How It Works

1. Resolve — Checks the URL is reachable. If not, probes nearby ports (and common dev ports like 3000, 5173, 8080) and offers to use whichever one is live. Self-signed HTTPS is accepted so local dev servers Just Work.
2. Capture — Takes a headless Chromium screenshot of your live URL via Playwright. If a login form is detected on the page, you're prompted to either log in (fields are auto-detected) or screenshot the login page as-is.
3. Diff — Compares the captured screenshot against your reference image pixel-by-pixel using Jimp, generating a visual diff overlay
4. Analyze — Sends both screenshots to Claude Vision, which identifies specific UI issues (not just "something changed" — it tells you what changed)
5. Select — Presents issues in an interactive terminal prompt (like yay on Arch) where you pick which ones to get fix suggestions for
6. Report — Generates a self-contained HTML report with all three images, issues, and fix suggestions, then auto-opens it in your browser

Usage

visual-mirror --ref <path> --url <url> [options]

Options

| Flag | Description | Default | |------|-------------|---------| | --ref <path> | Path to reference screenshot (PNG/JPG). If omitted, reads from clipboard | optional | | --url <url> | URL to capture and compare | required | | --width <number> | Viewport width in pixels | 1280 | | --height <number> | Viewport height in pixels | 720 | | --out <path> | Output directory for report | ./visual-mirror-report |

Example

visual-mirror --ref ./designs/homepage.png --url http://localhost:3000 --width 1440 --height 900

Login Detection

If the captured URL lands on a login screen, Visual Mirror detects the username, password, and submit selectors and asks whether you want to authenticate before the screenshot is taken:

  ⚙ Login screen detected.
    password field: #password
    user field:     input[name="email"]
    submit button:  button[type="submit"]

  ==> Log in before capturing? (y/N) y
  ==> Username / email: [email protected]
  ==> Password: ********
  ✔ Logged in successfully.

Decline the prompt to screenshot the login page as-is. Credentials are only used for the current run — nothing is stored on disk.

Interactive Flow

After analysis, you'll see something like:

  Severity: MINOR

  Issues found:
    1  Button alignment shifted 8px to the right          .cta-button
    2  Font color changed from #333 to #555               body
    3  Hero image 12px taller than reference              .hero-image

  ==> Select issues to get fix suggestions for (e.g. 1,2 or * for all)
  ==> 1,3

Then you'll get targeted fix suggestions:

  Fix suggestions:

  [1] Button alignment shifted 8px to the right
      → Check margin-right on .cta-button, likely a padding change.
        Try: padding-right: 16px;

  [3] Hero image 12px taller than reference
      → Set an explicit height on .hero-image: height: 320px;

  ✔ Report saved to ./visual-mirror-report/index.html
  Opening report...

Environment Setup

Visual Mirror uses the Claude API for analysis. If ANTHROPIC_API_KEY isn't set in your environment, you'll be prompted for one on first run and told how to persist it in your shell's rc file:

export ANTHROPIC_API_KEY="your-api-key-here"

Get one at console.anthropic.com.

Chromium is installed on-demand via Playwright the first time you run the tool — no manual setup required.

License

MIT