Percy Developer Hub

Welcome to the Percy Developer Hub. You'll find comprehensive guides and documentation to help you start working with Percy as quickly as possible, as well as support if you get stuck. Let's jump right in!


Integrating Percy with your Cypress tests

Covered in this doc

Integrating Percy with your Cypress tests
Installing and importing @percy/cypress
Calling and configuring cy.percySnapshot()

percy-cypress on GitHub

Package Status CircleCI This project is using for visual regression testing.


If you're not ready to integrate Percy, check out our 2-minute Cypress testing tutorial and example app with Percy for Cypress already added.

Install @percy/cypress using npm:

npm install --save-dev @percy/cypress

Or using yarn:

yarn add --dev @percy/cypress

TypeScript typings

If you're using TypeScript, you'll additionally want to include "types": ["cypress", "@percy/cypress"] in your tsconfig.json file.

Step 1: In order to start creating snapshots from your Cypress tests, you'll need to import the @percy/cypress package. A good place to do this is your Cypress commands.js file:

// At the top of cypress/support/commands.js
import '@percy/cypress';

This will give you access to the Percy snapshot command in any of your Cypress tests, via cy.percySnapshot().

Step 2: Next, you will need to require the percyHealthCheck task in your Cypress projects cypress/plugins/index.js file:

// In cypress/plugins/index.js
let percyHealthCheck = require('@percy/cypress/task')

module.exports = (on, config) => {
  on("task", percyHealthCheck);

Only v2.x of the @percy/cypress SDK uses a task. You can safely ignore this step if you're not using 2.x.

Step 3: You can now incorporate visual tests in your existing suite:

describe('Integration test with visual testing', function() {
  it('Loads the homepage', function() {
    // Load the page or perform any other interactions with the app.
    cy.visit(<URL under test>);

    // Take a snapshot for visual diffing

Step 4: Finally, wrap your test runner command in the percy exec command. This will start a Percy agent to receive snapshots from your Cypress tests and upload them to your Percy dashboard.

Before you can successfully run Percy, the PERCY_TOKEN environment variable must be set:

# Windows
$ set PERCY_TOKEN=<your token here>

# Unix 
$ export PERCY_TOKEN=<your token here>

If you are running your tests with cypress run, your new test command becomes:

percy exec -- cypress run

Note the double dash, --, between percy exec and your test run command.

That's it! Now, whenever CI runs, a snapshot of the app in that state will be uploaded to Percy for visual regression testing!

For an example showing how to add Percy snapshots to an existing Cypress test suite, see


cy.percySnapshot(snapshotName, options);

snapshotName is an optional string that will be used as the snapshot name. If you don't provide one, Percy will automatically create a name based on the descriptive strings in your describe and it blocks. For more details on generating snapshot names, see Autogenerated snapshot names.

options is an optional hash that can include:

  • widths: An array of integers representing the browser widths at which you want to take snapshots.

  • minHeight: An integer specifying the minimum height of the resulting snapshot, in pixels. Defaults to 1024px.

  • percyCSS: A string containing Percy specific CSS that will be applied to this snapshot.

  • requestHeaders: An object containing HTTP headers to be sent for each request made during asset discovery for this snapshot.

For example:

cy.percySnapshot('Homepage test');
cy.percySnapshot('Homepage responsive test', { widths: [768, 992, 1200] });

Global configuration

You can also configure Percy to use the same options over all snapshots. To see supported configuration including widths read our Configuration doc.


Debugging in CI

Sometimes snapshots fail to be taken while running in CI and it's difficult to debug what's going on in a remote environment. In these cases, we have found the Cypress dashboard with video recording to be extremely helpful. This will allow you to watch your tests run within the browser on CI and see the log output on screen.

Once you sign up to Cypress and set your dashboard record key you can pass the --record flag to cypress run. You now will be able to watch the video of your tests run in CI. This will help surface errors that are happening within the browsers command log.

Failed to execute 'send' on 'XMLHttpRequest'

If you're seeing the following log in your Cypress test output:

Error: Failed to execute 'send' on 'XMLHttpRequest': Failed to load 'http://localhost:5338/percy/snapshot'.

This is due to Content Security Policy (CSP) errors that is preventing the Percy SDK from sending the snapshot to our service. Starting with @percy/cypress v1.0.4 this should no longer be an issue. If you're on an older version of @percy/cypress try upgrading first.

If the error still persists, you can disable the browsers web security in the cypress.json config file:

  "chromeWebSecurity": false

Once that is set, the error should disappear.

Freezing date/time

As an example, if you have a date picker that auto selects the current day, each time new day you run your tests, Percy is going to snapshot a different day selected. In order to overcome this issue you need to freeze time in Cypress. You can do so by adding the to your tests:

const now = new Date(2018, 1, 1);
cy.clock(now); // freezes the system time to Jan 1, 2018
// continue with your normal tests below

Missing assets from snapshots

If your snapshots end up missing any assets, its possible they were missed while we did asset discovery on the snapshot that was taken. This can happen for various reasons, usually due to network latency. To work around this, you can up the default asset discovery idle timeout (which is 50) by passing a -t flag via the CLI:

percy exec -t 350 -- [YOUR_COMMAND_HERE]

This will leave the network window open longer.

What's next

Once you've set up Percy for Cypress, the next step is to add Percy to your CI service. That way, every time CI runs, Percy will automatically kick off visual tests as well.

CI integration overview


Integrating Percy with your Cypress tests

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.