PercyScript tutorial

👍

Covered in this doc

• Getting started with PercyScript and an example app
• Making some changes and reviewing them in Percy

❗️

Deprecated SDK

This SDK is deprecated -- please use the Percy CLI Snapshot command instead

The tutorial walks you through your first visual tests using Percy and PercyScript.

The tutorial assumes you have Node.js and git installed.

Step 1: Clone the example application and install dependencies:

$ git clone https://github.com/percy/example-percyscript.git
$ cd example-percyscript
$ npm install

The example app will now be ready to go. To see and explore the example app, run:

$ open index.html

This tutorial uses a PercyScript that is already written—you can see it in the snapshots.js file.

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 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), and run the script to take snapshots:

$ git checkout -b tutorial-example
$ npm run snapshots

This will run snapshots.js, which contains our PercyScript, will upload DOM snapshots, and render screenshots. Percy will use the token you used in Step 2 to know which organization and project to send renderings to.

You can view the screenshots in Percy, but there will be no visual comparisons yet since it is your first build. 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.html and introduce some visual change. For example, you can add a <strong> tag to the "Active" button on line 25. After the change, that line looks like this:

<a href="#/active"><strong>Active</strong></a>

Step 7: Commit the change:

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

Step 8: Run the snapshots again:

$ npm run snapshots

This will take snapshots of our modified application, render new screenshots to compare against previously rendered screenshots, and detect visual changes between the two.

At the end of the run output, you will see logs from Percy confirming that the screenshots were successfully rendered and giving you a direct URL to check out the visual changes.

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. Individual screenshots are grouped into snapshots for each page. By default, Percy renders screenshots at 375px and 1280, and across both Firefox and Chrome. You can see the baseline 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 snapshots were affected 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, if you like. If you do, re-run the snapshots script, and then you'll see any visual changes reflected in Percy.