Sanity Visual Regression

Sanity Visual Regression Testing

Visual regression runs on Chromatic, wired via .github/workflows/chromatic.yml. Three snapshot sources, one Chromatic project each:

All checks are non-gating during burn-in (exitZeroOnChanges); merges to main auto-accept baselines. Review diffs on the Chromatic build linked from the PR check.

The two chromatic.yml sources only run on a pull request that carries the trigger:chromatic label — a PR without it shows both jobs as skipped and produces no Chromatic build to review. The label persists, so every later push re-runs them until it is removed. Pushes to main always run, which is what keeps the baselines current. The Playwright source rides along with the e2e suite in e2e.yml and is not gated by the label.

Which source owns a state

Each source owns a disjoint set of states. Decide by how the state is reached, and never move a state between sources:

Consequences:

• A *.browser.test.tsx is the snapshot source for everything it renders — the Vitest plugin archives every test's end state with no test code changes. Browser tests keep their harness component inline (function FooHarness() in the test file) and never get a Storybook story on top. Do not re-export a browser test as a story, and do not port a browser test into a story with an elaborate play function.
• Every *Story.tsx file is a Storybook harness imported by a *.stories.tsx. Stories cover the states no browser test renders.
• Playwright stays in e2e/. Do not put specs, @chromatic-com/playwright, or e2e fixtures under dev/storybook, and do not turn an e2e spec into a story (or the reverse) to get a snapshot. dev/storybook's playwright dependency is only the browser runner for @storybook/addon-vitest.
• Do not add a Chromatic / … job that uploads one source's output to another source's project; Chromatic requires one project per integration type.

Quick start: add visual coverage for a component

Before writing anything, run pnpm visual-coverage <path> --prs and follow sanity-visual-coverage. It reports whether a story already renders the component or an open PR is about to, so you only add what is missing.

1. Add a co-located *.stories.tsx file to the owning package's src tree, usually in the same __tests__ directory as the component or harness. Storybook discovers story files in workspace package src trees — do not add CSF under dev/storybook/stories/. Two patterns:
   • Plain component states (ui-components wrappers, tone/card sentinels): render variants directly — see Button.stories.tsx. Put many variants in one story (a grid) to keep snapshot count low.
   • Studio-context states (form inputs, anything needing workspace/i18n/layers): wrap in the shared mock-studio wrapper TestWrapper (+ TestForm for form inputs) from packages/sanity/test/browser — the same wrapper the browser tests use — see Dialog.stories.tsx and EditorChrome.stories.tsx. New coverage can use a colocated *Story.tsx when the grid needs TestWrapper inside the harness — see ConfirmPopover.stories.tsx. Do not extract a browser test's inline harness into a *Story.tsx to reuse it from a story: that state is snapshotted by the Vitest integration, and the story would be a duplicate snapshot of the same pixels. If the test's harness lacks a state you need, add it to the test, or build a separate story-only harness.
2. Overlays that only exist after interaction (tooltips, menus, submenu flyouts) get a play function using storybook/test (userEvent + waitFor/expect(...).toBeVisible(), querying within(document.body) for portaled content). Chromatic and addon-vitest both run play before capturing, so the snapshot shows the open overlay — see Tooltip.stories.tsx and MenuGroup.stories.tsx (the latter also documents an animation pitfall with nested popovers). Statically controllable overlays (e.g. Popover's open prop) don't need play.
3. Verify locally: pnpm dev:storybook (port 6006), then pnpm --filter sanity-storybook test (every story runs as a vitest browser-mode test via @storybook/addon-vitest).
4. Push — the Chromatic / Storybook visual tests check snapshots only affected stories (TurboSnap) and links the build for review.

Migration priority: card and tone-related components first (tones cascade through everything), box primitives later. Snapshot the wrapper components in packages/sanity/src/ui-components and vanilla-extract-migrated components (change indicators, DocumentLayout) as sentinels.

Every story is browsable

The Storybook is a living document of how reusable components look and behave, and every story in it is meant to be read: authored variant grids, component states and migration sentinels, each with a concise JSDoc description of what it shows and why. Do not use story tags to hide stories from the sidebar (!dev) or docs (!autodocs). That convention existed only for the stories that re-exported vitest browser tests, and those are gone — browser tests are snapshotted in place by the Vitest project. If a state is not worth a person looking at, it does not belong in Storybook; drive it in a browser test instead (see "Which source owns a state").

A story that should be browsable but never snapshotted sets parameters: {chromatic: {disableSnapshot: true}}.

Determinism rules for stories

• Harness stories are deterministic by construction (mock client/workspace, no network).
• Never render live timestamps, random ids, or unfinished loading states. Chromatic pauses CSS animations automatically.
• Knobs via parameters.chromatic per story/meta: delay (ms before capture — Portable Text stories use 300 for editor boot), diffThreshold, disableSnapshot: true (story stays in Storybook + addon-vitest but is never snapshotted), modes (viewport/theme matrix — the global 1280×900 desktop mode in preview.tsx matches the vitest browser viewport).