percy-webdriverio on GitHub

This adds Percy visual testing and review to your WebdriverIO tests.

Beta release. Percy for WebdriverIO is in beta. It may change in backwards-incompatible ways until v1.0.0 is released.

Getting Started

📘
Make sure you have completed Setup of your CI service first. You can also test Percy in your local development environment.

Install @percy-io/percy-webdriverio using npm:

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

Or using yarn:

yarn add --dev @percy-io/percy-webdriverio

Next, update your wdio.conf.js:

  // At the top of the file
  var percy = require('@percy-io/percy-webdriverio');

  // In the plugins section, add the percy-webdriverio plugin.
  plugins: {
    '@percy-io/percy-webdriverio': {}
  },

  // Before your tests run, instruct Percy on where to find and mount your assets,
  // and create the build that snapshots will be added to.
  onPrepare: function (config, capabilities) {
    var assetLoaders = [percy.assetLoader('filesystem', { buildDir: 'compiled-assets-dir', mountPath: '/assets' })];
    return percy.createBuild(assetLoaders);
  },

  // After your tests have completed, finalize the build.
  onComplete: function(exitCode) {
    return percy.finalizeBuild();
  },

The asset loader instructs Percy where to find your compiled assets in your filesystem, and where to make them available. Configurable options:

buildDir: absolute path to your compiled static assets (not source assets).
mountPath: path prefix to where your webserver serves the assets (ex: /assets)

Percy requires the asset loader to be configured correctly so it can quickly find your CSS, images, fonts and other assets required for taking screenshots. If it's misconfigured, you may see screenshots that are missing styles and images.

Usage

You're now ready to start taking snapshots with percySnapshot in your tests:

describe('Homepage', function() {
  it('looks very nice', function () {
    browser.url('http://localhost:3000');
    browser.percySnapshot('Homepage');
  });
});

You can provide several options to percySnapshot:

browser.percySnapshot('name', { widths: [640, 800], enableJavaScript: true, minimumHeight: 400 });

widths: An array of widths to take screenshots at.
enableJavaScript: Boolean that instructs Percy whether to run javascript when rendering the page.
minimumHeight: Adjust the minimum height of your snapshots. The default is 1024px.

You can take multiple snapshots in the same test:

describe('Homepage', function() {
  it('button is clickable', function () {
    browser.url('http://localhost:3000');
    browser.percySnapshot('Homepage');

    browser.click('#myButton');
    browser.percySnapshot('Homepage button is clicked');
  });
});

Ready to go

That's all there is to it. Run wdio, and Percy will take your snapshots and prepare your visual review for you.

Whether running in your CI service or locally, it will take the snapshots as long as you've supplied the PERCY_TOKEN and PERCY_PROJECTenvironment variables.

Freezing time and dynamic data

As you start to introduce visual testing into your workflow, you might find that the passing of time or generated data from tools like faker can cause visual diffs.

It's fairly easy to stabilize these diffs. Tools like faker often allow you to provide a seed to ensure that the same data is generated each time faker is run. Libraries like MockDate allow you to override the current date, eliminating variations due to the screenshots being taking at a different date and time. If you use Math.random, you can seed it with seedrandom.

Source code integration

Percy automatically integrates with your source code so you can do visual reviews with each commit or pull request. See our source code integration docs for more info.

Contributing

Fork it ( https://github.com/percy/percy-webdriverio/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

Throw a ★ on it!