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!


Covered in this doc

Getting started with visual testing and PercyScript
Interacting with pages
Other Percy SDKs and ways to integrate

PercyScript is the easiest way to get started with visual testing and Percy.

With Percy, you can add visual testing to virtually anything that runs in a browser. PercyScript provides a drop-in way to start doing visual testing in just a couple of lines of JavaScript.


1 minute setup

Step 1: Install @percy/script:

$ npm install -D @percy/script

This will add @percy/script to your package.json file. Note: if your project doesn't have a package.json file, you will need to create one by running npm init.

Step 2: Create a file named snapshots.js and add the following:

const PercyScript = require('@percy/script'); (page, percySnapshot) => {
  await page.goto('http://localhost:8080/');
  await percySnapshot('homepage');

Replace localhost:8080 with the localhost and port for your application. Your application will need to be up and running locally before you continue. PercyScript can also be used to test live URLs.

Step 3: Run your PercyScript:

Copy the PERCY_TOKEN from your project, and then run:

$ export PERCY_TOKEN=aaabbbcccdddeee # Replace this with your project token
$ npx percy exec -- node snapshots.js

Remember to replace the PERCY_TOKEN with the token from your Percy project.

That's it!

You will see a URL to a Percy build, which will show you all of your snapshots and visual tests.

Next up:

Interacting with elements[, options])

You can use the method to click on elements, allowing you do to visually test more complex parts of your application.

const PercyScript = require('@percy/script'); (page, percySnapshot) => {
  await page.goto('http://localhost:8080/index.html');
  await percySnapshot('homepage');

  await percySnapshot('homepage signup modal');

The method fetches an element with any CSS selector and clicks on the center of the element. If there's no element matching selector, the method throws an error.

See the full documentation.


Use the page.type method to type into input boxes or text areas.

page.type('#mytextarea', 'Hello'); // Types instantly
page.type('#mytextarea', 'World', {delay: 100}); // Types slower, like a user
page.type(selector, text[, options])

See the full page.type documentation.

Waiting for elements

To make sure that the browser is in the correct state, you may need to wait for certain elements to appear after clicking them or after a certain amount of time. You can do this with the page.waitFor method:

// wait for selector
await page.waitFor('.foo');
// wait for 1 second
await page.waitFor(1000);
// wait for predicate
await page.waitFor(() => !!document.querySelector('.foo'));

See the full page.waitFor documentation.

Going further

Check out the PercyScript tutorial to try it out with an example app, or the PercyScript: Advanced doc for how to do more complex interactions with PercyScript.

Other ways to integrate Percy

PercyScript is the easiest way to get started with Percy — but there's more! Check out the SDKs overview for other ways to integrate Percy into your existing test suites and applications.


Suggested Edits are limited on API Reference Pages

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