Installation

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

Install @percy/protractor using npm:

npm install --save-dev @percy/protractor

Or using yarn:

yarn add --dev @percy/protractor

Quick Setup

These are the minimal steps required to add visual testing to your existing Protractor tests:

Import percySnapshot() into your test file: const { percySnapshot } = require("@percy/protractor")
Call percySnapshot(<snapshotName>) from your tests wherever you want to save a snapshot.
Wrap your test run command in percy exec --, e.g. percy exec -- protractor conf.js.

Next, we will go through each of these steps in detail.

Setup

In order to start creating snapshots from your Protractor tests, you'll need to import the percySnapshot() function from the @percy/protractor package. You will need to do this in each file from which you want to take snapshots:

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

You will then use percySnapshot(...) to generate a snapshot:

describe('Integration test with visual testing', function() {
  it('Loads the app', function() {
    browser.get('http://example.com')
    percySnapshot('My snapshot')
  })
})

Finally, wrap your script or 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. Your new test command becomes:

percy exec -- protractor conf.js

Note the double dash with spaces, --, between percy exec and your test run command.

That's it! Now, whenever CI runs, a snapshot of the app in that state will be uploaded to Percy for visual regression testing!

For an example showing how to add Percy snapshots to an existing Protractor test suite, see https://github.com/percy/example-percy-protractor/pull/4/files.

Usage

percySnapshot(snapshotName)
percySnapshot(snapshotName, options)

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.

🚧
percySnapshot(...) relies on the presence of the Protractor browser instance, and so can only be called within the context of a Protractor test. An exception will be thrown if the browser instance is not present.

Examples

percySnapshot('Homepage test');
percySnapshot('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 Configuration doc.

Contributing

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