Phantom JS: an alternative to Selenium

DZone 's Guide to

Phantom JS: an alternative to Selenium

· Agile Zone ·
Free Resource

PhantomJS is an headless browser based on an embedded webkit, suitable for testing of web applications involving JavaScript usage where simpler tools do not cut it.
Some people from Sencha (Ext JS creators) are behind the tool, and my colleague recently told me about it. We had some trouble using jsTestDriver because it's focused on unit tests, while here we needed just some walkthrough for the UI (end-to-end testing): the business logic is tested elsewhere.

He also compiled it beforehand, so I'm going through the installation process again by myself in this article. Don't let the word compile scare you: on Linux, it's just a couple of lines with no invasion of your /usr folder.


The Api of Phantom JS is based on JavaScript: how would you execute code in a browser? Web sites JavaScript code is sandboxed, so that it does not interact with the main tool. Nothing is rendered to the screen, as the usage is command-line based.

Phantom JS is a real browser, supporting DOM manipulation, Ajax calls, Canvas elements and more; it's able to load entire html pages for end-to-end testing and only Selenium compares with it in functionality.


I needed to download via apt about 50MB of QT libraries, but the compiling process is smooth. There are also binaries for Windows systems.

On Ubuntu, four commands are all you need:

sudo apt-get install libqt4-dev libqtwebkit-dev qt4-qmake
git clone git://github.com/ariya/phantomjs.git && cd phantomjs
git checkout 1.2
qmake-qt4 && make

Afterwards, you can cut the phantomjs binary from the bin/ folder in the checked out repository, and paste it wherever you want.


Tests are written as procedural scripts in JavaScript (or CoffeeScript if you want). There are no shared resources between the Phantom environment and the window environment, where the web applications code is loaded.

Let's see the example from the documentation where we read a bunch of tweets.

First of all, create a new WebPage object, which will be our Facade for the browser window.

var page = new WebPage();

console.log() executed in the Phantom scope will actually print to the standard output. Instead, console.log() executed in the browser environment will just write to its own console, which is not visible. This event redirect any console.log() executed in the window environment to the console.log method of Phantom, so that any log in the script gets printed.

page.onConsoleMessage = function(msg) {

The page.open method takes an URL to load and a function to execute one the loading has been complete. Usually you're only interested in going on if success is reached.

page.open("http://mobile.twitter.com/giorgiosironi", function (status) {
    if (status !== "success") {
        console.log("Unable to access network");
    } else {

page.evaluate executes a closure inside the browser's environment. It's important to understand that the two scopes:

  • Phantom, containing the page object;
  • window, containing the JavaScript code loaded by the page;

are totally disconnected and may communicate only via page.evaluate (which may return scalar values) and via the page.onConsoleMessage described earlier.

This may be confusing at first, but you can think of page.evaluate() as executing callback.toSource() and sending the result to the loaded page over the wire.

You cannot access variables in the Phantom scope from the closure run in the window scope: in this case we're only accessing document and console, which are global objects of the window environment.

        page.evaluate(function() {
            var list = document.querySelectorAll('span.status');
            for (var i = 0; i < list.length; ++i) {
                console.log((i + 1) + ": " + list[i].innerHTML.replace(/<.*?>/g, ''));

When phantom.exit is called, execution stops and the control is returned to the terminal where it was executed.


Usage is very simple:

[13:17:45][giorgio@Desmond:~]$ phantomjs example.js
1: @felhobacsi I'am checking *everything*, actually I'm installing a VM just to play with it :)
2: @AnthonySterling it makes even more sense given the new type hint wiki.php.net/rfc/callable

These were my last tweets while writing this article. We're running a simple

for i in $(find . -name '*.js'); do phantomjs $i; done;

to run all our scripts independently.

As a testing tool

PhantomJS does not ship assertions, and you shouldn't throw exceptions from the window scope, as they will be probably swallowed by the browser or a JavaScript framework. We log errors by outputting a . or F with console.log at each assertion. These assertion methods are not in the actual web page, but are loaded from the filesystem with:


or via a <script> tag, which is the simplest solution.

The console.log redirection can also be used for termination: in the handler for page.onConsoleMessage you can call phantom.exit in case the message is a special keyword like 'END_OF_TEST'.

Redirects and Ajax

You can listen for the completion of a new page loading with :

page.onLoadFinished = function (status) { ... };

which will work for redirects on the client or server side.

To find out wheen Ajax requests have been completed, you'll have to rely on your JavaScript framework and on its events (unless you want to just wait 2 seconds with setInterval or setTimeout). For Ext JS, an handler can be defined in the window scope:

Ext.Ajax.on('requestcomplete', function() { ... });


Phantom JS is promising and it seems that end-to-end test can be effectively performed: we even make it compile a form and login before each test, and follow the redirect; it's like having an actual browser.

The tool is also fundamentally different from Selenium 1.x as it favors executing JavaScript inside the browser window instead of driving the test via a standard Api. One example of the power of this approach is that we transformed the tests from asynchronous:

selenium.clickAndWait("Login", 60000);

to synchronous, where the assertion handlers are called just right after the completion of the request:

Ext.Ajax.on('requestcomplete', function() {
    if (...) {
        console.log('F: failure in snafucating the grid');

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}