Core Concepts

You only need five ideas to understand how Vizzly works day to day: screenshots, builds, baselines, comparisons, and context.

Screenshots

A screenshot is an image plus the metadata Vizzly uses to identify it.

At minimum, give it a stable name. You can also pass metadata like browser, viewport, or your own custom properties.

await vizzlyScreenshot('checkout-form', imageBuffer, {
  properties: {
    browser: 'chrome',
    viewport: { width: 1280, height: 800 },
    theme: 'dark',
  },
});

properties holds your metadata. Values named threshold, component, or viewport stay metadata; they don’t configure Vizzly. Pass comparison settings as top-level screenshot options. Vizzly reads image dimensions from the captured bitmap.

Cloud screenshot requirements

You can upload PNG, JPEG, and WebP screenshots. Each image can be up to 50 MiB and 60,000 pixels in either dimension. Animated images and multipage files aren’t supported.

The dimension limit uses the image’s actual pixels. For example, a 1280×60000 full-page PNG fits; a 1280×60001 image is too tall. Your browser’s CSS viewport size can differ from the screenshot’s dimensions.

Names like Checkout: empty cart are fine. Use up to 255 characters, and don’t leave the name empty or all whitespace. Keep names stable so screenshots continue matching their baselines.

Builds

A build is one test run or one upload session.

It groups screenshots together with metadata like:

branch
commit SHA
environment
build name
parallel ID

A passing test suite doesn’t guarantee a complete visual build. With vizzly run, check the final upload summary too. If any screenshots fail to upload, the CLI marks the Vizzly build as failed and keeps your test command’s exit code. See upload troubleshooting.

Baselines

Baselines are the reviewed screenshots Vizzly compares against.

By default, Vizzly uses Git-based baseline selection. You can also switch to manual modes when you want a fixed reference.

See Baselines for the full behavior.

Comparisons

A comparison is the result of checking one screenshot against its baseline.

The result is usually one of these:

identical
changed
new
missing

That is the core loop: capture screenshots, group them into a build, compare them to baselines, then review the differences.

changed and new comparisons need a review decision. Identical comparisons do not need a human decision. When every changed or new comparison is approved, the build is approved too.

Context

Context brings the baseline, screenshots, diff details, comments, and review state together.

Use vizzly context to read local TDD results. For cloud data in scripts or agents, discover the supported requests with the API schema:

vizzly context build current --source local --json
vizzly api schema --json
vizzly api schema sdk.listBuilds --json

See API schema and requests for the next step.

Two common workflows

Local development

vizzly tdd start

You compare against local baselines in .vizzly/. The same local workspace can be queried later:

vizzly context build current --source local --json

CI and team review

vizzly run "npm test" --wait

You create a cloud build your team can review.