Migrate from Chromatic to Argos
Migrate visual testing from Chromatic to Argos. Move your Storybook, Playwright, or Cypress visual tests off the chromatic CLI to the Argos SDK.
This guide shows how to move a project from Chromatic to Argos. Chromatic is built around a hosted chromatic CLI that builds and uploads your Storybook (or an archive of your E2E runs). Argos plugs into the test runner you already use and, for Storybook, can also publish a live Storybook URL on every pull request.
How Chromatic and Argos differ
Chromatic builds your Storybook, uploads it, and captures every story on Chromatic's infrastructure. Cross-browser and multi-viewport coverage come from Chromatic's cloud and story modes.
Argos captures your stories locally with the Storybook Vitest addon (a real Playwright browser) and uploads the images. It then deploys the built Storybook to an Argos URL so reviewers can open the live component next to the diff.
Both select baselines automatically and gate the pull request, so the review workflow feels similar. The main change is where rendering happens and how you scope large suites.
Concept mapping
chromatic CLI + @chromatic-com/storybook
@argos-ci/storybook + argos deploy
npx chromatic --project-token=<token>
npx vitest run --project=storybook + npx argos deploy ./storybook-static
CHROMATIC_PROJECT_TOKEN
ARGOS_TOKEN
TurboSnap (--only-changed)
Modes (viewports, themes, globals)
Publish Storybook (chromatic hosting + permalinks)
argos deploy ./storybook-static → Deployments
@chromatic-com/playwright + --playwright
@argos-ci/playwright reporter + argosScreenshot
@chromatic-com/cypress + --cypress
@argos-ci/cypress + cy.argosScreenshot
Chromatic web review
Review a build + PR comment
Migrate a Storybook project
Install the Argos Storybook SDK
Argos uses the Storybook Vitest addon to run your stories. The addon requires Storybook 9 or later; if you don't have it yet, install it before continuing. On Storybook 8, use the Test Runner quickstart instead, and on older versions the legacy quickstart.
Add the Argos plugin to your Vitest config
The Argos Vitest plugin captures a screenshot of every story and uploads it. Add it alongside the Storybook test plugin:
See the Storybook quickstart for the complete vitest.config.ts, including the browser provider and text-rendering flags.
Replace the CI step
Swap the single chromatic command for two steps: run the visual tests, then deploy the built Storybook.
Before (Chromatic)
After (Argos)
ARGOS_TOKEN comes from Settings → Authentication → Project token. On GitHub Actions you can use OIDC or tokenless authentication instead of a secret.
Migrate the published Storybook
Chromatic doesn't only run visual tests — it also publishes your Storybook and serves it at a hosted permalink (for example main--<appid>.chromatic.com), which you share with designers and stakeholders. Argos covers this with Deployments: the argos deploy step you added above uploads the built Storybook and serves it on its own URL, so you can drop Chromatic's publish entirely.
How the hosting maps
npx chromatic publishes the built Storybook
npx argos deploy ./storybook-static uploads and serves it
Per-build permalink
Immutable deployment URL (<project>-<hash>-<account>.argos-ci.live)
Branch permalink (e.g. main--<appid>.chromatic.com)
Branch URL that follows the latest deploy on that branch
"Latest published" / production Storybook
Production deployment (via --prod or your production branch)
Account-gated access to the published Storybook
Access protection (require sign-in per project)
What to change
Keep the argos deploy step
The CI step you added when migrating visual tests already publishes your Storybook:
By default this creates a preview deployment. Deployments from your production branch (usually main) are promoted to production automatically — or force it with --prod. See Environments.
Match your access setting
If your Chromatic Storybook required a login, turn on access protection in Argos so deployment URLs require an Argos sign-in. If it was public, no change is needed.
Migrate Playwright or Cypress E2E visual tests
Chromatic's E2E integrations (@chromatic-com/playwright, @chromatic-com/cypress) capture an archive during your test run, which you then upload with npx chromatic --playwright or --cypress. Argos captures screenshots inline instead — no archive step.
Playwright: install
@argos-ci/playwright, add the reporter toplaywright.config.ts, and callargosScreenshot(page, "Name")where you want a snapshot. Then runnpx playwright testdirectly (nochromaticcommand). See the Playwright quickstart.Cypress: install
@argos-ci/cypress, register the Argos task, and callcy.argosScreenshot("Name"). See the Cypress quickstart.
Migrating Chromatic features
Frequently asked questions
Next steps
Storybook quickstart — the full setup.
Storybook story modes — replace Chromatic modes.
Deployments — live Storybook URLs on every PR.
Argos vs Chromatic — a side-by-side comparison.
Last updated
Was this helpful?