PhantomJS 1.3 Release Notes

PhantomJS 1.3, Water Lily, was released on September 23, 2011. It is a minor update, mostly bug fixes and few additional new features.

This version is backward compatible with version 1.2. Existing scripts should work without any modification.

Minimum requirement to build PhantomJS 1.3 is Qt 4.6 or later. Latest stable release of Qt, i.e. version 4.7.4, is strongly recommended.

Initial module support

Module API modelled after CommonJS Modules is available, currently only supporting webpage and fs built-in modules.

For compatibility reason, WebPage object at the global scope is still available. It will be deprecated in some future release. The new recommended way to create a web page is as follows:

var page = require('webpage').create();

page.open(url, function (status) {
    // do something
});

WebPage object improvement

WebPage object wraps a native object that represents the web page. Because of technical limitation, a WebPage object can not be properly garbage collected and freed from the memory. To prevent increasing heap usage when create a lot of WebPage objects, use the new release() function, as in this example:

var page = require('webpage').create();

page.open(url, function (status) {
    // do something
    // ....
    // finish
    page.release();
});

A new callback onInitialized can be used to modify the global objects before a page is loaded. In the following example, further calls to Math.random() effectively will always return the specified constant.

page.onInitialized = function() {
    Math.random = function() {
        return 42;
    };
};

Related to page rasterization using render() function, it is now possible to control the physical scroll offset of the web page using the new property of WebPage called scrollPosition, as illustrated below:

page.scrollPosition = { top: 100, left: 0 };
page.render('output.png');

There is now a convenient way to create a new page by passing an option the constructor:

var page = new WebPage({
    onConsoleMessage: function (msg) {
      console.log(msg);
    },
  
    settings: {
      loadPlugins: false,
      userAgent: 'Dragonless Phantom'
    },
  
    viewportSize: {
      width: 800,
      height: 600
    }
});

Page settings

The behavior of the web page can be further modified by the following new settings:

Example usage:

var page = new WebPage();

page.settings.javascriptEnabled = true;
page.settings.XSSAuditingEnabled = true;
page.settings.localToRemoteUrlAccessEnabled = true;

page.open(url, function (status) {
  // do something
});

Mouse events

Mouse events can be sent to the page using the new sendEvent function, like in the following examples:

page.sendEvent('mousedown', 45, 50);

The first argument is the event type. Other available types are mouseup, mousemove, and click. The next two arguments represents the mouse position.

As of now, left button is the only pressed button for the event. For mousemove however, there is no button pressed (i.e. it is not dragging).

The events are not like synthetic DOM events. Each event is sent to the web page as if it comes as part of user interaction.

File system access

A set of API functions is available to access files and directories. They are modelled after CommonJS Filesystem proposal.

To start using, it needs to be instantiated via the fs module such as:

var fs = require('fs');

Read-only properties:

Query functions:

Directory-related functions:

File-related functions:

A stream object returned from the open() function has the following functions:

As an example of file access API, the following function recursively traverses a directory and prints all the found entries:

function scanDirectory(path) {
    var fs = require('fs');
    if (fs.exists(path) && fs.isFile(path)) {
        console.log(path);
    } else if (fs.isDirectory(path)) {
        fs.list(path).forEach(function (e) {
            if (e !== '.' && e !== '..') {
                scanDirectory(path + '/' + e);
            }
        });
    }
};

Command-line options

Newly available options are:

Rather than passing all options in the command-line, it is also possible to store the options in a file using JavaScript Object Notation (JSON) and then tell PhantomJS to read it:

phantomjs --config=/path/to/config.json script.js arg1 arg2 arg3

where the contents of config.json looks like:

{
    'ignoreSslErrors': true,
    'localToRemoteUrlAccessEnabled': true
}

Platform-specific

Mac OS X: There is no more application bundle, the executable is bin/phantomjs and not bin/phantomjs.app/Contents/MacOS/phantomjs anymore.

Bug fixes

New features

Examples

Back to all releases.