PercyScript
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
- Node.js >= 10 or greater. (See how to install Node.js.)
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:
- Set up your PercyScript to run continuously in CI
- Install the source code integration to get notified in pull/merge requests
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