How to Do Visual Testing with Cypress

Install cypress-image-snapshot

The cypress-image-snapshot plugin is the most popular open source option for adding visual comparison to Cypress. It wraps jest-image-snapshot under the hood and provides a matchImageSnapshot custom command.

Install the package:

npm install --save-dev @simonsmith/cypress-image-snapshot

Register the plugin in your Cypress config file (cypress.config.ts or cypress.config.js):

import { defineConfig } from 'cypress';
import { addMatchImageSnapshotPlugin } from '@simonsmith/cypress-image-snapshot/plugin';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      addMatchImageSnapshotPlugin(on, config);
    },
  },
});

Add the command to your support file (cypress/support/e2e.ts):

import { addMatchImageSnapshotCommand } from '@simonsmith/cypress-image-snapshot/command';

addMatchImageSnapshotCommand();

The matchImageSnapshot command is now available in all your Cypress tests.

Write Your First Visual Test

Add visual assertions to new or existing Cypress tests by calling cy.matchImageSnapshot() at any point where you want to verify the visual state:

describe('Homepage', () => {
  it('should match the visual baseline', () => {
    cy.visit('/');
    cy.matchImageSnapshot('homepage');
  });
});

describe('Pricing Page', () => {
  it('should display pricing cards correctly', () => {
    cy.visit('/pricing');
    cy.matchImageSnapshot('pricing-page');
  });
});

The string argument names the baseline file. Choose descriptive names that make it clear which page or component the baseline represents.

You can also capture element-level screenshots by chaining on a Cypress selection:

it('should display the navigation correctly', () => {
  cy.visit('/');
  cy.get('nav.main-nav').matchImageSnapshot('main-navigation');
});

The first run creates baseline images in a cypress/snapshots directory (configurable). Subsequent runs compare against these baselines and fail if differences exceed the threshold.

Configure Comparison Thresholds

The default threshold is strict enough to catch real regressions but may also flag anti-aliasing differences as failures. Tune the threshold with the failureThreshold and failureThresholdType options:

// Allow up to 0.5% of pixels to differ
cy.matchImageSnapshot('homepage', {
  failureThreshold: 0.005,
  failureThresholdType: 'percent',
});

// Or allow up to 200 pixels to differ
cy.matchImageSnapshot('homepage', {
  failureThreshold: 200,
  failureThresholdType: 'pixel',
});

Set global defaults in the addMatchImageSnapshotCommand call in your support file:

addMatchImageSnapshotCommand({
  failureThreshold: 0.003,
  failureThresholdType: 'percent',
  customDiffConfig: { threshold: 0.1 },
});

The customDiffConfig.threshold controls the per-pixel color sensitivity (0 to 1), where 0 requires exact color match and higher values tolerate more color variation. The combination of per-pixel threshold and overall failure threshold gives fine-grained control: the per-pixel threshold filters out anti-aliasing noise at the pixel level, and the overall threshold determines how many remaining different pixels constitute a test failure.

Handle Dynamic Content

Dynamic elements like timestamps, user avatars, live counters, and animations cause false positives because they change between test runs. Handle them before capturing the screenshot.

Hide dynamic elements with CSS:

cy.visit('/dashboard');
// Hide dynamic elements
cy.get('.timestamp').invoke('css', 'visibility', 'hidden');
cy.get('.user-avatar').invoke('css', 'visibility', 'hidden');
cy.matchImageSnapshot('dashboard');

Replace dynamic text with fixed values:

cy.get('.last-updated').invoke('text', 'Updated January 1, 2026');
cy.matchImageSnapshot('dashboard');

Disable animations globally by injecting a style tag in your beforeEach hook:

beforeEach(() => {
  cy.visit('/');
  cy.document().then(doc => {
    const style = doc.createElement('style');
    style.textContent = `
      *, *::before, *::after {
        animation-duration: 0s !important;
        transition-duration: 0s !important;
      }
    `;
    doc.head.appendChild(style);
  });
});

For data-driven pages, intercept API calls and return fixed responses so the page content is deterministic:

cy.intercept('GET', '/api/stats', { fixture: 'stats.json' });
cy.visit('/dashboard');
cy.matchImageSnapshot('dashboard');

Update Baselines

When you make intentional visual changes, update the baselines by running Cypress with the updateSnapshots environment variable:

npx cypress run --env updateSnapshots=true

This replaces all baseline images with new captures. Review the updated images, then commit them alongside your code changes. Pull request reviewers should see both the code diff and the updated baseline images, confirming that the visual change was intentional.

To update only specific baselines, delete the baseline files you want to regenerate and run the tests normally. The plugin will treat missing baselines as first-run captures and create new baseline files.

Integrate with CI

Consistent rendering is critical in CI. The same page looks different on macOS and Linux because of font rendering and anti-aliasing differences. Run Cypress in a Docker container to ensure the CI environment matches the environment where baselines were generated.

The official Cypress Docker images include all browser dependencies:

# GitHub Actions example
jobs:
  visual-tests:
    runs-on: ubuntu-latest
    container:
      image: cypress/included:13.6.0
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx cypress run --spec 'cypress/e2e/visual/**'
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: visual-diffs
          path: cypress/snapshots/**/__diff_output__/

The upload-artifact step preserves diff images when tests fail, so reviewers can inspect what changed without running the tests locally. Generate baselines inside the same Docker image to ensure consistency:

docker run --rm -v $(pwd):/e2e -w /e2e cypress/included:13.6.0 \
  npx cypress run --env updateSnapshots=true