Storybook

Visual testing for Storybook

Argos captures every story through the Storybook Vitest addon, in the browser your CI already runs, and compares it with the baseline from your Git history. Each pull request also gets a preview URL of your Storybook. Open source, with Storybook screenshots at $0.0015 each beyond the plan.

Setup

Set up Argos with Storybook

4 steps, then every pull request gets a visual check. The quickstart covers every option.

Step 1

Install the SDK

Argos works with Storybook 9 and later through the Vitest addon. If your Vitest addon setup doesn't include the browser-mode packages yet, add them too.

Terminal
npm i --save-dev @argos-ci/storybook
npm i --save-dev vitest @vitest/browser @vitest/browser-playwright playwright
Step 2

Add the Argos plugin next to storybookTest()

storybookTest() turns every story into a test, and the Argos plugin captures each one and uploads it from CI.

vitest.config.ts
import path from "node:path";
import { fileURLToPath } from "node:url";
import { defineConfig } from "vitest/config";
import { playwright } from "@vitest/browser-playwright";
import { storybookTest } from "@storybook/addon-vitest/vitest-plugin";
import { argosVitestPlugin } from "@argos-ci/storybook/vitest-plugin";

const dirname = path.dirname(fileURLToPath(import.meta.url));

export default defineConfig({
  test: {
    projects: [
      {
        extends: true,
        plugins: [
          storybookTest({ configDir: path.join(dirname, ".storybook") }),
          argosVitestPlugin({
            // Upload to Argos on CI only.
            uploadToArgos: !!process.env.CI,
          }),
        ],
        test: {
          name: "storybook",
          browser: {
            enabled: true,
            headless: true,
            provider: playwright({
              launchOptions: {
                args: ["--disable-lcd-text", "--font-render-hinting=none"],
              },
            }),
            instances: [{ browser: "chromium" }],
          },
          setupFiles: [".storybook/vitest.setup.ts"],
        },
      },
    ],
  },
});
Step 3

Capture more inside play functions

Stories are captured without any code change. To capture a state after an interaction, such as an open menu or an error, call argosScreenshot() in the play function.

Menu.stories.ts
import { argosScreenshot } from "@argos-ci/storybook/vitest";

export const Opened: Story = {
  play: async (ctx) => {
    // ...open the menu, then:
    await argosScreenshot(ctx, "menu-opened");
  },
};
Step 4

Test and deploy in CI

Run the stories, then deploy the built Storybook. The pull request gets the visual check and a link to the live Storybook.

.github/workflows/argos.yml
- run: npx playwright install --with-deps chromium
- run: npx vitest run --project=storybook
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
- run: npm run build-storybook
- run: npx --no-install argos deploy ./storybook-static
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
Compared

Argos or Chromatic for Storybook

Chromatic is made by the Storybook maintainers and is the default many teams start with. These are the differences that matter when you choose.

TopicChromaticArgos
Where stories are capturedIn Chromatic's cloud browsersIn your CI browser, through the Vitest addon
Entry paid plan$179/month for 35,000 snapshots$100/month for 35,000 screenshots, then $0.0015 per Storybook screenshot
Screenshots in play functionsOne snapshot after the play function endsargosScreenshot(ctx) wherever you need it, as many as you need
Interaction time limit15 seconds to render, 15 seconds for interactionsYour Vitest test timeout
DeploymentsStorybookStorybook or any static build
Source codeProprietaryOpen source (MIT)

Sources: Chromatic pricing, Chromatic interaction tests, checked October 2026.

Why Storybook teams use Argos

Every story, captured

With the Vitest addon, each story is a test and Argos screenshots it. A new story is covered the moment it exists, and its baseline comes from your Git history.

Themes and viewports with story modes

Define modes, such as light and dark or mobile and desktop, and Argos captures each story in every mode from the globals your stories already use.

A preview URL per pull request

argos deploy ./storybook-static publishes the build, and reviewers open the live Storybook from the pull request.

Learn more

Screenshots inside play functions

Call argosScreenshot(ctx, name) after an interaction to capture menus, dialogs and error states.

Learn more

Storybook 8 to 11

The Vitest addon needs Storybook 9 or later. Storybook 8 projects use the test runner integration instead.

Learn more

Storybook visual testing FAQ

How do I add visual testing to Storybook?

Install @argos-ci/storybook and add argosVitestPlugin() next to storybookTest() in your Vitest config. Every story becomes a test, Argos captures it, and when the tests run in CI with ARGOS_TOKEN set, the pull request gets a check with the visual changes to review. See the Storybook quickstart.

Is Argos a Chromatic alternative?

Yes. Argos covers the same workflow: stories captured on every pull request, changes reviewed and approved in a web UI, and a check on GitHub. The differences are that stories are captured in your CI browser through the Vitest addon rather than in a vendor's cloud, and that Argos is open source. The migration guide maps Chromatic's concepts to Argos.

Do I need the Storybook test runner?

Not on Storybook 9 or later: the Vitest addon runs your stories as tests and Argos captures them. On Storybook 8, use the test runner integration.

Can Argos host my Storybook?

Yes. argos deploy ./storybook-static uploads the build to a preview URL on every pull request, with a branch URL that follows the latest build. A push to your production branch updates the production URL. See Deploy.

How much does visual testing for Storybook cost?

Personal projects are free up to 5,000 screenshots a month. Pro is $100 a month with 35,000 screenshots included, and Storybook screenshots beyond that cost $0.0015 each.

Keep reading

Storybook visual testing without Chromatic

The two ways to do it, and what each one costs you.

Learn more

Argos vs Chromatic

Pricing, capture model and reviews, side by side.

Learn more

Deploy your Storybook on every pull request

Free preview URLs for Storybook and any static build.

Learn more

Supercharge your product quality

See every change your team and your agents make. Review with confidence, and merge faster.