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.