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:
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
:
{
"scripts": {
"test-storybook": "NODE_NO_WARNINGS=1 NODE_OPTIONS=--experimental-vm-modules test-storybook"
}
}
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:
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
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.
name: Storybook Test
permissions: {}
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
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
- Argos + Storybook example
- Argos Storybook SDK reference
- Storybook documentation
- Storybook test runner documentation
Join our Discord, submit an issue on GitHub or just send an email if you need help.