Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Storybook SDK reference (@argos-ci/storybook)

Reference for @argos-ci/storybook: capture stories with the Storybook Vitest addon or Test Runner, choose which stories are captured, set viewports, modes, and fit-to-content, and take screenshots in

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:

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

Project-Wide Setting

.storybook/preview.js

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

Choose which stories are captured

With the Vitest addon, Argos takes a screenshot after each story test that @storybook/addon-vitest runs. A story that doesn't run as a test is not captured. Argos has no parameter of its own to skip a story: parameters.argos only reads modes and fitToContent, and Chromatic's disableSnapshot is not supported. Use Storybook's test filters instead.

Exclude stories with tags

Remove the built-in test tag from a story with tags: ["!test"], or give it a custom tag and exclude that tag in storybookTest():

An excluded story is not tested at all, so it also loses its smoke test and its play function assertions. See Including, excluding, or skipping tests in the Storybook docs.

Skip the screenshot but keep the test

To keep testing every story, run Argos in a Vitest project of its own. One project runs every story test, the other runs the stories you want captured, with the Argos plugin:

Run npx vitest run --project=storybook-visual to capture the screenshots. When you run both projects, the captured stories render twice, once per project.

If your stories use modes, a story whose modes are all disabled is not captured either, and its test still runs.

Capture one folder

Vitest only runs the test files whose path contains the filter you pass on the command line, and with the Vitest addon your story files are the test files:

To narrow a project for good, point storybookTest({ configDir }) at a Storybook configuration whose stories globs only cover that folder. The addon tests the stories listed there and ignores Vitest's test.include.

If only some runs capture part of your stories, for example on pull requests, mark those builds as subset builds so the stories you didn't capture are not reported as removed.

With Test Runner

argosScreenshot only runs where you call it, so return early in postVisit for the stories you don't want captured. Their tests still run:

To leave stories out of the test run entirely, use the Test Runner's tags option or its --includeTags, --excludeTags and --skipTags flags. See Filter tests in the Storybook docs.

Where screenshots are saved and uploaded

The Vitest plugin writes every screenshot to ./screenshots, relative to the directory you run Vitest from. Change it with the root option. Screenshots are written whether or not they are uploaded, so you can open them locally.

The plugin uploads them to Argos at the end of the run only when uploadToArgos is true. If you leave it out, nothing is uploaded. The quickstart sets uploadToArgos: !!process.env.CI to upload from CI only. A few more rules:

  • Nothing is uploaded in watch mode.

  • The upload includes every screenshot in the directory. The plugin doesn't empty it between runs, so files left by an earlier run are uploaded too.

  • A failed upload fails the run (exit code 1). Set ignoreUploadFailures: true to keep the run passing when the upload fails.

With Test Runner, argosScreenshot also writes to ./screenshots, and you upload the directory with argos upload ./screenshots. See the Test Runner quickstart.

Capture several browsers

Screenshot names come from the story ID (and the mode), not from the browser. If one Vitest project lists several browser instances, they write the same files and overwrite each other, so capturing several browsers in one build is not supported.

Run Vitest once per browser instead, and give each run its own buildName and root. Each browser then gets its own Argos build and baseline, and no run uploads another one's files:

See Monorepos setup for how build names split builds.

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:

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.

  • uploadToArgos: Upload the screenshots to Argos at the end of the run. Nothing is uploaded unless you set it to true.

  • root: Directory where screenshots are written, relative to the working directory. Defaults to ./screenshots.

  • buildName: Name of the Argos build, to split builds.

  • ignoreUploadFailures: Don't fail the run when the upload fails. Defaults to false.

  • stabilize: Same as in Playwright, except that the automatic screenshots of your stories don't wait for aria-busy unless you set stabilize: { waitForAriaBusy: true }. See Wait for loading.

Also supports all options from the Playwright argosScreenshot function except viewports (use viewports and modes instead), and all upload parameters. See Where screenshots are saved and uploaded.

@argos-ci/storybook/vitest

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

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

  • page: The Playwright Page instance.

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

  • options: Customizable options for argosScreenshot. Explore available options; viewports is not supported. As with the Vitest plugin, waiting for aria-busy is off unless you set stabilize: { waitForAriaBusy: true }.

Additional Resources

Last updated

Was this helpful?