Puppeteer

👍

Covered in this doc

• Integrating Percy with your Puppeteer tests
• Installing and importing percySnapshot()
• Calling and configuring percySnapshot(page, name, options)
• Upgrading from v1

percy-puppeteer on GitHub

Setup

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

📘

These docs apply to version v2.0.0 or later. Previous versions of @percy/puppeteer are incompatible with what is described in this document. v1.x docs can be found here

Install @percy/puppeteer and @percy/cli using npm:

npm install --save-dev @percy/cli @percy/puppeteer

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.

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

# Windows
$ set PERCY_TOKEN=<your token here>

# PowerShell
$ $Env: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!

Configuration

percySnapshot(page, name[, options])

• page (required) - A puppeteer page instance
• name (required) - The snapshot name; must be unique to each snapshot
• options - See per-snapshot configuration options

For example:

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 SDK configuration docs

Upgrading from v1

Automatically with @percy/migrate

We built a package 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/puppeteer? 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

Import change

In v1.x there wasn't a default export of the package (only a named export). With v2.x the named export is removed and there is only a default export.

// old
import { percySnapshot } from '@percy/puppeteer';
const { percySnapshot } = require('@percy/puppeteer');

// new
import percySnapshot from '@percy/puppeteer';
const percySnapshot = require('@percy/puppeteer');

Migrating Config

If you have a previous Percy configuration file, migrate it to the newest version with the config:migrate command:

$ percy config:migrate