Integrating Percy with your Nightmare tests


Covered in this doc

  • Visual regression testing for Nightmare
  • Installing and importing @percy/nightmare
  • Calling and configuring percySnapshot(<snapshotName>, <options>)

Package Status Test


These docs apply to version v2.0.0 or later. Previous versions of @percy/nightmare are incompatible with what is described in this document. v1.x docs can be found here


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


This is an example using the percySnapshot function.

const Nightmare = require('nightmare');
const percySnapshot = require('@percy/nightmare);

  //... other actions ...
  .use(percySnapshot('Example Snapshot'))
  //... more actions ...
  .then(() => {
    // ...

Running the code above directly will result in the following logs:

$ node script.js
[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 -- node script.js
[percy] Percy has started!
[percy] Created build #1:[your-project]
[percy] Running "node script.js"
[percy] Snapshot taken "Example Snapshot"
[percy] Stopping percy...
[percy] Finalized build #1:[your-project]
[percy] Done!


percySnapshot(name[, options])

Global configuration

You can also configure Percy to use the same options over all snapshots. To see supported configuration including widths read our SDK configuration docs


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/nightmare? 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.


Installing @percy/cli

If you're coming from a pre-2.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

Import change

If you're coming from a pre-2.0 version of this package, the percySnapshot function is now the default export.

// before
const { percySnapshot } = require('@percy/nightmare');

// after
const percySnapshot = require('@percy/nightmare');

Migrating Config

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

$ percy config:migrate

What's next

Once you've set up Percy for Nightmare, the next step is to add Percy to your CI service. That way, every time CI runs, Percy will automatically kick off visual tests as well.