DEV Community

Cover image for How to perform visual regression tests with Cypress and Percy

Posted on • Updated on

How to perform visual regression tests with Cypress and Percy

Today in “Pinches of Cypress”, learn how to integrate Cypress with the service to carry out snapshot comparison tests

This is for Pedro Hyvo, who these days suggested the following theme for the series.

Visual regression tests would be nice.

Nice, indeed, Pedro.

Let's get to it then!

But first, let me contextualize what visual regression tests are.

Visual regression tests are those that interact with the application as a real user would. However, in addition to interacting (and sometimes running assertions), these tests also take snapshots throughout the execution, and these are compared with previously approved ones. If there is a visual difference, you will know about it before publishing the new software version to your users.

In some cases, the visual difference can be expected due to new functionality or a layout change.

On the other hand, sometimes the difference can be due to a real bug. You found the bug before your very precious customers (the users of your software.) Congrats on that!

Let's look at an example of an application for purchasing tickets.

First of all, we need to install Cypress and Percy packages as development dependencies. Such a process can be performed with the following command.

npm i cypress @percy/cypress -D
Enter fullscreen mode Exit fullscreen mode

After everything is installed and with Cypress initialized (that is, after running the npx cypress open command for the first time), it's time to make some changes to Cypress's files before starting to write the test.

At the top of the cypress/support/commands.js file, import the @cypress/percy library like this.

// cypress/support/commands.js

import '@percy/cypress'
Enter fullscreen mode Exit fullscreen mode

After that, update the cypress/plugins/index.js file with the following.

// This is not needed anymore.
// Read the update at the end of the post.
// cypress/plugins/index.js

let percyHealthCheck = require('@percy/cypress/task')

module.exports = (on, config) => {
  on("task", percyHealthCheck)
Enter fullscreen mode Exit fullscreen mode

Now let's look at the test.

// cypress/integration/tickets.spec.js

describe('Tickets', () => {
  beforeEach(() => cy.visit(''))

  it('enables the "Send" button after filling all mandatory fields', () => {
    cy.percySnapshot('Test started and form is empty')



    cy.percySnapshot('About to fill the last mandatory field')

    cy.percySnapshot('All mandatory fields were filled')
Enter fullscreen mode Exit fullscreen mode

Finally, create an account on, create a project on Percy's dashboard, and export the project_token environment variable that will be available on the terminal where the tests will run.

Note: See below how to export environment variables on Windows and Unix-based systems (Linux and OSX).

# Windows
$ set PERCY_TOKEN=<your token here>

# Unix 
$ export PERCY_TOKEN=<your token here>
Enter fullscreen mode Exit fullscreen mode

Also, instead of running npx cypress run to execute the tests, you should run npx percy exec -- cypress run.

With this, the test will take three snapshots during its execution. One at the beginning, when the form has not yet been filled out; another before filling in the last mandatory field (where the send button must still be disabled); and finally, one after completing all the mandatory fields, where the send button must be enabled to submit the form.

Visit the Percy dashboard project to view the snapshots taken during tests' execution.

Here's the official documentation of for its integration with Cypress.

Update: Percy has upgraded to version 3.x.x and some changes are needed. Here's the documentation to perform the upgrade.

Did you like it?

Leave a comment with what I should write in an upcoming "Pinch of Cypress".

This post was originally published in Portuguese on the Talking About Testing blog.

Would you like to learn about test automation with Cypress? Get to know my online courses on Udemy.

Top comments (0)