Wraith lecture at DrupalCamp London 2015

I gave a talk at DrupalCamp London 2015 about Wraith and how developers at Torchbox have used it as a tool to prevent awkward or unexpected visual regressions from making their way to a live environment. Here's an exclusive breakdown of my presentation, just for you.

What is Wraith?

Wraith is a handy tool, developed at the BBC, that provides a visual comparison between two images using the ImageMagick software suite - of which, these images can even be screenshots of web pages.

Wraith sits atop a headless browser (think Firefox/Chrome but without a window or screen) and runs on the command line (CLI), so can be used as a development tool or incorporated with a continuous integration service to run a set of image comparisons before a feature is put live.

What value does Wraith add to a project?

  • Wraith provides automated, reliable comparisons between web pages to aid developers, site builders, project managers or stakeholders in assessing visual changes when new functionality is added.
  • It frees up developer time by automating the dull, error-prone comparison work typically performed as part of the development process; I call this the "point 'n' click adventure game".  This misused time can be replaced with some well spent productive work.
  • It reduces the time required to address issues by offering developers the ability to spot unexpected, styling errors, before sharing work with the rest of the team or clients.
  • Wraith offers support for media queries, saving even more time by snapping web pages at multiple resolutions.
  • Reduces the context and engagement each developer needs with the content of a site. This is a real boon for agency environments where staff often work on short, focused features and don't always have the luxury of knowing when content looks right or out of place.

Great! How do I get started?

First things first, have a look at the installation instructions provided to get you up and running.

Next, create your own configuration (using a YAML file) that you'd need to assess the key pages on your app or website. Chances are you won't want to capture every single page across multiple media queries: it'll take a long time to run and discourage you from running your tests. A representative selection as well as known sensitive pages should be enough. Focus on the ones where unexpected changes would have a big impact.

In its most basic setup, Wraith can diff pages between two domains and provide you with a gallery of the changes. For convenience, you can also configure the gallery to present the pages with the highest number of changes at the top.

$ wraith capture config/site.yaml

This can be handy when wanting to compare pages across different environments.

So how much time does it take to get going? Building the necessary dependencies and installing Wraith, to snapping my first set of screenshots took around an hour, so I was pleasantly impressed with the speed of getting tangible results.

A more agile approach

While it is nice to diff all pages across multiple media queries, it can take a long time to load many pages, snap each multiple times in different resolutions and save the files to disk. In a fast moving project, this often isn't time you want to give.

Necessity often precedes invention and I found that last year's Chatham House project was getting harder to assess as it grew in size. It wasn't practical to spend hours familiarising myself with new or amended content and configuration. It also wasn't fair to the client to expect them to meticulously and regularly assess their site as features rolled past. The following approach worked well for features I knew involved extensive front end changes:

  • Amended my .gitignore file to exclude any Wraith configuration files with the pattern '.local.yaml' (nobody else in the team wants them!) and the default 'shots' folder that Wraith creates to house the gallery.
  • Copied the main site.yaml configuration file to a feature specific YAML file and:
  • Reduced the domains to compare to just one: my local build.
  • Reduced the paths in the feature YAML file to check to key pages affected by my work, one or two related ones and any sensitive pages.
  • At the start of my feature, run: $ wraith history config/feature-name.local.yaml to set a baseline for future comparisons.
  • At major milestones in the feature, run: $ wraith latest config/feature-name.local.yaml to produce a visual diff between the start of the feature and the current state of my build. This allows any changes to be assessed and if any unexpected differences are found they could be addressed.
  • At the end of the feature, before handing over to the client, a full site diff was run based on a baseline of my master (stable) branch against my completed feature branch and review for any unexpected changes.


In its default state, Wraith doesn't interact with your pages before snapping. As a result, if you require JavaScript events to be triggered, you may find tools like Selenium suit you better than Wraith. As it happens, the wraith-selenium project aims to bridge Selenium and Wraith together to achieve just that.

Wraith captures the entirety of a page rather than a specific element or section of the page. Some projects may have expected random content such as advertising banners which should be factored in as an expected difference in each test.

Webfonts can also be a problem. Wraith makes use of a headless browser (typically phantom.js) to open pages and capture their content, but if the underlying browser doesn't support webfonts or JavaScript then the output you'll see will reflect this. This isn't always a problem as Wraith's main strength is the ability to reliably point out differences, rather than provide a pixel perfect representation of a page.

It is important to be able to compare like-for-like. For instance, if your staging site contains out of date content compared to your live site, you will likely be distracted by visual differences in content instead of key differences in layout.

Working with Wraith in a bigger team

I have found Wraith can be very useful at an individual developer level, but there's no reason why teams can't use it as another means of quality assurance in a wider workflow. Wraith's ability to run on the command line means it is perfectly positioned to be included in a continuous integration system. Wouldn't it be great if every time a developer pushed their changes a job was automatically started to run a comparison of their changes against the live site and notify them over email, IRC or Slack when it's done and where to find the gallery?

Any tool that helps improve quality and helps to make developers happier and more productive is definitely something I'd endorse and encourage you to try for yourself.

For those who might find them useful, my slides from DrupalCamp London are also available.

Johan Gant

Johan GantDrupal Team Manager