Vitest browser mode visual testing quickstart

Set up visual testing in your Vitest browser tests with the Argos Vitest SDK.

To add visual testing to Vitest, install @argos-ci/vitest, add argosVitestPlugin() to your Vitest config, call argosScreenshot() in a browser mode test, and run npx vitest run in CI with the ARGOS_TOKEN environment variable set. Argos compares every screenshot with a baseline build picked from your Git history and reports the changes as a check on your pull request.

The Argos Vitest SDK captures two kinds of files:

• Screenshots of your rendered components, captured from Vitest browser tests.
• Snapshots of any value — objects, JSON, HTML, and more — captured from browser or plain Node tests. No browser required.

What Argos adds over toMatchScreenshot()

Vitest's built-in toMatchScreenshot() already compares screenshots in browser mode. Argos keeps your Vitest tests and changes what happens around them:

• No reference images in your repository. toMatchScreenshot() stores references in __screenshots__ folders that you commit, named per browser and platform (for example button-chromium-darwin.png), so references captured on macOS are not used on Linux CI. Argos picks the baseline from your Git history.
• Review on the pull request. A toMatchScreenshot() mismatch fails the test until you re-run with --update. Argos turns visual changes into a pull request check that your team approves or rejects.
• Diff more than pixels. argosSnapshot() compares any value — API responses, generated HTML, Markdown — from browser or Node tests.

Already using toMatchScreenshot()? Follow Migrate from Vitest toMatchScreenshot to Argos.

Using Storybook? Follow the Storybook Quickstart instead — it builds on this same Vitest integration.

Prerequisites

• Node.js 22 or later
• Vitest set up in your project
• Vitest running on your CI
• A project created in Argos

Capturing screenshots additionally requires Vitest browser mode with the Playwright provider. Snapshots run in any Vitest test and need neither.

1

Install

Install the Argos Vitest SDK:

npm

npm i --save-dev @argos-ci/vitest

yarn

yarn add --dev @argos-ci/vitest

pnpm

pnpm add --save-dev @argos-ci/vitest

bun

bun add --dev @argos-ci/vitest

To capture screenshots, also install the Vitest browser mode peer dependencies, plus vitest-browser-react to render the React component in the example below (skip this if you only need snapshots). On Vue or Svelte, install vitest-browser-vue or vitest-browser-svelte instead:

npm

npm i --save-dev vitest @vitest/browser @vitest/browser-playwright playwright vitest-browser-react

yarn

yarn add --dev vitest @vitest/browser @vitest/browser-playwright playwright vitest-browser-react

pnpm

pnpm add --save-dev vitest @vitest/browser @vitest/browser-playwright playwright vitest-browser-react

bun

bun add --dev vitest @vitest/browser @vitest/browser-playwright playwright vitest-browser-react

2

Add the Argos plugin to your Vitest config

The Argos plugin registers the argosScreenshot browser command and, when uploadToArgos is enabled, uploads the captured screenshots to Argos at the end of the run:

vitest.config.ts

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({
        // Stabilize text rendering so screenshots match across macOS and CI.
        launchOptions: {
          args: ["--disable-lcd-text", "--font-render-hinting=none"],
        },
      }),
      instances: [{ browser: "chromium" }],
    },
  },
});

The launchOptions above disable subpixel text and font hinting, so glyphs render identically on your machine and on CI. This single change prevents one of the most common causes of flaky screenshots — learn why in Stabilize text rendering.

The test.browser block is only required for screenshots. If you only capture snapshots, you can omit it — the plugin still uploads your snapshots to Argos.

3

Capture screenshots and snapshots

Use the argosScreenshot helper to capture a screenshot in a browser test:

Button.test.tsx

import { test } from "vitest";
import { render } from "vitest-browser-react";
import { argosScreenshot } from "@argos-ci/vitest";
import { Button } from "./Button";

test("Button", async () => {
  render(<Button>Click me</Button>);
  await argosScreenshot("button");
});

Unlike other Argos SDKs, argosScreenshot takes no page argument here — Vitest browser tests already run in the page context. The name is optional too: omit it and Argos derives one from the current test.

Use argosSnapshot to capture a snapshot of any value — it works in browser and Node tests, no browser required. The value comes first and the name is optional (omit it to auto-name from the current test, or pass options.name). Strings are written verbatim; any other value is serialized automatically:

user.test.ts

import { test } from "vitest";
import { argosSnapshot } from "@argos-ci/vitest";
import { fetchUser } from "./api";

test("API response", async () => {
  const user = await fetchUser();
  await argosSnapshot(user); // -> "src/user.test.ts > API response 1"
});

argosSnapshot lets you visually diff anything, not just UI — API responses, generated HTML, config files, Markdown, and more. Pass the extension option (e.g. .json, .html, .yml) to control how Argos renders and diffs it. See the SDK reference for details.

Both are written to the ./snapshots directory by default. Add ./snapshots to your .gitignore file to avoid committing them.

Tip: Check out our guides to capture multiple viewports or add ARIA snapshots.

4

Set up CI

Run your Vitest tests in CI with ARGOS_TOKEN set. The Argos plugin uploads screenshots automatically when uploadToArgos is enabled:

.github/workflows/argos.yml

name: Argos

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  argos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx vitest run
        env:
          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

ARGOS_TOKEN is the project token from Settings → General → Token. On GitHub Actions, you can also use OIDC or tokenless authentication to avoid managing a secret. On other CI providers, pass the token with the ARGOS_TOKEN environment variable or the plugin's token option. For GitLab CI, CircleCI, Buildkite, and other providers, see Run Argos in CI.

You're all set

Push your changes and open a pull request — the Argos check appears on it once the build is uploaded. Review the visual changes, approve or reject them, and merge with confidence.

Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as orphan. Merge this setup or run the workflow once on your default branch to establish the baseline.

Frequently asked questions

How do I update the baseline after an intended change?

You don't update any file. Review the build in Argos and approve the changes: an approved build is eligible as a baseline. Once you merge, the build on your default branch, which Argos approves automatically by default, becomes the baseline for the pull requests that follow. See Baseline build.

Why do screenshots differ between my machine and CI?

Fonts, text rendering, and browser versions depend on the operating system, so the same page renders slightly differently on macOS and on a Linux CI runner. The Argos plugin uploads to Argos only from CI (uploadToArgos: !!process.env.CI), so Argos only compares screenshots captured on CI, and the launchOptions flags make text render the same way on every machine. See Stabilize text rendering and Browser glitches.

Next steps

• Stabilize screenshots – Prevent flaky diffs before they reach your pull requests
• Vitest SDK reference – All options, including argosSnapshot
• Vitest browser mode documentation – Vitest's own browser testing guide
• Vitest visual testing – A guide to browser mode screenshots, on the Argos blog

---

Need help? Join our Discord, open an issue on GitHub, or send us an email.