# Storybook

### Getting Started

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

* [Storybook + Vitest](/docs/quickstart/storybook-quickstart.md)
* [Storybook + Test Runner](/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart.md)
* [Storybook Legacy (\<v8)](/docs/quickstart/storybook-quickstart/storybook-legacy-less-than-v8-quickstart.md)

### 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](https://argos-ci.com/compare/chromatic).

### Vitest vs Test Runner

Argos supports both [Vitest](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon) and [Test Runner](https://storybook.js.org/docs/writing-tests/integrations/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](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon#comparison-to-the-test-runner).

### 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](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon) or [Test Runner](https://storybook.js.org/docs/writing-tests/integrations/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:

```ts
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](/docs/learn/how-to-guides/visual-coverage/storybook-story-modes.md) 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`

```ts
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`

```ts
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`**:

```ts
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](https://storybook.js.org/docs/api/portable-stories/portable-stories-vitest#setprojectannotations).

### API Overview

#### `@argos-ci/storybook/vitest-plugin`

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

```ts
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](/docs/sdks-reference/playwright.md#argosscreenshotpage-name-options) and [upload parameters](https://js-sdk-reference.argos-ci.com/interfaces/UploadParameters.html).

#### `@argos-ci/storybook/vitest`

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

```ts
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.

```ts
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](https://playwright.dev/docs/api/class-page) instance.
* **`context`**: The test context provided by the Storybook test runner.
* **`options`**: Customizable options for `argosScreenshot`. Explore [available options](/docs/sdks-reference/playwright.md#argosscreenshotpage-name-options).

### Additional Resources

* [Quickstart with Argos + Storybook + Vitest](/docs/quickstart/storybook-quickstart.md)
* [Quickstart with Argos + Storybook Test Runner](/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart.md)
* [Quickstart with Argos + Storybook Legacy (\<v8)](/docs/quickstart/storybook-quickstart/storybook-legacy-less-than-v8-quickstart.md)
* [Argos + Storybook Test Runner example](https://github.com/argos-ci/argos-javascript/tree/main/examples/storybook-test-runner)
* [Argos + Storybook Vitest example](https://github.com/argos-ci/argos-javascript/tree/main/examples/storybook-vitest)
* [@argos-ci/storybook on GitHub](https://github.com/argos-ci/argos-javascript/tree/main/packages/storybook)
* [@argos-ci/storybook on npm](https://www.npmjs.com/package/@argos-ci/storybook)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://argos-ci.com/docs/sdks-reference/storybook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.