Official Argos Vitest integration

Capture Argos screenshots directly from your Vitest browser tests.

Visit the Vitest SDK documentation for guides, API and more.

Installation

Install the package:

npm install --save-dev @snapvisor/vitest

argosSnapshot runs in any Vitest test — browser or Node — and needs nothing else.

To capture screenshots with argosScreenshot, run your tests in Vitest browser mode with the Playwright provider and install the following peer dependencies:

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

Usage

Register the plugin in your Vitest config:

// vitest.config.ts
import { defineConfig } from "vitest/config";
import { playwright } from "@vitest/browser-playwright";
import { argosVitestPlugin } from "@snapvisor/vitest/plugin";

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

Then take screenshots from your browser tests:

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

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

Automatic naming

The name is optional. When omitted, Argos derives one from the current test, mimicking Vitest snapshots. Several unnamed captures in the same test get an incrementing counter so they 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.

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.

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 "@snapvisor/vitest";

test("API response", async () => {
  const user = await fetchUser();
  // Objects are serialized with `@vitest/pretty-format`, strings are written
  // verbatim.
  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",
});

Screenshots and snapshots are both written to the ./snapshots directory by default (configurable via the plugin root option) and uploaded by the reporter when uploadToArgos is enabled.

Links

• Official SDK Docs
• Quickstart
• Discord