Storybook Quickstart

Learn how to 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.

Prerequisites

To get the most out of this guide, you'll need to:

note

If you use Test Runner instead of Vitest, follow our Storybook Test Runner quickstart.
If you use a legacy version of Storybook (<v8), follow our legacy Storybook quickstart.

1. Install

npm
yarn
pnpm
bun

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

yarn add --dev @argos-ci/storybook

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

bun add --dev @argos-ci/storybook

Read the CLI documentation if you need information about advanced usages.

2. Add Argos plugin to your Vitest configuration

The Argos plugin for Vitest 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 { 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,

            // Set your Argos token (required if not using GitHub Actions).
            token: "<YOUR-ARGOS-TOKEN>",
          }),
        ],
        test: {
          name: "storybook",
          browser: {
            enabled: true,
            headless: true,
            provider: "playwright",
            instances: [{ browser: "chromium" }],
          },
          setupFiles: [".storybook/vitest.setup.ts"],
        },
      },
    ],
  },
});

note

Be sure to have already installed the Storybook Vitest Addon in your project.

3. Capture screenshots

All your stories will be automatically captured when you run the tests.

You can also capture screenshots in the play function by using the argosScreenshot function:

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

export const Example: Story = {
  play: async (ctx) => {
    // It captures a screenshot of the current story and uploads it to Argos
    // See options at: https://argos-ci.com/docs/storybook
    await argosScreenshot(ctx, "example-screenshot");
  },
};

It will capture screenshots of your stories in ./screenshots directory.

Add ./screenshots to your .gitignore file, to avoid uploading screenshots to your Git repository.

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

Congratulations on installing Argos! 👏

After committing and pushing your changes, the Argos check status will appear on your pull request in GitHub (or GitLab).

Note: you need a reference build to compare your changes with. If you don't have one, builds will remain orphan until you run Argos on your reference branch.

You can now review changes of your app for each pull request, avoid visual bugs and merge with confidence. Welcome on board!

Additional resources

Join our Discord, submit an issue on GitHub or just send an email if you need help.

Prerequisites​

1. Install​

2. Add Argos plugin to your Vitest configuration​

3. Capture screenshots​

4. Set up CI​