> For the complete documentation index, see [llms.txt](https://argos-ci.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://argos-ci.com/docs/quickstart/storybook-quickstart.md).

# Storybook visual testing quickstart

Set up Argos with Storybook and Vitest to get visual testing and live deployment URLs on every pull request.

To add visual testing to [Storybook](https://storybook.js.org/), install `@argos-ci/storybook`, add `argosVitestPlugin()` next to `storybookTest()` in your Vitest config, and run `npx vitest run --project=storybook` in CI with the `ARGOS_TOKEN` environment variable set: Argos captures every story automatically. Add `npx argos deploy ./storybook-static` to publish your built Storybook on a unique URL for each pull request.

By the end of this guide, every pull request will:

* Run visual tests on your stories with Vitest.
* Deploy your Storybook to a unique URL you can share with your team.

### What Argos adds over Chromatic

* **Capture in your own CI.** The Storybook Vitest addon renders each story in a real Playwright browser on your CI, and Argos diffs exactly what your tests rendered. Chromatic renders stories on its own infrastructure.
* **Your Chromatic modes keep working.** Argos reads `parameters.chromatic.modes`, so existing [story modes](/docs/learn/how-to-guides/visual-coverage/storybook-story-modes.md) carry over.
* **Open source.** The whole platform, diff engine included, is MIT-licensed on [GitHub](https://github.com/argos-ci/argos).

Coming from Chromatic? Follow [Migrate from Chromatic to Argos](/docs/learn/how-to-guides/migrate-to-argos/from-chromatic.md), or read the [Argos vs Chromatic](https://argos-ci.com/compare/chromatic) comparison.

{% hint style="info" %}
This guide uses the Storybook Vitest addon, which only runs on a Storybook framework that uses Vite. On a Webpack-based framework such as `@storybook/angular` or `@storybook/nextjs`, on Storybook 8, or if you use Test Runner instead of Vitest, follow the [Storybook Test Runner quickstart](/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart.md): Test Runner works with every Storybook framework. On Angular 21 or later, Storybook's Vite-based `@storybook/angular-vite` framework (in preview) supports the Vitest addon.

If you use a legacy version of Storybook (\<v8), follow the [legacy Storybook Quickstart](/docs/quickstart/storybook-quickstart/storybook-legacy-less-than-v8-quickstart.md).
{% endhint %}

### Prerequisites

* Node.js 22 or later
* [Storybook v9+](https://storybook.js.org/docs/get-started/install) set up in your project, with a Vite-based framework such as `@storybook/react-vite`, `@storybook/vue3-vite`, `@storybook/nextjs-vite` or `@storybook/sveltekit`
* [The Storybook Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon) installed
* [A project created in Argos](https://app.argos-ci.com/new)

{% stepper %}
{% step %}

### Install

Install the Argos Storybook SDK, plus the Argos CLI that deploys your Storybook later in this guide:

{% tabs %}
{% tab title="npm" %}

```
npm i --save-dev @argos-ci/storybook @argos-ci/cli
```

{% endtab %}

{% tab title="yarn" %}

```
yarn add --dev @argos-ci/storybook @argos-ci/cli
```

{% endtab %}

{% tab title="pnpm" %}

```
pnpm add --save-dev @argos-ci/storybook @argos-ci/cli
```

{% endtab %}

{% tab title="bun" %}

```
bun add --dev @argos-ci/storybook @argos-ci/cli
```

{% endtab %}
{% endtabs %}

If they are not already part of your Storybook Vitest addon setup, also install the browser-mode peer dependencies the configuration below relies on:

{% tabs %}
{% tab title="npm" %}

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

{% endtab %}

{% tab title="yarn" %}

```
yarn add --dev vitest @vitest/browser @vitest/browser-playwright playwright
```

{% endtab %}

{% tab title="pnpm" %}

```
pnpm add --save-dev vitest @vitest/browser @vitest/browser-playwright playwright
```

{% endtab %}

{% tab title="bun" %}

```
bun add --dev vitest @vitest/browser @vitest/browser-playwright playwright
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Add the Argos plugin to your Vitest config

The Argos plugin captures screenshots of your stories and uploads them to Argos. Add it to your Vitest or Vite configuration file (e.g., `vitest.config.ts` or `vite.config.ts`):

{% code title="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 =
  typeof __dirname !== "undefined"
    ? __dirname
    : path.dirname(fileURLToPath(import.meta.url));

// More info at: https://storybook.js.org/docs/next/writing-tests/integrations/vitest-addon
export default defineConfig({
  test: {
    projects: [
      {
        extends: true,
        plugins: [
          // The plugin will run tests for the stories defined in your Storybook config
          // See options at: https://storybook.js.org/docs/next/writing-tests/integrations/vitest-addon#storybooktest
          storybookTest({ configDir: path.join(dirname, ".storybook") }),

          // The plugin will capture screenshots of your stories and upload them to Argos.
          // See options at: https://argos-ci.com/docs/storybook
          argosVitestPlugin({
            // Upload to Argos on CI only.
            uploadToArgos: !!process.env.CI,
          }),
        ],
        test: {
          name: "storybook",
          browser: {
            enabled: true,
            headless: true,
            provider: playwright({
              // Reduce text rendering differences between machines.
              launchOptions: {
                args: ["--disable-lcd-text", "--font-render-hinting=none"],
              },
            }),
            instances: [{ browser: "chromium" }],
          },
          // Storybook 9 to 10.2 only: since 10.3, the addon applies .storybook/preview itself.
          // setupFiles: [".storybook/vitest.setup.ts"],
        },
      },
    ],
  },
});
```

{% endcode %}

{% hint style="success" %}
The `launchOptions` above disable subpixel text and font hinting, which reduces text rendering differences between your machine and CI. This single change prevents one of the most common causes of flaky screenshots — learn why in [Stabilize text rendering](/docs/learn/reliability-and-flakiness/flaky-tests/stabilize-text-rendering.md).
{% endhint %}
{% endstep %}

{% step %}

### Capture screenshots

All your stories are captured automatically when the tests run — no code change required.

You can also capture additional screenshots in a [play function](https://storybook.js.org/docs/writing-stories/play-function) with the `argosScreenshot` helper, for example after an interaction:

{% code title="example.stories.ts" %}

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

export const Example: Story = {
  play: async (ctx) => {
    // Captures a screenshot of the current story and uploads it to Argos
    await argosScreenshot(ctx, "example-screenshot");
  },
};
```

{% endcode %}

Screenshots are written to the `./screenshots` directory. Add `./screenshots` to your `.gitignore` file to avoid committing them.
{% endstep %}

{% step %}

### Set up CI

Add a workflow that runs your visual tests **and** deploys your Storybook on every pull request. Argos serves the built Storybook on a unique URL — no extra hosting required:

{% code title=".github/workflows/argos.yml" %}

```yaml
name: Argos

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  argos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 22
      - run: npm ci

      # Run visual tests
      - run: npx playwright install --with-deps chromium
      - run: npx vitest run --project=storybook
        env:
          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

      # Build and deploy the Storybook
      - run: npm run build-storybook
      - run: npx --no-install argos deploy ./storybook-static
        env:
          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
```

{% endcode %}

`ARGOS_TOKEN` is the project token from **Settings → Authentication → Project token**. On GitHub Actions, you can also use [OIDC or tokenless authentication](/docs/learn/integrations/github-actions-authentication.md) to avoid managing a secret.

For other CI providers, see [Run Argos in CI](/docs/learn/how-to-guides/ci-pipelines/run-argos-in-ci.md) for the tests and [Use deployments in CI](/docs/learn/deployments/use-deployments-in-ci.md) for the deployment.
{% endstep %}
{% endstepper %}

### You're all set

Push your changes and open a pull request — the Argos check appears on it once the build is uploaded, along with a link to your deployed Storybook. Review the visual changes, approve or reject them, and merge with confidence.

{% hint style="info" %}
Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as [orphan](/docs/learn/platform-fundamentals/baseline-build.md#orphan-builds). Merge this setup or run the workflow once on your default branch to establish the baseline.
{% endhint %}

### Frequently asked questions

<details>

<summary>How do I update the baseline after an intended change?</summary>

You don't update any file. Review the build in Argos and [approve the changes](/docs/learn/review-workflow/review-a-build.md): an approved build is eligible as a baseline. Once you merge, the build on your default branch, which Argos approves automatically by default, becomes the baseline for the pull requests that follow. See [Baseline build](/docs/learn/platform-fundamentals/baseline-build.md).

</details>

<details>

<summary>Why do screenshots differ between my machine and CI?</summary>

Fonts, text rendering, and browser versions depend on the operating system, so the same page renders slightly differently on macOS and on a Linux CI runner. The Argos plugin uploads to Argos only from CI (`uploadToArgos: !!process.env.CI`), so Argos only compares screenshots captured on CI, and the `launchOptions` flags make text render the same way on every machine. See [Stabilize text rendering](/docs/learn/reliability-and-flakiness/flaky-tests/stabilize-text-rendering.md) and [Browser glitches](/docs/learn/reliability-and-flakiness/flaky-tests/browser-glitches.md).

</details>

### Next steps

* [Stabilize screenshots](/docs/learn/reliability-and-flakiness/flaky-tests.md) – Prevent flaky diffs before they reach your pull requests
* [Storybook story modes](/docs/learn/how-to-guides/visual-coverage/storybook-story-modes.md) – Capture stories in multiple themes and viewports
* [Storybook SDK reference](/docs/reference/storybook.md) – All options and helpers
* [Storybook + Vitest example](https://github.com/argos-ci/argos-javascript/tree/main/examples/storybook-vitest) – A complete working setup
* [Storybook visual testing without Chromatic](https://argos-ci.com/blog/storybook-visual-testing-without-chromatic) – The guide on the Argos blog

***

Need help? [Join our Discord](https://argos-ci.com/discord), [open an issue on GitHub](https://github.com/argos-ci/argos/issues), or [send us an email](mailto:contact@argos-ci.com).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://argos-ci.com/docs/quickstart/storybook-quickstart.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.