How to Use Argos CI with Storybook Visual Testing
Capture Storybook stories in CI with Argos, compare visual changes, and choose between the Vitest and Test Runner workflows.
Argos CI adds visual regression review to Storybook by capturing story screenshots during CI browser tests, uploading them to Argos, and comparing them with baselines. For a current Storybook project using its Vitest integration, Argos identifies the @argos-ci/storybook Vitest plugin as the recommended path; projects already using Storybook Test Runner can use its documented integration. Check the Argos and Storybook documentation for compatibility with your installed versions before choosing commands, since the supported combinations can change.
The usual loop is: run the browser tests against your stories, capture each story (and any interaction states you need), upload snapshots, then review changed screenshots in the pull request. Argos can also deploy a static Storybook build to a pull-request preview URL; that is a separate workflow from snapshot comparison.
1. Choose the Storybook test path
Start by checking your Storybook version and how the project currently runs browser-based story tests. Avoid installing both integrations just to try them; use the route that fits the existing setup and is supported for your versions.
| Project setup | Likely route | What to confirm |
|---|---|---|
| Storybook project using its Vitest integration | Argos Storybook Vitest plugin | Current Argos and Storybook compatibility and the plugin setup in the Argos visual-diff docs. |
| Project already using Storybook Test Runner, or an older configuration | Argos Test Runner hook | Package compatibility and the runner setup in the Argos guide. |
Argos documents visual modes for testing variants such as themes, viewports, or locales, and supports taking a screenshot at a selected point in a story’s play function. These let you cover configuration and interactive states without treating the initial render as the only meaningful appearance.
2. Configure the current Vitest integration
For projects on the compatible Storybook Vitest path, follow the current Argos Storybook visual testing documentation for the exact plugin and configuration syntax. Wire the plugin into the project’s existing Storybook Vitest setup, then ensure CI runs those browser tests and gives the upload step the Argos credentials required by the current instructions.
Do not copy Test Runner configuration into a Vitest project: these are distinct execution paths. Keep the package versions aligned with the compatibility guidance in both projects’ docs, and commit the lockfile so CI uses the same dependency resolution as local development.
Capture an interaction state
A story’s initial render may not represent the state you want to guard. Where the integration supports it, invoke the Argos screenshot helper at the desired point in the story’s play function, after the interaction and any resulting UI update. For example, a menu story can be captured after opening the menu, so changes to the expanded state are reviewed. Use the current integration docs for the helper’s exact import and call signature.
3. Configure Storybook Test Runner in GitHub Actions
The following is the structure of Argos’s documented Test Runner workflow: install the CLI, Storybook SDK, and runner; register a postVisit hook that captures each visited story; build and serve the static Storybook in CI; run the test runner; then upload the captured screenshots with the CLI. The concrete recipe was published in Argos’s Test Runner guide on October 29, 2024. Treat it as a documented recipe, not a universal current command set, and verify package compatibility before using it.
Install the packages
npm install --save-dev @argos-ci/cli @argos-ci/storybook @storybook/test-runnerUse the package manager and version constraints already used by your project. The command above reflects the documented recipe; check the current Argos guide if your Storybook version requires different setup.
Add the capture hook
Create .storybook/test-runner.ts and register the screenshot hook shown in the guide:
import { argosScreenshot } from "@argos-ci/storybook";
const config = {
async postVisit(page, context) {
await argosScreenshot(page, context);
},
};
export default config;The hook runs after the runner visits a story. If your project needs a particular interaction state, use the integration path and capture point documented for that setup rather than assuming a post-visit screenshot includes an interaction that has not run.
Build, serve, test, and upload
A CI job needs a static Storybook build served at a URL the runner can reach. In GitHub Actions, the workflow’s environment should provide ARGOS_TOKEN from a repository secret, then build Storybook, start its server, run the Test Runner against it, and upload the generated snapshots with the Argos CLI. This is an ordered outline; use the current guide for exact CLI flags and server orchestration for your versions.
# Example workflow steps; verify commands against your installed versions.
- name: Build Storybook
run: npm run build-storybook
- name: Start Storybook and run browser tests
run: |
npm run serve-storybook &
npx test-storybook --url http://127.0.0.1:6006
- name: Upload snapshots to Argos
run: npx argos uploadConfigure ARGOS_TOKEN as a GitHub Actions secret and expose it only to the job steps that need it. The exact static server script, readiness wait, output directory, and upload syntax depend on the project and current CLI. Do not assume the illustrative script names above already exist in your package scripts.
4. Review visual changes and expand coverage
After CI uploads snapshots, Argos compares them with baselines and presents visual changes for review. The Argos product pages describe checks that link reviewers to diffs in pull requests. A changed image can represent an intended design update or a regression; review the changed component and its context before accepting a new baseline.
- Start with representative stories. Ensure important components and states have stories that render deterministically.
- Add meaningful modes. Use supported modes for themes, viewport sizes, or locales when those variations are part of the user interface you need to protect.
- Capture after the state change. For interactive coverage, place the capture after the relevant action and UI update in the supported
playflow. - Keep previews distinct from diffs. If reviewers also need a browsable build, configure Argos Deploy’s Storybook pull-request preview workflow separately from snapshot comparison.
5. Keep captures stable and CI reliable
Visual regression is useful only when the same story produces comparable output across runs. Keep CI’s browser environment and story data predictable, wait for the UI state you intend to capture, and avoid making a snapshot depend on live, changing content. If a story includes animation or time-sensitive data, arrange for a stable state before the capture using the mechanisms supported by your test setup.
For reliability, make sure the Storybook server is ready before launching browser tests, preserve the test process’s failure status, and make upload happen only after capture has completed. Keep the Argos token in CI secret storage. A failed build, browser test, or upload is a different problem from an actual screenshot difference, so inspect the relevant CI step before changing a baseline.
Or skip the browser setup
For a one-off page capture or a screenshot outside your Storybook CI flow, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns an image or PDF. It can take cleaner captures by accepting cookie or consent banners and removing more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; those steps can each be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and each response identifies the page verdict and billing status in headers. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 shots a month without a card; paid plans start at $5 for 3,000.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for authentication and request options. The service also supports custom viewport and device settings, full-page capture, element capture, interaction and wait options, request controls, caching, signed image links, async jobs, bulk capture, and PDF output.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| Argos receives no snapshots | The browser test path did not run, the capture hook/plugin was not loaded, or upload did not run. | Inspect CI step order and logs; confirm the chosen integration is configured and the upload step follows successful capture. |
| Upload cannot authenticate | The CI job does not receive a valid Argos token. | Check that ARGOS_TOKEN is configured as a repository secret and passed to the relevant step. Do not print the secret in logs. |
| Storybook URL cannot be reached | The static server is not started, is bound to a different address/port, or is not ready when tests begin. | Verify the serving script, URL, port, and readiness ordering in the workflow. |
| Unexpected or inconsistent diffs | The captured state or rendered content varies between runs, or the capture occurs before the intended state is ready. | Stabilize story data and timing; capture after the interaction and UI update you intend to compare. |
| Configuration examples do not work | The recipe targets a different Storybook or package version. | Check the current Argos integration docs and compatibility guidance for the installed versions; the Test Runner recipe is dated and is not the only supported path. |
| PR has no browsable Storybook | Snapshot upload and preview deployment are separate workflows. | Configure the documented Argos Deploy Storybook preview flow if reviewers need a live build. |
Performance, reliability, and cost
CI time depends on how many stories and modes you run, the browser test setup, and the build and upload steps. Begin with the stories that protect important UI and add theme, viewport, or locale coverage where it catches real variation. Avoid multiplying modes without a review reason, and keep captures deterministic to reduce time spent investigating noise.
Argos’s researched pages describe snapshot comparison, review checks, and a separate preview deployment workflow, but do not establish pricing or performance benchmarks. Check Argos’s current product and plan information for cost details relevant to your project. Keep browser test failures and upload failures visible in CI so missing visual data cannot be mistaken for a clean comparison.
FAQ
Does Argos replace Storybook?
No. Storybook provides the component stories and browser test environment; Argos receives screenshots and helps compare and review visual changes.
Can I test a state after a click?
Yes, the documented Vitest integration supports capturing at a chosen point in a story’s play function. Place the capture after the interaction and resulting update.
Does uploading screenshots also deploy a live Storybook?
No. Argos documents pull-request Storybook previews as a separate deployment workflow.
Which integration should an older project use?
Choose based on the project’s installed Storybook version and existing runner, then verify the current compatibility guidance. Argos documents both its Vitest path and Test Runner support.
