Setting Up Visual Regression Tests

Installation

Paperclip integrates with Percy to allow you test for CSS bugs in your Paperclip UI files. To get started, install the NPM module:

npm install percy percy-paperclip --save-dev

Next, grab your percy token, then run the following command in the same directory as your paperclip.config.json file:

PERCY_TOKEN=[TOKEN] percy exec -- percy-paperclip

After that, you should see something like this:

Percy demo

Setting up with GitHub actions

percy-paperclip pairs nicely with GitHub actions, especially for PR checks. Here's a GitHub action you can use:

name: PR Checks
on:
pull_request
jobs:
visual-regression-test:
name: Visual Regression Test
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- uses: actions/setup-[email protected]
- uses: actions/[email protected]
with:
fetch-depth: 0 # fetches all branches
- name: Maybe snapshot
run: |
CHANGED_PC_FILES=$(git diff --name-only origin/${{ github.base_ref }} origin/${{ github.head_ref }} -- "./**/*.pc")
if [ -n "$CHANGED_PC_FILES" ]; then
yarn add percy percy-paperclip
percy exec -- percy-paperclip
fi
working-directory: ./path/to/frontend
env:
PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

Be sure to change working-directory to point to where your paperclip.config.json file is.

☝🏻 This script will run only when PC files change, so if you're working with people working on the back-end, for instance, they won't get this check (since we're assuming they won't touch PC files).

To go along with the script above, you'll need to set up a baseline for your master branch. Here's a script for that:

name: Master Checks
on:
push:
branches:
- master
jobs:
visual-regression-test:
name: Visual Regression Test
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- uses: actions/setup-[email protected]
- uses: actions/[email protected]
with:
fetch-depth: 0
- name: Maybe snapshot
run: |
CHANGED_PC_FILES=$(git diff --name-only origin/master^ origin/master -- "./**/*.pc")
if [ -n "$CHANGED_PC_FILES" ]; then
yarn add percy
yarn snapshot
fi
working-directory: ./path/to/frontend
env:
PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}

Again, be sure to change working-directory to point to where your paperclip.config.json file is.

☝🏻 This script runs whenever a *.pc file changes on master, and ensures that subsequent PRs are visually testing against the correct baseline.