Percy visual regression testing

tldr: Percy is BrowserStack's visual regression testing platform. It captures screenshots of your UI on every build, diffs them against a baseline, and uses AI to surface only the changes that matter. With a permanent free tier and SDKs for every major test framework, it's the most practical starting point for teams adding visual testing to their CI pipeline.

Why visual regression testing matters

You can have 100% passing E2E tests and still ship a broken UI. A misaligned button, a truncated headline, a z-index collision that hides your CTA. Functional tests don't catch these. They verify behavior, not appearance.

Visual regression testing fills that gap. It takes a screenshot of your UI, compares it to a known good baseline, and flags differences. Simple concept. Surprisingly hard to get right at scale.

The hard part isn't taking screenshots. It's dealing with the noise. Anti-aliasing differences between environments. Sub-pixel rendering variations. Font smoothing. A naive pixel-diff approach generates so many false positives that teams stop trusting the results within a month.

That's the problem Percy was built to solve.

The history of Percy

Percy started as an independent startup focused on visual testing for web applications. The founding insight was simple: developers needed a way to catch visual regressions without manually comparing screenshots or writing brittle pixel-diff scripts.

BrowserStack acquired Percy in 2020. The acquisition made sense. BrowserStack had the browser infrastructure (thousands of real devices and browsers). Percy had the visual comparison engine and developer-friendly SDK model. Combined, Percy could render snapshots in real browsers at scale instead of relying on headless rendering.

For the first few years under BrowserStack, Percy's development focused on expanding SDK support and improving the baseline comparison engine. The 2025 AI features (Visual Review Agent and Visual Test Integration Agent) represent a new phase. Percy is now competing on intelligence, not just infrastructure.

What Percy is

Percy is a cloud-based visual testing and review platform owned by BrowserStack. You integrate it into your test suite using one of its SDKs, and it handles screenshot capture, baseline management, diff generation, and team review workflows.

Here's the core loop:

1. Your tests run in CI (Playwright, Cypress, Selenium, Storybook, whatever).
2. At key moments, your test calls percySnapshot() to capture the current state.
3. Percy compares that snapshot to the baseline from the previous approved build.
4. Differences are highlighted in Percy's web dashboard.
5. Your team approves or rejects the changes.
6. Approved snapshots become the new baseline.

Percy renders snapshots in real browsers, not headless or simulated environments. This matters because rendering differences between Chrome and Safari are real. Your users see them. Your tests should too.

The baseline model is the key concept. Percy doesn't compare against a fixed golden image that you generate once. It compares against the last approved build. Every time you approve changes, that approval becomes the new baseline. This means your baselines evolve with your product. You never have to manually regenerate reference screenshots after an intentional design change.

Percy also supports branch-aware baselines. When you create a feature branch, Percy tracks a separate baseline for that branch. This prevents unrelated changes on main from polluting your feature branch's visual diff. When the branch merges, the baselines converge automatically.

The Visual Review Agent

In late 2025, Percy shipped the Visual Review Agent. This is the biggest feature addition since BrowserStack acquired Percy.

Before the Visual Review Agent, Percy showed you pixel-level highlighting. Every changed pixel got a red overlay. This was accurate but noisy. A font rendering change could light up an entire page in red, even though nothing meaningful changed.

The Visual Review Agent replaces pixel highlighting with smart highlights. It draws bounding boxes around meaningful changes and ignores the rest. Instead of "47,000 pixels changed," you get "the header navigation shifted 4px left and the hero image was replaced."

The practical impact:

• 3x faster review time. You scan bounding boxes and read summaries instead of squinting at pixel diffs.
• 40% fewer changes to review. The agent filters out rendering noise, anti-aliasing, and sub-pixel differences automatically.
• Human-readable summaries. Each flagged change comes with a plain-English description of what changed and where.

This is a real shift. The biggest reason teams abandon visual testing is review fatigue. When every build surfaces 50 diffs and 45 of them are false positives, people stop looking. The Visual Review Agent directly attacks that problem.

To put this in perspective: a medium-sized SaaS application with 100 visual snapshots might generate 15-25 diffs per build during active development. Before the Visual Review Agent, an engineer would spend 10-15 minutes reviewing each build. With smart highlights and auto-filtering, that drops to about 4-5 minutes. Over 10 builds per day, that's the difference between 2.5 hours and 45 minutes spent on visual review. Across a sprint, the time savings add up fast.

The summaries are particularly useful for design reviews. Instead of asking a designer to parse pixel diffs, you can share a Percy review link where each change has a plain-English description. "The card border-radius changed from 8px to 12px" is something a designer can evaluate in seconds.

Visual Test Integration Agent

Percy also launched the Visual Test Integration Agent alongside the Review Agent. This one is about setup speed.

Integrating Percy into an existing test suite used to take an hour or more. You needed to install the right SDK, configure your test runner, set environment variables, modify your CI config, and add snapshot calls to your tests.

The Visual Test Integration Agent cuts that to a single prompt in your IDE. You describe your setup ("I'm using Playwright with GitHub Actions"), and the agent identifies the right SDK, installs it, configures your environment, and adds snapshot calls to your existing tests. Percy claims 6x faster setup compared to manual integration.

This is genuinely useful for teams evaluating visual regression testing tools. The biggest barrier to adoption isn't cost (Percy has a free tier). It's the friction of getting started.

Setting up Percy with Playwright

Let's walk through a real setup. Playwright is the most popular test framework for visual regression right now, so we'll start there.

Install the SDK

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

Add snapshots to your tests

import { test, expect } from '@playwright/test';
import percySnapshot from '@percy/playwright';

test('homepage renders correctly', async ({ page }) => {
  await page.goto('https://your-app.com');
  await percySnapshot(page, 'Homepage');
});

test('pricing page layout', async ({ page }) => {
  await page.goto('https://your-app.com/pricing');
  await percySnapshot(page, 'Pricing Page');
});

test('dashboard after login', async ({ page }) => {
  await page.goto('https://your-app.com/login');
  await page.fill('[name="email"]', 'test@example.com');
  await page.fill('[name="password"]', 'password123');
  await page.click('button[type="submit"]');
  await page.waitForURL('/dashboard');
  await percySnapshot(page, 'Dashboard - Logged In');
});

Run with Percy

npx percy exec -- npx playwright test

The percy exec wrapper sets up the Percy environment, runs your tests, uploads snapshots, and triggers the comparison. You need a PERCY_TOKEN environment variable set to your project token.

Configure responsive widths

await percySnapshot(page, 'Homepage', {
  widths: [375, 768, 1280],
});

This captures three snapshots at mobile, tablet, and desktop widths. Percy renders each one in real browsers and diffs them independently.

Wait for page stability

Percy automatically waits for network idle and image loading before capturing. But if your page has animations or lazy-loaded content, you might need to add explicit waits:

test('dashboard with charts loaded', async ({ page }) => {
  await page.goto('https://your-app.com/dashboard');
  // Wait for chart library to finish rendering
  await page.waitForSelector('.chart-container svg');
  await percySnapshot(page, 'Dashboard - Charts Loaded');
});

This prevents flaky snapshots caused by capturing mid-animation or before async content finishes rendering.

Setting up Percy with Cypress

Cypress integration follows a similar pattern.

npm install --save-dev @percy/cli @percy/cypress

Add to your cypress/support/commands.js:

import '@percy/cypress';

Use in your tests:

describe('Visual regression', () => {
  it('captures the login page', () => {
    cy.visit('/login');
    cy.percySnapshot('Login Page');
  });

  it('captures the settings page', () => {
    cy.visit('/settings');
    cy.percySnapshot('Settings Page', { widths: [375, 1280] });
  });
});

Run:

npx percy exec -- npx cypress run

Setting up Percy with Storybook

For component-level visual testing, Percy's Storybook integration snapshots every story automatically.

npm install --save-dev @percy/cli @percy/storybook

Run:

npx percy storybook http://localhost:6006

Or if you want to build Storybook first:

npx percy storybook ./storybook-static

Percy will snapshot every story in your Storybook. No code changes to your stories. No percySnapshot() calls. It discovers and captures everything automatically.

This is useful for design systems and component libraries where you want regression coverage on every component variant.

Percy SDK support

Percy has official SDKs for:

• Playwright (@percy/playwright)
• Cypress (@percy/cypress)
• Selenium (@percy/selenium-webdriver for JS, percy-selenium for Python, Ruby, Java)
• Storybook (@percy/storybook)
• Puppeteer (@percy/puppeteer)
• WebDriverIO (@percy/webdriverio)
• Ember (@percy/ember)
• Capybara (percy-capybara)

Plus a generic CLI snapshot command for static sites:

npx percy snapshot ./public

If you're using a framework not listed here, the Percy CLI can capture snapshots from any URL list.

The breadth of SDK support is one of Percy's strongest advantages. Most competitors focus on one or two frameworks. Chromatic only works with Storybook. Many open source tools only support Puppeteer or Playwright. Percy covers virtually every test runner you might already be using.

Using Percy with Selenium

For teams still on Selenium (and there are many), Percy's Selenium integration works across all four supported languages:

# Python
from percy import percySnapshot
from selenium import webdriver

driver = webdriver.Chrome()
driver.get('https://your-app.com')
percySnapshot(driver, 'Homepage')

// Java
import io.percy.selenium.Percy;

Percy percy = new Percy(driver);
driver.get("https://your-app.com");
percy.snapshot("Homepage");

This matters because migrating from Selenium to Playwright just for visual testing isn't practical for most teams. Percy meets you where your test suite already is.

How Percy compares to alternatives

Percy vs. Applitools

Applitools uses its own Visual AI engine. It's been doing AI-powered visual comparison longer than Percy. Applitools' Ultrafast Grid renders snapshots across 100+ browser/device combinations simultaneously. It supports layout, strict, and content match levels.

Percy's Visual Review Agent closes the AI gap significantly. The smart highlights and auto-filtering address the same false positive problem Applitools has been solving. The key difference now is pricing and ecosystem. Percy has a free tier. Applitools doesn't. Percy is tightly integrated with BrowserStack's broader testing platform. Applitools is standalone.

For teams already on BrowserStack, Percy is the natural choice. For teams that need the most advanced visual AI capabilities and are willing to pay, Applitools still has an edge.

Percy vs. Chromatic

Chromatic is built specifically for Storybook. It's made by the Storybook team. If your visual testing starts and ends with components in Storybook, Chromatic is purpose-built for that workflow.

Percy is broader. It tests full pages, user flows, and specific application states. The Storybook integration is just one SDK among many. If you need visual regression testing beyond components, Percy covers more ground.

Percy vs. open source tools

Open source visual regression tools like BackstopJS, jest-image-snapshot, and reg-suit are free. They work. They also require you to manage your own screenshot infrastructure, baseline storage, review workflows, and false positive filtering.

Percy handles all of that as a service. The free tier gives you 5,000 screenshots per month, which is enough for small-to-medium projects. The trade-off is vendor dependency vs. infrastructure management.

For teams that want visual regression testing without running their own comparison server, Percy's free tier is hard to beat.

Summary comparison table

Percy's pricing model

Percy uses screenshot-based pricing. Every percySnapshot() call at a specific width counts as one screenshot.

• Free: 5,000 screenshots/month. Unlimited team members. This is a permanent free tier, not a trial.
• Paid plans: Start based on screenshot volume. Pricing scales with the number of snapshots per month.

The free tier is generous enough for most small teams. A typical project with 50 visual tests at 3 responsive widths uses 150 screenshots per build. At one build per day, that's 4,500 screenshots per month. Still under the free limit.

Costs climb when you test across many pages, many responsive widths, and many builds per day. A team running 200 visual tests at 4 widths with 10 builds per day needs 8,000 screenshots per day, or 240,000 per month. That's firmly in paid territory.

Percy is part of BrowserStack, so paid plans often bundle with other BrowserStack products. If you're already paying for BrowserStack Automate or App Live, ask about combined pricing.

Estimating your screenshot usage

Here's a quick formula:

Monthly screenshots = (number of visual tests) x (responsive widths per test) x (builds per day) x 30

Some real-world examples:

• Small project: 20 tests x 3 widths x 1 build/day x 30 = 1,800/month (free tier)
• Medium project: 80 tests x 3 widths x 3 builds/day x 30 = 21,600/month (paid)
• Large project: 200 tests x 4 widths x 10 builds/day x 30 = 240,000/month (paid, high volume)

The most common mistake is capturing too many responsive widths. Three widths (mobile, tablet, desktop) cover 90% of layout bugs. Adding a fourth or fifth width doubles your cost for diminishing returns.

Best practices for Percy visual regression testing

Snapshot the right things

Don't snapshot everything. Focus on:

• Critical user-facing pages. Homepage, pricing, checkout, dashboard.
• Components with complex layouts. Data tables, charts, navigation menus, modals.
• States that are easy to break. Empty states, error states, loading states, long content overflow.

A targeted suite of 30-50 snapshots catches more real bugs than 500 snapshots of every page variation.

Handle dynamic content

Dynamic content (timestamps, user avatars, ads, randomized data) creates false positives. Percy offers a percyCSS option to hide or freeze dynamic elements:

await percySnapshot(page, 'Dashboard', {
  percyCSS: `
    .timestamp { visibility: hidden; }
    .user-avatar { visibility: hidden; }
    .ad-banner { display: none; }
  `,
});

You can also use data-percy-* attributes in your HTML to control snapshot behavior per element.

Set meaningful snapshot names

Snapshot names are how you identify changes in the Percy dashboard. Use descriptive names:

// Good
await percySnapshot(page, 'Checkout - Payment Step - Credit Card Selected');

// Bad
await percySnapshot(page, 'test1');

Configure responsive widths globally

Instead of setting widths on every snapshot, configure them in .percy.yml:

version: 2
snapshot:
  widths:
    - 375
    - 768
    - 1280

This applies to all snapshots unless overridden.

Integrate with your CI pipeline

Percy works best when it runs on every pull request. Set your PERCY_TOKEN as a CI secret and add the Percy exec command to your test step. Percy will automatically compare the PR's snapshots against the base branch.

# GitHub Actions example
- name: Run visual tests
  env:
    PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
  run: npx percy exec -- npx playwright test

Percy's review workflow in practice

Understanding Percy's snapshot capture is only half the picture. The review workflow is where Percy earns its keep day-to-day.

When a build runs, Percy creates a "build" in its dashboard. Each build contains all the snapshots from that test run. Snapshots are grouped by name and compared against the baseline. You see three categories:

• No change. The snapshot matches the baseline exactly. Nothing to review.
• Changed. Percy detected a difference. You need to approve or request changes.
• New. A snapshot that doesn't exist in the baseline (new test or new page). You approve it to set the initial baseline.

For changed snapshots, the dashboard shows a side-by-side view. The old baseline is on the left. The new snapshot is on the right. With the Visual Review Agent enabled, smart highlights draw bounding boxes around meaningful differences, and a summary explains each change.

Approval workflow

Percy integrates with your pull request workflow. When visual changes are detected, Percy posts a status check on your PR. The check stays pending until all changes are reviewed. This creates a natural gate: visual changes must be explicitly approved before the PR can merge.

Team members can approve individual snapshots or approve all changes at once. Rejected changes send the PR back for fixes. This keeps designers, front-end engineers, and QA aligned on visual changes without Slack threads or screenshot comparisons in comments.

Auto-approval rules

For teams with high build frequency, Percy supports auto-approval of specific snapshot groups. If you know that certain pages change frequently (like a dashboard with live data), you can configure rules to auto-approve those snapshots. This prevents low-value reviews from blocking your pipeline.

Visual testing + functional testing

Percy catches visual regressions. It doesn't catch functional bugs. A button that looks perfect but doesn't work will pass Percy's review. A form that renders correctly but submits to the wrong endpoint won't trigger a visual diff.

The best testing strategies combine both. Run visual regression tests alongside your functional E2E suite. Percy snapshots verify appearance. Your test assertions verify behavior.

If you're looking to combine visual and functional testing in a single workflow, Bug0 Studio runs AI-driven E2E tests that verify both behavior and UI state. For teams that need comprehensive E2E coverage beyond visual testing, including functional flows, cross-browser validation, and regression testing managed by forward-deployed engineers, Bug0 Managed handles the full QA pipeline.

When Percy isn't enough

Percy is excellent at what it does. It's also limited to visual comparison. There are scenarios where you need more:

Complex user flows. Percy snapshots are static moments in time. It doesn't test that a user can complete a multi-step checkout or that form validation works correctly. You need functional E2E tests for that.

Accessibility testing. A page can look perfect and still be inaccessible. Color contrast issues, missing ARIA labels, keyboard navigation problems. These need dedicated accessibility testing tools.

Performance regression. A page that looks identical but loads 3 seconds slower won't show up in Percy. Performance monitoring is a separate concern.

Cross-browser functional behavior. Percy catches rendering differences across browsers. It doesn't catch JavaScript bugs that only occur in Safari or Edge. You need real cross-browser functional tests for that.

The teams that get the most from Percy use it as one layer in a multi-layer testing strategy. Visual tests + functional E2E tests + accessibility checks + performance monitoring.

Common pitfalls with Percy visual regression testing

Teams new to Percy tend to make the same mistakes. Here's what to watch for.

Snapshotting too early in the page lifecycle

If you call percySnapshot() before fonts load, before images render, or before CSS animations complete, you'll get inconsistent baselines. Percy waits for network idle by default, but custom fonts loaded via JavaScript or complex CSS transitions can still cause timing issues. Add explicit waits for critical visual elements before snapshotting.

Ignoring the .percy.yml config

Many teams configure everything inline in their test code. This leads to inconsistency. One test captures at widths [375, 1280], another at [320, 768, 1440]. A .percy.yml file at the project root standardizes settings across all snapshots:

version: 2
snapshot:
  widths:
    - 375
    - 768
    - 1280
  min-height: 1024
  enable-javascript: true

Not using Percy in local development

Most teams only run Percy in CI. But Percy also works locally. Running npx percy exec -- npx playwright test on your machine before pushing lets you preview visual changes before they hit the PR. This catches obvious regressions earlier and reduces the review cycle.

Overusing percyCSS to hide elements

It's tempting to hide every dynamic element with percyCSS. But if you hide too much, you're not actually testing your UI anymore. A better approach: stabilize dynamic content with test fixtures or mock data. Only use percyCSS for truly uncontrollable elements like third-party ads or live clocks.

Percy and AI-powered testing

Percy's Visual Review Agent is part of a broader trend: AI in UI testing. The testing industry is moving from rule-based automation to AI-assisted workflows at every level.

Percy's AI contributions are focused on the review and setup phases:

• The Visual Review Agent uses AI to understand what changed and whether it matters.
• The Visual Test Integration Agent uses AI to automate SDK setup and configuration.

These are practical, narrowly scoped uses of AI. They don't replace human judgment. They reduce the busy work that makes visual testing tedious.

Expect Percy to push further into AI-assisted visual testing over the next year. The foundation is there. Smart highlights and auto-filtering are just the beginning. Automated visual approval rules, pattern recognition for known-safe changes, and predictive diff analysis are likely next.

FAQs

What is Percy visual regression testing?

Percy visual regression testing is a cloud-based approach to catching UI bugs. You integrate Percy's SDK into your test suite, and it captures screenshots at key moments during test execution. These screenshots are compared to a baseline, and differences are flagged for review. Percy is owned by BrowserStack and offers a permanent free tier with 5,000 screenshots per month.

How does Percy's Visual Review Agent work?

The Visual Review Agent, launched in late 2025, uses AI to analyze visual diffs. Instead of highlighting every changed pixel, it draws bounding boxes around meaningful changes and provides human-readable summaries. It reduces review time by 3x and filters out 40% of visual changes that are rendering noise rather than real regressions.

Is Percy free to use?

Yes. Percy has a permanent free tier that includes 5,000 screenshots per month with unlimited team members. For a project with 50 visual tests at 3 responsive widths running once daily, that's roughly 4,500 screenshots per month. Most small teams stay within the free limit.

Which test frameworks does Percy support?

Percy has official SDKs for Playwright, Cypress, Selenium (JavaScript, Python, Ruby, Java), Storybook, Puppeteer, WebDriverIO, Ember, and Capybara. The Visual Test Integration Agent can set up any of these integrations from a single prompt in your IDE, making setup about 6x faster than manual configuration.

How is Percy different from Applitools?

Both use AI for visual testing. Applitools has been doing AI-powered visual comparison longer and offers more granular match levels (strict, layout, content). Percy's Visual Review Agent is newer but addresses the same false positive problem. The biggest practical difference: Percy has a permanent free tier. Applitools does not. Percy also integrates deeply with BrowserStack's broader testing platform.

How is Percy different from Chromatic?

Chromatic is built specifically for Storybook by the Storybook team. It's the best tool for component-level visual testing if your workflow centers on Storybook. Percy is broader. It tests full pages, user flows, and application states across Playwright, Cypress, Selenium, and Storybook. Choose Chromatic for pure component testing. Choose Percy for full-page and full-flow visual regression.

Can Percy replace functional E2E tests?

No. Percy catches visual regressions. It does not verify that buttons work, forms submit correctly, or APIs return the right data. You need functional E2E tests alongside visual tests. The two are complementary, not interchangeable.

How do I handle flaky visual tests in Percy?

Most flaky visual tests come from dynamic content (timestamps, ads, user-generated data) or rendering inconsistencies. Use Percy's percyCSS option to hide dynamic elements. Configure consistent viewport sizes. Use Percy's built-in stabilization features that wait for fonts and images to load before capturing. The Visual Review Agent also helps by automatically filtering rendering noise that previously caused false positives.