Vitest Quickstart

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

Set up Argos with Vitest to run visual tests on every pull request. The Argos Vitest SDK adds visual testing to Vitest in two ways:

• 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.

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

Prerequisites

• 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

pnpm

bun

To capture screenshots, also install the Vitest browser mode peer dependencies (skip this if you only need snapshots):

npm

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

yarn

pnpm

bun

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

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.

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

---

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