Sign in or start for free
Hey! These docs are for version 1, which is no longer officially supported. Click here for the latest version, 2-web!

### [percy-nightwatch on GitHub <i class="fa fa-github" aria-hidden="true"></i>](🔗)

[![Package Status](https://img.shields.io/npm/v/@percy/nightwatch.svg)](🔗)

Visual regression testing for [Nightwatch](🔗) tests with Percy.

# Installation



Make sure you have completed [Setup](🔗) of your CI service first. You can also test Percy in your [local development](🔗) environment.

Install `@percy/nightwatch` using `npm`:


# Quick Setup
These are the minimal steps required to add visual testing to your existing Nightwatch tests:
  1. Add the path to the `percySnapshot` command to the `custom_commands_path` array in your Nightwatch configuration:  `const percy = require('@percy/nightwatch)` and `custom_commands_path: [ percy.path ]`.
  2. Call `browser.percySnapshot()` from your tests wherever you want to save a snapshot.
  3. Wrap your test run command in `percy exec --`, e.g.  `percy exec -- nightwatch`.  
Next, we will go through each of these steps in detail.
# Setup
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`):

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

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. Your new test command becomes:

Note the double dash with spaces, `--`, between `percy exec` and your test run command.
That's it! Now, whenever CI runs, 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.
# Usage

`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.

`browser` is the Nightwatch browser instance that is passed into your tests.
## Examples

# 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](🔗).
# Contributing
  1. Fork it ( https://github.com/percy/percy-nightwatch/fork )
  2. Create your feature branch (`git checkout -b my-new-feature`)
  3. Commit your changes (`git commit -am 'Add some feature'`)
  4. Push to the branch (`git push origin my-new-feature`)
  5. Create a new pull request
[Throw a ★ on it!](🔗) 😄