Percy Developer Hub

Welcome to the Percy Developer Hub. You'll find comprehensive guides and documentation to help you start working with Percy as quickly as possible, as well as support if you get stuck. Let's jump right in!


Integrating Percy with your Nightwatch tests


Covered in this doc

Visual regression testing for Nightwatch
Installing @percy/nightwatch
Configuring and calling browser.percySnapshot(<snapshotName>, <options>)

Package StatusPackage Status TestTest


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


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

Nightwatch configuration

Add the path exported by @percy/nightwatch to your Nightwatch configuration's custom_commands_path property.

const percy = require('@percy/nightwatch');

module.exports = {
  // ...
  custom_commands_path: [percy.path],
  // ...


This is an example test using the browser.percySnapshot() command. For other examples of how to write Nightwatch tests, check out the official Nightwatch guides.

module.exports = {
  'Snapshots pages': function(browser) {
      .assert.containsText('h1', 'Example Domain')
      .percySnapshot('Example snapshot');
      .percySnapshot('Google homepage');

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

$ nightwatch

[Example] Test Suite

Running:  Snapshots pages

āœ” Testing if element <h1> contains text 'Example Domain'
[percy] Percy is not running, disabling snapshots
āœ” Testing if element <img[alt="Google"]> is present

OK. 2 assertions passed.

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 -- nightwatch
[percy] Percy has started!
[percy] Created build #1:[your-project]
[percy] Running "nightwatch"

[Example] Test Suite

Running:  Snapshots pages

āœ” Testing if element <h1> contains text 'Example Domain'
[percy] Snapshot taken "Snapshots pages"
āœ” Testing if element <img[alt="Google"]> is present
[percy] Snapshot taken "Google homepage"

OK. 2 assertions passed.
[percy] Stopping percy...
[percy] Finalized build #1:[your-project]
[percy] Done!


percySnapshot([name][, options])

  • name - The snapshot name; must be unique to each snapshot
  • 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/nightwatch? 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

Migrating Config

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

$ percy config:migrate

Updated about a month ago

What's next

Once you've set up Percy for Nightwatch, 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.

CI integration overview


Integrating Percy with your Nightwatch tests

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.