Percy Developer Hub

Welcome to the Percy Developer Hub. You'll find comprehensive guides and documentation to help you start working with Percy as quickly as possible, as well as support if you get stuck. Let's jump right in!

WebdriverIO

Adding visual testing to your WebdriverIO tests

👍

Covered in this doc

Integrating Percy with your WebdriverIO tests
Installing and importing percySnapshot()
Calling and configuring percySnapshot(browser, <snapshotName>, <options>)

Package StatusPackage Status Build StatusBuild Status This project is using Percy.io for visual regression testing.This project is using Percy.io for visual regression testing.

🚧

This documentation is for @percy/webdriverio version 1.0.0 or above, and is not compatible with older versions. If you're already using Percy for WebdriverIO, see our docs to upgrade to our newest version.

Installation


Install @percy/webdriverio using npm:

npm install --save-dev @percy/webdriverio

Or using yarn:

yarn add --dev @percy/webdriverio

Next, import the percySnapshot() function into the test files where you'll want to use it:

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

If you'll be using Percy in many of your test files, you might consider requiring Percy as part of your WebdriverIO wdio.conf.js configuration. The before hook is a good place for that, where you can do something like:

// In your wdio.conf.js
before: function (capabilities, specs) {
  // Import percySnapshot function
  const { percySnapshot } = require('@percy/webdriverio');
  // Make percySnapshot available as a global variable in all wdio tests
  global.percySnapshot = percySnapshot;
}
For more details on the hooks and options available in `wdio.conf.js`, see: https://webdriver.io/docs/configurationfile.html

Now you can use `percySnapshot(...)` to generate a snapshot for visual testing at any point in your tests:
describe('Integration test with visual testing', function() {
  it('Loads the example.com site', async function() {
    await browser.url('https://example.com/')
    await percySnapshot(browser, this.test.fullTitle())
  })
})

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>

Your new test command becomes:

percy exec -- wdio wdio.conf.js

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(browser, snapshotName)
percySnapshot(browser, snapshotName, options)

browser is the WebdriverIO Browser object representing the web page and state 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.

  • 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.

Examples

percySnapshot(browser, 'Homepage test');
percySnapshot(browser, '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 6 months ago


What's next

Once you've set up Percy for WebdriverIO, the next step is to add Percy to your CI service. That way, every time CI runs, Percy will automatically kick off visual tests as well.

CI integration overview

WebdriverIO


Adding visual testing to your WebdriverIO tests

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.