Skip to main content

Argos Storybook SDK

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:

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.

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: {
      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​

@storybook/addon-themes is not working with Vitest​

If you are using the @storybook/addon-themes with Vitest, you may encounter issues with the theme not being applied correctly during tests. This is a known limitation, as the @storybook/addon-themes is not compatible with Vitest's test environment.

To work around this limitation, we added an applyGlobals option to the argosVitestPlugin. This allows you to manually apply the theme based on the globals set in your Storybook configuration.

argosVitestPlugin({
  applyGlobals: async ({ handler, globals }) => {
    await handler.evaluate((globals) => {
      if (globals.theme === "dark") {
        document.documentElement.classList.add("dark");
      } else {
        document.documentElement.classList.remove("dark");
      }
    }, globals);
  },
}),

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​