Catch UI Regressions With Cypress

Conducting Visual Testing With Cypress: A Step-By-Step Guide

I’ve seen teams try to solve visual bugs with tools that were never built for the job.

Assertions check that elements exist, text matches, or APIs respond correctly, so everything looks fine on paper. Meanwhile, spacing breaks, fonts shift, and layouts collapse on real screens.

The problem isn’t a lack of testing, it’s using functional tools to catch visual problems.

Cypress is excellent at end-to-end testing, but visual regression testing needs a different approach than DOM assertions alone. Cypress can support visual testing, but only when it’s set up intentionally and paired with the right visual comparison layer. Otherwise, teams end up writing brittle tests or missing UI changes entirely.

In this article, I’ll explain how visual testing works in a Cypress-based workflow and where Cypress fits best. I’ll walk through running visual tests with Cypress, show how Percy extends Cypress for true visual regression testing, and explain why the combination works better than using Cypress alone.

What is Visual Testing?

Visual testing checks whether an application looks the way it’s supposed to, not just whether it functions correctly. Instead of validating the DOM or specific values, it compares screenshots of the UI against a known baseline. Any unexpected visual change, such as spacing issues, font changes, or broken layouts, gets flagged automatically.

This approach works differently from traditional test assertions. Functional tests confirm that elements exist or actions succeed, but they rarely catch visual regressions caused by CSS changes, responsive behavior, or browser differences.

Visual testing fills that gap by focusing on what users actually see on the screen, making it especially useful for UI-heavy and design-driven applications.

How Does Cypress Help With Visual Regression Testing?

Cypress wasn’t built as a visual testing tool, but it plays an important supporting role in visual regression workflows. It handles test execution, page interactions, and state control, which makes it a strong foundation for capturing consistent visual snapshots.

• Reliable Test Execution: Cypress runs tests in a real browser, which helps ensure screenshots reflect actual user conditions.
• Deterministic App State: Tests can pause, stub APIs, or control data, so screenshots are taken at predictable moments.
• Component and Page Coverage: Cypress works well for both full-page flows and isolated component views.
• Easy Screenshot Capture: Built-in screenshot commands make it simple to capture UI states during test runs.
• CI-Friendly by Design: Cypress integrates cleanly into CI pipelines, enabling visual checks on every pull request.
• Strong Ecosystem Support: Plugins and integrations extend Cypress to handle true visual comparisons.
• Developer-Friendly Debugging: Clear logs and time-travel debugging help diagnose why a visual change occurred.

Conducting Visual Tests With Cypress: Step-by-Step Tutorial

This tutorial shows how to set up basic visual regression testing in Cypress using an image comparison plugin. The goal is to demonstrate how Cypress captures screenshots and compares them against a baseline to detect visual changes over time.

Before you begin, make sure the following prerequisites are installed on your system:

• Node.js (LTS version recommended)
• Visual Studio Code or any code editor
• Cypress installed in your project

Step 1: Install the image diff plugin

Navigate to your project’s root directory, where the package.json file is located. Install the Cypress image diff plugin as a development dependency.

npm i -D cypress-image-diff-js

This plugin adds image comparison capabilities on top of Cypress’s screenshot functionality.

Step 2: Configure the image diff plugin

Open the Cypress plugin file and register the image comparison plugin.

// cypress/plugins/index.js

module.exports = (on, config) => {

  const getCompareSnapshotsPlugin =

    require('cypress-image-diff-js/dist/plugin')

  getCompareSnapshotsPlugin(on, config)

}

This setup enables Cypress to process and compare visual snapshots during test runs.

Step 3: Import the image comparison command

Next, add the custom snapshot command so it’s available across your tests.

// cypress/support/commands.js

const compareSnapshotCommand =

  require('cypress-image-diff-js/dist/command')

compareSnapshotCommand()

This command allows you to call cy.compareSnapshot() directly inside test files.

Step 4: Configure the visual report

To generate an HTML report after tests finish, add the following to the Cypress support index file.

// cypress/support/index.js

after(() => {

  cy.task('generateReport')

})

The report helps teams review visual differences without digging through raw image files.

Step 5: Write your first visual test

Create a new test file inside the cypress/integration folder, for example visual-test.js.

// visual-test.js

describe('Cypress Visual Testing', () => {

  it('Compares the Google homepage visually', () => {

    cy.visit('https://www.google.com/?hl=hi')

    cy.compareSnapshot('google-page')

  })

})

This test visits a page and captures a full-page screenshot for visual comparison.

Step 6: Run the visual regression test

Execute the test using the Cypress CLI.

npx cypress run --spec "cypress/integration/visual-test.js"

On the first run, Cypress saves the screenshot as the baseline. Future runs compare new screenshots against this baseline to detect visual differences.

Step 7: Review visual reports and screenshots

After the test completes, two folders are generated automatically:

• cypress-visual-report: Contains an HTML report. Passed tests show no images, while failed tests display baseline, current, and diff images.
• cypress-visual-screenshots: Stores raw images in three folders, baseline, comparison, and diff.

This setup works well for learning visual regression basics. However, as test suites grow, managing baselines, approvals, and cross-browser differences manually can become difficult, which is where dedicated visual testing platforms start to add more value.

What Are the Challenges of Cypress Visual Testing?

Cypress makes it easy to capture screenshots, but visual testing introduces challenges that go beyond basic test execution. Many of these issues appear once teams rely on Cypress alone for visual regression at scale.

• No Native Visual Comparison Engine: Cypress captures screenshots but lacks built-in visual diffing or baseline management. Percy uses a native visual comparison engine built specifically for visual testing, with specialized algorithms that go beyond basic pixel matching to detect meaningful UI changes through mobile web visual testing.
• High Maintenance of Local Baselines: Storing and updating images locally becomes difficult as test coverage expands. Percy is designed to automate the management of baselines in the cloud, removing the need for manual, local, or Git-based baseline management.
• Flaky Results From Dynamic Content: Animations, fonts, and data changes can trigger inconsistent visual failures. Percy minimizes flaky visual test results by stabilizing snapshots, ignoring dynamic regions, and ensuring screenshots are captured only after the UI reaches a consistent state.
• Limited Cross-Browser Coverage: Cypress primarily runs in a single browser per test configuration. Percy has a dedicated real device infrastructure of over 50,000 devices to test across multiple browsers and viewports. This allows you to catch browser-specific regressions, through different screen sizes.
• Manual Review Overhead: Reviewing raw images without a visual dashboard slows down feedback loops. Percy’s primary purpose is to reduce rather than increase manual QA overhead by highlighting only meaningful visual changes.
• Difficulty Scaling in CI: Large image sets increase storage, runtime, and maintenance costs in pipelines. Percy has a native snapshot stabilization metric to synchronize hundreds of screenshots on the same format.
• Lack of Collaboration Features: Cypress alone does not support shared visual approvals or audit trails. You can adopt Percy to expand potential collaborations and divide them into branches with separate baselines.

How to Implement Cypress Visual Testing Using Percy

BrowserStack Percy is a dedicated visual testing platform built to catch UI changes automatically and at scale. Percy adds intelligent visual comparison tests, baseline management, and team-based review workflows on top of your existing test setup.

Instead of managing screenshots locally, Percy uploads snapshots to a centralized dashboard where visual changes can be reviewed, approved, or rejected with context.

Percy integrates cleanly with Cypress and other test runners. Cypress controls the test flow and application state, while Percy handles screenshot capture, intelligent visual diffing, and cross-browser rendering.

AI-powered comparison reduces noise from minor rendering differences, which helps teams focus on real visual regressions instead of false positives.

Upgrade to AI-powered Visual Automation

Unlock 5x faster review times across 50,000+ browsers & devices

Try Percy

Step 1: Install Percy dependencies

Install the Percy CLI and Cypress SDK as development dependencies in your project.

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

These packages enable snapshot capture and communication with the Percy platform during test runs.

Step 2: Import Percy into Cypress

Add Percy support so Cypress can use Percy’s snapshot command.

// cypress/support/index.js

import '@percy/cypress'

This makes the cy.percySnapshot() command available in your test files.

Step 3: Write your first Percy visual test

Create or update a Cypress test and add a Percy snapshot where you want to capture the UI.

describe('Cypress Visual Testing', () => {

  it('Visually compares the Google homepage', () => {

    cy.visit('https://www.google.com/?hl=hi')

    cy.percySnapshot('Google')

  })

})

Each snapshot is uploaded to Percy and compared against an existing baseline.

Step 4: Create a Percy project and generate a token

Visit the Percy website and create a new project from the dashboard. Percy generates a unique project token that authenticates test runs and links snapshots to the correct project.

Set the Percy token as an environment variable before running tests.

• macOS or Linux

export PERCY_TOKEN=<your_token>

• Windows (Command Prompt)

set PERCY_TOKEN=<your_token>

• Windows (PowerShell)

$env:PERCY_TOKEN=<your_token>

Step 5: Run Cypress tests with Percy enabled

Execute your Cypress tests through the Percy CLI.

npx percy exec -- cypress run

During execution, Cypress runs as usual while Percy captures and uploads visual snapshots in the background.

Step 6: Review results in the Percy dashboard

After the run completes, results appear in the Percy dashboard. Each build shows visual diffs, baseline comparisons, and browser-specific renderings. Reviewers can approve intended changes or request fixes directly from the UI.

This workflow scales better than local image comparison. Percy handles baseline history, cross-browser rendering, and collaborative review, which makes visual testing more reliable as applications and teams grow.

Why Combine Cypress Visual Testing with Percy?

Cypress and Percy solve different parts of the visual testing problem. Cypress controls how and when the UI is exercised, while Percy focuses on accurate visual comparison, review, and collaboration. Together, they create a visual testing workflow that is both developer-friendly and scalable.

Best Practices For Visual Regression Testing With Cypress

Visual tests are most effective when they stay stable, focused, and easy to maintain. Following a few practical best practices helps reduce flakiness and ensures visual failures point to real issues.

• Stabilize the UI Before Snapshots: Wait for animations, fonts, and network calls to fully settle before capturing visuals.
• Control Test Data and State: Use stubs, fixtures, or seeded data to keep screenshots consistent across runs.
• Limit Snapshot Scope: Capture key components or critical pages instead of every possible screen.
• Use Clear Snapshot Names: Name snapshots based on user flows or UI states for easier review and tracking.
• Avoid Dynamic Content: Mask or ignore timestamps, ads, or randomized content that changes frequently.
• Run Visual Tests in CI: Execute visual checks on pull requests to catch regressions early.
• Review and Update Baselines Carefully: Approve visual changes intentionally to avoid locking in unintended UI regressions.

These practices keep Cypress visual tests reliable and help teams scale coverage without increasing noise.

Conclusion

Using Cypress alone for visual checks can work at a small scale, but it often falls short as applications grow. Cypress excels at driving user flows and controlling application state, yet visual regression requires smarter comparison, baseline tracking, and review workflows. Without those pieces, teams spend more time managing screenshots than fixing real UI issues.

Combining Cypress with Percy creates a more reliable visual testing setup. Cypress handles test execution, while Percy manages visual diffs, approvals, and cross-browser coverage. Together, they help teams catch visual regressions earlier, reduce manual review effort, and ship UI changes with greater confidence.