Vitest

Integrate visual testing into your Vitest browser tests with Argos. Capture screenshots and snapshots and review visual changes directly within your CI.

The @argos-ci/vitest SDK captures Argos screenshots directly from your Vitest browser tests, and snapshots of any serializable value from either browser or Node tests.

Get started

To get started with Argos and Vitest, follow our Vitest Quickstart.

Using Storybook? The Storybook SDK builds on this same Vitest integration. Follow the Storybook Quickstart instead.

Requirements

Install @argos-ci/vitest:

npm

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

yarn

pnpm

bun

Capturing screenshots requires Vitest browser mode with the Playwright provider. Install these peer dependencies as well:

npm

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

yarn

pnpm

bun

Snapshots (argosSnapshot) run in any Vitest test—browser or Node—and require none of the browser-mode dependencies.

Capturing screenshots

Use the argosScreenshot function to capture a screenshot during a browser test. It requires the Argos Vitest plugin to be registered in your config (see argosVitestPlugin below).

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");
});

The name is optional. When omitted, Argos derives one from the current test—mimicking Vitest's snapshot naming—with a per-test counter so several unnamed captures in the same test stay unique:

test("Button", async () => {
  render(<Button>Click me</Button>);
  await argosScreenshot(); // -> "src/Button.test.tsx > Button 1"
  await argosScreenshot(); // -> "src/Button.test.tsx > Button 2"
});

Unlike Vitest—which keeps a per-file .snap, so its keys only need to be unique within a file—Argos names are global across the build. The generated name therefore includes the test file path, so two tests with the same title in different files never collide. It is also truncated when needed so the resulting filename stays within the filesystem's 255-character limit.

Screenshots are written to the ./snapshots directory by default and uploaded by the plugin when uploadToArgos is enabled.

Capturing snapshots

argosSnapshot captures a snapshot of any value—not just a screenshot—and uploads it to Argos to diff across builds, mimicking Vitest snapshots. Unlike argosScreenshot, it does not need a browser and works in both browser and Node tests.

Strings are written verbatim; any other value is serialized with @vitest/pretty-format (the serializer Vitest itself uses).

The value comes first; the name is optional. Omit it to auto-name the snapshot from the current test (like screenshots above), or pass options.name to set it explicitly:

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

test("API response", async () => {
  const user = await fetchUser();
  // Objects are serialized automatically.
  await argosSnapshot(user); // -> "src/user.test.ts > API response 1"
  await argosSnapshot(user, { name: "user" }); // explicit name
});

Use the extension option to control how Argos renders and diffs the snapshot, and tag to attach tags:

await argosSnapshot(JSON.stringify(config, null, 2), {
  name: "config",
  extension: ".json",
  tag: "config",
});

Snapshots are written to the same ./snapshots folder as screenshots and uploaded by the plugin when uploadToArgos is enabled.

Tests Sharding

Argos integrates with Vitest sharding (vitest --shard=<index>/<count>). When a shard is detected, Argos Sharding/Parallel mode is configured automatically — you only need to set the ARGOS_PARALLEL_NONCE environment variable to a value shared across the shards.

# Each machine runs a shard; they upload into a single Argos build.
ARGOS_PARALLEL_NONCE=$CI_RUN_ID vitest run --shard=1/4
ARGOS_PARALLEL_NONCE=$CI_RUN_ID vitest run --shard=2/4
# …

The parallel total and index default to the shard's count and index, and can be overridden with ARGOS_PARALLEL_TOTAL and ARGOS_PARALLEL_INDEX if needed.

API Overview

argosVitestPlugin(options)

Registers the argosScreenshot/argosSnapshot browser commands and, when uploadToArgos is enabled, the reporter that uploads captured files to Argos. Import it from @argos-ci/vitest/plugin and add it to your Vitest config.

import { defineConfig } from "vitest/config";
import { playwright } from "@vitest/browser-playwright";
import { argosVitestPlugin } from "@argos-ci/vitest/plugin";

export default defineConfig({
  plugins: [
    argosVitestPlugin({
      // Upload the captured files to Argos at the end of the run.
      uploadToArgos: process.env.CI === "true",
    }),
  ],
  test: {
    browser: {
      enabled: true,
      headless: true,
      provider: playwright(),
      instances: [{ browser: "chromium" }],
    },
  },
});

• uploadToArgos: Upload the captured files to Argos at the end of the run (default: false).
• root: Folder where screenshots and snapshots are written (default: "./snapshots").

The plugin also accepts every option supported by the Playwright argosScreenshot function—including non-serializable ones like beforeScreenshot and afterScreenshot—and all upload parameters. These act as defaults for every screenshot and can be overridden per call.

argosScreenshot(name?, options?)

Take a screenshot in a Vitest browser test. Import it from @argos-ci/vitest.

import { argosScreenshot } from "@argos-ci/vitest";

await argosScreenshot("button"); // explicit name
await argosScreenshot(); // automatic name, derived from the current test
await argosScreenshot({ fullPage: true }); // automatic name, with options

• name: A unique name for the screenshot. When omitted, Argos derives one from the current test (including the test file path, so names stay unique across files).
• options: Serializable screenshot options (see below).

Per-call options cross the Vitest browser/Node boundary, so they must be JSON-serializable. Non-serializable options (beforeScreenshot, afterScreenshot, a Locator/ElementHandle element, …) can only be set on the plugin.

Available options:

• element: String selector of the element to screenshot.
• viewports: Array of viewports to capture.
• fullPage: Capture the full page instead of fitting the screenshot to the content (default: false).
• argosCSS: Custom CSS evaluated during the screenshot process.
• threshold: Sensitivity threshold between 0 and 1. The higher the threshold, the less sensitive the diff (default: 0.5).
• tag: A tag or array of tags to attach to the screenshot.
• ariaSnapshot: Capture an ARIA snapshot along with the screenshot (default: false). Each ARIA snapshot counts as an additional screenshot for billing.
• disableHover: Disable hover effects by moving the mouse to the top-left corner (default: true).
• stabilize: Wait for the UI to stabilize before taking the screenshot. Set to false to disable or pass an object to customize it (default: true).

argosSnapshot(content, options?)

Take a snapshot of any serializable value. Works in both browser and Node tests. Import it from @argos-ci/vitest.

import { argosSnapshot } from "@argos-ci/vitest";

await argosSnapshot(user); // automatic name, derived from the current test
await argosSnapshot(user, { name: "user" }); // explicit name

• content: The value to snapshot. Strings are written as-is; any other value is serialized.
• options: Snapshot options (see below).

Available options:

• name: A unique name for the snapshot. When omitted, Argos derives one from the current test (including the test file path, so names stay unique across files).
• root: Folder where the snapshot is written. In Node tests it defaults to "./snapshots"; in browser tests it defaults to the plugin root.
• extension: Extension of the snapshot file. It also determines how Argos renders and diffs the snapshot, e.g. .txt, .json, .yml, .html, .md (default: ".txt").
• tag: A tag or array of tags to attach to the snapshot.
• serialize: Custom serializer used when content is not already a string. Defaults to @vitest/pretty-format.

Additional Resources

• Vitest Quickstart
• @argos-ci/vitest on npm
• @argos-ci/vitest on GitHub
• Vitest browser mode documentation