Visual regression testing: what it is and how to set it up

What visual regression testing is

Visual regression testing captures a screenshot of your UI, compares it against an approved baseline, and flags every difference for a person to review. Intended changes get approved and become the new baseline; unintended ones get rejected before they merge.

It exists because functional tests assert behavior, not appearance. These are the failures it is built to surface:

• Layout shift. A CTA drifts out of place after an unrelated CSS change. Pixels move; tests stay green.
• Color regression. A token update repaints a primary button off-brand. No assertion ever checks the hue.
• Text overflow. A longer string clips inside a fixed button. Logic is fine — the label is unreadable.

How a visual regression workflow runs

1. Capture. Your CI uploads screenshots from the Storybook stories, Playwright, Cypress or Puppeteer specs you already run.
2. Compare. Each screenshot is diffed against the baseline, the last approved build on your base branch.
3. Review. The result lands as a status check on the pull request. Approve the intended changes, reject the regressions.
4. Update the baseline. Approving a change promotes it to the new baseline for that branch, so intended changes never need approving twice.

The very first build on a branch has nothing to compare against, so it becomes the baseline and is approved automatically. Run it on a base branch that already looks right.

Set it up with Snapvisor

The path from an empty project to a reviewed build is four steps. The getting started guide has the full version.

1. Create a project and copy its token. Sign up, create a project, and copy its project token (ARGOS_TOKEN) from the project settings. Store it as a CI secret, never in the repository.
2. Install the SDK for your test runner.
   shellCopy

   npm install --save-dev @snapvisor/cli @snapvisor/playwright

3. Register the reporter and capture screenshots. The Playwright reporter uploads the screenshots when the run finishes.
   playwright.config.tsCopy

   // playwright.config.ts
   import { defineConfig } from "@playwright/test";
   import { createArgosReporterOptions } from "@snapvisor/playwright/reporter";
   
   export default defineConfig({
     reporter: [
       process.env.CI ? ["dot"] : ["list"],
       [
         "@snapvisor/playwright/reporter",
         createArgosReporterOptions({ uploadToArgos: !!process.env.CI }),
       ],
     ],
   });

   tests/example.spec.tsCopy

   // tests/example.spec.ts
   import { test } from "@playwright/test";
   import { argosScreenshot } from "@snapvisor/playwright";
   
   test("screenshot homepage", async ({ page }) => {
     await page.goto("http://localhost:3000");
     await argosScreenshot(page, "homepage");
   });

4. Run it in CI. No wrapper command is needed; the token comes from the environment.
   GitHub ActionsCopy

   - run: npm run build
   - run: npx playwright test # captures via argosScreenshot, uploads via the reporter
     env:
       ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

Snapvisor Free includes 7,000 screenshots a month with no card to start. Pro starts at $9/month with 15,000 included; see pricing.

Keep the screenshots trustworthy

• Stable captures. argosScreenshot stabilizes the page before it captures: it waits for web fonts, images and aria-busy regions to settle, hides carets and scrollbars and normalizes font anti-aliasing.
• Browsers and sizes. To cover Chromium, Firefox and WebKit, run them as Playwright projects. Pass viewports on a capture for each size you care about.
• Flaky changes. Reviewers can mark a recurring change as ignored, and Snapvisor can auto-ignore changes that keep reappearing. See flaky test detection.
• Big suites. Shard screenshot uploads across CI jobs and review them as one build. See parallel testing.

Visual regression testing with Percy

Percy is BrowserStack's visual testing product. These are the parts of its workflow that matter when you set up or compare tools, each from Percy's public documentation (checked 2026-10-11, sources below):

• Capture. Percy captures a snapshot of the DOM within the test browser and sends it to Percy's API to be rendered across browsers and widths. Screenshots are taken in Percy's infrastructure, not inside your test suite. The default widths are 375 and 1280 pixels.
• CI. You set the PERCY_TOKEN environment variable in your CI service and wrap the test command with percy exec, for example percy exec -- node test.js.
• Baseline. A build on the main branch is compared against the previous build on that branch; a pull request build is compared against the merge base, the common ancestor commit of your branch and the target branch. With no base build, every snapshot is marked as new, and the first build has no visual comparisons.
• Review. You can approve a whole build, groups of matching visual changes, or individual snapshots, and approved snapshots keep their approval across builds on the branch. A snapshot that is not ready can be sent back with a request for changes.

The same workflow in Snapvisor

The loop is the same: capture, compare against a baseline, review, approve. The differences are in how each stage is done.

• Capture. Percy sends a DOM snapshot and renders it; Snapvisor takes a real screenshot in the browser your test is already running in with argosScreenshot, and your pipeline uploads the images.
• Browsers and widths. Percy renders them for you; with Snapvisor you ask for them: viewports on each call and one Playwright project per browser engine.
• CI. PERCY_TOKEN and percy exec become ARGOS_TOKEN with no wrapper. On GitHub Actions you can skip the token with tokenless authentication.
• Baseline. Snapvisor diffs against the last approved build on your base branch, found by walking your Git history to the first ancestor commit that has an approved build. See baseline builds.
• Review. Changes land as a status check on the pull request, and you approve or reject them in the review UI. Approving promotes the change to the baseline for that branch.

For plans, free tiers, browser coverage and AI-agent access side by side, read Snapvisor vs Percy.

Moving from Percy

You keep your test runner and your CI. What changes is the snapshot call, the token and where baselines live.

1. Replace each percySnapshot call with its Snapvisor equivalent (argosScreenshot on Playwright and Cypress, or @snapvisor/storybook for Storybook).
2. Swap PERCY_TOKEN for ARGOS_TOKEN and remove percy exec from your CI scripts.
3. Run the first Snapvisor build on a base branch that is visually correct. Percy baselines cannot be imported, so that build becomes the new baseline.
4. Require the Snapvisor check in branch protection and take the Percy check out of the required checks.

The full mapping, with Playwright, Cypress and Storybook examples, is in Migrate from Percy.

Comparing other tools

Frequently asked questions

Sources

Try Snapvisor free