Visual Regression Testing with Cypress and Percy: A Comprehensive Guide

Introduction

Visual regression testing is an essential part of ensuring that your web application maintains its visual integrity over time. As applications evolve, unintended visual changes can occur, potentially impacting user experience. Combining Cypress with Percy, a powerful visual testing tool, allows you to automate visual regression testing seamlessly. In this post, we’ll explore how to set up and use Cypress and Percy to catch visual discrepancies in your web applications.

Why Visual Regression Testing Matters

1. User Experience: Ensures that UI changes do not negatively impact the user experience.
2. Consistency: Maintains visual consistency across different releases and environments.
3. Early Detection: Detects unintended visual changes early in the development process.
4. Automated Workflow: Integrates into CI/CD pipelines for continuous visual testing.

Getting Started with Cypress and Percy

To get started with visual regression testing using Cypress and Percy, follow these steps:

Step 1: Install Cypress and Percy
First, ensure you have Cypress installed in your project. If not, you can install it using the following command:

npm install cypress --save-dev

Next, install the Percy CLI and the @percy/cypress package:

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

Step 2: Configure Percy
Create a Percy project on the Percy dashboard. Once created, you’ll get a Percy project token. Set this token as an environment variable:

export PERCY_TOKEN=<your_percy_project_token>

Step 3: Integrate Percy with Cypress
In your cypress/support/index.js file, add the following line to import Percy:

import '@percy/cypress';

This will add Percy commands to Cypress, allowing you to take visual snapshots during your tests.

Writing Visual Regression Tests

Let’s write some visual regression tests using Cypress and Percy. We’ll start with a simple test to capture a visual snapshot of a web page.

Example: Capturing a Visual Snapshot
Create a new test file in the cypress/e2e directory, for example, visual-regression.spec.js, and add the following code:

describe('Visual Regression Testing with Cypress and Percy', () => {
    beforeEach(() => {
        cy.visit('/');
    });

    it('should capture a visual snapshot of the homepage', () => {
        cy.percySnapshot('Homepage');
    });
});

In this test:

• cy.visit('/'): Navigates to the root URL of the application.
• cy.percySnapshot('Homepage'): Captures a visual snapshot of the page and names it "Homepage".

Example: Testing a Specific Component
You can also capture visual snapshots of specific components or sections of a page. For instance, let’s capture a snapshot of a login form.

describe('Visual Regression Testing with Cypress and Percy', () => {
    beforeEach(() => {
        cy.visit('/login');
    });

    it('should capture a visual snapshot of the login form', () => {
        cy.get('.login-form').percySnapshot('Login Form');
    });
});

In this test:

• cy.visit('/login'): Navigates to the login page.
• cy.get('.login-form'): Selects the login form element.
• cy.percySnapshot('Login Form'): Captures a visual snapshot of the login form.

Advanced Visual Regression Testing

Capturing Snapshots in Different States
You can capture snapshots of your application in different states, such as after user interactions.

describe('Visual Regression Testing with Cypress and Percy', () => {
    beforeEach(() => {
        cy.visit('/login');
    });

    it('should capture visual snapshots in different states', () => {
        cy.get('input[name="username"]').type('testuser');
        cy.get('input[name="password"]').type('password123');
        cy.percySnapshot('Login Form - Filled');

        cy.get('button[type="submit"]').click();
        cy.percySnapshot('Dashboard');
    });
});

In this test:

• We capture a snapshot of the login form after filling it out.
• We capture another snapshot of the dashboard after logging in.

Running Visual Regression Tests

To run your visual regression tests, use the following command:

npx percy exec -- cypress run

This command runs Cypress tests with Percy, capturing and comparing visual snapshots.

Reviewing Visual Changes

After running the tests, Percy uploads the snapshots to the Percy dashboard, where you can review the visual changes. The dashboard highlights any differences between the new snapshots and the baseline images, allowing you to approve or reject changes.

Best Practices for Visual Regression Testing

1. Isolate Visual Elements: Capture snapshots of isolated components or sections to pinpoint visual changes more effectively.
2. Use Descriptive Snapshot Names: Use descriptive names for snapshots to make it easier to identify and review them.
3. Integrate with CI/CD: Add visual regression tests to your CI/CD pipeline to catch visual changes automatically with each deployment.
4. Review Changes Regularly: Regularly review and approve changes in the Percy dashboard to maintain an accurate visual baseline.

Conclusion

Visual regression testing with Cypress and Percy is a powerful way to ensure your web application maintains its visual integrity over time. By integrating visual tests into your workflow, you can detect and address unintended visual changes early, providing a consistent and polished user experience. Follow the steps and best practices outlined in this guide to set up and leverage visual regression testing in your projects.

Happy testing!