Skip to content
Vizzly Docs

Core Concepts

Vizzly revolves around four core concepts: screenshots, builds, baselines, and comparisons. Understanding how these work will help you catch visual bugs before they reach production.

Visual Testing Workflow

Here’s how these concepts fit into your development workflow:

  1. Local Development (TDD Mode)

    Run tests locally with instant visual feedback:

    Terminal window
    npx vizzly tdd run "npm test"

    Comparisons happen locally against baseline images. No uploads. Fast feedback while building UI.

  2. CI/CD Integration

    Your CI runs visual tests and uploads results:

    Terminal window
    npx vizzly run "npm test" --wait

    Vizzly creates a build with your screenshots, picks the right baseline, runs comparisons, and updates your PR with the results.

  3. Review & Approval

    Your team reviews comparisons in the web UI. Approve intentional changes, reject bugs. Once all comparisons are resolved, the build gets approved and can become the new baseline.

  4. Merge & Deploy

    Merge your PR. Future branches use the updated baselines. Visual regressions caught automatically.

Screenshots

A screenshot is an image plus metadata that determines its identity.

Name and Properties

Every screenshot needs a unique name. Properties add context:

await vizzlyScreenshot('checkout-form', imageBuffer, {
  browser: 'chrome',
  viewport: { width: 1280, height: 800 },
  url: 'https://example.com/checkout',
  theme: 'dark',
  device: 'Desktop'
});

Built-in properties (stored as database columns):

  • browser - Browser name
  • viewport - Object with width and height
  • url - Page URL when captured

Custom properties (stored in metadata):

  • Add whatever makes sense for your workflow
  • Common examples: device, theme, locale, os, orientation

Screenshot Identity

Vizzly uses a signature to match screenshots with baselines. The signature is a pipe-separated string that determines which baseline a screenshot compares against.

Signature format: name|viewport_width|browser|custom1|custom2|...

Default signature properties:

  • name - The screenshot name
  • viewport_width - Width only (height varies with content and scrolling)
  • browser - Browser name if provided

Custom signature properties: Add properties via Project Settings → Baseline Signature Properties. Common additions:

  • device - Device name (e.g., “iPhone 15 Pro”, “Pixel 8”)
  • os / osVersion - Operating system
  • theme - Light/dark mode
  • locale - Language/region (e.g., “en-US”, “ja-JP”)
  • orientation - Portrait or landscape

When you add a custom property to the signature, screenshots with different values get separate baselines. For example, adding device means “Login Screen” on iPhone and “Login Screen” on iPad maintain separate baselines.

Best Practices

Use descriptive names that explain what you’re testing:

  • login-form-error not test1
  • modal-open vs modal-closed
  • homepage-logged-in vs homepage-logged-out

Names describe what you’re testing, not how you’re testing it.

Builds

A build is a collection of screenshots from a single test run, usually tied to a Git commit.

Build States

Builds move through these states:

  • created - Build record created
  • pending - Ready to receive screenshots
  • running - Test suite executing
  • processing - Screenshots uploaded, comparisons running
  • completing - Finalizing comparisons and approval workflow
  • completed - All comparisons finished successfully
  • failed - Build failed (test suite errors, processing errors, upload failures)

The CLI sets build status to failed if your test command exits with a non-zero code. Processing errors during screenshot comparison also trigger failed status.

Build Metadata

Each build captures:

  • Commit SHA - Git commit identifier
  • Branch - Git branch name
  • Build Name - Custom identifier for organization
  • Timestamp - When created
  • Environment - Testing environment (test, staging, production)
  • Parallel ID - Coordinates parallel test runs

The CLI captures most of this automatically. For advanced configuration, see the CLI documentation.

Baselines

Baselines are reference screenshots. New screenshots get compared against them to detect changes.

Vizzly supports three baseline modes:

  • Git mode (default) - Automatic baseline selection based on Git history
  • Manual mode - You pick one build as the baseline for the entire project
  • Manual-branch mode - Different manual baselines per branch

In Git mode, Vizzly finds the commit where your branch diverged from the main branch and uses a build from that point. Baselines update automatically when you merge approved changes.

In manual modes, you explicitly set which builds serve as baselines.

See Baseline Management for detailed configuration.

Comparisons

A comparison is the result of analyzing one screenshot against its baseline. Each screenshot gets exactly one comparison.

Vizzly Build Detail Overview

Comparison Results

Comparisons have a status (processing state) and a result (what was found):

Status (processing state):

  • pending - Waiting to process
  • processing - Currently comparing
  • completed - Comparison finished
  • failed - Processing error
  • no_baseline - No baseline available for comparison

Result (what changed):

  • identical - No visual differences detected
  • changed - Visual differences detected
  • new - Screenshot exists in current build but not in baseline
  • removed / missing - Screenshot exists in baseline but missing from current build
  • returning - Screenshot returned after being missing in previous builds
  • error - Comparison failed to process

The web UI focuses on the result. The GitHub status check considers both status and result.

Visual Diff Detection

Vizzly uses Honeydiff, a custom-built comparison engine:

  • Analyzes pixel-level differences using CIEDE2000 Delta E color space (perceptually accurate)
  • Processes 1.1B pixels/second for Full HD images
  • Uses 8-connectivity spatial clustering to identify changed regions
  • Generates bounding boxes around changed areas
  • Accounts for anti-aliasing and font rendering variations
  • Calculates difference percentages (changed pixels / total pixels)

Configure thresholds per project to ignore minor differences. Threshold is measured in CIEDE2000 Delta E units (default 2.0).

Comparison Review

In the web UI:

  • View side-by-side comparisons
  • Toggle between baseline, current, and diff views
  • Leave comments on specific screenshots
  • Approve or reject individual comparisons

Once all comparisons are resolved, the build can be approved. Approved builds can become new baselines depending on your baseline mode.

See Build Settings for details on auto-approval and review workflows.

Next Steps