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.


Note: PercyScript is a thin wrapper around Puppeteer. You can read the full Puppeteer docs here

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/');
  // ensure the page has loaded before capturing a snapshot
  await page.waitFor('.a-selector-on-page');
  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:
# If you're using Windows:
$ set PERCY_TOKEN=<your token here>

# Otherwise:
$ export PERCY_TOKEN=<your token here>

$ npx percy exec -- node snapshots.js
Remember to replace the `PERCY_TOKEN` with the token from your Percy project.

  "type": "info",
  "title": "That's it!",
  "body": "You will see a URL to a Percy build, which will show you all of your rendered screenshots.\n\nNext up:\n- Set up your PercyScript to [run continuously in CI](\n- Install the [source code integration]( to get notified in pull/merge requests"

## Configuration
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.

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.

  • percyCSS: A string containing Percy specific CSS that will be applied to this snapshot.

  • requestHeaders: An object containing HTTP headers to be sent for each request made during asset discovery for this snapshot.

For example:

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

Interacting with elements[, options])

You can use the method to click on elements, allowing you 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.

Updated 2 months ago


Suggested Edits are limited on API Reference Pages

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