Run Percy tests on Gatsby

A guide to integrating your Gatsby static site with BrowserStack Percy. Catch visual differences in your web application on time.

Prerequisites

• Node 12.0.0 or higher
• A PERCY_TOKEN. Your token can be found on your Percy project settings page.

Create a Percy project

Sign in to Percy. In Percy, create a project of the type, Web, and then name the project. After the project is created, Percy generates a token. Make a note of it. You have to use it set your environment variable in the next step.

For details on creating a project, see Create a Percy project.

Environment setup

The first step is to make your PERCY_TOKEN available in your environment. The percy package relies on the PERCY_TOKEN environment variable for authenticating and authorizing access to each project.

Install dependencies

Modify your test

First, add the Percy plugin to your gatsby-config.js file:

Now when running gatsby build, the plugin will first check if Percy is running before querying for pages using Gatsby’s graphQL functions and sebsequently take snapshots of discovered pages. If Percy is not running, the plugin will not do anything.

You can run Percy around the build command using percy exec along with your Percy project’s PERCY_TOKEN:

Options

Options are not required. The following are accepted plugin options within your gatsby-config.js file:

• query - The GraphQL query used when retrieving pages to snapshot. If querying without using the allSitePage.nodes query structure, you will also need to set a custom resolvePages function.
• resolvePages - A function given data retrieved by the query and returns an array of page paths.
• ... - Any additional static snapshot options. Percy also searches the current working directory and up for a matching Percy config file.

Example