Skip to content
Vizzly Docs

Local Development

Vizzly’s TDD mode runs visual tests on your machine with a live dashboard. You see comparisons in real-time as tests run, accept or reject changes in the browser, and work without uploading anything to the cloud.

How it works

TDD mode starts a local server that captures screenshots from your tests and compares them against baseline images stored in .vizzly/baselines/. The dashboard at http://localhost:47392 shows you comparisons as they happen.

You have two workflows:

Background server - Start once, keep running:

Terminal window
npx vizzly tdd start
npm test -- --watch

One-off runs - Run tests, see results, exit:

Terminal window
npx vizzly tdd run "npm test"

The background server is better for active development. The one-off approach works for quick checks or CI-like verification.

File structure

TDD mode creates a .vizzly/ directory in your project:

.vizzly/
├── baselines/          # Reference images to compare against
│   ├── metadata.json   # Baseline source info (build ID, branch)
│   └── *.png          # Baseline screenshots
├── current/           # Latest screenshots from your tests
│   └── *.png
├── diffs/             # Visual difference images (only for failures)
│   └── *.png
└── report-data.json   # Comparison results for the dashboard

Add .vizzly/current/ and .vizzly/diffs/ to .gitignore. Commit .vizzly/baselines/ if you want shared local baselines across your team.

Background server

Start the server once and leave it running:

Terminal window
npx vizzly tdd start --open

The --open flag launches the dashboard in your browser. The server stays running until you stop it.

Now run your tests in watch mode:

Terminal window
npm test -- --watch

Every time tests run, comparisons appear in the dashboard. Change your code, tests re-run automatically, dashboard updates.

Stop the server when you’re done:

Terminal window
npx vizzly tdd stop

Check if it’s running:

Terminal window
npx vizzly tdd status

One-off runs

Run tests once and see results:

Terminal window
npx vizzly tdd run "npm test"

This starts the server, runs your test command, shows comparison results, then exits. The dashboard is available at http://localhost:47392 while tests run.

The process exits with code 1 if any comparisons fail. Good for pre-commit hooks or local CI checks.

Dashboard views

The dashboard has four sections:

  • Comparisons (/) - See all screenshots with pass/fail status, filter by status or search by name
  • Stats (/stats) - Summary of total comparisons, pass rate, failure breakdown
  • Settings (/settings) - Download baselines from cloud builds, configure comparison threshold
  • Projects (/projects) - Connect to cloud projects for OAuth-based baseline downloads

Working with baselines

First run

When you first run tests, you won’t have baselines. TDD mode creates them automatically:

Terminal window
npx vizzly tdd run "npm test"

All screenshots show as “new” because there’s nothing to compare against. These initial screenshots become your baselines. The next run will compare against them.

Accepting changes

When you change something and comparisons fail, you can accept the new screenshots as baselines:

In the dashboard:

  1. Click a failed comparison to see the diff
  2. Click “Accept as baseline” if the change is correct
  3. The comparison updates to “passed” immediately

Accept everything at once:

Terminal window
npx vizzly tdd run "npm test" --set-baseline

This overwrites all baselines with the current screenshots. Use it when you’ve updated designs across many screenshots.

Using cloud baselines

Instead of local baselines, you can compare against screenshots from a cloud build:

Terminal window
npx vizzly tdd start --baseline-build abc123def

This downloads baselines from build abc123def to .vizzly/baselines/ and compares your tests against them. You need an API token for this to work - run npx vizzly login first.

You can also download baselines from the dashboard Settings page. Enter a build ID and click Download.

Comparison threshold

Vizzly uses CIEDE2000 Delta E for color difference. The default threshold is 2.0. Comparisons with differences below the threshold pass, differences above fail.

Adjust the threshold if you’re seeing false positives or want stricter matching:

Terminal window
npx vizzly tdd start --threshold 5.0

Or in vizzly.config.js:

export default {
  comparison: {
    threshold: 5.0
  }
}

Lower values are stricter. Higher values are more forgiving.

Common workflows

Feature development

Terminal window
# Start server with production baselines
npx vizzly tdd start --baseline-build abc123def --open


# Run tests in watch mode
npm test -- --watch


# Make changes, see diffs in dashboard
# Accept correct changes in the UI
# Fix incorrect changes and re-run tests


# When done, stop the server
npx vizzly tdd stop

Pre-commit check

Terminal window
# Verify no visual regressions before committing
npx vizzly tdd run "npm test"


# Exit code 1 if anything fails, 0 if all pass

Updating designs

Terminal window
# You've updated styles across many components
npm test


# See all the failures in dashboard
# Verify they look correct


# Accept all at once
npx vizzly tdd run "npm test" --set-baseline

Next steps