Wondering what’s next for npm?Check out our public roadmap! »

    TypeScript icon, indicating that this package has built-in type declarations

    3.1.0 • Public • Published


    Version Test

    Percy visual testing for Cypress.


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

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

    import '@percy/cypress'


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


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

    • name - The snapshot name; must be unique to each snapshot; defaults to the full test title
    • options - Additional snapshot options (overrides any project options)
      • options.widths - An array of widths to take screenshots at
      • options.minHeight - The minimum viewport height to take screenshots at
      • options.percyCSS - Percy specific CSS only applied in Percy's rendering environment
      • options.requestHeaders - Headers that should be used during asset discovery
      • options.enableJavaScript - Enable JavaScript in Percy's rendering environment


    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.


    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


    npm i @percy/cypress

    DownloadsWeekly Downloads






    Unpacked Size

    8.23 kB

    Total Files


    Last publish


    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar