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 tutorial


Covered in this doc

Cloning an example JavaScript application tested with Protractor
Making some changes and seeing the snapshots and visual diffs in Percy

The tutorial assumes you're already familiar with JavaScript and Protractor and focuses on using it with Percy. You'll still be able to follow along if you're not familiar with Protractor, but we won't spend time introducing Protractor concepts.

The tutorial also assumes you have node with npm and git installed.

Step 1: Clone the example application and install dependencies:

$ git clone [email protected]:percy/example-percy-protractor.git
$ cd example-percy-protractor
$ npm install

The example app and its tests will now be ready to go. You can explore the app by opening the index.html file in a browser. This tutorial used an app with Protractor tests and Percy already added‚ÄĒsee how we¬†added Percy to the example Protactor tests.

Step 2: Sign in to Percy, create a new organization, and create a new project. You can name both the organization and project 'todo'.

After you've created the project, you'll be shown a token environment variable.

Step 3: In the shell window you're working in, export the token environment variable:

# Windows
$ set PERCY_TOKEN=<your token here>

# Unix 
$ export PERCY_TOKEN=<your token here>

Note: Usually this would only be set up in your CI environment, but to keep things simple we'll configure it in your shell so that Percy is enabled in your local environment.

Step 4: Check out a new branch for your work in this tutorial (we'll call this branch tutorial-example) run tests and take snapshots:

$ git checkout -b tutorial-example
$ npm test

This will run the app's tests, which contain calls to create and upload Percy snapshots. The snapshots will then be uploaded to Percy for comparison. Percy will use the Percy token you used in Step 2 to know which organization and project to upload the snapshots to.

You can view the screenshots in Percy now if you want, but there will be no visual comparisons yet. You'll see that Percy shows you that these snapshots come from your tutorial-example branch.

Step 5: Use your text editor to edit index.css and introduce some visual change. For example, you can add a font-weight: 900; to the .clear-completed class that styles the "Clear completed" button, on lines 305 to 312 of index.css. After that change, this CSS class looks like:

html .clear-completed:active {
        float: right;
        position: relative;
        line-height: 20px;
        text-decoration: none;
        cursor: pointer;
        font-weight: 900;

Step 7: Commit the change:

$ git add . && git commit -m "Emphasize 'Clear completed' button"

Step 8: Run the tests with snapshots again:

$ npm test

This will run the tests again, and take new snapshots of our modified application. The new snapshots will be uploaded to Percy and compared with the previous snapshots, showing any visual diffs.

At the end of the test run output, you will see logs from Percy confirming that the snapshots were successfully uploaded and giving you a direct URL to check out any visual diffs.

Step 9: Visit your project in Percy and you'll see a new build with the visual comparisons between the two runs. Click anywhere on the Build 2 row. You can see the original snapshots on the left and the new snapshots on the right.

Percy has highlighted what's changed visually in the app! Snapshots with the largest changes are shown first You can click on the highlight to reveal the underlying screenshot.

If you scroll down, you'll see that no other test cases were impacted by our changes to the 'Clear completed' button. The unchanged snapshots appear grouped together at the bottom of the list.

Finished! ūüėÄ

From here, you can try making your own changes to the app and tests, if you like. If you do, re-run the tests, and then you'll see any visual changes reflected in Percy.

Updated about a year ago

What's next

This tutorial used an app with Protractor tests and Percy already added‚ÄĒyou can see the example app on GitHub and to learn how to add Percy to your own Protractor tests.


Protractor tutorial

Suggested Edits are limited on API Reference Pages

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