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.
export VIZZLY_TOKEN=your-project-tokenIn 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:
npm install -D @vizzly-testing/clinpx vizzly initThe 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:
npx vizzly run "npm test" --waitVizzly 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 runso the CLI starts the server and passes connection details to your tests. - For cloud builds, set
VIZZLY_TOKENin 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:
npx vizzly tdd run "npm test" --no-openLocal 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:
npx vizzly tdd start --opennpm test -- --watchUse 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:
npx vizzly upload ./screenshots --waitWhat 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:
npx vizzly api schema --jsonnpx vizzly tdd screenshots list --jsonSee API schema and requests for cloud queries.