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-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] yarn percy-paperclip
After that, you should see something like this:
That's it! You're now set up to catch visual regressions in your UIs.
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 yourpaperclip.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 yourpaperclip.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.