Migrate from Percy

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.

Concept mapping

Percy	Argos
@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	Responsive viewports
.percy.yml → percy-css / percyCSS	Injecting CSS
Percy project + browsers dashboard	Argos project (Settings → General → Token)
Percy build review	Review a build + PR comment

Migrate a Playwright project

1

Remove the Percy packages

npm uninstall @percy/cli @percy/playwright

2

Install the Argos Playwright SDK

npm

npm i --save-dev @argos-ci/playwright

yarn

pnpm

bun

3

Add the Argos reporter to your Playwright config

Percy hooks in by wrapping your test command with percy exec. Argos hooks in through a Playwright reporter instead, so there is no wrapper command to run.

playwright.config.ts

import { defineConfig } from "@playwright/test";
import { createArgosReporterOptions } from "@argos-ci/playwright/reporter";

export default defineConfig({
  reporter: [
    process.env.CI ? ["dot"] : ["list"],
    [
      "@argos-ci/playwright/reporter",
      createArgosReporterOptions({
        uploadToArgos: !!process.env.CI,
      }),
    ],
  ],
  use: {
    // Stabilize text rendering so screenshots match across macOS and CI.
    launchOptions: {
      args: ["--disable-lcd-text", "--font-render-hinting=none"],
    },
  },
});

4

Replace percySnapshot with argosScreenshot

The call signature is nearly identical — swap the import and the function name.

Before (Percy)

import { test } from "@playwright/test";
import { percySnapshot } from "@percy/playwright";

test("homepage", async ({ page }) => {
  await page.goto("http://localhost:3000");
  await percySnapshot(page, "Homepage");
});

After (Argos)

import { test } from "@playwright/test";
import { argosScreenshot } from "@argos-ci/playwright";

test("homepage", async ({ page }) => {
  await page.goto("http://localhost:3000");
  await argosScreenshot(page, "Homepage");
});

5

Update the CI command

Drop percy exec -- and run your tests directly. Rename the token secret from PERCY_TOKEN to ARGOS_TOKEN.

Before (Percy)

- run: npx percy exec -- npx playwright test
  env:
    PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

After (Argos)

- run: npx playwright test
  env:
    ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

ARGOS_TOKEN comes from Settings → General → Token in your Argos project. On GitHub Actions you can skip the secret entirely with OIDC or tokenless authentication.

6

Delete Percy configuration

Remove .percy.yml / percy.config.js and the PERCY_TOKEN secret. See the notes below for where its options map in Argos.

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

Responsive widths (snapshot.widths)

Percy re-renders each width in the cloud. In Argos you capture each viewport in the browser. The cleanest approach is a Playwright project per viewport, or the responsive-viewport helper. See Responsive viewports.

Snapshot-time CSS (percy-css / percyCSS)

Percy lets you inject CSS to hide dynamic content at render time. Argos supports the same idea — hide or neutralize dynamic elements with injected CSS. See Injecting CSS.

Cross-browser rendering

Percy renders one DOM snapshot across multiple browsers server-side. Argos screenshots the real browser your test runs in, so to cover multiple browsers you add Playwright projects for chromium, firefox, and webkit. Each becomes its own set of screenshots in the build.

Ignoring regions

Percy uses data-percy-hide / percy-specific CSS. In Argos, mark elements you want excluded or stabilized before the screenshot. See the flaky test playbook and Argos helpers.

Frequently asked questions

Do I have to rewrite my tests?

No. Your test files, selectors, and navigation stay the same. You only change the import, the snapshot function name, and the CI command.

What happens to my Percy baselines?

They don't transfer, and they don't need to. The first Argos build on your reference branch becomes the baseline automatically. Until that build exists, pull request builds stay orphan — so run Argos on your default branch first.

Do I still need a separate percy exec step?

No. The Argos reporter uploads screenshots as part of your normal test run when it detects CI. There is no wrapper command.

Is Argos open-source friendly?

Yes. Argos has a free plan for open-source projects.

Next steps

• Keep your screenshots stable — avoid false positives after you switch.
• Responsive viewports — reproduce Percy's multi-width coverage.
• Playwright SDK reference