Visual testing for Vitest
Argos adds visual regression testing to Vitest. In browser mode, argosScreenshot() captures your components; in any test, argosSnapshot() records a value such as JSON or HTML. Argos diffs both against the baseline from your Git history and puts the review on the pull request.
Set up Argos with Vitest
4 steps, then every pull request gets a visual check. The quickstart covers every option.
Install the SDK
The second line is only for screenshots, which run in Vitest browser mode with the Playwright provider. Snapshots work in plain Node tests.
npm i --save-dev @argos-ci/vitest
npm i --save-dev vitest @vitest/browser @vitest/browser-playwright playwrightAdd the Argos plugin
The plugin registers the argosScreenshot browser command and uploads what your tests captured at the end of the run. The test.browser block is only needed for screenshots.
import { defineConfig } from "vitest/config";
import { playwright } from "@vitest/browser-playwright";
import { argosVitestPlugin } from "@argos-ci/vitest/plugin";
export default defineConfig({
plugins: [
argosVitestPlugin({
// Upload to Argos on CI only.
uploadToArgos: !!process.env.CI,
}),
],
test: {
browser: {
enabled: true,
headless: true,
provider: playwright({
launchOptions: {
args: ["--disable-lcd-text", "--font-render-hinting=none"],
},
}),
instances: [{ browser: "chromium" }],
},
},
});Capture screenshots and snapshots
argosScreenshot() takes no page: browser tests already run in the page. argosSnapshot() takes any value and serializes it. Both names are optional and default to the test's name. Render components with the vitest-browser-* package for your framework.
import { test } from "vitest";
import { render } from "vitest-browser-react";
import { argosScreenshot, argosSnapshot } from "@argos-ci/vitest";
import { Button } from "./Button";
import { getUser } from "./api";
test("Button", async () => {
render(<Button>Click me</Button>);
await argosScreenshot("button");
});
test("user payload", async () => {
await argosSnapshot(await getUser());
});Run it in CI
Set ARGOS_TOKEN to your project token, or use GitHub Actions OIDC and skip the secret.
- run: npx playwright install --with-deps chromium
- run: npx vitest run
env:
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}What Argos adds over toMatchScreenshot()
Vitest 4 ships a toMatchScreenshot() assertion for browser mode. It works, and its own guide is clear about where it gets hard: baselines per platform, and environments that must match.
| Topic | toMatchScreenshot() | Argos |
|---|---|---|
| Baselines | PNG files committed per browser and platform, such as button-chromium-darwin.png | Picked from your Git history, nothing committed |
| Updating a baseline | Re-run with --update, then commit the images | Approve the change in the review UI |
| Rendering differences | The Vitest guide recommends Docker or a cloud service for consistent results | CI captures are compared with CI captures |
| Review | Diff images in the test output | A diff viewer on every pull request, with comments and a GitHub check |
| Values that aren't pixels | Text snapshot files committed next to the tests | argosSnapshot() reviews JSON, HTML or Markdown like a screenshot |
| Cost | Free | Free for personal projects, Pro at $100/month |
Sources: Vitest visual regression testing guide, checked October 2026.
Why Vitest teams use Argos
Snapshot any value
argosSnapshot() records objects, JSON, HTML or Markdown from browser or Node tests, and Argos shows each change as a text diff in the same review as your screenshots.
Screenshots stay out of your repository
Captures are uploaded from CI and baselines come from your Git history, so there is no folder of PNGs per platform to commit and keep in sync.
Sharding
Run vitest --shard with ARGOS_PARALLEL_NONCE set, and every shard uploads into one Argos build.
Viewports and full page
Pass viewports to capture several sizes in one call, and fullPage to capture the whole page instead of the component.
Storybook on the same setup
The Storybook integration builds on this plugin, so component tests and stories share one configuration.
Learn moreVitest visual testing FAQ
How do I add visual regression testing to Vitest?
Install @argos-ci/vitest, add argosVitestPlugin() to your Vitest config, and call argosScreenshot() in browser tests or argosSnapshot() in any test. Run Vitest in CI with ARGOS_TOKEN set and the pull request gets the visual changes to review. See the Vitest quickstart.
How is it different from toMatchScreenshot()?
toMatchScreenshot() compares against PNG files committed to your repository, one per browser and platform, and you review failures in the test output. With Argos, baselines come from your Git history, only CI captures are compared, and changes are reviewed and approved on the pull request.
Do I need Vitest browser mode?
For screenshots, yes: browser mode with the Playwright provider. argosSnapshot() runs in any Vitest test, including plain Node tests.
Which Vitest versions are supported?
Vitest 4 and later, with @vitest/browser and @vitest/browser-playwright for screenshots.
Does it work with Vitest sharding?
Yes. With vitest --shard, set ARGOS_PARALLEL_NONCE to a value shared by the shards, such as the CI run ID, and they upload into a single build.
How much does it cost?
Argos is free for personal projects up to 5,000 screenshots a month. Pro is $100 a month with 35,000 screenshots included, then $0.004 per screenshot.
Supercharge your product quality
See every change your team and your agents make. Review with confidence, and merge faster.