Migrate from Chromatic

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	Argos
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)	Subset builds / sharding
Modes (viewports, themes, globals)	Storybook story modes
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

1

Remove the Chromatic packages

npm uninstall chromatic @chromatic-com/storybook

2

Install the Argos Storybook SDK

npm

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

yarn

pnpm

bun

Argos uses the Storybook Vitest addon to run your stories. If you're on Storybook v8+ and don't have it yet, install it before continuing. (On older Storybook, use the Test Runner quickstart or the legacy quickstart.)

3

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:

vitest.config.ts

import { argosVitestPlugin } from "@argos-ci/storybook/vitest-plugin";
// ...alongside storybookTest({ ... }) in your plugins array:

argosVitestPlugin({
  uploadToArgos: !!process.env.CI,
}),

See the Storybook quickstart for the complete vitest.config.ts, including the browser provider and text-rendering flags.

4

Replace the CI step

Swap the single chromatic command for two steps: run the visual tests, then deploy the built Storybook.

Before (Chromatic)

- run: npm ci
- run: npx chromatic
    --project-token=${{ secrets.CHROMATIC_PROJECT_TOKEN }}

After (Argos)

- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npx vitest --project=storybook
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
- run: npm run build-storybook
- run: npx --no-install argos deploy ./storybook-static
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

ARGOS_TOKEN comes from Settings → General → Token. On GitHub Actions you can use OIDC or tokenless authentication instead of a secret.

5

Remove Chromatic config

Delete chromatic.config.json, the @chromatic-com/storybook addon entry in .storybook/main.ts, and the CHROMATIC_PROJECT_TOKEN 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

Chromatic	Argos
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

1

Keep the argos deploy step

The CI step you added when migrating visual tests already publishes your Storybook:

- run: npm run build-storybook
- run: npx --no-install argos deploy ./storybook-static
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

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.

2

Point shared links at the Argos URL

Replace any *.chromatic.com links in your README, PR templates, or design docs with the Argos deployment URL. Argos posts the deployment status and URL back to the pull request, so reviewers get the link automatically — no separate publish command to run.

3

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.

If you only used Chromatic to publish Storybook (not for visual tests), you can adopt just the deploy step. See the Deployments quickstart and Use deployments in CI for non-GitHub providers.

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 to playwright.config.ts, and call argosScreenshot(page, "Name") where you want a snapshot. Then run npx playwright test directly (no chromatic command). See the Playwright quickstart.
• Cypress: install @argos-ci/cypress, register the Argos task, and call cy.argosScreenshot("Name"). See the Cypress quickstart.

Migrating Chromatic features

TurboSnap (only test changed stories)

Argos doesn't use TurboSnap's git-diff story selection. Instead it runs your test runner, so you scope work with the tools you already have: subset builds to run part of the suite, and parallel testing and sharding to spread it across CI machines.

Modes (viewports, themes, locales)

Chromatic modes map to Storybook story modes in Argos, which capture the same story under multiple viewports, themes, or globals.

Interaction tests (play functions)

Your play functions keep working. Call argosScreenshot(ctx, "name") inside a play function to capture a specific interaction state. See the Storybook quickstart.

Frequently asked questions

Do I keep writing stories the same way?

Yes. Your stories, args, and play functions are unchanged. Argos runs them through Vitest and screenshots each one.

What replaces Chromatic's hosted Storybook?

argos deploy ./storybook-static publishes your built Storybook to a unique Argos deployment URL on every pull request, so reviewers can open the live component.

What happens to my Chromatic baselines?

They don't transfer. The first Argos build on your reference branch establishes the baseline automatically. Run Argos on your default branch first so pull request builds have something to compare against.

Is there an open-source plan?

Yes — see Open source.

Next steps

• Storybook quickstart — the full setup.
• Storybook story modes — replace Chromatic modes.
• Deployments — live Storybook URLs on every PR.