Improve your workflow with CSS regression testing.

If you haven't heard of CSS regressiong testing well today is the day. I've been following the list of tools lately and I see the potential of such tools like these. The overall improve the quality of web projects and can increase productivity.

The Problem

When you are working a web project you are typically checking your browser to make sure everything is going as expected. As the project grows the number of stylesheets and pages increase. That is completely fine but problems can occur as the project grows. Here are a few scenarios.

You are working on a page, make a few CSS changes and then you go back to a page you worked on before and you see that your new styles somehow affected that page or even others. What do you do now? Well manually check every page until you find all the affected pages, find a solution, and apply your new styles. This could take hours to do and it overall slows you down.

You might think that this is not an issue for you and your might be right. However, when you are working on a large project that involves many people the probability of it happening rises. I have to admit that I had the problem even when working on a project alone.

The Solution(s)

CSS regression testing. For those who don't know, CSS regressions testing is done to make sure your page(s) look as expected after you make changes.

A CSS Regression testing tool will detect and highlight differences between reference and screenshots update taken from web pages and CSS selectors you specify.

As of time of writing there are a number of good and popular CSS Regression testing tools. One thing to point out is that some of these tools can be incorporated with Grunt or Gulp and they are also commandline options. Most of these tools are built on top of popular tools like PhantomJS, CasperJS, and ResembleJS.

Succss - A commnandline tool that's easy to learn, deploy, and incorporate into your workflow and projects with minimal configuration. It a Node.JS module that can be installed globally and used without any Javascript task runner.

Example configuration file test.js:

// data.js
Succss.pages = {
  'home': {
    // captures: { 'name' : 'CSS selector' }
    captures: {
      // leave an empty value if selector == name
      'dynamic-text':'body #header-text > #static-line + span',
  'another-page': { 

Succss.viewports = {
  // './screenshots/dir/home--header--1366x768.png' file
  // './screenshots/dir/home--dynamic-text--1366x768.png' file
  'default': {
    width: 1280,
    height: 768
  // './screenshots/dir/home--header--640x480.png' file
  // './screenshots/dir/home--dynamic-text--640x480.png' file
  'mobile-landscape': {
    width: 640,
    height: 480

Then simply add the test which uses the current version of your site as reference.

succss add test.js

Make a few changes and run the test.

succss check test.js

succss regression testing
The test uses the images created when the test was added as reference and checks for any differences. It displays whether the test failed or passed along with the generated image results.

I find Succss overall easy to use and configure. It is globally available via the commandline. It integrates well with your current project regardless if you're using a Javascript task runner. It also has advanced configuration to make it even more powerful.

PhantomCSS - Under the hood it's running on the similar plugins as Succss but it's a CasperJS module. It works great if you are using CasperJS on your project and workflow, otherwise it can be a little complicated to setup.

Example configuration file test.js.

casper.start( url ).then(function(){
		// do something'button#open-dialog');
		// Take a screenshot of the UI component
		phantomcss.screenshot('#the-dialog', 'a screenshot of my dialog');


Run the test

casperjs test test.js

Overall it is powerful but it can be a little complicated to set up and add to your current project depending on your workflow and project but it's still a good tool. To learn more about I would it visit the Github repo.

BackstopJS - Relies heavily on Gulp since it was build on top of it. It also uses Resemble.js, CasperJS and PhantomJS to report on visual changes. If you are using Gulp then this tool work great for you workflow and project.

Example config file data.json.

  "viewports": [
      "name": "phone",
      "width": 320,
      "height": 480
    }, {
      "name": "tablet_v",
      "width": 568,
      "height": 1024
    }, {
      "name": "tablet_h",
      "width": 1024,
      "height": 768
  "scenarios": [
      "label": "",
      "url": "",
      "hideSelectors": [],
      "removeSelectors": [
      "selectors": [
        "body .bs-docs-featurette:nth-of-type(1)",
        "body .bs-docs-featurette:nth-of-type(2)",
      "readyEvent": null,
      "delay": 500

Assuming you have Gulp and all of the other dependencies create a reference.

gulp reference

Then run the test

gulp test

The test will compare the new images created with the ones created as reference.
BackstopJS - Image by CSS-Tricks

Overall it's a powerful tool and it supports advance configuration. It does require Gulp and that can make it hard to add implement within current projects and workflow. To learn more about BackstopJS visit it's Github page. Also, read this great tutorial on CSS-Tricks.

CSS Critics - A Node.js module that runs on the commandline. Also relies on the technologies that most testing tools use among others. As the developer describes it:

A lightweight framework for regression testing of Cascading Style Sheets - Christoph Burgmer

The setup and configuration works different than the other tool. You will need to first create a RegressionRunner.html and then register your page under test.

    url: 'SOME_URL',     // link to the test case HTML document
    // Optionally:
    desc: 'some text',   // a description of the test case
    width: number,       // the viewport width in pixel
    height: number,      // the viewport height in pixel
    hover: 'A.SELECTOR', // element receiving an :hover effect
    active: 'A.SELECTOR' // element receiving an :active effect

Open the RegressionRunner.html in Chrome or Firefox to save the resulting image as future reference. Re-run it again to run the test and check it agains the referenced images
CSS Critic

CSS Critics is a nice tool and overally easy to use and implement. The configuration is straight forward and it can be easily added into any current and future projects. However, it only works in Firefox and Chrome.

These are great CSS testing tools and they do a great job. Some can be hard to implement into your current workflow and projects. Some can be easy to use and support advance configuration. If you are familar with CasperJS then PhantomCSS might be the way to go. If you are using Gulp as part of your Javascript task runner then BackstopJS is the tool that works best with Gulp. However, if you want to just add CSS regression testing without and tools on top then Succss or CSS Critics can be used without any Javascript task runner or other tool on top.

Personally I have to say that Succss is my favorite CSS regression testing tool so far. Not only can I easily added to my current projects but I can also create advance and complex testing configurations. I also don't need another tool on top of it.

Edgar Pino

About Edgar Pino

I’m a passionate software engineer. I currently work at Envano Interactive on application backends, server management, and finding solutions to technological challenges our clients face.