[Tracking Issue]: Vitest → Chromatic Integration v0

[AriPerkkio]

This project integrates Vitest Browser Mode with Chromatic's visual regression testing platform. Users can capture and compare visual snapshots of their UI components directly from Vitest tests. Screenshots are compared on Chromatic's infrastructure rather than locally, eliminating the flakiness caused by differences in OS, fonts, and rendering engines.

Technical Deliverables

0. Finalized API design: Decide the supported features and shape of the API for the v0 release.
1. New @chromatic-com/vitest package in the chromatic-e2e monorepo, enabling users to take snapshots within existing Vitest component test suites and upload results to Chromatic.
2. Changes to chromatic.com/apps web app: User can select Vitest project in the onboarding flow
3. Support in Chromatic CLI for a --vitest flag to enable the Vitest-specific upload path.
4. QA against real-world Vitest projects. Validate that the API holds up against realistic project structures, including workspaces, mixed test suites (unit + component test), and existing fixture setups.
5. Draft documentation (API + Migration Guide)
6. Update internal documentation

Proposed higher level architecture

Project Tracking

✅ Milestone 1: Define Test APIs

• Owner: @AriPerkkio
• Completed By: 27th March
• Decide which APIs to implement in the initial v0. Finalize plan in https://www.notion.so/chromatic-ui/Test-API-for-chromatic-com-vitest-RFC-30d6e816203480d288d9d3b4b4ee4775?source=copy_link#3106e81620348083a8dcce979360f3c8.

Completed

• Test API: https://www.notion.so/chromatic-ui/Test-API-for-chromatic-com-vitest-RFC-30d6e816203480d288d9d3b4b4ee4775?source=copy_link#3106e81620348083a8dcce979360f3c8
• Reporter API: https://www.notion.so/chromatic-ui/Test-Reporter-for-chromatic-com-vitest-RFC-30d6e816203480a486ddc0af7c05c10c?source=copy_link#3106e8162034802a8180f19f829a813b

✅ Milestone 2: Minimal implementation for generating DOM snapshot and archives on file system on test run

• Owner: @AriPerkkio
• Completed By: 1st April
• The most minimal implementation required for generating snapshot and archives on file system during test run. Not configurable, controllable or extensible.
• Support for @vitest/browser-playwright #277

Completed

• feat: add @chromatic-com/vitest, minimal setup #296

✅ Milestone 3: Expose takeSnapshot() as public API

• Owner: @AriPerkkio
• Completed By: 7th April
• Finalize takeSnapshot() API and expose it as part of public API

Completed

• feat: expose takeSnapshot() as public API #300

✅ Milestone 4: Network idle detection

• Owner: @AriPerkkio
• Completed By: 9th April
• Implement smart network traffic detector that can be used before writing archives. Before this we’ve used just setTimeout + await.

Completed

• feat: wait for idle network before auto snapshot, expose waitForIdleNetwork API #301

✅ Milestone 5: Controlling Automatic Snapshots

• Owner: @AriPerkkio
• Completed By: 13th April
• Expose disableAutoSnapshot: boolean plugin option and disableAutoSnapshot() function to user.

Completed

• feat: add disableAutoSnapshot: boolean plugin option and disableAutoSnapshot() API #302

✅ Milestone 6: Limiting tests using tags

• Owner: @AriPerkkio
• Completed By: 15th April
• Expose tags: string[] plugin option and implement test filtering based on tags.

Completed

• feat: add tags plugin option #303

✅ Milestone 7: Chromatic CLI can upload Vitest projects

• Owner: @AriPerkkio
• Completed By: 22nd April
• chromatic-cli can do chromatic --vitest.

Completed:

• feat: add --vitest flag for @chromatic-com/vitest integration chromatic-cli#1252

✅ Milestone 8: Web app changes

• Owner: @treeforever
• Completed By: April 10th
• User can select Vitest as project type when creating new project on web app

✅ Milestone 9: Draft documentation

• Owner: @AriPerkkio
• Compelted By: 27th April
• Initial version of the API documentation. No need to be publish-ready.

Completed:

PRs below are finished from my end and handed to @winkerVSbecks for final changes:

• docs: add Vitest documentation chromatic-docs#796
• feat: add VitestIcon and Vitest into Header tetra#147

✅ Milestone 10: Internal documentation updates

• Owner: @AriPerkkio
• Completed By: 4th May
• Write down architechture and implementation solution.

Completed

• Updated System Documentation / Explanations / E2E Visual Tests Notion docs

✅ Milestone 11: @chromatic-com/* packages to support Storybook 10

• Owner: @AriPerkkio
• Completed By: 4th May
• Bump Storybook version dependency from storybook@8.5.x to latest. Ideally fix versioning for long term using plans described in https://www.notion.so/chromatic-ui/E2E-with-Storybook-Versioning-Ideas-2066e81620348009b732fcedabefa7c7.
• Support for Storybook v9 #268
• Storybook v8 security issue #279

Completed

• Experiment with sb & dependencies upgrade #282

Other issues

• fix: don't clean results if vitest --merge-reports is used #311
• fix: resolve viewport dimensions from Vitest's iframe #314
• fix: allow plugin to be set in non-browser context #316
• fix: viewports to be snapshot specific #318
• fix: preserve CSS pseudo states in snapshots #323
• fix(snapshot): transform more css pseudo states rrweb#7
• Define convention for test reporter output directory vitest-dev/vitest#9952