Puppeteer
Integrating Percy with your Puppeteer setup
Visual regression testing for Puppeteer 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/puppeteer
using npm
:
npm install --save-dev @percy/puppeteer
Or using yarn
:
yarn add --dev @percy/puppeteer
These docs apply to version
1.0.0
or later. Previous versions of@percy/puppeteer
are incompatible with what is described in this document.
Quick Setup
These are the minimal steps required to add visual testing to your existing Puppeteer code:
- Import
percySnapshot()
into your file:const { percySnapshot } = require('@percy/puppeteer')
- Call
percySnapshot(page, <snapshotName>)
wherever you want to save a snapshot. - Wrap your script or test run command in
percy exec --
, e.g.percy exec -- mocha
.
Next, we will go through each of these steps in detail.
Setup
In order to start creating snapshots from your Puppeteer scripts or tests, you'll need to import the percySnapshot()
function from the @percy/puppeteer
package. You will need to do this in each file from which you want to take snapshots:
const { percySnapshot } = require('@percy/puppeteer')
You will then use percySnapshot(...)
to generate a snapshot:
describe('Integration test with visual testing', function() {
it('Loads the homepage', async function() {
const browser = await puppeteer.launch()
const page = await browser.newPage()
await page.goto(TEST_URL)
await percySnapshot(page, this.test.fullTitle())
})
})
Finally, wrap your script or 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. 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 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 Puppeteer test suite, see https://github.com/percy/example-percy-puppeteer/pull/4.
Usage
percySnapshot(page, snapshotName)
percySnapshot(page, snapshotName, options)
page
is the Puppeteer Page object that you want to snapshot. Required.
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.
Examples
percySnapshot(page, 'Homepage test');
percySnapshot(page, '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.
Contributing
- Fork it ( https://github.com/percy/percy-puppeteer/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new pull request
Updated over 4 years ago