Client API reference
Import the screenshot client from @vizzly-testing/cli/client.
Install
npm install -D @vizzly-testing/cliMain 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 nameimageBuffer: aBufferor a file path stringoptions: screenshot options and customproperties
Supported top-level options:
properties: user metadata, like browser, viewport, theme, locale, or statethreshold: comparison threshold for this screenshotminClusterSize: smallest changed cluster Vizzly should countfullPage: whether this capture represents a full-page screenshotrequestTimeout: HTTP request timeout in millisecondsbuildId: 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:
VIZZLY_SERVER_URL.vizzly/server.jsonin 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.
Recommended usage
Use the extra helpers when you’re:
- debugging client/server discovery
- conditionally enabling capture
- building a custom wrapper around the client