Storybook

Integrate visual testing with your Storybook seamlessly using Argos. This SDK allows you to capture and review visual changes in your Storybook components directly within your CI.

Getting Started

To get started with Argos and Storybook, check out our quick start guides:

• Storybook + Vitest

• Storybook + Test Runner

• Storybook Legacy (<v8)

Comparing Argos and Chromatic

While both Argos and Chromatic provide visual testing for Storybook, they take different approaches:

• Argos captures screenshots of your Storybook components in your CI using Playwright.

• Chromatic captures screenshots of your Storybook components in the cloud.

For a deeper comparison, see our Argos vs Chromatic guide.

Vitest vs Test Runner

Argos supports both Vitest and Test Runner for visual testing in Storybook.

Storybook recommends using Vitest for testing and Argos experience is also better if you use it. To learn more about the differences, see Vitest vs Test Runner comparison guide.

Interactions using the play function

The play function in Storybook lets you define interactions for your components, ensuring they are in a specific state before capturing a screenshot.

When running tests, either Vitest or Test Runner automatically executes the play function before taking a screenshot.

If you use Vitest, you can also take custom screenshots in your tests using the argosScreenshot function:

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

export const FormStory: Story = {
  play: async (ctx) => {
    const { canvasElement } = ctx;

    // Take a screenshot before filling the form
    await argosScreenshot(ctx, "before-fill");

    const canvas = within(canvasElement);

    await userEvent.type(
      canvas.getByLabelText("Email", { selector: "input" }),
      "[e-mail]",
      { delay: 100 },
    );

    // Take a screenshot after filling the form
    await argosScreenshot(ctx, "after-fill");

    await userEvent.click(canvas.getByRole("button"));
  },
};

Story Modes

Argos supports Story modes to capture different states of your components. Read our Story modes guide for more details.

Fit to Content vs Page

By default, Argos screenshots are cropped to fit the rendered component (fitToContent: true). You can capture the entire page instead by setting argos.parameters.fitToContent to false.

Per Story

src/components/ProductPage/ProductPage.stories.js

import { ProductPage } from "./ProductPage";
import { allModes } from "../../../.storybook/modes";

export default {
  title: "Pages/ProductPage",
  component: ProductPage,
  parameters: {
    argos: {
      fitToContent: false,
    },
  },
};

Project-Wide Setting

.storybook/preview.js

import { allModes } from "./modes";

const preview = {
  parameters: {
    argos: {
      fitToContent: false,
    },
  },
};

export default preview;

Options

• fitToContent: Adjusts the screenshot to the content size (default: true).

• fitToContent.padding: Sets padding around the content in pixels (default: 16).

• fitToContent.zoom: Specifies the zoom level (default: 2).

Troubleshooting

My addon is not working with Vitest

To be sure that your addons are properly loaded when running Vitest, be sure to specify your addon annotations in setProjectAnnotations:

Example for storybook-addon-pseudo-states:

import { setProjectAnnotations } from "@storybook/react-vite";
import * as projectAnnotations from "./preview";
import * as addonAnnotations from "storybook-addon-pseudo-states/preview";

setProjectAnnotations([projectAnnotations, addonAnnotations]);

Read more in the Storybook documentation.

API Overview

@argos-ci/storybook/vitest-plugin

Exposes the Vitest plugin to capture screenshots of your Storybook stories during tests.

import { argosVitestPlugin } from "@argos-ci/storybook/vitest-plugin";
import { defineConfig } from "vitest/config";
export default defineConfig({
  plugins: [
    argosVitestPlugin({
      uploadToArgos: true, // Set to false to disable uploading
      buildName: "My Build Name", // Optional build name
    }),
  ],
});

• uploadToArgos: Set to true to upload screenshots to Argos CI.

Also supports all options from the Playwright argosScreenshot function and upload parameters.

@argos-ci/storybook/vitest

Take a screenshot of the Story inside the play function of a Storybook story (only available when using Vitest).

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

export const Example: Story = {
  play: async (ctx) => {
    // Take a screenshot of the story
    await argosScreenshot(ctx, "example-screenshot");
  },
};

• ctx: The Storybook context provided to the play function.

• name: A name for the screenshot.

@argos-ci/storybook/test-runner

argosScreenshot(page, context[, options])

Take a screenshot of the Story inside the postVisit hook of the Storybook Test Runner.

import { type TestRunnerConfig } from "@storybook/test-runner";
import { argosScreenshot } from "@argos-ci/storybook/test-runner";

const config: TestRunnerConfig = {
  async postVisit(page, context) {
    await argosScreenshot(page, context);
  },
};

export default config;

• page: The Playwright Page instance.

• context: The test context provided by the Storybook test runner.

• options: Customizable options for argosScreenshot. Explore available options.

Additional Resources

• Quickstart with Argos + Storybook + Vitest

• Quickstart with Argos + Storybook Test Runner

• Quickstart with Argos + Storybook Legacy (<v8)

• Argos + Storybook Test Runner example

• Argos + Storybook Vitest example

• @argos-ci/storybook on GitHub

• @argos-ci/storybook on npm