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>)
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
Installation
$ 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],
// ...
};
Usage
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) {
browser
.url('http://example.com')
.assert.containsText('h1', 'Example Domain')
.percySnapshot('Example snapshot');
browser
.url('http://google.com')
.assert.elementPresent('img[alt="Google"]')
.percySnapshot('Google homepage');
browser.end();
}
};
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: https://percy.io/[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: https://percy.io/[your-project]
[percy] Done!
Configuration
percySnapshot([name][, options])
name
- The snapshot name; must be unique to each snapshotoptions
- See per-snapshot configuration 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
Upgrading
Automatically with @percy/migrate
@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.
Manually
Installing @percy/cli
@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 over 1 year ago
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.