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!

Protractor

Integrating Percy with your Protractor tests

👍

Covered in this doc

Visual regression testing for Protractor
Installing @percy/protractor
Adding and calling percySnapshot(<snapshotName>, <options>)

📘

These docs are for version 2.x of @percy/protractor. If you're looking for 1.x documentation, see these docs

Package StatusPackage Status TestTest

Installation

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

$ npm install --save-dev @percy/cli @percy/protractor

Usage

This is an example using the percySnapshot() function using async/await.

import percySnapshot from '@percy/protractor';

describe('angularjs homepage', function() {
  it('should greet the named user', async function() {
    await browser.get('http://www.angularjs.org');
    await percySnapshot('AngularJS homepage');

    await element(by.model('yourName')).sendKeys('Percy');
    var greeting = element(by.binding('yourName'));
    expect(await greeting.getText()).toEqual('Hello Percy!');

    await percySnapshot('AngularJS homepage greeting');
  });
});

Running the test above will result in the following log:

$ protractor conf.js
...

[percy] Percy is not running, disabling snapshots
  ✓ angularjs homepage should greet the named user

  1 passing (1s)

When running with percy exec, and your project's PERCY_TOKEN, a new Percy build will be created and snapshots will be uploaded to your project.

$ export PERCY_TOKEN=[your-project-token]
$ percy exec -- protractor conf.js
[percy] Percy has started!
[percy] Created build #1: https://percy.io/[your-project]
[percy] Running "protractor conf.js"
...

[percy] Snapshot taken "AngularJS homepage"
[percy] Snapshot taken "AngularJS homepage greeting"
  ✓ angularjs homepage should greet the named user

  1 passing (1s)

...
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/[your-project]
[percy] Done!

🚧

Make sure Control Flow is disabled

Our SDK is written using async / await. You will need to disable the WebDriver Control Flow for reliable results. See this issue for more information

Configuration

percySnapshot(name[, options])
percySnapshot(browser, name[, options]) (standalone mode only)

  • browser (required) - The Protractor browser object
  • name (required) - The snapshot name; must be unique to each snapshot
  • options - Additional snapshot options (overrides any project options)
    • options.widths - An array of widths to take screenshots at
    • options.minHeight - The minimum viewport height to take screenshots at
    • options.percyCSS - Percy specific CSS only applied in Percy's rendering environment
    • options.requestHeaders - Headers that should be used during asset discovery
    • options.enableJavaScript - Enable JavaScript in Percy's rendering environment

Upgrading

Automatically with @percy/migrate

We built a tool 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/protractor? 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

If you're coming from a pre-2.0 version of this package, the percySnapshot function is now the default
export.

// before
const { percySnapshot } = require('@percy/protractor');

// after
const percySnapshot = require('@percy/protractor');

Migrating Config

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

$ percy config:migrate

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 about a month ago


What's next

Once you've set up Percy for Protractor, 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

Protractor


Integrating Percy with your Protractor tests

Suggested Edits are limited on API Reference Pages

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