@percy/percy-webdriverio on GitHub

Percy WebdriverIO version 1 introduces improvements to snapshotting, and simplifies using Percy in your WebdriverIO tests. This document walks you through the steps you'll need to follow to migrate from older versions to Percy WebdriverIO version 1.

If you're new to Percy WebdriverIO, and are looking to integrate it into your tests for the first time, please refer to the WebdriverIO documentation instead.

What's new in version 1

Percy WebdriverIO version 1 is based on the Percy agent. The agent is a process that runs alongside your tests, creating snapshots and uploading them to Percy on your behalf.

The agent understands how to snapshot complex modern web pages out of the box, without requiring you to use custom loaders. It also processes and uploads the snapshots to Percy for you, outside of your test process.

Migration steps

v1 introduces a simpler API for snapshotting, so most of the migration work is removing most references to Percy, and renaming the snapshot call.

Installation

Update to the newer @percy/percy-webdriverio package (which replaces the old @percy-io/percy-webdriverio):

npm install --save-dev @percy/percy-webdriverio

Or using yarn:

yarn add --dev @percy/percy-webdriverio

Updating your code

1. Update your wdio.conf.js

The Percy snapshot function is no longer provided as a custom WebdriverIO command, so you need to remove all references to Percy in your wdio.conf.js. In particular, remember to:

• Remove any references to @percy-io/percy-webdriverio in the plugins section.
• Remove any calls to percy.createBuild(...) and percy.finalizeBuild(...).
• Remove any references to percy.assetLoader(...).

2. Replace browser.percySnapshot with percySnapshot

First, import the new percySnapshot(...) function wherever you want to use it:

const { percySnapshot } = require('@percy/percy-webdriverio')

(If you are going to be doing this in many of your files, you might want to import percySnapshot in wdio.conf.js, in the before or onPrepare hooks, and make percySnapshot globally available from there.)

Then replace any existing calls to browser.percySnapshot(<title>, <options>) with percySnapshot(browser, <title>, <options>). You can leave the title and options parameters unchanged. For example:

// Old
browser.percySnapshot('My homepage snapshot', { widths: [640, 800] })
// New
percySnapshot(browser, 'My homepage snapshot', { widths: [640, 800] })

3. Wrap your test runner in percy exec --

You can still run your tests in the usual way, with wdio wdio.conf.js, but if you want snapshots to be taken and uploaded to Percy, you'll need to wrap this test runner command in percy exec -- :

percy exec -- wdio wdio.conf.js

4. (Optional) Add any global config to .percy.yml

With this new version, you can set default snapshot configuration parameters (such as widths or minimum height) in a .percy.yml file. See the Configuration documentation for all the available options.

More resources

You can learn more detailed usage information on @percy/percy-webdriverio in the WebdriverIO docs.