Testing What Users Actually See with Vitest and Chromatic

Testing What Users Actually See with Vitest and Chromatic

Add fast, stable visual testing to your Browser Mode component tests.

Editor’s note: Today, our friends at Chromatic are sharing an early look at their new visual testing plugin for Vitest. We’re excited to feature this guest article by Kyle Gach, who walks through how visual testing complements traditional component tests and helps catch UI regressions before they reach production.

Your PR to insert an “add to favorites” button is green. Every automated test passes. CI reports no failures. Then a user reports that the product card doesn’t look right on their phone.

The test suite verified the component logic, but missed the rendered state the user saw: the breakpoint, the spacing, the wrapping, and the final painted layout. Your Vitest tests can’t see your UI. Visual tests close that gap.

That’s why we’re opening early access to our new Chromatic plugin for Vitest.

Visual component tests are perfect for UI development

Visual tests are easier to write and maintain than traditional component tests. At the same time, they provide more confidence because they test more.

A traditional component test for a product card might verify that:

• The correct title and price are rendered
• The CTA has the correct text and is clickable

Visual tests go beyond that and verify that every detail of the card’s appearance is correct:

• The fonts in use
• Colors
• Spacing
• Layout
• Breakpoints, etc.

And they cover all of that without a single assertion you have to write and maintain.

By adding visual tests to your Vitest tests, you get the best of both worlds: regular assertions for interactive behavior and non-visual output like accessibility properties, plus visual tests for appearance. Users care about both, so we must test both.

Visual testing with Vitest and Chromatic

If you’re testing your components with Vitest’s Browser Mode, the Chromatic plugin can add visual tests with no required changes to your test files.

ℹ️ What’s Browser Mode?

Vitest runs in Node. By default, it renders the components in your tests in Node, too, using a simulated browser environment, like jsdom or happydom. Because it’s only simulated, you often need to mock various browser and DOM APIs. Or worse, skip testing your components’ use of them.

With Browser Mode, Vitest spins up a real (typically headless) browser and renders your components there. No more mocking browser APIs. You test all the ways your components interface with the real browser.

The tradeoff is fidelity vs. speed. Browser Mode tests are far more realistic and capable, but slightly slower because of the real browser. Browser Mode is a requirement for visual testing with Vitest.

How does it work?

Getting started is as simple as registering the plugin in your Vitest config:

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

export default defineProject({
  plugins: [chromaticPlugin()], // 👈 Add this; no test file changes required
  test: {
    browser: {
      provider: playwright(),
      enabled: true,
      instances: [{ browser: 'chromium' }],
    },
  },
});

With the plugin in place, performing a test run will collect the rendered result at the end of each test. (You can also collect the rendered output at arbitrary points during a test.)

Then you run Chromatic, which:

1. Uploads those results to the cloud
2. Takes snapshots in parallel
3. Computes their diffs
4. Automatically finds and reduces flake
5. Reports the result as a PR check

The last step is review. You approve the diffs that look correct and reject the ones that don’t. Then push the changes to fix the rejected snapshots until you’re able to approve everything and merge your PR.

How is Chromatic different than Vitest’s visual testing?

Vitest offers a built-in visual testing capability, which also requires Browser Mode. It takes screenshots of your test results and produces diffs to review.

The key difference is that it stores those screenshots in your repo, which means you must store them with git and manage updates. You also must provide the environment to capture those screenshots, which is hard to keep stable, because it can vary based on the OS, browser, installed fonts, locale, etc.

Chromatic, by contrast, collects the rendered result of your tests locally, but captures the actual visual snapshots in a stable cloud environment. This provides a number of benefits:

• Branch-aware baselines track main and feature branches for you, so you don’t have to store them in git
• Cloud rendering takes snapshots in a controlled, consistent platform to reduce environmental flake
• SteadySnap stabilizes snapshots against animation, loading variance, and capture timing
• Parallel snapshotting runs your visual tests as fast as possible
• Chromatic collects the rendered HTML, CSS, and assets behind each screenshot, so you can inspect the DOM and reproduce failures without running tests locally

Or, to summarize with a table:

Get early access

We are opening early access to the Chromatic plugin for teams already using Vitest Browser Mode or actively moving component tests there.

The beta is private, with hands-on onboarding for a limited number of teams and free snapshots while evaluating the product. Bring a real repo, and we will validate Browser Mode collection, CI behavior, PR review, branch baselines, and debugging against it together.

Early-access teams can influence the product before launch, with priority access as the beta expands. This is a good fit if your team already uses Vitest for component tests, has started adopting Browser Mode, and wants visual regression coverage without building screenshot infrastructure around the built-in API.

Requires Vitest Browser Mode using Playwright. We’ll follow up with onboarding details.