Chromatic for Vitest (beta)

Chromatic’s visual tests integrate with Vitest via a plugin. This means you can transform your existing Vitest Browser Mode tests into visual regression tests with a minimal configuration file change. Start capturing interactive snapshots while Vitest tests run, and review visual changes in Chromatic’s cloud environment.

Why visual test with Vitest?

Vitest Browser Mode enables you to write component tests that drive the browser to simulate and verify key user interactions like ‘toggle accordion’ and ‘filter search results’. By snapshotting the UI states generated during your component tests, you can proactively catch visual bugs that might slip through traditional logic-based tests.

How does Chromatic work?

Chromatic works alongside your Browser Mode component tests. During your test run, Chromatic captures an archive of each test case and uploads it to Chromatic’s cloud. There, Chromatic generates snapshots and performs pixel diffing to identify any unintended visual changes.

How does Chromatic’s visual testing differ from Vitest’s?

While Vitest offers a basic ability to capture and visually compare screenshots of UI. Chromatic’s difference is that it provides a significantly more robust and developer-friendly visual testing solution:

• Robustness: Chromatic captures archives (including DOM, styling, and assets) of your test cases, which you can debug interactively in the Chromatic app, using browser dev tools. This eliminates the need to run further tests to troubleshoot errors.
• Workflow: Chromatic removes the need to manage snapshots locally in your repo. Chromatic’s snapshots are indexed automatically, linked to git commits, and stored in the cloud for easy access.
• Parallelized testing: Chromatic’s cloud infrastructure automatically scales to run all tests simultaneously, eliminating the need for you to configure multiple workers on your CI.
• Dedicated review app: Chromatic offers a suite of visual diffing tools to spot regressions fast. Features include unified and split diffs, highlighting ignored regions, spotlight mode to focus and zoom in on changes, and strobe diff to pinpoint subtle changes.

Requirements

• Vitest version 4.0.0 and above
• Vitest project must use @vitest/browser-playwright

Set up Chromatic for Vitest

1. Sign up and create a new project

Create a Chromatic account and/or sign in with your GitHub, GitLab, Bitbucket, or email. Then reach out to your point of contact at Chromatic to enable Vitest support for your account.

Generate a unique project token for your app by creating a project.

2. Install Chromatic

Install chromatic and @chromatic-com/vitest packages from npm.

$ npm install --save-dev chromatic @chromatic-com/vitest

$ yarn add --dev chromatic @chromatic-com/vitest

$ pnpm add --dev chromatic @chromatic-com/vitest

3. Add Chromatic to Vitest tests

Add chromaticPlugin in your Vitest configuration file.

import { defineProject } from 'vitest/config';
import { playwright } from '@vitest/browser-playwright';
import { chromaticPlugin } from '@chromatic-com/vitest/plugin'; 

export default defineProject({
  plugins: [chromaticPlugin()], 

  test: {
    // Your existing browser mode configuration, https://vitest.dev/guide/browser/#configuration
    browser: {
      provider: playwright(),
      enabled: true,
      instances: [{ browser: 'chromium' }],
    },
  },
});

If you are using browser mode in a single Vitest project, you can apply the plugin on project level:

import { defineConfig } from "vitest/config";
import { chromaticPlugin } from "@chromatic-com/vitest/plugin"; 

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: "Unit Tests",
          include: ["**/*.test.ts"],
        },
      },

      // Option 1: For all browser tests
      {
        plugins: [chromaticPlugin()],  
        test: {
          name: "Browser Tests",
          include: ["**/*.test.tsx"],
          browser: { ... }
        },
      },

      // Option 2: For tests ending with "*.visual.test.tsx" only
      {  
        plugins: [chromaticPlugin()], 
        test: { 
          name: "Visual Regression", 
          include: ["**/*.visual.test.tsx"], 
          browser: { ... }, 
        }, 
      }, 
    ],
  },
});

4. Run Vitest

Run your Vitest tests as you normally would.

While your Vitest tests are running, Chromatic captures an archive of your app’s UI for each test.

$ npx vitest

$ yarn vitest

$ pnpm vitest

5. Run Chromatic

Use your project token and run the following command in your project directory.

$ npx chromatic --vitest -t=<TOKEN>

$ yarn chromatic --vitest -t=<TOKEN>

$ pnpm chromatic --vitest -t=<TOKEN>

When you execute the chromatic command, it uploads this archive to Chromatic’s cloud infrastructure to capture a snapshot of each test.

6. Review changes

When complete, you’ll see the build status and a link to review the changes. Click on that link to open Chromatic.

✔ Started build 1
  → Continue setup at https://www.chromatic.com/setup?appId=...
✔ Build 1 auto-accepted
  → Tested X stories across 10 components; captured 10 snapshots in 1 minute 3 seconds

import { describe, test } from 'vitest';
import { configure } from '@chromatic-com/vitest'; 

import { Page } from './Page';

configure({ title: 'Dashboard' }); 

test('Dashboard', async () => {
  await render(<Page />);
});

The build will be marked “unreviewed” and the changes will be listed in the “Tests” table. Go through each snapshot to review the diff and approve or reject the change.

Once you accept all changes, your build is marked as passed 🟢. This updates the baselines for those tests, ensuring future snapshots are compared against the latest approved version.

Next: enhance your UI Testing workflow

You’re building robust components by uncovering bugs during development. Take your testing to the next level and safeguard against visual bugs by automating Chromatic whenever you push code.

Integrate Chromatic into your CI pipeline to get notified about any visual changes introduced by a pull request. Chromatic runs test any time you push code and reports changes via the “UI Tests” badge for your pull request.

Advanced configuration options

Take full control of your Chromatic and Vitest setup to match your team’s specific workflows. Here are some powerful customizations we offer:

• Take targeted snapshots: Learn how to programmatically capture snapshots at specific points during your tests.
• Fine-tune snapshot capture: Add delays before snapshots, modify the sensitivity threshold for change detection, and employ other granular controls.
• Test for flexible user preferences: Ensure your UI gracefully adapts to user preferences like forced-colors and prefers-reduced-motion.
• Manage sharded Vitest runs: If your Vitest test suite is distributed across multiple CI jobs, learn how to coordinate their completion before running Chromatic.

Frequently asked questions

TypeError [ERR_INVALID_ARG_TYPE]: The "paths[1]" argument must be of type string. Received undefined
  at Object.resolve (node:path:1222:7)
  at binPath (/Users/aaa/dev/temp/chromatic-e2e-examples/node_modules/@chromatic-com/playwright/dist/bin/build-archive-storybook.js:15:2773)
  at /Users/aaa/dev/temp/chromatic-e2e-examples/node_modules/@chromatic-com/playwright/dist/bin/build-archive-storybook.js:15:2630 {
code: 'ERR_INVALID_ARG_TYPE'

"overrides": {
  "storybook": "$storybook"
}