Front End Testing with Wraith: A Step by Step Recipe

I had occasion to finally get to one of my goals from last year – and that was to introduce some testing to my front end development.

My goal was to have a way to have a before/after visual regression test. The open source Wraith project, from the BBC, fits the bill wonderfully.

This post is merely meant to be a step-by-step procedure to get Wraith up and running. I’m not going to provide any context to what each step means.

First off, this post assumes that you’re running Mac OS X, and already have Ruby installed. This post also assumes that you want to use the “history” mode in Wraith – where you are taking two snapshots of the same URL. (The “standard” mode requires two different URLs).

Step 1: install home brew (if you don’t already have it)

Open a terminal and enter this:

ruby -e "$(curl -fsSL"

Hit enter and enter password at prompts

Step 2: install imagmagik

brew install imagemagick

Step 3: install phantomjs

brew install phantomjs

Step 4: install capserjs

brew install casperjs --devel

Step 5: install wraith

sudo gem install wraith

I needed sudo, anyway.

Step 6: cd to your project directory

cd path/to/project

Step 7: set up wraith

wraith setup

This creates two files:

  • /javascript/snap.js
  • /configs/config.yaml

Step 8: if desired, set up config for history mode

See this example config file for an example.

Step 9: initiate wraith history to take first set of screenshots

wraith history configs/config.yaml

If you get “unable to find config” errors, check the YAML syntax.

step 10: do development (or, switch branches)

step 11: have wraith capture the latest

wraith latest configs/config.yaml

This will take a bit, so be patient.

step 12: wraith will generate a gallery page with diffs visually highlighted

It will be found in the “directory” you configured – e.g. ‘shots/gallery.html’. Just open that file in your favorite browser.


This is all with the defaults as presented by wraith. There is nothing to stop you from rearranging directories, if it makes sense. For instance, in my project I consolidated everything into /tests/.

If you change the config file – e.g. add more paths, etc, delete your inital shots and shots_history directories.

My initial instinct is to not commit shots generated by your tests into a version control repo. (In git, this would be done by modifying your .gitignore file) There are a lot of image files generated, and binary files tend to make git repos balloon in size if they are running amok.

  • This is cool! Have you seen a good DOM comparer?

    For example, it seems like Wraith would be good for showing visual differences you didn’t notice, but more often the circumstance is, I notice a difference between staging and local (e.g.) but a diff of the source files says they match. My recourse becomes taxingly using inspector to figure out what is different in the output—whether affected by the browser, browser extensions, or any middleman.

  • Hi, I’m following the tutorial and it seems no. 4 is having a typo “capser to casper”, got this error: No available formula with the name “capserjs”

    • Chip Cullen

      Wow! How completely embarrassing – that’s been hanging out there for over two years. Yikes.

      Thank you for letting me know! I’ve updated the article accordingly. Sorry for the confusion! I hope the rest of the article is helpful!