Nightmare v1
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>)
These docs apply to version
1.0.0
or later. Previous versions of@percy/nightmare
are incompatible with what is described in this document.
Setup
If you're not ready to integrate Percy, check out our 2-minute Nightmare testing tutorial and example app with Percy for Nightmare already added.
Install @percy/nightmare
using npm
:
npm install --save-dev @percy/nightmare
Or using yarn
:
yarn add --dev @percy/nightmare
In order to start creating snapshots from your Nightmare tests, you'll need to import the percySnapshot()
function from the @percy/nightmare
package. You will need to do this in each test file from which you want to take snapshots:
const { percySnapshot } = require('@percy/nightmare')
You will then use percySnapshot(...)
inside a nightmare.use(...)
statement:
describe('Integration test with visual testing', function() {
it('Loads the homepage', function() {
nightmare
.goto(<URL under test>)
.use(percySnapshot('Homepage snapshot'))
// Any other test actions
.end()
})
})
Finally, wrap your test runner command 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>
For example, if you are using Mocha for your tests, your new test command becomes:
percy exec -- mocha
Note the double dash, --
, 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 Nightmare test suite, see https://github.com/percy/example-percy-nightmare/pull/6.
Configuration
percySnapshot(snapshotName)
percySnapshot(snapshotName, options)
snapshotName
is a required 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. 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.
For example:
percySnapshot('Homepage test');
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 SDK configuration docs
Updated almost 2 years ago