Sign in or start for free

Percy Snapshot

The easiest way to start visual testing with Percy

Suggest Edits

👍

Covered in this doc

  • Getting started with Percy CLI's snapshot command
  • Configuration
  • Advanced usage
  • Migrating from PercyScript
  • Troubleshooting

📘

Requirements

Getting started

The Percy CLI snapshot command is the easiest way to start visual testing. With Percy, you can visually test virtually anything that runs in a browser. Percy’s CLI snapshot command provides a drop-in way to start doing visual testing by providing a list of URLs & names to the CLI.

Step 1

To use the CLI’s snapshot command, you will need to install the @percy/cli dependency. Inside of your project:

$ npm install --save-dev @percy/cli

Step 2

Next, create a snapshots.yml file listing the pages to snapshot with Percy. 

- name: First example
  url: http://localhost:8080
- name: Second example
  url: http://localhost:8080/two

Step 3

Before you can run the CLI snapshot command, you’ll have to set your PERCY_TOKEN. 

export PERCY_TOKEN=[your-projects-token]

set PERCY_TOKEN=[your-projects-token]

# Powershell
$Env:PERCY_TOKEN="[your-projects-token]"

Finally, you can run the visual tests by running the CLI command:

$ npx percy snapshot snapshots.yml
[percy] Percy has started!
[percy] Created build #1: https://percy.io/org/project/123
[percy] Snapshot taken: http://localhost:8080
[percy] Snapshot taken: http://localhost:8080/two
[percy] Stopping percy...
[percy] Finalized build #1: https://percy.io/org/project/123
[percy] Done!

🎉 Now you’re visual testing with Percy!

👍

Up next

Now that you're capturing snapshots, next you can setup CI to capture snapshots on each commit.

You can also setup a source code integration like GitHub, GitLab, etc for Percy status messages on each commit/PR

Configuration

Per-snapshot

These are all the available options for each page:

  • url (required) - URL of the page to visit and snapshot
  • name - Name of the snapshot (must be unique)
  • execute - JavaScript you would like to execute in browser before capturing a snapshot
  • waitForTimeout - An amount of time to wait before capturing a snapshot
  • waitForSelector A CSS selector to wait to appear on page before capturing a snapshot
  • See per-snapshot configuration options for additional common per-snapshot options (like widths, percy-css, etc)

See the advanced section for details on how to use these options.

Build

The snapshot command has a top-level key (snapshot) for configuration to control widths, Percy CSS, and other snapshot options. Percy’s CLI has a standardized config file and provides commands for creating/validating your config. See our CLI config docs for more information

Advanced

Providing a yaml file with a list of names & URLs is a quick way to get started with Percy. Often you will need to wait for specific page states, interact with the page before capturing snapshots, or need to provide a dynamic list of pages.

Waiting for elements

If you only provide name & url, the snapshot command will wait for network requests to settle before capturing a snapshot (in a similar way asset discovery’s network-idle-timeout works).

Sometimes that’s not enough wait time to capture the right page state. In those cases, you can provide either a waitForTimeout or waitForSelector option. This is so you can ensure the page is in the exact state you want before capturing a snapshot. 

- name: Snapshot Example
  url: http://localhost:8080/example
  # wait for a timeout and/or selector before snapshotting
  waitForTimeout: 1000
  waitForSelector: .some-element-on-page

Interacting with the page

With the snapshot command, you can interact with the page by providing an execute option. This can be any valid JavaScript you run inside of a browser.

- name: Execute Example
  url: http://localhost:8080/example
  execute: "document.querySelector('.my-button-example').click()"

Executing JavaScript after events

The execute option can also accept an object with these keys:

  • afterNavigation - called after the page navigates to the given URL
  • beforeResize - called before the page viewport is resized to one of the passed width(s)
  • afterResize - called after the page viewport is resized to one of the passed width(s)
  • beforeSnapshot - called before Percy captures a snapshot
- name: Execute Example
  url: http://localhost:8080/example
  execute:
    afterNavigation:
    beforeResize:
    afterResize:
    beforeSnapshot:

[{
  name: 'Execute Example',
  url: 'http://localhost:8080/example',
  execute: {
    afterNavigation() {},
    beforeResize() {},
    afterResize() {},
    beforeSnapshot() {}
  }
}]

Dynamic snapshot scripts

The snapshot command also accepts a JavaScript file that exports an array of objects (with the keys name & url present). You can export sync or async functions from this file.

For example, a common use case is to build an array of pages dynamically and then iterate over that array to snapshot pages. You can export that array to the snapshot command. As a snapshots.js file:

module.exports = async () => {
  // your method for building the urls/names
  let urls = await getSnapshotUrls();
  return urls.map(url => ({ name: url, url }));
}

Upgrading from PercyScript

Percy CLI’s snapshot command is a replacement for PercyScript. Most PercyScript projects we helped customers with would have some form of URL building & iterating over those URLs to snapshot. The downside to this in PercyScript is if you have more than 40 pages to snapshot, you run the risk of the Puppeteer tab crashing (since it’s reused across all the snapshots).

The snapshot command uses @percy/core’s asset discovery browser & queue management system to iterate through the pages quickly and efficiently. This will make your scripts more reliable and faster than PercyScript.

@percy/puppeteer

If the CLI snapshot command is not a good fit for you, we recommend upgrading to our Puppeteer SDK. PercyScript was essentially our Puppeteer SDK, except we launched the browser for you. This is also the right path forward if you outgrow the snapshot command and need to graduate to a test runner.

Troubleshooting

CLI Installation

command not found: percy

We recommend you install @percy/cli as a development dependency (not globally). Using npx to reference the local percy binary is the preferred usage (or use npx @percy/[email protected] snapshot to avoid installing any dependencies at all). For more info, see the npx docs.

Updated 4 months ago