Storybook Quickstart

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

Set up Argos with Storybook to get visual testing and live deployment URLs on every 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.

If you use Test Runner instead of Vitest, follow the Storybook Test Runner Quickstart.

If you use a legacy version of Storybook (<v8), follow the legacy Storybook Quickstart.

Prerequisites

• Storybook v8+ set up in your project
• The Storybook Vitest addon installed
• A project created in Argos

1

Install

Install the Argos Storybook SDK:

npm

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

yarn

yarn add --dev @argos-ci/storybook

pnpm

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

bun

bun add --dev @argos-ci/storybook

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

npm

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

yarn

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

pnpm

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

bun

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

2

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):

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 =
  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({
              // Stabilize text rendering so screenshots match across macOS and CI.
              launchOptions: {
                args: ["--disable-lcd-text", "--font-render-hinting=none"],
              },
            }),
            instances: [{ browser: "chromium" }],
          },
          setupFiles: [".storybook/vitest.setup.ts"],
        },
      },
    ],
  },
});

The launchOptions above disable subpixel text and font hinting, so glyphs render identically on your machine and on CI. This single change prevents one of the most common causes of flaky screenshots — learn why in Stabilize text rendering.

3

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 with the argosScreenshot helper, for example after an interaction:

example.stories.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");
  },
};

Screenshots are written to the ./screenshots directory. Add ./screenshots to your .gitignore file to avoid committing them.

4

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:

.github/workflows/argos.yml

name: Argos

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  argos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
      - 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 }}

ARGOS_TOKEN is the project token from Settings → General → Token. On GitHub Actions, you can also use OIDC or tokenless authentication to avoid managing a secret.

For other CI providers, follow Use deployments in CI.

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.

Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as orphan. Merge this setup or run the workflow once on your default branch to establish the baseline.

Next steps

• Stabilize screenshots – Prevent flaky diffs before they reach your pull requests
• Storybook story modes – Capture stories in multiple themes and viewports
• Storybook SDK reference – All options and helpers
• Storybook + Vitest example – A complete working setup

---

Need help? Join our Discord, open an issue on GitHub, or send us an email.