To get up and running with PhantomJS, let's start by installing the toolkit as per the instructions at http://phantomjs.org/download.html. Note that the installation procedures are operating system dependent, with packages for Windows, Mac OS X, and Linux. Alternatively, PhantomJS can be installed directly with NPM using the phantomjs Node.js wrapper (https://github.com/Obvious/phantomjs).

Once installation is complete, you can verify that the PhantomJS binary is available:

$ phantomjs --help

With PhantomJS in place, we next turn to the Mocha-PhantomJS bridge library. Mocha-PhantomJS uses PhantomJS to run a Mocha test driver page and transform the test results into formatted command line output. The library throws proper errors on test failures, making it quite useful for scripting. See the online documentation at http://metaskills.net/mocha-phantomjs/ for additional capabilities and details.

To install Mocha-PhantomJS, you need the Node.js framework, which can be obtained by following the instructions at http://nodejs.org/download/. A modern Node.js installation includes the NPM package manager tool used for Mocha-PhantomJS. We can confirm that Node.js and the package manager are correctly installed with the following commands:

$ node --help
$ npm --help

Next, install Mocha-PhantomJS with the global NPM flag (-g) to make the mocha-phantomjs binary available anywhere in a shell:

$ npm install -g mocha-phantomjs

After NPM finishes the installation, check whether Mocha-PhantomJS is available with the following command:

$ mocha-phantomjs --help

With the necessary tools installed, we can now adapt our Backbone.js test infrastructure to run against PhantomJS. Mocha-PhantomJS provides a replacement proxy object, mochaPhantomJS, to control Mocha tests and reports. We just need to replace the real mocha object where mocha.run() is normally called in the test driver web page. Inserting the following code snippet into the test driver page will allow Mocha to run both in a real browser and with PhantomJS:

<!-- Test Setup -->
<script>
  var expect = chai.expect;
  mocha.setup("bdd");

  window.onload = function () {
    (window.mochaPhantomJS || mocha).run();
  };
</script>

Once we have modified the test driver page with the (window.mochaPhantomJS || mocha).run() function call, we can execute the page tests with Mocha-PhantomJS. For example, if we modify the Notes application test driver file chapters/05/test/test.html from the previous chapter with the mochaPhantomJS change, we can run the file and generate the following command line report:

$ mocha-phantomjs chapters/05/test/test.html


  App.Views.NotesItem
    remove
√ is removed on model destroy
    render
√ renders on model change w/ stub
√ renders on model change w/ mock
    DOM
√ renders data to HTML
    actions
√ views on click
√ edits on click
√ deletes on click
  App.Routers.Router
√ can route to note
√ can route around

  9 tests complete (39 ms)

Reviewing this report, we can see that all of our tests passed, and that the PhantomJS test run was quite fast, clocking in at 39 milliseconds. With these modest test driver web page changes, we can run nearly any test web page from the command line or a build script using PhantomJS.

Putting these suggested principles into practice, nearly all of the test code samples presented in this book are scripted to run from the command line under PhantomJS. If you review the downloadable code samples repository, you will notice that all of the chapter and application test pages actually use the (window.mochaPhantomJS || mocha).run() function call instead of a raw mocha.run() statement.

The integration of PhantomJS into the code samples provides a practical starting point for some of the automated testing use cases that we discussed earlier in this chapter. Specifically, the examples implement the following automation scenarios: