Sign in or start for free

PercyScript

Suggest Edits

👍

Covered in this doc

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

🚧

Deprecated

PercyScript has been deprecated in favor of the Percy Snapshot CLI command. You can find the snapshot docs here

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.

Requirements

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');

PercyScript.run(async (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.

📘

That's it!

You will see a URL to a Percy build, which will show you all of your rendered screenshots.

Next up:

Configuration

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.

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

page.click

page.click(selector[, options])

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

const PercyScript = require('@percy/script');

PercyScript.run(async (page, percySnapshot) => {
  await page.goto('http://localhost:8080/index.html');
  await percySnapshot('homepage');

  await page.click('a[id="signup-button"]');
  await percySnapshot('homepage signup modal');
});

The page.click 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 page.click documentation.

page.type

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 over 1 year ago

What's next