Skip to content
Vizzly Docs

JavaScript SDK Overview

For JavaScript, the normal integration path is the client bundled with @vizzly-testing/cli.

Install it

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

Use it in tests

import { vizzlyScreenshot } from '@vizzly-testing/cli/client';


let screenshot = await page.screenshot();
await vizzlyScreenshot('homepage', screenshot);

That is the core API most teams need.

Run modes

Local TDD mode

Terminal window
npx vizzly tdd start --open

Run your tests normally in another terminal. The client auto-discovers the local server through VIZZLY_SERVER_URL or .vizzly/server.json.

Cloud mode

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

The same test code works. The difference is what the CLI does after capture.

Useful metadata

await vizzlyScreenshot('dashboard', screenshot, {
  properties: {
    browser: 'chrome',
    viewport: { width: 1920, height: 1080 },
    theme: 'dark',
  },
});

Pass custom metadata in properties. Keep metadata focused on things that matter for filtering or baseline identity.

Keep SDK options like threshold, minClusterSize, fullPage, requestTimeout, and buildId at the top level. Every key inside properties is kept as user metadata. A property named threshold or component doesn’t change how Vizzly captures or compares the image. See the client reference for supported options.

Next steps