I wrote not long about the virtues of CSS visual regression testing. There’s a small problem: getting it set up.

PhantomCSS is incredibly powerful, but an incredible pain the ass. I had the chance to install PhantomCSS on my desktop from scratch, and thus this time I documented my adventure. It took me several hours to get this up and working on my development computer. The only assumptions I’ll make is that you have Xcode installed and are using OS X. *Nix users will be able to follow along and my apologies to Windows users. Users may be at all walks of skill so I’ll try to keep this as humanly sane as possible despite jamming in a bunch of terminal commands. PhantomCSS requires pieces of software to work (and several more to install these):

  • PhantomJS (a headless webkit web browser)
  • CasperJS (a navigation scripting & testing utility that interacts with headless web browsers)
  • ImageMajack (a CLI batch image processor that makes Visual Regression Testing possible)

Let’s begin, shall we?

Terminal Commands

  1. Check to see if node is installed:
    node -v
    If you do not have Node installed, you can grab it Here.
    Node is an open source cross-platform runtime enviroment for fullstack js development, but contains built-in libraries to act as a web server without software like Apache or IIS, and used commonly to distribute packages.
  2. Check to see if you have bower installed
    bower --version
    If you do not have Bower installed,
    npm install -g bower
    Bower is a package manager for popular web libraries, allowing for quick distribution of code.
  3. Install Xcode developer utilities:
    xcode-select --install
    This is required to install Ruby, and even if you have installed Xcode, will still need to be run. Skip if you have already installed it.
  4. Install Homebrew, a package manager for OS X, skip if you have already installed it:
    ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
  5. Make sure Brew is up-to-date:
    brew update
  6. Make sure Brew packages are upgraded
    brew upgrade
  7. Install ImageMagick
    brew install imagemagick
  8. Install CasperJS
    sudo npm install -g casperjs
  9. Install PhantomCSS
    sudo npm install phantomcss
  10. Casper bundles the wrong version of PhantomJS, uninstall it.
    brew uninstall phantomjs
  11. Install a compatible version of PhantomJS
    brew install homebrew/versions/phantomjs192
    Note: this will install version 1.9.2, you can manually install 1.9.8 by visiting PhantomJS’s downloads section, downloading 1.9.8, unzipping it and moving the phantomjs to /usr/local/Cellar/
  12. Install Resemble.JS
    sudo npm install resemblejs

Testing to make sure it is installed correct

In your terminal, go to your desired directory and run
bower install phantomcss

Next test to make sure it works by running the default test from this same directory.
run casperjs test bower_components/phantomcss/demo/testsuite.js
You should see three or so failed tests as the testfile isn’t entirely configured correctly but followed by “Must be your first time?” Success!


Problem: npm ERR! Error: EACCES, open ‘somefile path’

Fix: You didn’t run a npm install as sudo, re-run the npm install as sudo npm install

Problem: Fatal: [Errno 2] No such file or directory; did you install phantomjs?

Fix: brew install homebrew/versions/phantomjs192

Problem: CasperJS needs PhantomJS v1.x

Fix:Casper, the library that talks to PhantomJS only works with PhantomJS 1.x, you have currently installed PhantomJS 2.0. Run brew uninstall phantomjs and brew install homebrew/versions/phantomjs192

Problem: FAIL [PhantomCSS] Resemble.js not found: ./node_modules/resemblejs/resemble.js

Fix:You need to install resemblejs, sudo npm install resemblejs