Storybook Quickstart

Learn how to setup visual testing in a Storybook using Argos.

Prerequisites

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

note

If use a legacy version of Storybook (<v8), follow our legacy Storybook quickstart.

1. Install

npm
yarn
pnpm
bun

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

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

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

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

Read the CLI documentation if you need information about advanced usages.

2. Update your package.json

Add the following scripts to your package.json:

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

note

NODE_OPTIONS=--experimental-vm-modules is required because Storybook uses Jest that requires this flag to run modern packages like Argos Storybook SDK.

3. Capture screenshots

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

.storybook/test-runner.ts
import type { TestRunnerConfig } from "@storybook/test-runner";
import { argosScreenshot } from "@argos-ci/storybook";

const config: TestRunnerConfig = {
  async postVisit(page, context) {
    await argosScreenshot(page, context);
  },
};

export default config;

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

Add ./screenshots to your .gitignore file, to avoid uploading screenshots to your Git repository.

4. Setup CI to run tests and upload screenshots

First build your Storybook:

npm run build-storybook

Then serve your Storybook and run tests:

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"

Finally upload screenshots to Argos:

npm exec -- argos upload --token <ARGOS_TOKEN> ./screenshots

Note: The value of ARGOS_TOKEN is available in your project settings.

To learn how to run tests on a deployed Storybook, refer to the Storybook test runner documentation.

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!

Additional resources

Join our Discord, submit an issue on GitHub or just send an email if you need help.

Prerequisites​

1. Install​

2. Update your package.json​

3. Capture screenshots​

4. Setup CI to run tests and upload screenshots​