Skip to content
Latest

Client API reference

Import the screenshot client from @vizzly-testing/cli/client.

Install

Terminal window
npm install -D @vizzly-testing/cli

Main API

vizzlyScreenshot(name, imageBuffer, options?)

import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
await vizzlyScreenshot('homepage', await page.screenshot(), {
properties: {
browser: 'chrome',
viewport: { width: 1280, height: 800 },
},
});

Vizzly reads width and height from the captured image. A custom viewport property is metadata; it doesn’t override the image dimensions.

What it accepts:

  • name: screenshot name
  • imageBuffer: a Buffer or a file path string
  • options: screenshot options and custom properties

Supported top-level options:

  • properties: user metadata, like browser, viewport, theme, locale, or state
  • threshold: comparison threshold for this screenshot
  • minClusterSize: smallest changed cluster Vizzly should count
  • fullPage: whether this capture represents a full-page screenshot
  • requestTimeout: HTTP request timeout in milliseconds
  • buildId: build grouping override for this screenshot

Any other top-level keys are ignored. Put custom metadata inside properties.

Every key inside properties is preserved as user metadata. Names such as threshold, component, and even properties are allowed; they don’t become Vizzly options.

await vizzlyScreenshot('checkout', await page.screenshot({ fullPage: true }), {
threshold: 2,
fullPage: true,
properties: { component: 'Cart', threshold: 'business-rule', theme: 'dark' },
});

Here, the top-level threshold sets color tolerance. The value inside properties is stored only as metadata.

requestTimeout controls the HTTP request and isn’t stored as screenshot metadata. buildId defaults to VIZZLY_BUILD_ID.

Helper exports

Most tests only need vizzlyScreenshot(). Let the CLI finish the run and report its results.

The client module also exports helpers for custom integrations:

  • isVizzlyReady()
  • configure()
  • setEnabled()
  • getVizzlyInfo()
  • autoDiscoverTddServer()
  • shouldLogClient()
  • LOG_LEVELS

Notes on behavior

Server discovery

The client looks for:

  1. VIZZLY_SERVER_URL
  2. .vizzly/server.json in the current directory or a parent directory

When no server is running

If the client cannot find a server, screenshots are skipped instead of crashing your tests.

When cloud uploads finish

await vizzlyScreenshot() returns once the local server accepts your capture. The cloud upload happens in the background. When your tests finish, vizzly run waits for those uploads and prints how many succeeded, reused an existing image, or failed.

If a cloud upload fails, later captures still upload and your tests keep running. Check the final summary to see whether any screenshots are missing. See screenshot requirements and what happens when an upload fails.

TDD-mode diffs

A local visual difference normally returns a result so later captures can continue.

Set VIZZLY_FAIL_ON_DIFF=true or call configure({ failOnDiff: true }) when you want diff responses to throw.

Use the extra helpers when you’re:

  • debugging client/server discovery
  • conditionally enabling capture
  • building a custom wrapper around the client

Next steps