VARIANCE AUTHORITY
BrowsePackage reference

Package reference

@variance-authority/vitest-browser

Observe a component against its baseline from inside a Vitest browser-mode test, without leaving the test body.

Part of Variance Authority. Point your coding agent at llms.txt.

Your component test in Vitest browser mode has already mounted the component in a real engine with the real stylesheets, and the locator it awaited is proof the thing arrived. Add one call to that test and you get a second answer out of the same mount: whether this render still matches the image you approved, and — when it does not — which components drew the pixels that moved and the file:line each was written at.

A subject is one named UI state you asked for and can ask for again, such as cart/empty or save-button/disabled. Each subject has exactly one baseline: the last image of it that a person approved.

test('save button, disabled', async () => {
  const screen = await render(<SaveButton disabled />);
  await expect.element(screen.getByRole('button')).toBeVisible();

  assertUnchanged(await variance(screen.container, { subjectId: 'save-button/disabled' }));
});

Your existing toHaveScreenshot assertions keep working. This does not replace them and does not read their baselines.

Install

npm install --save-dev @variance-authority/vitest-browser

What you need in place

Vitest browser mode must already be running your component tests, and the locator you would normally assert on must already resolve. Two browsers are in play: the one your provider mounts components in, and a Chromium the Vitest process owns and paints baselines with. The second does not arrive with a package install:

npx playwright install chromium

Vitest takes its browser provider as a value, from a package of its own:

npm install --save-dev @vitest/browser-playwright

The line each changed region is reported at comes from a second plugin, which makes react/jsx-dev-runtime resolve to a runtime that keeps the location the JSX transform already computed:

npm install --save-dev @variance-authority/jsx-source

The example below also uses vitest-browser-react to mount (npm install --save-dev vitest-browser-react). Any binding works — variance takes a DOM element or a locator — but component names, file:line, framework wiring and the Suspense guard are read out of the React tree. Mount a Vue or Svelte component and the image comparison still runs, with regions coming back unattributed.

Register the command

A test body in browser mode runs inside an iframe in a tab, and a tab has neither the baseline directory nor a browser it can launch to paint with. Vitest's command protocol carries the reading out to the Vitest process, and variancePlugin registers that command. Without it variance() throws, naming the plugin you have to add.

// vitest.config.mts
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';
import { playwright } from '@vitest/browser-playwright';
import { jsxSource } from '@variance-authority/jsx-source/vite';
import { variancePlugin } from '@variance-authority/vitest-browser/node';

export default defineConfig({
  plugins: [jsxSource(), react(), variancePlugin({ baselines: '.variance/baselines' })],
  test: {
    browser: {
      enabled: true,
      provider: playwright(),
      instances: [{ browser: 'chromium' }],
    },
  },
});

The .mts extension is what lets a config that is ESM load in a package that is not "type": "module"; a package that is may spell the file vitest.config.ts.

baselines defaults to .variance/baselines; the line above is the default written out. The plugin contributes only the command registration and a hook that closes the browser at the end of the run, so its position in plugins does not matter, and neither does jsxSource()'s — it declares itself a pre plugin, which is what puts it ahead of Vite's own resolver for react/jsx-dev-runtime.

Browser mode serves your components through the dev server, unminified and with the development JSX transform already on, so nothing else has to be configured for a region to name a component and a line.

optiondefaultwhat it decides
baselines.variance/baselinesthe directory baselines are stored in
baselinePath{title}/{name}-{engine}where each baseline goes under baselines: {title} is the describe titles, {name} the test's title, {file} and {dir} the test file. {dir}/__baselines__/{file}/{title}/{name}-{engine} with baselines: '.' keeps each image beside its test
storea durable store on baselinesan existing store, when baselines do not live in a directory
renderera Playwright renderer opened on first usean existing renderer, whose lifetime then stays yours
acceptVitest's own --updatewhether this run may promote a candidate to a baseline

Use varianceCommands(options) instead of the plugin when your config already builds its own command map and decides when the browser closes.

Add the comparison

import { render } from 'vitest-browser-react';
import { expect, test } from 'vitest';
import { assertUnchanged, variance } from '@variance-authority/vitest-browser';
import { SaveButton } from './SaveButton';

test('save button, disabled', async () => {
  const screen = await render(<SaveButton disabled />);
  await expect.element(screen.getByRole('button')).toBeVisible();

  assertUnchanged(await variance(screen.container, { subjectId: 'save-button/disabled' }));
});

render resolves to the mount rather than returning it, so the await is load bearing: without it screen is a promise and screen.getByRole is not a function.

screen.container is vitest-browser-react's root element for the mount. If your binding does not expose one, pass a locator: variance accepts any DOM element, or anything with an element() method, which is every browser-mode locator.

variance returns the observation rather than throwing on it, so a test may read the verdict before deciding what it means. assertUnchanged is the usual decision — it throws the sentence the run would have printed — and toBeUnchanged is the same decision as a matcher function, for a suite that composes its own expect. variance itself throws in two cases only: the subject is still showing a Suspense fallback, and no subject id could be derived because the call was made outside a test.

subjectId identifies one UI state rather than one test, so a test comparing three states needs three ids, and its uniqueness scope is the baseline directory rather than the file. Left out, the id is the test's full name — renaming the test then orphans its baseline and the next run reports new, so pass it explicitly for any baseline you expect to keep.

Run it and approve the first baseline

npx vitest run

The first run has nothing to compare against, so the assertion fails with:

save-button/disabled: new — no baseline under this renderer; nothing to compare against

Approve with the flag you already type for the snapshots in the same suite:

npx vitest run -u

That promotes the image this run already painted rather than painting a second one, so the bytes that became the baseline are the bytes the run produced. The run it wrote during still fails and still exits non-zero: the assertion had already made its verdict on a subject with no baseline, and writing one afterwards does not turn that verdict into a pass. Open the PNG it wrote under .variance/baselines before you commit it — that review is the approval. Run the suite again and the subject reports unchanged.

--update reaches every selected test and adopts what variance accept --all adopts: every changed candidate, whatever identity painted its baseline. Set accept: false on the plugin to keep baselines out of --update altogether, or accept: true for a job whose whole purpose is to write them, which adopts every image it painted.

Commit the baselines

The baseline directory is ordinary tracked files, and it is how CI finds the approved state. A run that cannot read what the last run wrote does not fail — it reports every subject new. If your repository ignores .variance/, exclude its contents rather than the directory, so git still descends into it:

.variance/*
!.variance/baselines/

The images a run paints to compare go to renders/ in the cache, not to the baseline directory, and the plugin prunes them when the run closes. A store you pass in keeps its render cache wherever you built it to.

Read a failure

There is no HTML report on this path — the message is the report. It opens with the subject, the verdict and the sentence explaining it, then lists each changed region with the component that drew it, the element it landed in, and the file:line that element was written at:

save-button/disabled: changed — 612 pixels differ across 2 regions in Stack, Toggle
2 region(s), ordered by area — no causes were supplied, so this
ordering measures displacement rather than blame:
  511px — Stack
      in button "Save"
      src/app/cart.tsx:18
  101px — Toggle
      in checkbox "Gift wrap"
      src/app/cart.tsx:42

The ordering caveat is printed because it is true: area measures displacement, so a container pushed by an edit can outrank the edit itself. Regions with no component behind them are printed as coordinates and marked unattributed. The file:line row is what @variance-authority/jsx-source buys; without that plugin the component and the element are still named and the row is absent. Paths are absolute, and are made relative to sourceRoot when you pass one.

The images are files. The approved baseline is the .webp under the baseline directory, beside a .json recording what painted it; the candidate this run painted is in renders/ in the cache, named by the digest of the document it came from.

Read the verdict yourself

const observed = await variance(screen.container, { subjectId: 'save-button/disabled' });

if (observed.verdict === 'new') {
  console.log(observed.message);
} else {
  assertUnchanged(observed);
}

There are four verdicts, and assertUnchanged throws on all three that are not unchanged, ignored included, because it asserts exactly what its name says.

verdictwhat it means
unchangedthe two images were compared and no pixels differ beyond the default policy's tolerance: antialiasing, and a colour change of up to 1%. The reason counts any pixels it forgave
changedpixels differ; regions names what drew them, and the reason names a moved identity first
newno baseline exists for this subject. Not a pass and not a failure
ignoredpixels differ and every one of them fell inside something you excluded, or within a sensitivity you set

The observation reports these fields:

fieldwhat it gives you
subjectthe subject id this observation is about
verdictone of the four above
becauseone sentence saying what happened and why it has that verdict
messagethe whole formatted failure, regions included — what assertUnchanged throws
regionschanged regions, each with its component, the element it landed in, file:line, box, pixel count and fingerprint where it has one
renderedfalse when the image came from the cache rather than from a paint
missingFontsfamilies the document declared that the renderer did not have
signalsthe document and the pixels as separately observed boundaries, plus the accessibility diff when one was read
comparison, isolationthe raw pixel comparison and the region clustering behind regions
causes, movedcomponents whose own hashes differ, and in which band. Absent when either side is missing hashes, which means unknown rather than nothing moved
ignoredwhat your exclusions absorbed here, per rule, including rules that absorbed nothing
relaxedthe sensitivity that decided this verdict, and the bands it absorbed
diagnosticswhat this comparison could not do, or did under a condition worth stating

Options

Every option is the second argument to variance.

optiondefaultwhat it decides
subjectIdthe running test's full namewhat the baseline is stored under
subjectKind'fixture'what produced the subject, recorded rather than guessed
fontsnonethe font stack this machine is asserted to have, as family/weight/style/hash — see below
featuresnoneenvironment facts folded into the capture and into media-condition resolution
sourceRootnonethe root component paths are made relative to, so file:line survives the trip to another machine
suspenseTimeoutMs5000how long to wait for the subject's Suspense boundaries before refusing
loadingfalsethis subject's loading state is the thing being captured
wiringtrueread each node's framework wiring — hook names, wrappers, contexts, keys — into the reading
holdingsfalseread what each boundary was handed and retained, as digests beside the reading
sensitivitynone{ rule, reason, level }, where level is 'strict', 'layout' or 'content' — which bands this subject is still asserted on

About fonts

Leave it out unless you are pinning a font stack. It is a declaration, not a measurement: a page can ask whether Inter resolves and can never read the bytes behind it, so nothing observable from inside the tab can produce this value for you.

Only the family — everything before the first / — is used to ask the renderer whether it has the font, and what it could not find comes back in missingFonts. The weight, style and hash are folded into the renderer identity and compared for equality, never parsed, so any stable digest of the font file's bytes serves as the hash. What the declaration buys is that two machines with different cuts of one family produce different identities, and a change between them names the font as its cause instead of blaming a component for a substituted typeface.

About wiring

Splitting one useState into two changes this reading, and it does not make your subject changed. The verdict on this path comes from the two images: either pixels differ or they do not. The per-component hashes stored beside a baseline — the ones that let a later run rank a region by which component's own content changed — are built from structure, semantics, text, style and geometry, and wiring is deliberately not among them. A component that gained a memo() renders the same thing, and folding the annotation into the content hashes would make a performance change read as a visual regression and re-baseline every subject the first time the reading was switched on.

What wiring buys is the record: hook shape, the memo/forwardRef chain around a component, the contexts it subscribes to and its reconciliation key, kept as their own band, so that two subjects agreeing on every content band and disagreeing here remain distinguishable. Hook names are recorded only by React development builds; against a production build the field is absent rather than empty, because "declares no hooks" and "nobody could read the hooks" are different claims.

Set wiring: false to skip the read. holdings is separate and off by default because it changes what a structure hash is — a node that has a holding suppresses the inert-wrapper collapse — so both sides of a comparison have to be read the same way.

A subject that had not arrived yet

A subject still showing a Suspense fallback is refused rather than captured. The locator assertion above it passes against a skeleton, and a baseline taken over a skeleton records the wrong state: a slower machine records the skeleton, a faster one records the content, and the next run reports the difference as a regression. The refusal names the boundary and the component that created it.

When the skeleton is the subject, declare it:

assertUnchanged(await variance(screen.container, { subjectId: 'cart/loading', loading: true }));

The declaration is symmetric — a subject declared loading that then settles is refused too, because a declaration nobody deleted would otherwise record whichever state the machine's speed produced.

Media queries resolve against the iframe the test body runs in rather than the browser tab, because that is the frame the component was laid out in. Animation, caret blink and scroll position are held still before the reading, and what held them is recorded in it, so two runs that stabilized differently are not silently compared.

The two halves, and why the tab's screenshot is not used

The tab reads the subject: markup, the CSS that applies to it, the component chain behind each node, and the bytes of every resource it references, fetched with the page's own fetch against the server that served them. A response the server refuses is recorded as absent rather than throwing, because a fixture pointing an <img> at a path nobody serves is testing the fallback.

@variance-authority/vitest-browser/node is the other half, and the entrypoint your Vitest config imports. It owns the baseline store and one browser for the whole run — opened on the first observation, not at config time — and it paints that reading rather than screenshotting the tab. A live screenshot has nothing behind it that records which machine, which scale and which font stack produced it, so nothing can name the machine when a later run differs from it.

The consequence is that a baseline approved on your laptop usually changes on a CI runner. That run names both identities as the cause of every change rather than reporting a day of changed pixels nobody caused. Two ways to get a verdict about your code instead: approve with -u inside the CI image and commit what it wrote, or pass one shared renderer to the plugin so laptop and CI paint on the same machine.

Full walkthrough: add one baseline comparison to a Vitest browser-mode test. How a region resolves to a component and a line: attribution. Where the bytes live: baseline placement.


@variance-authority/vitest-browser is part of Variance Authority — documentation · GitHub · MIT