CSS testing and pattern libraries

Visual regression testing with PhantomCSS

The project I’m working on right now uses a bought-in piece of software with a complex set of patterns and styles. HTML elements can be used in different ways in different contexts, and the resulting css can be complicated and fiddly.

To add to the complexity, much of the system has already been built (and is live) while the majority has yet to be built and is actively evolving.

If ever there were a use-case for automated testing, this would be it.

And yet as we all know testing web styling has in the past usually involved making changes, checking a few key pages, and then hoping everything will be ok. This works ok in smaller projects, but can be time consuming and error prone in larger projects.


I therefore looked at a handy visual regression tool called PhantomCSS. It’s actually a CasperJS module which uses PhantomJS and Resemble.js to compare baseline screenshots of a webpage with the current screenshots.

Of course, comparing one complete web page with another complete web page isn’t much use, especially if those pages are dynamic.

Far better is to compare your website’s building blocks in a pattern library.

Luckily I already have a living pattern library for this project, which you can find out more about on my blog post about a github-hosted pattern library. You might also want to bear Brad Frost’s atomic design principles in mind too.

With a pattern library you can tell PhantomCSS to pick out the HTML examples (for example using an id on each example). It will then build screenshots of things like example panels, tables, forms and compare them to your baseline. Any differences will be picked up before you roll to live.


The great thing about PhantomCSS is that it’s pretty easy to set up. I’m not per se a full-on web developer (although I have some experience in that area) but I managed to get things set up pretty quickly.

If you’re at all familiar with node and npm then you can set up the required phantomcss, phantomjs, casperjs, and resemblejs dependencies in your package.json file.

You will also need the phantomcss.js config file. I had to manually copy this into my project, as I couldn’t figure out how else to include it. There might be a better way of doing this, but for now it works.

Get testing

Finally you’ll need to write your test suite file, using standard casperjs syntax.

For example you’ll end up writing tests like:

casper.then( function () {
  phantomcss.screenshot( '#example-table', 'tables' );
  phantomcss.screenshot( '#example-form', 'forms' );

where casperjs follows a link, loads a page, looks for certain elements, and takes a screenshot.

Any good?

I’ve so far used PhantomCSS in a fairly experimental way. I certainly found it to be much much nicer than having to check things manually!

Setup and configuration was pretty simple even though I’m very far from being a hardcore dev.

I would say that for this to work you really need a pattern library using the principles of atomic design. That will give you a great base for testing out all the possible design examples.

In my current project things were a bit more complex design-wise. It’s a pain but it’s just how things often are. So it made testing far harder, but still possible in many cases.

For that reason I’d only advise automated css testing as a kind of fire blanket. It gives you peace of mind, but you will always need to do some manual testing as well.


PhantomCSS is a great tool for quickly and easily setting up some visual regression testing, preferably on your site’s pattern library (you do have a pattern library, don’t you?)

It won’t cure all your most complex css testing issues, but it will give you an element of peace of mind that if you edit some css it won’t have some catastrophically weird effect somewhere else.

Leave a Reply

Your email address will not be published.