Skip to content
This repository has been archived by the owner on Mar 14, 2024. It is now read-only.

Percy

Jump to bottom
Rob Dodson edited this page Oct 1, 2021 · 2 revisions

Percy is a screenshot diffing tool. We run it against key pages whenever someone sends in a PR to make sure that nothing broke.

Percy failed, what now?

Percy will fail the build if it sees that there is a visual change on the site. To approve the visual change, click the Details button next to the GitHub check (it should look like a purple hedgehog). It will open the percy dashboard (screenshot). Compare the changes. You can click on the image on the right to toggle visual diff mode on and off. If everything looks good, click the big green Approve build button in the top left.

GitHub Action

We run Percy as a GitHub Action (workflow). It runs when a PR is created/updated, and it also runs when a PR lands on master. It's important for Percy to run when a PR lands on master because that's when it updates the "golden" snapshots that it uses to compare against future PRs.

Process

  • The GitHub Action runs the npm percy command. This builds the site and starts a local server. The build uses an env var, PERCY, that tells the site to add placeholder data to the pages so we get consistent snapshots. Note: d.c.c. does not use placeholder data, which means new blog posts always invalidate things. This is bad and should be fixed by #78
  • The script that Percy runs to actually do the screenshotting is called snapshots.js. It lists a number of pages that should be screenshotted, and does a bit of waiting for CSS and JS to properly load. It's using a library called PercyScript which is just a wrapper on top of Puppeteer.
  • There is a configuration file, .percy.conf.yml that sets a few rules for Percy, for instance, it sets the dimensions of the screenshots. It also injects CSS into the page to hide iframes or other unstable items that could mess up the screenshots.

Important! Because web.dev used to be an SPA, we had to use snapshots.js to make it work right with Percy. But developer.chrome.com has a much simpler setup in its .percy.js file and web.dev should consider moving to this.

Browserstack

Percy was recently purchased by Browserstack so when you sign into it, you may have to create a Browserstack account first.

Clone this wiki locally