Percy vs Chromatic Visual Regression (2026)

TL;DR

Percy is the stronger default for cross-framework QA programs and teams already using BrowserStack. Chromatic is usually the cleaner choice for Storybook-centered design systems that also want Cypress journey snapshots. Both are credible cloud visual testing platforms, so decide with a short proof of concept using identical states, browsers, viewports, and reviewer rules.

Key Takeaways

• Choose Percy when visual coverage spans several automation frameworks or BrowserStack is already central to the test platform.
• Choose Chromatic when Storybook is the component catalog and one review system should cover stories plus Cypress journeys.
• Percy captures deliberate points through cy.percySnapshot(), while Chromatic captures test endings automatically and supports named cy.takeSnapshot() calls.
• Both tools need deterministic data, loaded assets, stable clocks, deliberate viewports, and human baseline review.
• Evaluate the tools with the same scenarios and browsers because snapshot consumption and review effort depend on the actual test portfolio.
• Keep functional Cypress assertions around each visual capture so setup failures are not mistaken for approved UI states.

The percy vs chromatic visual regression decision is no longer a simple choice between an end-to-end tool and a Storybook tool. In 2026, both services integrate with Cypress, archive the rendered page and its assets, render comparisons in managed cloud browsers, track baselines, and support collaborative review. The practical difference is the workflow each platform makes easiest.

Pick Percy when Cypress is one runner among several or your organization already uses BrowserStack. Pick Chromatic when Storybook stories are the center of UI development and Cypress journeys should enter the same visual review system. If neither condition decides it, run the same representative test portfolio through both services and compare reviewer effort, supported browser requirements, build behavior, and snapshot usage.

This tutorial implements both integrations against one controlled catalog page. For broader Cypress foundations, read the Cypress visual testing guide before expanding the proof of concept.

TL;DR: Percy vs Chromatic Visual Regression Verdict

The fastest defensible verdict is conditional. Choose Chromatic if the same frontend team authors stories, owns the design system, and reviews Cypress UI changes. Choose Percy if a central QA group needs one visual convention across Cypress and other runners, especially inside an existing BrowserStack program. A product with no Storybook and only a few Cypress flows should test both before committing.

What You Will Build

You will create a small provider-neutral Cypress scenario, then add two independent visual configurations. By the end, you will have:

• A fixed catalog response with stable names, prices, and image paths.
• Functional readiness checks that run before either visual capture.
• A Percy test with named responsive snapshots.
• A Chromatic test with controlled automatic capture and named targeted snapshots.
• A CI design that keeps tokens secret and makes the provider choice explicit.

Use this as an evaluation branch. Do not publish both services on every pull request indefinitely unless they protect different visual contracts.

Prerequisites

Use Node.js 22 or 24, a Git repository with accessible history, and Cypress 13.5 or newer. Chromatic documents Cypress 13.5 as its minimum, while using a current Cypress release keeps browser support and TypeScript types current. The example assumes the application runs at http://localhost:3000 and exposes /catalog plus /api/products.

Install Cypress if the project does not already contain it:

npm install --save-dev cypress
npx cypress verify

Start the application in a separate terminal:

npm run dev
curl --fail http://localhost:3000/catalog

The verification request must return a successful response. Adapt the port once in every configuration if your application uses a different address. Create separate Percy and Chromatic projects, but keep PERCY_TOKEN and CHROMATIC_PROJECT_TOKEN in shell or CI secrets, never in Git.

Step 1: Create One Deterministic Cypress Scenario

Start with provider-neutral state. The fixture removes database drift, while the helper proves that the expected page has finished rendering.

// cypress/fixtures/products.json
[
  {
    "id": "prod-101",
    "name": "API Testing Handbook",
    "price": 39,
    "imageUrl": "/test-assets/api-handbook.png"
  },
  {
    "id": "prod-102",
    "name": "Cypress Field Notes",
    "price": 29,
    "imageUrl": "/test-assets/cypress-notes.png"
  }
]

// cypress/support/catalog.ts
export const openStableCatalog = () => {
  cy.clock(Date.UTC(2026, 7, 6, 9, 0, 0))
  cy.intercept('GET', '/api/products', { fixture: 'products.json' }).as('products')
  cy.visit('/catalog')
  cy.wait('@products').its('response.statusCode').should('eq', 200)
  cy.get('[data-cy=product-card]').should('have.length', 2)
  cy.contains('[data-cy=product-card]', 'API Testing Handbook').should('be.visible')
  cy.get('[data-cy=loading]').should('not.exist')
  cy.document().its('fonts.status').should('eq', 'loaded')
}

Verify the state without either vendor. This test should pass before a visual baseline exists:

// cypress/e2e/catalog.functional.cy.ts
import { openStableCatalog } from '../support/catalog'

describe('catalog state', () => {
  it('renders two fixed products', () => {
    openStableCatalog()
    cy.get('[data-cy=product-card]').eq(1).should('contain.text', '$29')
  })
})

npx cypress run --browser chrome --spec cypress/e2e/catalog.functional.cy.ts

Expect one passing test. If it fails, fix the route, selector, asset, or readiness condition before installing a visual SDK. The Cypress cy.intercept examples show how to control more complex request patterns without introducing live-data noise.

Step 2: Add Percy Cypress Visual Testing

Install Percy's CLI and Cypress SDK, then give Percy its own support file and configuration. Separate configuration files make the comparison reversible and prevent one provider's hooks from changing the other's run.

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

// cypress/support/percy.ts
import '@percy/cypress'

// cypress.percy.config.ts
import { defineConfig } from 'cypress'

export default defineConfig({
  viewportWidth: 1280,
  viewportHeight: 900,
  e2e: {
    baseUrl: 'http://localhost:3000',
    supportFile: 'cypress/support/percy.ts',
    specPattern: 'cypress/e2e/**/*.percy.cy.ts',
  },
})

Create the visual spec. Percy can render a captured DOM state at multiple widths, which is efficient when CSS alone controls the responsive layout.

// cypress/e2e/catalog.percy.cy.ts
import { openStableCatalog } from '../support/catalog'

describe('catalog visual states with Percy', () => {
  it('captures the populated catalog', () => {
    openStableCatalog()

    cy.percySnapshot('Catalog, two products', {
      widths: [375, 768, 1280],
      minHeight: 900,
    })
  })
})

Verify the integration with the token from your Percy project:

PERCY_TOKEN=<TOKEN> npx percy exec -- cypress run \
  --config-file cypress.percy.config.ts \
  --spec cypress/e2e/catalog.percy.cy.ts

A successful command prints a Percy build URL and the dashboard lists Catalog, two products at three widths. A first build establishes a baseline only after the team's normal approval policy is satisfied. The Cypress visual testing examples provide additional state patterns for modals, themes, error screens, and long content.

Step 3: Make Percy Capture an Interaction State

Add a second explicit snapshot after opening the filters drawer. The stable name should describe user-visible state, not an implementation detail or timestamp.

// add inside the Percy test after the first snapshot
cy.get('[data-cy=open-filters]').click()
cy.get('[role=dialog]')
  .should('be.visible')
  .and('have.attr', 'aria-label', 'Filter products')
cy.get('[role=dialog]').contains('Category').should('be.visible')

cy.percySnapshot('Catalog, filters open', {
  widths: [375, 1280],
  minHeight: 900,
})

Verify this step by rerunning the same provider command:

PERCY_TOKEN=<TOKEN> npx percy exec -- cypress run \
  --config-file cypress.percy.config.ts \
  --spec cypress/e2e/catalog.percy.cy.ts

The build should now contain five renderings: three for the populated page and two for the open drawer. If opening behavior changes at initial load based on viewport, write distinct Cypress tests with cy.viewport() before cy.visit() instead of assuming a width-only cloud render recreates that JavaScript path.

Step 4: Add Chromatic Cypress Visual Testing

Install the current Chromatic CLI and Cypress integration. Chromatic needs both a browser-side support import and a Node event plugin. It also requires Chrome for Cypress archive capture.

npm install --save-dev chromatic @chromatic-com/cypress

// cypress/support/chromatic.ts
import '@chromatic-com/cypress/support'

// cypress.chromatic.config.ts
import { installPlugin } from '@chromatic-com/cypress'
import { defineConfig } from 'cypress'

export default defineConfig({
  viewportWidth: 1280,
  viewportHeight: 900,
  env: {
    disableAutoSnapshot: true,
  },
  e2e: {
    baseUrl: 'http://localhost:3000',
    supportFile: 'cypress/support/chromatic.ts',
    specPattern: 'cypress/e2e/**/*.chromatic.cy.ts',
    setupNodeEvents(on, config) {
      installPlugin(on, config)
    },
  },
})

Disabling automatic snapshots is deliberate for this evaluation. Chromatic otherwise captures the page at the end of every test, whether the test passes or fails. Targeted capture makes the portfolio equivalent to Percy's explicit points.

// cypress/e2e/catalog.chromatic.cy.ts
import { openStableCatalog } from '../support/catalog'

describe('catalog visual states with Chromatic', () => {
  it('captures populated and filter states', () => {
    openStableCatalog()
    cy.takeSnapshot('Catalog, two products')

    cy.get('[data-cy=open-filters]').click()
    cy.get('[role=dialog]').should('be.visible')
    cy.takeSnapshot('Catalog, filters open')
  })
})

Chromatic's Cypress integration first archives the states during Cypress execution. Its CLI then uploads those archives for cloud rendering and comparison. Run both commands from the repository root:

ELECTRON_EXTRA_LAUNCH_ARGS=--remote-debugging-port=9222 \
  npx cypress run --browser chrome \
  --config-file cypress.chromatic.config.ts \
  --spec cypress/e2e/catalog.chromatic.cy.ts

CHROMATIC_PROJECT_TOKEN=<TOKEN> \
  npx chromatic --cypress --exit-zero-on-changes

Expect the Cypress test to pass and the second command to print a Chromatic build URL. Confirm that exactly two named states appear. If an unexpected third state appears, check whether disableAutoSnapshot reached the configuration used by the test.

Step 5: Compare Responsive Behavior Fairly

Do not count Percy's three widths against one Chromatic viewport and call the comparison complete. Exercise the same product layouts. With Chromatic, set the Cypress viewport before the page state is archived:

// cypress/e2e/catalog-responsive.chromatic.cy.ts
import { openStableCatalog } from '../support/catalog'

for (const [label, width] of [['mobile', 375], ['tablet', 768], ['desktop', 1280]] as const) {
  it(`captures the ${label} catalog`, () => {
    cy.viewport(width, 900)
    openStableCatalog()
    cy.get('[data-cy=catalog-grid]').should('be.visible')
    cy.takeSnapshot(`Catalog, two products, ${label}`)
  })
}

Verify all three archives before upload:

ELECTRON_EXTRA_LAUNCH_ARGS=--remote-debugging-port=9222 \
  npx cypress run --browser chrome \
  --config-file cypress.chromatic.config.ts \
  --spec cypress/e2e/catalog-responsive.chromatic.cy.ts

Percy's width array is compact for CSS-responsive pages. Explicit Cypress viewports are more verbose but accurately replay code that reads viewport dimensions during initialization. Apply the same explicit-flow principle to both tools when the application changes navigation, requests, or hydration logic based on initial width.

Step 6: Control Dynamic Content Before Comparing Results

Visual noise can make either vendor look weak. Keep the comparison about rendering and review, not random test data. Freeze time before navigation, intercept volatile APIs, serve committed test assets, and assert fonts and important images before capture. For selectors that must change, use the narrowest provider feature that preserves useful coverage.

Percy supports snapshot options such as percyCSS for a targeted visual-test adjustment. Chromatic supports options including ignoreSelectors, delay, reduced-motion preferences, animation control, and diff thresholds. These controls are not interchangeable. An ignored live chat panel and a frozen final animation frame represent different test contracts. Document the reason beside the configuration.

Avoid using broad ignore rules during the trial. First run with the same raw page state, record every unstable region, then fix instability at the application boundary. The dynamic content masking guide explains when masking is justified and when it erases a real regression surface.

Verify determinism by running the functional scenario twice before uploading new visual builds:

npx cypress run --browser chrome --spec cypress/e2e/catalog.functional.cy.ts
npx cypress run --browser chrome --spec cypress/e2e/catalog.functional.cy.ts

Both runs should pass without retries or content differences. Compare two no-code-change vendor builds as well. Any reported diff deserves investigation before the scoring exercise begins.

Step 7: Put One Provider Behind a CI Check

Use locked dependencies, full Git history for baseline selection, secret tokens, and a stable browser image. Do not run both providers after the proof of concept unless the team has assigned separate ownership. The following package scripts preserve the tested commands:

{
  "scripts": {
    "test:visual:percy": "percy exec -- cypress run --config-file cypress.percy.config.ts",
    "test:visual:chromatic:capture": "cypress run --browser chrome --config-file cypress.chromatic.config.ts",
    "test:visual:chromatic:publish": "chromatic --cypress --exit-zero-on-changes"
  }
}

For Percy, start the application, wait for readiness, and run npm run test:visual:percy with PERCY_TOKEN. For Chromatic, run the capture script with ELECTRON_EXTRA_LAUNCH_ARGS=--remote-debugging-port=9222, retain the default cypress/downloads archive directory between jobs if jobs are split, then run the publish script with CHROMATIC_PROJECT_TOKEN. Chromatic's CLI does not run Cypress for you.

Verify scripts locally with the selected provider before committing the workflow:

npm run test:visual:percy -- --spec cypress/e2e/catalog.percy.cy.ts

ELECTRON_EXTRA_LAUNCH_ARGS=--remote-debugging-port=9222 \
  npm run test:visual:chromatic:capture -- \
  --spec cypress/e2e/catalog.chromatic.cy.ts
npm run test:visual:chromatic:publish

A useful required check distinguishes execution failure from visual change awaiting review. Decide whether a detected change should fail immediately or remain pending until a reviewer accepts or rejects it. Document who can approve baselines, what evidence is required, and how forked pull requests behave without secrets. The visual regression CI setup guide covers the surrounding gate design.

Percy vs Chromatic Visual Regression Architecture

Both integrations let Cypress create a known state locally, but their capture semantics differ. Percy waits for cy.percySnapshot(), serializes the current DOM and resources, and sends the snapshot through the Percy process for remote rendering at requested widths and project browsers. The test author owns every capture point.

Chromatic's Cypress plugin communicates through the Chrome DevTools Protocol and writes a page archive during the Cypress run. By default, the integration archives the end of each test. cy.takeSnapshot() adds named mid-test states, while disableAutoSnapshot lets a team use only targeted points. The later chromatic --cypress phase finds the archives and uploads them for parallel capture and comparison.

This difference affects failure diagnosis. In Percy, ask whether the snapshot command ran and whether Percy discovered every asset. In Chromatic, separate Cypress archive creation from the upload and cloud capture phases. A passing Cypress test does not prove that the Chromatic archive was found, uploaded, and rendered. Conversely, a visual build cannot compensate for a test that reached the wrong state.

For component-heavy work, Chromatic's connection to Storybook can combine isolated stories and selected Cypress journeys in one UI workflow. Percy also supports component-oriented integrations, but its strategic advantage is broader runner continuity and BrowserStack alignment. Compare the organizational boundary, not only the screenshot API.

Which Should You Choose for Percy vs Chromatic Visual Regression?

Choose Percy when the QA platform must standardize visual checks across multiple test runners, teams, or application types. It is also a natural shortlist leader when procurement, identity, browsers, and support already flow through BrowserStack. Explicit snapshots suit a QA team that wants every capture justified in test code. Percy width options are convenient when one deterministic DOM state needs several CSS breakpoint renders.

Choose Chromatic when Storybook stories are already reviewed as product artifacts. Component owners can keep design-system states, interaction checks, and selected Cypress journeys close to the same UI review process. Automatic test-end capture can accelerate initial coverage, while targeted snapshots and disableAutoSnapshot support a curated mature suite. Chromatic is also credible for Cypress without Storybook, but the Storybook connection is where its differentiation is clearest.

Run a two-week proof of concept if the answer remains unclear. Select 15 to 25 states across one page, one modal, one responsive grid, one error state, and one component family. Use the same browser matrix and reviewer group. Record setup time, unexplained diffs, median review time, archive or asset failures, accessibility of evidence, and actual snapshot consumption. Do not use vendor demo projects because they omit your fonts, authentication, CDN rules, and branch model.

Test the review workflow with controlled defects rather than waiting for accidental changes. Introduce a one-pixel spacing shift, a missing icon, a font-weight change, mobile overflow, and one intentionally updated color token on separate commits. Ask reviewers to classify each result as regression, intended change, or rendering noise without telling them which defect you planted. Record whether they can find the affected source area, compare all viewports, assign an owner, leave a useful explanation, and reverse an incorrect approval. Detection sensitivity matters, but a technically accurate diff still wastes time if the reviewer cannot understand its scope. Include a no-change rerun between defect commits so environmental instability has its own score. This exercise reveals whether grouping, navigation, comments, and branch baselines fit the team's daily work. It also prevents a polished sales demo from outweighing evidence gathered from the actual application.

Pricing changes, and nominal snapshot allowances can count dimensions differently. Calculate cost from the measured portfolio, expected pull requests, reruns, widths, browsers, and retention needs. The Applitools vs Percy comparison is useful if AI-assisted comparison or a third enterprise option belongs in the evaluation.

Troubleshooting

Percy command exists but no snapshots appear -> Confirm @percy/cypress is imported by the support file selected in cypress.percy.config.ts. Run through npx percy exec -- ..., check that PERCY_TOKEN belongs to the intended project, and verify that the spec actually reaches cy.percySnapshot().

Chromatic reports that no Cypress archives were found -> Run Cypress before the Chromatic CLI, use Chrome, provide ELECTRON_EXTRA_LAUNCH_ARGS=--remote-debugging-port=9222, and check cypress/downloads. If downloadsFolder changed, point CHROMATIC_ARCHIVE_LOCATION to the same location.

Chromatic creates an unwanted snapshot at test completion -> Set env.disableAutoSnapshot to true globally or on that test. Keep cy.takeSnapshot() only at reviewed stable points and confirm the intended config file is active.

Cloud output has missing fonts or images -> Make assets reachable from the provider's capture environment, avoid expiring signed URLs, and assert font and image readiness locally. Add only required asset hosts, with no credentials embedded in URLs.

Mobile and desktop results show the same composition -> Determine whether responsiveness is CSS-driven or initialized through JavaScript. Use provider widths for CSS reflow, but set cy.viewport() before cy.visit() when application logic reads the initial viewport.

Every build shows dates, cursors, or animations changing -> Freeze browser time, return fixed server timestamps, disable caret-producing focus when it is irrelevant, and pause a specific animation at an intentional state. Do not raise a global threshold until meaningful small changes disappear.

Interview Questions and Answers

The interview bank below covers architecture, capture timing, baseline governance, responsive state, and trial design. Practice explaining why a stable Cypress assertion belongs before a visual snapshot, because that distinction separates tool knowledge from dependable test engineering.

Common Mistakes

• Describing Chromatic as Storybook-only even though its current Cypress integration archives end-to-end states.
• Comparing one Percy snapshot across three widths with one Chromatic archive at a single width.
• Letting live API data, current dates, rotating ads, or remote avatars decide the baseline.
• Importing both integrations into the default Cypress support file during an evaluation and losing provider isolation.
• Assuming a successful Cypress run means Chromatic has uploaded and rendered its archives.
• Calling cy.percySnapshot() outside percy exec and expecting a cloud build.
• Accepting every changed baseline to turn a required check green.
• Hiding large regions or increasing thresholds before identifying the unstable input.
• Publishing service tokens in configuration files, command history, logs, or pull requests.
• Choosing from feature grids without measuring reviewer time on the team's own UI.

Where To Go Next

Expand the winning proof of concept into component, page, interaction, empty, and error contracts. The Cypress component testing example helps isolate reusable UI states, while the Cypress visual testing example library shows how to stabilize full journeys. Keep the losing provider configuration on the evaluation branch or remove it in a reviewed change so future engineers do not run two billable suites accidentally.

Conclusion

Percy and Chromatic can both deliver reliable Cypress visual regression in 2026. Percy is the better default for heterogeneous automation estates and BrowserStack-aligned QA organizations. Chromatic is the better default for Storybook-centered frontend teams that want component and end-to-end UI evidence in one review culture.

Make the final choice from an identical, deterministic trial. Measure false-change investigation, review clarity, browser coverage, CI failure modes, and real snapshot use. The service that produces the fewest unexplained approvals and the clearest ownership is the one your team will continue to trust.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• Smoke vs sanity vs regression (2026)
• How to Set up visual regression in CI (2026)
• Stress vs soak vs spike testing (2026)
• Using vision models for visual regression (2026)
• Visual Regression Testing With Dynamic Content Masking (2026)
• AI powered visual testing with vision models (2026)