• page

PhantomJS funcunit.phantomjs


PhantomJS is a headless WebKit. FuncUnit integrates with Phantom to run tests from the commandline. This has large performance benefits, enough that it makes it much more feasible to integrate FuncUnit tests into your build process without significantly slowing it down.

FuncUnit supports running in phantom two ways: via Rhino (like the rest of JMVC) and via NodeJS (the future of JMVC).

Rhino Mode

The advantage to Rhino mode is there is little additional setup. If you're already using JMVC, you have Java installed, so all you must do is install PhantomJS.

The disadvantage to Rhino mode is, due to a compatibility issue, it is required to use an old version of Phantom - 1.3.0.


Before you can use PhantomJS, you have to install it. The other automation tools come prepackaged in JMVC, but Phantom is too large of a download.

Note: There is a known issue with Phantom 1.4.0+ in Rhino Mode. Please be sure to use Phantom 1.3.0 to avoid Broken Pipe errors.

On Mac

  1. Download PhantomJS
  2. Unzip it somewhere like: /Applications/
  3. Add it to your path:
sudo ln -s /Applications/phantomjs-1.3.0/bin/phantomjs /usr/local/bin/

Note: Not all systems will have /usr/local/bin/. Some systems will have: /usr/bin/, /bin/, or usr/X11/bin instead.

On Windows

  1. Download PhantomJS
  2. Install it
  3. Add it to your path. For information on setting path variable in Windows, click here.


To run any test via PhantomJS:

./js funcunit/open/phantomjs http://localhost/path/to/funcunit.html

NodeJS Mode

The advantage to NodeJS mode is Node is faster than Rhino and can integrate with [funcunit.grunt GruntJS.

The disadvantage to NodeJS mode is you have to install and setup Node and NPM.


  1. Install NodeJS. It should come with NPM - Node's package manager.
  2. Install the latest PhantomJS. Make sure the binary is in your PATH - Instructions on this are listed above in Rhino Mode Install.
  3. cd funcunit and npm install to install FuncUnit's node module dependencies.


To run any test via PhantomJS in NodeJS:

node node funcunit/node/run.js http://localhost/path/to/funcunit.html

Differences between Phantom and other browsers

Drag events

Note that Phantom emulates mobile Webkit, so it provides support for touch events. Because of this, FuncUnit drag actions don't work in Phantom.

Iframe vs window.open

In Rhino mode, calling S.open will open an iframe in the funcunit.html page, rather than a separate window via window.open. Phantom 1.3.0 doesn't support window.open, so a frame is used instead. This can occassionally cause problems if your application assumes it is running within window.top.

In NodeJS mode we're running off latest Phantom 1.8.0 that does support window.open, so this isn't an issue.


If you notice a broken test, debugging it in Phantom is not the place to start. Open the test in browser, and verify the same test breaks there. If so, debug the test in browser.

If you notice the more rare event that a test breaks in Phantom but works in browser, you can use console.log to debug it. In steal/browser/phantomjs/launcher.js, uncomment the page.onConsoleMessage function. Add console.logs to your code and debug.