> For the complete documentation index, see [llms.txt](https://argos-ci.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://argos-ci.com/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart.md).

# Storybook Test Runner Quickstart

## Prerequisites

To get the most out of this guide, you'll need to:

* [Use Storybook v8+](https://storybook.js.org/docs/get-started/install)
* [Create your project in Argos](https://app.argos-ci.com/new)

{% hint style="info" %}
If use Vitest and not Test Runner, follow our [Storybook Vitest quickstart](/docs/quickstart/storybook-quickstart.md).

If use a legacy version of Storybook (\<v8), follow our [legacy Storybook quickstart](/docs/quickstart/storybook-quickstart/storybook-legacy-less-than-v8-quickstart.md).
{% endhint %}

{% stepper %}
{% step %}

### Install

{% tabs %}
{% tab title="npm" %}

```
npm i --save-dev @argos-ci/cli @argos-ci/storybook @storybook/test-runner
```

{% endtab %}

{% tab title="yarn" %}

```
yarn add --dev @argos-ci/cli @argos-ci/storybook @storybook/test-runner
```

{% endtab %}

{% tab title="pnpm" %}

```
pnpm add --save-dev @argos-ci/cli @argos-ci/storybook @storybook/test-runner
```

{% endtab %}

{% tab title="bun" %}

```
bun add --dev @argos-ci/cli @argos-ci/storybook @storybook/test-runner
```

{% endtab %}
{% endtabs %}

Read the [CLI documentation](/docs/sdks-reference/argos-command-line-interface-cli.md) if you need information about advanced usages.
{% endstep %}

{% step %}

### Update your package.json

Add the following scripts to your `package.json`:

package.json

```json
{
  "scripts": {
    "test-storybook": "NODE_NO_WARNINGS=1 NODE_OPTIONS=--experimental-vm-modules test-storybook"
  }
}
```

{% hint style="info" %}
`NODE_OPTIONS=--experimental-vm-modules` is required because Storybook uses Jest that requires this flag to run modern packages like Argos Storybook SDK.
{% endhint %}
{% endstep %}

{% step %}

### Capture screenshots

Add `.storybook/test-runner.ts` file to your project:

{% code title=".storybook/test-runner.ts" %}

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

{% endcode %}

It will capture screenshots of your stories in `./screenshots` directory.

Add `./screenshots` to your `.gitignore` file, to avoid uploading screenshots to your Git repository.
{% endstep %}

{% step %}

### Setup CI to run tests and upload screenshots

Below is a complete GitHub Actions workflow to build your Storybook, run tests, capture screenshots, and upload them to Argos. If you use another CI provider, adapt the steps accordingly.

{% code title=".github/workflows/storybook-test.yml" %}

```yml
name: Storybook Test

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4

      - name: Install dependencies
        run: npm ci

      - name: Build Storybook
        run: npm run build-storybook

      - name: Install Playwright dependencies
        run: npx playwright install --with-deps chromium

      - name: Run Storybook tests and capture screenshots
        run: |
          npx concurrently -k -s first -n "SB,TEST" -c "magenta,blue" \
            "npx http-server ./storybook-static --port 6006 --silent" \
            "npx wait-on tcp:127.0.0.1:6006 && npm run test-storybook"

      - name: Upload screenshots to Argos
        # 👇 Replace `<ARGOS_TOKEN>` with your project token, available in your Argos project settings.
        run: npm exec -- argos upload --token <ARGOS_TOKEN> ./screenshots
```

{% endcode %}

To learn how to run tests on a deployed Storybook, refer to the [Storybook test runner documentation](https://storybook.js.org/docs/writing-tests/integrations/test-runner).
{% endstep %}
{% endstepper %}

## Congratulations on installing Argos! 👏

After committing and pushing your changes, the Argos check status will appear on your pull request in GitHub (or GitLab).

**Note:** you need a reference build to compare your changes with. If you don't have one, builds will remain orphan until you run Argos on your reference branch.

You can now review changes of your app for each pull request, avoid visual bugs and merge with confidence. Welcome on board!

## Next step: keep your screenshots stable

Now that Argos is running, the next thing to learn is how to keep your screenshots free of flakiness. Read [Best practices for stable screenshots](/docs/learn/reliability-and-flakiness/flaky-tests.md) to avoid false positives before they reach your pull requests.

## Additional resources

* [Argos + Storybook + Test Runner example](https://github.com/argos-ci/argos-javascript/tree/main/examples/storybook-test-runner)
* [Argos Storybook SDK reference](/docs/sdks-reference/storybook.md)
* [Storybook documentation](https://storybook.js.org/docs)
* [Storybook test runner documentation](https://storybook.js.org/docs/writing-tests/integrations/test-runner)

***

[Join our Discord](https://argos-ci.com/discord), [submit an issue on GitHub](https://github.com/argos-ci/argos/issues) or just [send an email](mailto:contact@argos-ci.com) if you need help.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://argos-ci.com/docs/quickstart/storybook-quickstart/storybook-test-runner-quickstart.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.