Migrate from Percy to Argos
Migrate visual testing from Percy (BrowserStack) to Argos. Replace the Percy SDK and percy exec with the Argos reporter for Playwright, Cypress, or Storybook.
This guide shows how to move a project from Percy (now part of BrowserStack) to Argos. You keep your existing tests. The migration is three edits: swap the SDK package, rename the snapshot call, and drop percy exec from your CI command.
How Percy and Argos differ
Both tools catch visual regressions on every pull request, but the capture model is different, and it changes a few steps below:
Percy captures the DOM, CSS, and assets in your test, uploads them, and re-renders each snapshot in Percy's cloud across the widths and browsers you configure in
.percy.yml.Argos captures the rendered screenshot in the real browser your test already runs and uploads the image. Extra viewports and browsers come from your test framework (for example Playwright projects), not from a server-side re-render.
The practical upshot: with Argos, what you see in your test is exactly what gets diffed, and there is no separate rendering configuration to maintain. Baselines are selected automatically from your Git history — there is no equivalent of managing them per branch in a dashboard.
Why teams switch
Beyond the capture model, the reasons teams pick Argos over Percy:
Review where you work — a pull request comment summarizes every build, and reviews support comments pinned to the exact pixel that changed, threads, and real-time collaboration.
Flakiness under control — flaky test detection scores unstable tests, and recurring flaky changes can be ignored once or auto-ignored.
Built for agents — an MCP server, a scriptable CLI, and AI agent skills let AI tools review builds with you.
Open source — the whole platform, diff engine included, is MIT-licensed on GitHub.
Concept mapping
@percy/cli + @percy/playwright
@argos-ci/playwright
percySnapshot(page, "Name")
argosScreenshot(page, "Name")
cy.percySnapshot("Name") (Cypress)
cy.argosScreenshot("Name")
percy exec -- <test command>
<test command> (the reporter uploads automatically)
PERCY_TOKEN
ARGOS_TOKEN
.percy.yml → snapshot.widths
.percy.yml → percy-css / percyCSS
Percy project + browsers dashboard
Argos project (Settings → Authentication → Project token)
Percy build review
Review a build + PR comment
Migrate a Playwright project
Update the CI command
Drop percy exec -- and run your tests directly. Rename the token secret from PERCY_TOKEN to ARGOS_TOKEN.
Before (Percy)
After (Argos)
ARGOS_TOKEN comes from Settings → Authentication → Project token in your Argos project. On GitHub Actions you can skip the secret entirely with OIDC or tokenless authentication.
Migrate a Cypress project
Cypress follows the same pattern. Replace @percy/cypress with @argos-ci/cypress, swap the import in cypress/support/e2e.js, register the Argos task in cypress.config.js, and rename cy.percySnapshot("Name") to cy.argosScreenshot("Name"). Then remove percy exec from your test command. Full steps are in the Cypress quickstart.
Migrate a Storybook project
If you used @percy/storybook (percy storybook), Argos captures stories with the Storybook SDK and can also deploy a live Storybook URL on every PR. Follow the Storybook quickstart.
Migrating Percy configuration
Frequently asked questions
Next steps
Keep your screenshots stable — avoid false positives after you switch.
Responsive viewports — reproduce Percy's multi-width coverage.
Argos vs Percy — a side-by-side comparison.
Last updated
Was this helpful?