https://github.com/percy/percy-cypress
Visual testing with Cypress and Percy
https://github.com/percy/percy-cypress
cypress percy percy-sdk visual-regression-testing visual-testing visual-tests
Last synced: 2 months ago
JSON representation
Visual testing with Cypress and Percy
- Host: GitHub
- URL: https://github.com/percy/percy-cypress
- Owner: percy
- License: mit
- Created: 2018-09-24T23:36:13.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-03-17T13:29:19.000Z (3 months ago)
- Last Synced: 2025-03-19T03:33:34.894Z (3 months ago)
- Topics: cypress, percy, percy-sdk, visual-regression-testing, visual-testing, visual-tests
- Language: JavaScript
- Homepage: https://percy.io
- Size: 1.87 MB
- Stars: 347
- Watchers: 13
- Forks: 42
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# @percy/cypress
[](https://npmjs.org/package/@percy/cypress)
[Percy](https://percy.io) visual testing for [Cypress](https://cypress.io).
## Installation
```sh-session
$ npm install --save-dev @percy/cli @percy/cypress
```
Then add to your `cypress/support/index.js` file
```javascript
import '@percy/cypress'
```
## Usage
This is an example using the `cy.percySnapshot` command.
```javascript
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:
```sh-session
$ cypress run
...
[percy] Percy is not running, disabling snapshots
```
When running with [`percy
exec`](https://github.com/percy/cli/tree/master/packages/cli-exec#percy-exec), and your project's
`PERCY_TOKEN`, a new Percy build will be created and snapshots will be uploaded to your project.
```sh-session
$ 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](https://www.browserstack.com/docs/percy/take-percy-snapshots/overview#per-snapshot-configuration)
## 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:
``` shell
$ 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.
```sh-session
$ 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`](https://github.com/percy/cli/tree/master/packages/cli-config#percy-configmigrate-filepath-output) command:
```sh-session
$ percy config:migrate
```