Upgrading to Percy WebdriverIO v1
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
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 theplugins
section. - Remove any calls to
percy.createBuild(...)
andpercy.finalizeBuild(...)
. - Remove any references to
percy.assetLoader(...)
.
2. Replace browser.percySnapshot
with percySnapshot
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 --
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
.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.
Updated over 3 years ago