Visual regression testing with Cypress: plugins, setup and pitfalls

Pick a comparison plugin

Community plugins such as cypress-image-diff-js and cypress-visual-regression add a cy.compareSnapshot() command. They save a baseline on the first run and compare later screenshots against it. Hosted services like Percy, Applitools and Chromatic provide their own Cypress integrations with a web review UI instead.

A minimal snapshot test

After installing and registering the plugin in your Cypress config and support file, a visual check is one command at the point in the test where the page is stable.

describe('homepage', () => {
  it('matches the visual baseline', () => {
    cy.viewport(1280, 800);
    cy.visit('/');
    cy.get('[data-cy="cookie-accept"]').click();
    cy.get('h1').should('be.visible');
    cy.compareSnapshot('homepage');
  });
});

Make captures stable

Cypress screenshots are sensitive to timing. Assert on the content you expect before capturing, stub network data that changes, and run in the same browser and headless mode locally and in CI.

• Wait on assertions, not fixed timeouts
• Stub APIs that return changing data
• Hide dynamic elements before capture
• Use one browser and viewport per baseline

Know the limits

Plugin baselines live in your repository, reports are local files, and only the states your specs visit are covered. That is fine for a focused set of flows, harder for hundreds of pages and languages.

Or skip the test code entirely

Code-based visual tests only cover the pages and states someone wrote a test for, and only run when the pipeline runs. VisualRunner captures production pages from a sitemap, crawl or URL list, across languages and viewports, and monitors them on a schedule — so CMS edits, translations and third-party scripts are caught too. Engineers can still trigger a monitor from CI through the API.