Quick Start

The fastest way to understand Vizzly is to send one real screenshot through it.

Start small. Create a project, create a token, add one screenshot capture to a test, then open the build in Vizzly. That gives you the whole loop without forcing you to design the perfect visual testing setup on day one.

What you need

Node.js 22+
a Vizzly account
one app, page, or flow you can screenshot from a test

1. Create a project

In Vizzly, create a project for the app or site you want to test.

Projects keep builds, screenshots, baselines, and review history together. If you are just getting started, use one project for one product surface. Split it later if separate apps or teams need their own builds and baselines.

2. Create an API token

Open your project, then go to:

Settings -> API Access -> Create Token

Copy the token when Vizzly shows it. You won’t be able to see the full token again.

Store it as an environment variable:

export VIZZLY_TOKEN=your-project-token

Use the same variable locally and in CI. In CI, store it as a secret instead of committing it to the repo.

3. Install the CLI package

Install the Vizzly CLI in the project that runs your browser tests:

npm install -D @vizzly-testing/cli

The CLI package includes the JavaScript client you use from your tests.

4. Capture one screenshot

Add one screenshot capture to a test that already opens a real page.

Here is the basic Playwright shape:

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

test('homepage visual review', async ({ page }) => {
  await page.goto('http://localhost:3000');

  let screenshot = await page.screenshot({ fullPage: true });

  await vizzlyScreenshot('homepage', screenshot, {
    properties: {
      browser: 'chromium',
      viewport: { width: 1280, height: 720 },
    }
  });
});

The screenshot name matters. Use something stable like homepage, pricing-page, or account-settings. Vizzly uses the name and properties to match future screenshots to the right baseline.

Full-page captures are supported within the cloud screenshot requirements.

5. Run the test through Vizzly

Wrap your test command with vizzly run:

npx vizzly run "npm test" --wait

If your test command is more specific, use that instead:

npx vizzly run "npx playwright test tests/homepage.spec.js" --wait

Vizzly starts a local capture server, runs your tests, uploads the screenshots, compares them, and prints the build URL.

Check the final screenshot summary for failed uploads, then open the build URL to review your screenshot. Passing tests alone don’t confirm that it reached Vizzly. If it’s missing, see upload troubleshooting.

6. Review the first build

Open the build URL in Vizzly.

The first build usually creates the first baseline. Review it and approve the screenshot if it looks right. After that, future builds compare against the approved baseline and show what changed.

That is the core loop:

Your test captures a screenshot.
Vizzly compares it to the approved baseline.
You review the diff.
Approved changes become review history for the next build.

Troubleshoot the first build

If the screenshot does not appear in the build, check the Vizzly capture setup first.

Run the test command through vizzly run, not directly. vizzly run starts the local capture server and passes VIZZLY_SERVER_URL and VIZZLY_BUILD_ID to your test process.
For local TDD, start with npx vizzly tdd start --open. The client can discover the local server from .vizzly/server.json.
For cloud builds, make sure VIZZLY_TOKEN is set in the same terminal or CI job that runs vizzly run.
If a later screenshot shows up as new, check the screenshot name and properties. They need to stay stable between runs.
If the first build has no diff, that is normal. The first reviewed screenshot usually becomes the baseline.

Work locally before uploading

Use TDD mode when you want fast local feedback while you work:

npx vizzly tdd start --open

Then run your tests normally in another terminal:

npm test -- --watch

TDD mode keeps local visual history in .vizzly/. It is useful while you are building UI or asking an agent to iterate on a screen.

When you are ready for shared review, use vizzly run.

Upload screenshots you already have

If you already have screenshots on disk, you can skip SDK setup for the first pass:

npx vizzly upload ./screenshots --wait

That creates a Vizzly build from the files in the folder. It is a good way to try visual review before wiring screenshots into your tests.

What to do next

Add screenshots for the flows you care about most.
Keep screenshot names stable.
Add useful properties like browser, viewport, theme, or locale when they affect the expected UI.
Run vizzly run in CI once the first local build looks right.

Give your agent review history

Once you have a build, your agent can ask Vizzly what changed instead of guessing from screenshots or console output.

For cloud data, use the API schema to find supported requests:

npx vizzly api schema --json
npx vizzly api schema sdk.listBuilds --json

For local TDD work, read the current results:

npx vizzly context build current --source local --json

See API schema and requests for cloud examples.