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

Canonical: https://argos-ci.com/integrations/storybook

Quickstart: https://argos-ci.com/docs/quickstart/storybook-quickstart
SDK reference: https://argos-ci.com/docs/reference/storybook

## Set up Argos with Storybook

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

```bash
npm i --save-dev @argos-ci/storybook
npm i --save-dev vitest @vitest/browser @vitest/browser-playwright playwright
```

### 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`:

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

### 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`:

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

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

### 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`:

```yaml
- 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 }}
```

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

| | Chromatic | Argos |
| --- | --- | --- |
| Where stories are captured | In Chromatic's cloud browsers | In 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 functions | One snapshot after the play function ends | `argosScreenshot(ctx)` wherever you need it, as many as you need |
| Interaction time limit | 15 seconds to render, 15 seconds for interactions | Your Vitest test timeout |
| Deployments | Storybook | Storybook or any static build |
| Source code | Proprietary | Open source (MIT) |

Sources: [Chromatic pricing](https://www.chromatic.com/pricing), [Chromatic interaction tests](https://www.chromatic.com/docs/interactions/) (checked 2026-10-04).

## 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. (https://argos-ci.com/docs/reference/storybook)
- **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. (https://argos-ci.com/docs/learn/how-to-guides/visual-coverage/storybook-story-modes)
- **A preview URL per pull request**: `argos deploy ./storybook-static` publishes the build, and reviewers open the live Storybook from the pull request. (https://argos-ci.com/deploy)
- **Screenshots inside play functions**: Call `argosScreenshot(ctx, name)` after an interaction to capture menus, dialogs and error states. (https://argos-ci.com/docs/reference/storybook#interactions-using-the-play-function)
- **Storybook 8 to 11**: The Vitest addon needs Storybook 9 or later. Storybook 8 projects use the test runner integration instead. (https://argos-ci.com/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart)

## Frequently asked questions

### 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](https://argos-ci.com/docs/quickstart/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](https://argos-ci.com/docs/learn/how-to-guides/migrate-to-argos/from-chromatic) 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](https://argos-ci.com/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart).

### 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](https://argos-ci.com/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](https://argos-ci.com/blog/storybook-visual-testing-without-chromatic): The two ways to do it, and what each one costs you.
- [Argos vs Chromatic](https://argos-ci.com/compare/chromatic): Pricing, capture model and reviews, side by side.
- [Deploy your Storybook on every pull request](https://argos-ci.com/deploy): Free preview URLs for Storybook and any static build.