Visual Regression Testing via BackstopJS

BackStopJS, Visual regression testing for web apps.

As a front-end, I must be sure the output of my codes is what I expected. Sometimes I just check it by viewing the output page. But, when the project grows bigger, it is not easy to check output by viewing it. Especially if you need to test it in several screen sizes (responsive output) and multiple browsers. Just imagine you need to check all outputs in 3 different resolutions and 3 different browsers. It takes too much time! So, let’s automate it.


There several tools for visual regression testing but I’m using BackstopJS. It creates screenshots of a web page (or its DOM elements), and tests them against reference images. It supports screen rendering with Chrome-headless, Phantom, and SlimerJS. You could customize tests scenarios with many options such as viewports, selectors, delay, and misMatchThreshold.

1. sample test result


You could install it globally (recommended) or locally.

$ npm install -g backstopjs

Note: Google Chrome 62 or greater is required.



At first, you need to set up a new BackstopJS instance.

$ backstop init

It creates sample scenarios. Please note that before going further, you must modify the backstop.json file according to your needs.

Building references

After initializing backstop, it’s time to build the reference files for the first time.

$ backstop reference

Note: You could run tests without building any reference files and after the failure, use the test result as references with approve command:

$ backstop approve

Running tests

You could run tests with the test command:

$ backstop test

The test command will create an HTML report and there is a command for viewing it:

$ backstop openReport 

If you modify codes (HTML, CSS or JS) without updating reference files, the result will be a failure. In this case, you must replace reference files with test result if you are sure that they are correct:

$ backstop approve
2. sample comparison of test result

How I am using BackstopJS

One of my current projects is creating D3-based charts. They are a combination of HTML, CSS, JS codes to draw SVG interactive images.

‌BackstopJS runs 55 different test scenarios in Gitlab pipelines. Whenever I push my commits, BackstopJS assures me that I didn’t break anything or I changed the appearance of charts.