### [percy-cypress on GitHub <i class="fa fa-github" aria-hidden="true"></i>](🔗)

[](🔗)

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`:

Or using `yarn`:

# 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:

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:

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:

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

`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

# 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:

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](🔗):

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:

# 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!](🔗) 😄