# phantom-proxy * Allows you to drive [phantomjs](www.phantomjs.org) from [node](www.nodejs.org) * Does not rely on alert side effects for communicating with phantomjs * Uses Phantom's embedded mongoose web server for communication - more efficient, simpler, faster. * Provides a full api - including a parametrized evaluate function - no more hard coded strings * Provides additional useful methods such as waitForSelector * Can easily integrate with feature testing frameworks such as [cucumber](https://github.com/cucumber/cucumber-js), jasmine, mocha ## Overview PhantomJs is an incredibly useful tool for functional and unit testing. PhantomJs runs in its own process, making it difficult to drive from node. Phantom-proxy solves this problem, allowing you to fully drive phantomjs from node. ## Installation `npm install phantom-proxy` ## Usage ### Examples See the [API](https://github.com/sheebz/phantom-proxy/blob/master/api.md) documentation for more usage information. #### wait for a specific selector to appear ```javascript var phantomProxy = require('phantom-proxy'); phantomProxy.create({}, function (proxy) { var page = proxy.page; page.open('http://www.w3.org', function () { page.waitForSelector('body', function () { console.log('body tag present'); proxy.end(); }); }); }); ``` #### render a screenshot ```javascript phantomProxy.create({"debug":true}, function (proxy) { proxy.page.open('http://www.w3.org', function (result) { assert.equal(result, true); proxy.page.waitForSelector('body', function (result) { assert.equal(result, true); proxy.page.render('./scratch/scratch.png', function (result) { assert.equal(result, true); proxy.end(function () { console.log('done'); }); }); }, 1000); }); }); ``` #### subscribe to events - see api docs for complete list ```javascript phantomProxy.create({"debug":true}, function (proxy) { self.proxy.page.on('navigationRequested', function (url) { console.log('at %s', url); if (url === 'http://www.w3.org') { console.log('at w3.org'); } else { console.log('how did we get here?'); } proxy.end(function () { console.log('done'); }); }); proxy.page.open('http://www.w3.org', function (result) { proxy.page.on('alert', function (msg) { if (msg.trim() === 'hello') { console.log('it said hello'); } proxy.end(function () { console.log('done'); }); }); }); }); ``` # API Documentation ## phantomProxy object ### create([options], callbackFn) use this method to create an instance of the phantom proxy objects. The return value will be an object with a page proxy and a phantom proxy. These properties correspond to the phantom and webpage objects on the native phantom API. When this method is called, a new phantomjs process is spawned. The new phantomjs process creates a mongoose webserver on localhost:1061. All subsequent communication with phantom occurs via http requests. #### Options argument (experimental) Create accepts an options object as the first parameter. This argument is optional. Properties and their default values are listed below. ```javascript var defaultoptions = { 'ignoreSslErrors':true, 'localToRemoteUrlAccessEnabled':true, 'cookiesFile':'cookies.txt', 'diskCache':'yes', 'loadImages':'yes', 'localToRemoteUrlAccess':'no', 'maxDiskCache':'50000', 'outputEncoding':'utf8', 'proxy':'0', 'proxyType':'yes', 'scriptEncoding':'yes', 'webSecurity':'yes', 'port':1061 }; ``` ### end(callbackFn) You should call end on the returned proxy object to ensure that phantomjs is properly shut down. ```javascript var phantomProxy = require('phantom-proxy').create(function(proxy){ var page = proxy.page, phantom = proxy.phantom; //do some stuff... //... //call end when done proxy.end(function(){ console.log('phantom has exited'); }); }); ``` ## phantom Object The phantom object corresponds to the phantom object in the native phantomJs API. ## Page Object The page object corresponds to the webpage object in the native phantomJs API. ### set(propertyName, propertyValue, callbackFn) sets setting on page object ```javascript proxy.page.set('userAgent', 'iPad', function (result) { console.log(result.toString()); }); ``` ### get(propertyName, callbackFn) gets a setting on page object ```javascript proxy.page.get('userAgent', function (result) { console.log(result.toString()); }); ``` ### open(url, callbackFn) Opens a webpage with url and callback function arguments. ```javascript var phantomProxy = require('phantom-proxy').create({}, function(proxy){ var page = proxy.page, phantom = proxy.phantom; page.open('http://www.w3.org', function(){ console.log('page now open'); //close proxy phantomProxy.end(); }); }); ``` ### waitForSelector(selector, callbackFn, timeout) Polls page for presence of selector, executes callback when selector is present. ```javascript var phantomProxy = require('phantom-proxy').create({}, function(proxy){ var page = proxy.page, phantom = proxy.phantom; page.open('http://www.w3.org', function(){ page.waitForSelector('body', function(){ console.log('body tag present'); //close proxy phantomProxy.end(); }); console.log('page now open'); }); }); ``` ### render(fileName, callbackFn) Renders a image of browser. ```javascript var phantomProxy = require('phantom-proxy').create({}, function(proxy){ var page = proxy.page, phantom = proxy.phantom; page.open('http://www.w3.org', function(){ page.waitForSelector('body', function(){ console.log('body tag present'); page.render('myimage.png', function(){ console.log('saved my picture!'); //close proxy phantomProxy.end(); }); }); console.log('page now open'); }); }); ``` ### renderBase64(type, callbackFn) Returns a base64 representation of image. ### evaluate(functionToEvaluate, callbackFn, [arg1, arg2,... argN] Executes functionToEvaluate in phantomJS browser. Once function executes, callbackFn will be invoked with a result parameter. The Third and sebsequent arguments represent optional parameters which will be passed to the functionToEvaluate function when it is invoked in the browser. ## Events The following events are supported, see [PhantomJs Docs](https://github.com/ariya/phantomjs/wiki/API-Reference) for more information.

Event Name	Notes
urlChanged
resourceReceived
resourceRequested
prompt	Event will fire, but callback will not execute in phantomjs context
pageCreated
navigationRequested
loadStarted
loadFinished
initialized
error
consoleMessage
confirm	See onConfirmCallback for handling this event
closing
callback
alert

#### Subscribing to events ```javascript phantomProxy = require('phantom-proxy'); phantomProxy.create({}, function (proxy) { proxy.page.on('urlChanged', function(){ console.log('url changed'); }); }); ``` #### Special events Some phantomjs functions allow you to return a value to drive phantom interaction. Currently, onConfirm is supported. To register a callback function for intercepting confirm dialogs, use onConfirmCallback: ```javascript // return true corresponds to accepting confirm, return false is denying proxy.page.set('onConfirmCallback', function(msg) { return true; }); ``` Pre-registering a confirm function can be useful if you encounter a page that prompts you when you try to leave. Without registering a function that returns true, phantomjs will hang. Please note you can still listen for the 'confirm' event in conjunction with this special handler. ## Revision History * 2012-11-06 - version 0.1.6 - reworked event communication interface to use socket.io - no longer using filesyste to pass event messages, should help with dropped msgs * 2012-11-06 - version 0.1.6 - reworked event communication interface - no longer using stdoutput to pass event messages - reworked process creation and exit logic - startup time and event latency are much improved - should run much faster than before * 2012-11-03 - version 0.1.3 - added callback parameter to end method on proxy. - removed unref call in proxy - added debug option * 2012-10-22 - version 0.1.2 - breaking - changed the way events are consumed, switched to using nodes emmitter to brodcast events as opposed to invoking instance methods on the object. To fix issues, use [object].on('eventname') style syntax. - Code clean up * 2012-10-17 - version 0.1.16 - fixed waitforSelector issue * 2012-10-12 - version 0.1.15 - fixed a problem w/ waitforSelector fn. - fixed problem where process wasn't shutting down existing server. * version 0.1.13 - added args property handling for phantom object - added ability to specify port for rpc channel - added timeout on waitforSelector function - added ability to pass cmd line arguments for phantom via options object * version 0.1.10 - cleaned up and reorganized code - added unit tests - fixed process related issues