Wraith

A responsive screenshot comparison tool

The project is hosted on GitHub and is available for use under the Apache 2.0 open source license. You can report bugs and discuss features on the GitHub issues page, or send tweets to @ResponsiveNews.

Fork on GitHub »

Setup

First, you'll need to follow the instructions for your operating system to install Wraith's dependencies, as Wraith relies on various programs for it to function properly.
Once you have installed all of Wraith's pre-requisites, you are ready to install the gem:

          
gem install wraith

Wraith is now ready to use. Wraith has some built-in JavaScript and configuration file templates for you to get started with right away. The following command will create folders in the directory you are in:

          
wraith setup

Using Wraith

There are two main modes for using Wraith: 'capture' mode and 'history' mode.

Capture mode

Summary: given two domains, Wraith will take screenshots of both and compare them.

Use case: good for comparing test and live versions of the same site.

How do I use it?

Specify TWO domains, and any number of paths and screen widths. Run `wraith capture`.

          
wraith capture configs/capture.yaml

If you wish to take screenshots of a component rather than the entire page, use casperjs and pass a selector along with your paths. In the 'component' example config, you can see how we specify a component name, domain path and selector we want to capture.

History mode

Summary: compare the same domain over time.

Use case: good for checking that your website continues to look the same (especially useful if your site relies on third-party components).

How do I use it?

Specify ONE domain, and any number of paths and screen widths. Make sure you have a `history_dir` property set. Run `wraith history` to generate your base screenshots, and `wraith latest` to generate new screenshots to compare against the old ones. An example of this can be found in the 'history' example config.

  
  wraith history

This will create 2 folders with the labels you have specified in the config file, for example, shots and shots_history. The original shots will be copied into your 'history' folder, then copied back into the shots folder once you have run your latest job. This workflow will essentially mean your history folder is your baseline, being copied back into the shots folder every time you run the following

  
  wraith latest

All modes

Regardless of which mode you use, certain config options are applicable to both.

All config options will be placed in a YAML config file. You set the headless browser, diff mode, threshold, fuzz amount and screen widths.

Headless browser : This is typically PhantomJS or CasperJS - a browser that doesn't have a user interface; it runs in the backround.
Diff Mode : How you would like the gallery to be presented, you can set ordering and for the unchanged images to be removed.
Threshold : This is the minimal level of change you that want to present a failure. The metric is percentage change of the page and set globally for a Wraith run.
Fuzz : Use this option to match colors that are close to the target color in RGB space, this number helps with anti-aliasing.
resize_or_reload : (optional) As of Wraith 3.0.0, you can now tell Wraith to run more efficiently. The old default is 'reload', which reloads the browser for every screen width you want to take a screenshot of. However, you can set it to 'resize' to tell Wraith to resize the browser (rather than reload it) in between taking screenshots - making Wraith run much more quickly.
verbose : (optional: boolean) As of Wraith 3.1.0, you can run Wraith in verbose mode, which lists helpful debug information. Default: false
snap_file : (optional: string) Before Wraith 3.0.0, you were required to specify a path to a snap JavaScript file responsible for taking the command line arguments from Wraith and loading up Phantom/Casper to take screenshots. As of 3.0.0, this functionality has been abstracted away, so you should no longer specify a snap file. However, you are still able to specify a snap file if you wish.
threads : (optional: integer) Number of capture threads to run simultanously
settle : (optional: integer) Number of seconds to wait for the page to settle (when using Chrome as the headless browser)

Spider functionality

You can specify paths in one of two ways. 1) specify the paths manually, or 2) have Wraith crawl your website to determine your paths for you.

To have Wraith crawl your site for you, remove the 'paths' property and specify an 'imports' property in your YML file, e.g.

  
  imports: "spider_paths.yml"

Tell Wraith to crawl your domain:

  
  wraith spider my_config.yml

...this creates a file called spider_paths.yml in the same directory as your my_config.yml. Now you can run Wraith commands as normal, as if you've specified the paths manually:

  
  wraith capture my_config.yml

Gallery & Output

After each screenshot is captured, the compare task will run, this will output a diff.png and a data.txt. The data.txt for each file will show the number of pixels that have changed.

A gallery is available to view each of the images and the respective diff images located in the shots folder once all the images have been compared.

As of Wraith version 2.8.0, there are now multiple gallery templates for you to choose from. The basic template is the default one and is simply a list of thumbnails sat side by side. The slideshow template is a new one and gives a more managable way of comparing thumbnails (including seeing everything at once in a lightbox), but is still under development and so is not the default yet.

You can choose your template, as well as the size of the generated thumbnails, by specifying the following config:


# this property and its sub-properties are all optional
gallery:
  template: 'slideshow_template' # or 'basic_template' (which is the default)
  thumb_width: 200 # default
  thumb_height: 200 # default

before_capture hooks

Using Casper Mode allows you to hook into a 'before_capture' event so that you can run arbitrary JavaScript before taking the screenshot. This allows you to regression test interactive content. (Note: the before_capture hook is currently only supported in Casper Mode).

There are two options for hooking your JavaScript into the Wraith process, which are denoted by where you specify your 'before_capture' property. This is best illustrated using an example config:


before_capture: "javascript/config-level.js"

# Add as many domains as necessary. Key will act as a label
domains:
  english: "http://www.bbc.co.uk/news"

#Type screen widths below, here are a couple of examples
screen_widths:
  - 320
  - 600
  - 768
  - 1024
  - 1280

#Type page URL paths below, here are a couple of examples
paths:
  clickable_guide:
    path: /entertainment-arts-27221191
    selector: '.idt__news'
  clickable_guide__after_click:
    path: /entertainment-arts-27221191
    selector: '.idt__news'
    before_capture: 'javascript/path-level.js'

The before_capture at the top of the example is called before EVERY path (i.e. before both 'clickable_guide' and 'clickable_guide__after_click'). The before_capture at the bottom of the example is called only before the path which it is associated with (i.e. only before 'clickable_guide__after_click').

The config-level JS is always executed before the path-level JS. In the example above, that means 'clickable_guide' has config-level.js executed before a screenshot is taken, and 'clickable_guide__after_click' has config-level.js then path-level.js executed before a screenshot is taken.

All of the before_capture hooks are optional.

before_capture files should be in module form. Depending on the browser engine used, you may have direct access to the DOM or you may need to access it through the engine in another way. The important thing is to execute the `ready` callback when you're done, otherwise Wraith will hang forever.

CasperJS before_capture module


module.exports = function (casper, ready) {
    // make Wraith wait a bit longer before taking the screenshot
    casper.wait(2000, ready); // you MUST call the ready() callback for Wraith to continue
}

PhantomJS before_capture module


module.exports = function (phantom, ready) {
    // make Wraith wait a bit longer before taking the screenshot
    setTimeout(ready, 2000); // you MUST call the ready() callback for Wraith to continue
}

Command line options

Wraith allows for most of the commands to be used individually, allowing you perform tasks as you see fit. This assumes that your snap.js and config.yaml are in the folders that were created on setup. There are other commands also available, these all expect a config_name to be passed as an option.

		  
  wraith capture [config_name]              # Capture paths against two domains, compare them, generate gallery
  wraith compare_images [config_name]       # compares images to generate diffs
  wraith copy_base_images [config_name]     # copies the required base images over for comparison with latest images
  wraith crop_images [config_name]          # crops images to the same height
  wraith generate_gallery [config_name]     # create page for viewing images
  wraith generate_thumbnails [config_name]  # create thumbnails for gallery
  wraith help [COMMAND]                     # Describe available commands or one specific command
  wraith history [config_name]              # Setup a baseline set of shots
  wraith info                               # See useful system Wraith/ImageMagick/Phantom info
  wraith latest [config_name]               # Capture new shots to compare with baseline
  wraith multi_capture [filelist]           # A Batch of Wraith Jobs
  wraith reset_shots [config_name]          # removes all the files in the shots folder
  wraith save_images [config_name]          # captures screenshots
  wraith setup                              # creates config folder and default config
  wraith setup_folders [config_name]        # create folders for images
  wraith spider [config_name]               # crawl your domain to generate a YML of paths
  wraith validate [config_name]             # checks your configuration and validates that all required properties exist
  wraith version                            # Show the version of Wraith

More help/tutorials

If you are new to ruby, rake and PhantomJS, here is a great screencast about how to use Wraith by Kevin Lamping