Cypress v2

👍

Covered in this doc

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

percy-cypress on GitHub

Setup

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.

📘

These docs apply to version 2.x. Other versions of @percy/cypress are incompatible with what is described in this document.

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 add Percy snapshots to 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
    cy.percySnapshot();
  });
});

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 rendered screenshots 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, screenshots of the app in that state at each responsive width and browser will be uploaded to Percy!

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

Configuration

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.

• 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();
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 SDK configuration docs

Troubleshooting

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.

Waiting for elements

It's important that you capture the percySnapshot at the correct time during your Cypress tests, to help make sure the snapshot is captured at the right time when the DOM has stabilized and assets are fully loaded.

Cypress has sophisticated internal waiting logic, which is triggered when interacting with elements. You can use normal Cypress assertions to naturally wait for elements to load, as well as for functional testing of your application.

For example:

// This will naturally wait for the element to fully load.
cy.get('.login-panel').should('be.visible')

cy.percySnapshot();

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 following to your tests:

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

Missing assets

If your screenshots 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.