@percy/cypress

Percy visual testing for Cypress.

Installation

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

Then add to your cypress/support/index.js file

import '@percy/cypress'

Usage

This is an example using the cy.percySnapshot command.

describe('My app', () => {
  it('should look good', () => {
    cy.get('body').should('have.class', 'finished-loading');
    cy.percySnapshot();

    cy.get('button').click();
    cy.percySnapshot('Clicked button');
  });
});

Running the test above will result in the following log:

$ cypress run
...
[percy] Percy is not running, disabling snapshots

When running with percy exec, and your project's PERCY_TOKEN, a new Percy build will be created and snapshots will be uploaded to your project.

$ export PERCY_TOKEN=[your-project-token]
$ percy exec -- cypress run
[percy] Percy has started!
[percy] Created build #1: https://percy.io/[your-project]
[percy] Running "cypress run"
...
[percy] Snapshot taken "My app should look good"
[percy] Snapshot taken "Clicked button"
...
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!

Configuration

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

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

Advanced Options

Percy Cypress now supports comprehensive snapshot options including:

• Minimum Height: minHeight: 2000 - Set minimum snapshot height for tall pages
• Animation Freezing: Use percyCSS to freeze animations - percyCSS: 'img { animation: none !important; }'
• Custom CSS: percyCSS - Inject temporary CSS before snapshot
• Sync Results: sync: true - Get processed results synchronously
• Cookie Capture: Automatically captures cookies for accurate session reproduction

Cypress Config

• percyThrowErrorOnFailure - If set to true, it will throw an error when one is encountered. By default, it is set to false, and errors are suppressed. If you are using uncaught exeception then test test will pass.

cy.on("uncaught:exception", (e, runnable) => {});

Upgrading

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/cypress@3.0.0? 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