Storybook Legacy (<v8) Quickstart

Set up visual testing in a legacy Storybook (<v8) with Storycap and the Argos CLI.

Set up Argos with a legacy version of Storybook (<v8) using Storycap: Storycap crawls your Storybook and captures a screenshot of each story, then the Argos CLI uploads them.

If you use Storybook v8 or later, follow the Storybook Quickstart instead.

Prerequisites

• Storybook <v8 set up in your project
• A project created in Argos

1

Install

Install the Argos CLI and Storycap:

npm

npm i --save-dev @argos-ci/cli storycap

yarn

yarn add --dev @argos-ci/cli storycap

pnpm

pnpm add --save-dev @argos-ci/cli storycap

bun

bun add --dev @argos-ci/cli storycap

2

Capture screenshots

There are two ways to capture screenshots of your Storybook.

If your Storybook is already running and accessible via a URL, point Storycap at it:

npm exec -- storycap <STORYBOOK-URL> --outDir ./screenshots

If it isn't deployed, build and serve it before capturing:

# Build Storybook
npm exec -- storybook build --output-dir ./storybook-static

# Screenshot Storybook with Storycap
npm exec -- storycap --serverCmd "npx http-server ./storybook-static --port 6006" http://127.0.0.1:6006/ --outDir ./screenshots

Read the Storycap documentation for advanced usage.

Screenshots are written to the ./screenshots directory. Add ./screenshots to your .gitignore file to avoid committing them.

3

Set up CI

Add a workflow that captures the screenshots and uploads them to Argos. If you use another CI provider, adapt the steps accordingly:

.github/workflows/argos.yml

name: Argos

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  argos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
      - run: npm ci

      - name: Build Storybook
        run: npm exec -- storybook build --output-dir ./storybook-static

      - name: Capture screenshots with Storycap
        run: npm exec -- storycap --serverCmd "npx http-server ./storybook-static --port 6006" http://127.0.0.1:6006/ --outDir ./screenshots

      - name: Upload screenshots to Argos
        run: npm exec -- argos upload ./screenshots
        env:
          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

ARGOS_TOKEN is the project token from Settings → General → Token. On GitHub Actions, you can also use OIDC or tokenless authentication to avoid managing a secret.

You're all set

Push your changes and open a pull request — the Argos check appears on it once the build is uploaded. Review the visual changes, approve or reject them, and merge with confidence.

Argos needs a baseline to compare against. Until a build runs on your default branch, pull request builds are marked as orphan. Merge this setup or run the workflow once on your default branch to establish the baseline.

Next steps

• Stabilize screenshots – Prevent flaky diffs before they reach your pull requests
• CLI reference – All upload options
• Storybook legacy example – A complete working setup

---

Need help? Join our Discord, open an issue on GitHub, or send us an email.