Cypress

👍

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 3.0.0 or later. Previous versions of @percy/cypress are incompatible with what is described in this document. v2 docs can be found here

Install @percy/cypress and @percy/cli:

$ npm install --save-dev @percy/cli @percy/cypress

In order to add Percy snapshots to your Cypress tests, you'll need to first import the @percy/cypress package into your cypress/support/index.js file:

import '@percy/cypress';

📘

TypeScript typings

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

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 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!

Configuration

cy.percySnapshot([name][, options])

• name - The snapshot name; must be unique to each snapshot; defaults to the test title
• options - See per-snapshot configuration options

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

Upgrading from v2

Automatically with @percy/migrate

We built a tool to help automate migrating to the new CLI toolchain! Migrating can be done by running the following commands and following the prompts:

$ npx @percy/migrate
? Are you currently using @percy/cypress? Yes
? Install @percy/cli (required to run percy)? Yes
? Migrate Percy config file? Yes
? Upgrade SDK to @percy/[email protected]? Yes

This will automatically run the changes described below for you.

Manually

Installing @percy/cli

If you're coming from a pre-3.0 version of this package, make sure to install @percy/cli after upgrading to retain any existing scripts that reference the Percy CLI command.

$ npm install --save-dev @percy/cli

Removing tasks

If you're coming from 2.x the health check task, @percy/cypress/task, is no longer needed and no longer exists. You should remove this task from your cypress/plugins/index.js file.

Migrating Config

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

$ percy config:migrate

Component Testing

Percy supports Cypress Component Testing out of the box.

Just use the normal SDK above and include a cy.percySnapshot line at the end of the component test.

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, 0, 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.