Skip to content
Vizzly Docs

Vitest SDK Overview

The Vitest package is designed to feel native.

You add vizzlyPlugin() to your config, keep using toMatchScreenshot(), and let Vizzly handle storage, comparison, and review.

Requirements

This integration is for Vitest browser mode.

Install

Terminal window
npm install -D @vizzly-testing/cli @vizzly-testing/vitest vitest @vitest/browser @vitest/browser-playwright

Configure Vitest

import { defineConfig } from 'vitest/config';
import { vizzlyPlugin } from '@vizzly-testing/vitest';
import { playwright } from '@vitest/browser-playwright';


export default defineConfig({
  plugins: [vizzlyPlugin()],
  test: {
    browser: {
      enabled: true,
      instances: [
        {
          browser: 'chromium',
          provider: playwright(),
        },
      ],
    },
  },
});

The plugin also disables Vitest’s native screenshot failure handling so Vizzly can take over that job.

Write tests

import { expect, test } from 'vitest';
import { page } from 'vitest/browser';


test('hero section', async () => {
  await expect(page).toMatchScreenshot('hero.png', {
    properties: { theme: 'dark' },
    threshold: 5,
  });
});

Run it

Local review:

Terminal window
vizzly tdd start
npx vitest

Cloud build:

Terminal window
vizzly run "npx vitest"

Use --wait on vizzly run if CI should fail on unresolved visual changes.

With or without --wait, vizzly run waits for pending uploads and reports failures before exiting. Upload failures preserve the test exit code. --wait waits for comparisons only when uploads succeed. Set VIZZLY_TOKEN in CI; vizzly run supplies the server and build routing values to Vitest.

Screenshot metadata

Vizzly adds framework: 'vitest', vitest: true, browser, and url metadata. Your properties override those defaults.

Image dimensions come from the captured bitmap. The client doesn’t generate viewport properties; any viewport-shaped values you supply remain user metadata.

Extra helpers

The package also exports:

  • getVizzlyStatus()
  • getVizzlyInfo()

Those are useful when you want to check whether the client is available inside tests.

Next steps