Skip to main content

Storybook Quickstart

Learn how to setup visual testing in a Storybook using Vitest + Argos.

Prerequisites​

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

note

If use a legacy version of Storybook (<v8), follow our legacy Storybook quickstart.

1. Install​

npm i --save-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. Setup CI to run tests and upload screenshots​

Argos is just a plugin running on top of Storybook Vitest Addon, so you can run the tests in your CI as you would normally do with Vitest.

To run the tests in your CI, please refer to the Testing in CI guide of Storybook.

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.