Skip to content
Vizzly Docs

Client API Reference

This page covers the actual client exports 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 plus a properties metadata bag

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, Vizzly compares with a threshold of 2 and stores business-rule as user metadata. Framework integrations send their capture details separately.

requestTimeout is transport-only and is not serialized into screenshot metadata. If buildId is omitted, the client falls back to VIZZLY_BUILD_ID when it is set.

Helper exports

Most test suites should only import vizzlyScreenshot(). The CLI lifecycle handles run finalization when you use vizzly run, vizzly tdd run, or a running TDD server.

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

In TDD mode, visual differences normally return a diff result so the rest of the run can continue and you still get a full summary.

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

Most teams only need vizzlyScreenshot(). Let the CLI/run lifecycle finish the build.

Reach for the helper exports when you are:

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

Next steps