<p align="center"><img src="https://variance-authority.dev/mark.svg" alt="Variance Authority mark" width="72"></p>

# @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](https://variance-authority.dev).
Point your coding agent at [`llms.txt`](https://variance-authority.dev/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.

```tsx
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

```bash
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:

```bash
npx playwright install chromium
```

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

```bash
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:

```bash
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.

```ts
// 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.

| option | default | what it decides |
|---|---|---|
| `baselines` | `.variance/baselines` | the 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 |
| `store` | a durable store on `baselines` | an existing store, when baselines do not live in a directory |
| `renderer` | a Playwright renderer opened on first use | an existing renderer, whose lifetime then stays yours |
| `accept` | Vitest's own `--update` | whether 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

```tsx
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

```bash
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:

```bash
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:

```gitignore
.variance/*
!.variance/baselines/
```

The images a run paints to compare go to `renders/` in
[the cache](https://variance-authority.dev/docs/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

```ts
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.

| verdict | what it means |
|---|---|
| `unchanged` | the 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 |
| `changed` | pixels differ; `regions` names what drew them, and the reason names a moved identity first |
| `new` | no baseline exists for this subject. Not a pass and not a failure |
| `ignored` | pixels differ and every one of them fell inside something you excluded, or within a sensitivity you set |

The observation reports these fields:

| field | what it gives you |
|---|---|
| `subject` | the subject id this observation is about |
| `verdict` | one of the four above |
| `because` | one sentence saying what happened and why it has that verdict |
| `message` | the whole formatted failure, regions included — what `assertUnchanged` throws |
| `regions` | changed regions, each with its component, the element it landed in, `file:line`, box, pixel count and fingerprint where it has one |
| `rendered` | `false` when the image came from the cache rather than from a paint |
| `missingFonts` | families the document declared that the renderer did not have |
| `signals` | the document and the pixels as separately observed boundaries, plus the accessibility diff when one was read |
| `comparison`, `isolation` | the raw pixel comparison and the region clustering behind `regions` |
| `causes`, `moved` | components whose own hashes differ, and in which band. Absent when either side is missing hashes, which means *unknown* rather than *nothing moved* |
| `ignored` | what your exclusions absorbed here, per rule, including rules that absorbed nothing |
| `relaxed` | the sensitivity that decided this verdict, and the bands it absorbed |
| `diagnostics` | what this comparison could not do, or did under a condition worth stating |

## Options

Every option is the second argument to `variance`.

| option | default | what it decides |
|---|---|---|
| `subjectId` | the running test's full name | what the baseline is stored under |
| `subjectKind` | `'fixture'` | what produced the subject, recorded rather than guessed |
| `fonts` | none | the font stack this machine is asserted to have, as `family/weight/style/hash` — see below |
| `features` | none | environment facts folded into the capture and into media-condition resolution |
| `sourceRoot` | none | the root component paths are made relative to, so `file:line` survives the trip to another machine |
| `suspenseTimeoutMs` | `5000` | how long to wait for the subject's Suspense boundaries before refusing |
| `loading` | `false` | this subject's *loading* state is the thing being captured |
| `wiring` | `true` | read each node's framework wiring — hook names, wrappers, contexts, keys — into the reading |
| `holdings` | `false` | read what each boundary was handed and retained, as digests beside the reading |
| `sensitivity` | none | `{ 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:

```ts
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](https://variance-authority.dev/start/vitest-browser).
How a region resolves to a component and a line:
[attribution](https://variance-authority.dev/docs/attribution). Where the bytes
live: [baseline placement](https://variance-authority.dev/docs/placement).

---

**[@variance-authority/vitest-browser](https://variance-authority.dev/reference/packages/vitest-browser)** is part of [Variance Authority](https://variance-authority.dev) — [documentation](https://variance-authority.dev/docs) · [GitHub](https://github.com/Variance-Authority/variance-authority/tree/main/packages/vitest-browser) · MIT
