Storybook SDK reference (@argos-ci/storybook)

Reference for @argos-ci/storybook: capture every story with the Storybook Vitest addon or Test Runner, set viewports, modes, and fit-to-content, and take screenshots in play functions.

Get started

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

Compatibility

Storybook 8 through 11, including the 11 pre-releases. The Vitest addon needs Storybook 9 or later; the Test Runner works from Storybook 8.
Vitest 4 or later, with @vitest/browser and @vitest/browser-playwright 4 or later, when using the Vitest addon.
Node.js 22 or later.

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" }),
      "example-email@email.com",
      { 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.

Viewports

Argos captures a story at the viewport selected by its viewport global, whether the global comes from a story mode or from the story’s own globals. The value is resolved against parameters.viewport.options (parameters.viewport.viewports on Storybook 8):

"compact": a key of the viewport options.
{ value: "compact", isRotated: true }: Storybook’s global format, where isRotated swaps the width and height.
800: a number is used as the width.

When no viewport matches, the story is captured at the test browser’s default size.

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";

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

Project-Wide Setting

.storybook/preview.js

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.

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

Last updated 0 minutes ago

Was this helpful?