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!

Cypress

Integrating Percy with your Cypress tests

percy-cypress on GitHub

Package Status

Visual regression testing for Cypress tests with Percy.

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:

  1. Add import @percy/cypress at the top of your cypress/support/commands.js file
  2. Call cy.percySnapshot() from your tests wherever you want to save a snapshot.
  3. 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

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

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

Throw a ★ on it! 😄