Step 1: Install Dependencies

$ brew install node
$ brew install phantomjs
$ brew install casperjs --devel
$ cd your repo directory
$ npm install phantomcss --save

Make sure everything works:

$ npm -v
$ phantomjs -v
$ which casperjs

Should you get errors running the commands above you might want to refer to my article.

Step 2: Run a demo test

Create a test.coffee with the following content. Make sure to require phantomcss.js from your node_modules directory.

phantomcss = require("./../../node_modules/phantomcss/phantomcss.js")
phantomcss.init()

#  The test scenario
#  ----------------------------------
casper.start "test/grid.html" # Change this to wherever you placed your html files
casper.viewport 1024, 768
casper.then ->
  phantomcss.screenshot "body"
  return

casper.then now_check_the_screenshots = ->
  phantomcss.compareAll()
  return

casper.then end_it = ->
  casper.test.done()
  return

#  Casper runs tests
#  ----------------------------------
casper.run ->
  console.log "\nTHE END."
  phantom.exit phantomcss.getExitStatus()
  return

Place test.coffee in your test/instructions/ folder and run it. CasperJS looks for all test files within a directory and so you can call it with just:

$ casperjs test test/instructions/

By now you should see screenshots/ folder in your root directory with a grid_0.png file in it.

Step 3: Cleanup your PhantomCSS setup

PhantomCSS comes with a set of handy config options you might want to explore in order to keep your folder structure neat and clean. In the end I wanted to have all test-related files in one single directory and I just wanted to see the failed test results so I set it up this way:

# Paths
screenshotRoot          : "./test/blueprints"   # Folder with GIT-staged comparison Blueprints
comparisonResultRoot    : "./test/results"      # Folder for temporary test results
failedComparisonsRoot   : "./test/failures"     # Folder for test failures

# Options
cleanupComparisonImages : true                  # Cleanup results folder after test

Step 4: Test more files with a single command

CasperJS can run only one test at a time. Therefore, in order to test more files with one command, you need to queue them in some way. There seem to be a few approaches—one, two—on how to do it, but this one by Brikou Carre worked for me the best.

Step 5: Test files in multiple environments

In the end, when working on Catalyst, our goal was to run few tests (one per each viewport size) on multiple files so we needed to create an array of functions per each file per each breakpoint. We ended up with the following code which you may also find on Gist.

# Require dependencies
# --------------------

phantomcss  = require("./../../node_modules/phantomcss/phantomcss.js")

# Init PhantomCSS magic
# --------------------
phantomcss.init

  # Paths
  libraryRoot             : "./node_modules/phantomcss"

  screenshotRoot          : "./test/blueprints"   # Folder with GIT-staged comparison Blueprints
  comparisonResultRoot    : "./test/results"      # Folder for temporary test results
  failedComparisonsRoot   : "./test/failures"     # Folder for test failures

  # Options
  addLabelToFailedImage   : false                 # Don't add label to generated failure image
  cleanupComparisonImages : true                  # Cleanup results folder after test
  mismatchTolerance       : 0.00                  # Mismatch tolerance defaults to 0.05%

  # Callbacks
  # onPass: passCallback = ->
  # onFail: failCallback = ->
  # onTimeout: timeoutCallback = ->
  # onComplete: completeCallback = ->

  outputSettings:
    errorColor:
      red: 228
      green: 28
      blue: 113
    errorType: "movement"
    transparency: 0.3

# Define Test scenarios
# --------------------

config = [
  {name: "grid", path: "test/grid.html", viewports: [1440, 1024, 640]}
  {name: "spaces", path: "test/spaces.html", viewports: [1440, 1024, 640]}
  {name: "utilities", path: "test/utilities.html", viewports: [1440, 1024, 640]}
  {name: "visibility", path: "test/visibility.html", viewports: [1440, 1024, 640]}
]

scenarios = config.reduce(((acc, scenario) ->
  acc.concat scenario.viewports.map (viewportWidth) ->
    ->
      @echo scenario.name
      @start scenario.path, ->
        @echo "CURRENTLY TESTING: " + (@getTitle())
      @viewport viewportWidth, 600
      @then ->
        phantomcss.screenshot "body", "#{scenario.name}-#{viewportWidth}" # where (selector, filename)
      @then ->
        phantomcss.compareAll()
  ), [])

casper.start()
casper.then ->
  @echo "Starting"

currentSuite = 0
check = ->
  if scenarios[currentSuite]
    scenarios[currentSuite].call this
    currentSuite++
    casper.run check
  else
    @echo "All done."
    @exit()

casper.run check