How to perform visual regression tests with Cypress and Percy

Today in “Pinches of Cypress”, learn how to integrate Cypress with the Percy.io 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

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'

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)
}

Now let's look at the test.

// cypress/integration/tickets.spec.js

describe('Tickets', () => {
  beforeEach(() => cy.visit('https://example.com/tickets'))

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

    cy.get('#name')
      .should('be.visible')
      .type('Walmyr')
    cy.get('#email')
      .should('be.visible')
      .type('walmyr@example.com')

    cy.contains('Send')
      .should('be.visible')
      .and('be.disabled')

    cy.percySnapshot('About to fill the last mandatory field')
    cy.get('#i-agree')
      .should('be.visible')
      .check()

    cy.percySnapshot('All mandatory fields were filled')
    cy.contains('Send')
      .should('be.visible')
      .and('not.be.disabled')
  })
})

Finally, create an account on Percy.io, 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>

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 Percy.io 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.