Skip to content
Latest

Quick start

Start with one screenshot from a test you already run. You can compare it locally without an account, or send it to Vizzly Cloud for team review.

For local testing, skip to Work locally before uploading. The steps below create your first cloud build.

What you need

  • Node.js 22.18+ on Node 22, or Node.js 24+
  • a Vizzly account for cloud review
  • a test that can capture a page or screen

1. Create a project

Create a project in Vizzly for the app or site you want to test. It keeps your builds, baselines, and reviews together.

2. Create an API token

In your project, open Settings → API Access → Create Token. Copy the token when it’s shown; you can’t view the full value again.

Terminal window
export VIZZLY_TOKEN=your-project-token

In CI, store the token as a secret. Keep it out of your repository.

3. Install the CLI package

Run setup locally in the project that runs your tests:

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

The wizard creates config and offers agent guidance and cloud linking. Use npx vizzly init --quick if you want to create config and edit it yourself. Commit the config before using it in CI.

Init doesn’t choose or install a client. Pick the client for your test setup and follow its guide to add screenshot capture.

4. Capture one screenshot

For Node.js tests, the CLI package includes a JavaScript client. This example uses Playwright; start your app before running it:

import { test } from '@playwright/test';
import { vizzlyScreenshot } from '@vizzly-testing/cli/client';
test('homepage visual review', async ({ page }) => {
await page.goto('http://localhost:3000');
await vizzlyScreenshot('homepage', await page.screenshot({ fullPage: true }), {
properties: { browser: 'chromium' },
});
});

Keep screenshot names stable, such as homepage or account-settings. Vizzly uses the name, captured image width, browser, and configured signature properties to match baselines. Full-page images must meet the cloud screenshot requirements.

5. Run the test through Vizzly

Replace npm test with your test command:

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

Vizzly starts a capture server, runs your tests, uploads screenshots, and prints a build URL. --wait waits for comparisons and fails on visual differences.

Check the final upload summary too. Passing tests don’t guarantee every screenshot arrived. See upload troubleshooting if captures are missing.

6. Review the first build

Open the build URL and review the new screenshots. Approve them when they look right. Later builds compare with approved baselines and show what changed.

Troubleshoot the first build

  • Run through vizzly run so the CLI starts the server and passes connection details to your tests.
  • For cloud builds, set VIZZLY_TOKEN in the terminal or CI job running Vizzly.
  • If a screenshot appears as new, check its name, image width, browser, and signature properties.
  • A first screenshot has no baseline to diff against. Review it before approving.

Work locally before uploading

Install the CLI and the client for your test setup, then run:

Terminal window
npx vizzly tdd run "npm test" --no-open

Local comparisons need no account. Review the report in .vizzly/report/index.html. For watch mode, keep a TDD server running and use another terminal for tests:

Terminal window
npx vizzly tdd start --open
npm test -- --watch

Use vizzly run when you’re ready to upload for team review.

Upload screenshots you already have

You can upload image files without adding a client to your tests:

Terminal window
npx vizzly upload ./screenshots --wait

What to do next

Add captures for the screens you care about. Use stable names and properties such as theme or locale when those variants need different baselines.

Give your agent review history

Agents can inspect cloud builds through the API schema and local results through vizzly tdd screenshots:

Terminal window
npx vizzly api schema --json
npx vizzly tdd screenshots list --json

See API schema and requests for cloud queries.