Visual Regression Testing with BackstopJS

Brought to you by the folks at Pantheon

Visual Regression Testing with BackstopJS

The Pagoda atop the Pantheon office

Hi, I'm David Needham

Developer Advocate at Pantheon

davidneedham on GitHub and Twitter

[email protected]

In my free time I like:

David Needham


Intro and Setup
Visual Regression Testing
Using BackstopJS
Continuous Integration
Standalone Node App
Q&A + Extracurricular


You need:

Visual Regression Testing

What is Visual Regression?




  1. a return to a former or less developed state.

When have you been plagued by Visual Regression?

Killer Use Case #1: Routine Updates

A screenshot of a WordPress website with updates available

Live (before update):

An animated gif of a website before a change

Dev (after update):

An animated gif of a website after a change

Side by side:

An animated gif of the website before and after the change side-by-side

Side by side (mobile):

An animated gif of the website on mobile before and after the change side-by-side


A screenshot of a website showing the differences highlighted

Visual Regression: Benefits

A website on multiple devices

Limits to Visual Regression

Static noise

Using BackstopJS

The BackstopJS logo on a background


Everything defined in the backstop.json file

			  "id": "backstop_default",
			  "viewports": [
			      "label": "phone",
			      "width": 320,
			      "height": 480
			      "label": "tablet",
			      "width": 1024,
			      "height": 768
			  "scenarios": [
			      "label": "Homepage",
			      "url": "",
			      "referenceUrl": "",
			      "readyEvent": "",
			      "readySelector": "",
			      "delay": 0,
			      "hideSelectors": [],
			      "removeSelectors": [],
			      "hoverSelector": "",
			      "clickSelector": "",
			      "postInteractionWait": 0,
			      "selectors": [],
			      "selectorExpansion": true,
			      "expect": 0,
			      "misMatchThreshold" : 0.1,
			      "requireSameDimensions": true
			  "paths": {
			    "bitmaps_reference": "backstop_data/bitmaps_reference",
			    "bitmaps_test": "backstop_data/bitmaps_test",
			    "engine_scripts": "backstop_data/engine_scripts",
			    "html_report": "backstop_data/html_report",
			    "ci_report": "backstop_data/ci_report"
			  "report": ["browser"],
			  "engine": "puppeteer",
			  "engineOptions": {
			    "args": ["--no-sandbox"]
			  "asyncCaptureLimit": 5,
			  "asyncCompareLimit": 50,
			  "debug": false,
			  "debugWindow": false

Running BackstopJS globally

  1. Navigate to your local project
  2. Initialize Backstop: backstop init
  3. Edit your backstop.json file:
    • label: name of your scenario
    • url: local or development URL
    • referenceUrl: production URL
  4. Create new reference screenshots: backstop reference
  5. Run tests: backstop test

Killer Use Case #2: Theming & Site Building

Boy with hands over his eyes

Running BackstopJS (notes)

Continuous Integration

Robots serving platters of food and drink with the quote, What parts of your job can robots do better and faster than you?

Example #1: On Cron

Pantheon Example Terminus Auto Update Script

Get the script

A screenshot of the github repo for Pantheon Example Terminus Auto Update Script

Example #2: On Commit

Automated Workflows in Drupal 8 with GitHub, Composer and CircleCI

Get the script

DrupalCon Seattle 2019

Standalone App

Clone the example repo

We've created an example repo that we're going to clone to give you a jumpstart.

There are detailed instructions in the README to run through this on your own next time.

Today we're going to get started by cloning the repo:

git clone
A screenshot of the repo we're cloning

Running the example node app

  1. Change into the folder
    cd visual-regression-testing-workshop
  2. Checkout a new branch
    git checkout -b my-hacking-1
  3. Install Node dependencies
    npm install
  4. Run the example script
    npm run start
  5. Wait for the results (it should open in your browser automatically)

Customizing the example


WebOps is a set of practices that facilitates collaboration and automates processes to improve the productivity of the whole web team from developers and designers to content editors, stakeholders, and more.

The result is cross-functional web teams empowered to develop, test, and release website changes faster and more reliably.

WebOps with Pantheon


Let's build something!