Installation

📘
Make sure you have completed Setup of your CI service first. You can also test Percy in your local development environment.

Install @percy/cypress using npm:

npm install --save-dev @percy/cypress

Or using yarn:

yarn add --dev @percy/cypress

Quick Setup

These are the minimal steps required to add visual testing to your existing Cypress tests:

Add import @percy/cypress at the top of your cypress/support/commands.js file
Call cy.percySnapshot() from your tests wherever you want to save a snapshot.
Wrap your test run command in percy exec --, e.g. percy exec -- cypress run.

Next, we will go through each of these steps in detail.

Setup

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(). 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
    cy.percySnapshot();
  });
});

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. 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 https://github.com/percy/example-percy-cypress/pull/6

Usage

cy.percySnapshot();
cy.percySnapshot(snapshotName);
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.

Examples

cy.percySnapshot();
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.

Troubleshooting

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. To work around this issue you can disable the browsers web security in the cypress.json config file:

{
  "chromeWebSecurity": false
}

Once that is set, that 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

Contributing

Fork it ( https://github.com/percy/percy-cypress/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new pull request

Throw a ★ on it! 😄