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!

Nightwatch

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>)

percy-nightwatch on GitHub

Package Status CircleCI This project is using Percy.io for visual regression testing.

Setup


If you're not ready to integrate Percy, check out our 2-minute Nightwatch tutorial and example app with Percy for Nightwatch already added.

Install @percy/nightwatch using npm:

npm install --save-dev @percy/nightwatch

In order to start creating snapshots from your Nightwatch tests, you'll need to add the custom percySnapshot() command to your Nightwatch configuration.

To do that, add the path to your @percy/nightwatch installation to the custom_commands_path array in your Nightwatch configuration. @percy/nightwatch provides a path property that you can use for this.

In your Nightwatch configuration (typically nightwatch.conf.js or nightwatch.json):

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

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

You can now use browser.percySnapshot() to generate a snapshot:

'Loads the app': function(browser) {
  browser
    .url('http://example.com')
    .percySnapshot()
    .end()
},

Finally, wrap your test runner in the percy exec command. This will start a Percy agent to receive snapshots from your tests and upload them to your Percy dashboard.

Before you can successfully run Percy, the PERCY_TOKEN environment variable must be set:

# Windows
$ set PERCY_TOKEN=<your token here>

# Unix 
$ export PERCY_TOKEN=<your token here>

Your new test command becomes:

percy exec -- nightwatch

Note the double dash with spaces, --, between percy exec and your test run command.

That's it! Now, whenever your tests run with the Percy command, 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 Nightwatch test suite, see https://github.com/percy/example-percy-nightwatch/pull/3/files.

Configuration


browser.percySnapshot()
browser.percySnapshot(snapshotName)
browser.percySnapshot(snapshotName, options)

snapshotName is a string that will be used as the snapshot name. It can be any string that makes sense to you to identify the page state. It should be unique and remain the same across builds. If not provided, Percy will use the name of the currently executing test. 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.

  • percyCSS: A string containing Percy specific CSS that will be applied to this snapshot.

  • requestHeaders: An object containing HTTP headers to be sent for each request made during asset discovery for this snapshot.

browser is the Nightwatch browser instance that is passed into your tests.

For example:

browser.percySnapshot();
browser.percySnapshot('Homepage test');
browser.percySnapshot('Homepage responsive test', { widths: [768, 992, 1200] });

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.


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

Nightwatch


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.