Grunt and PhantomJS, sitting in a tree
npm install grunt-lib-phantomjs> Grunt and PhantomJS, sitting in a tree.
The best way to understand how this lib should be used is by looking at the grunt-contrib-qunit plugin. Mainly, look at how the lib is required, how event handlers are bound and how PhantomJS is actually spawned.
Also, in the case of the grunt-contrib-qunit plugin, it's important to know that the page being loaded into PhantomJS doesn't know it will be loaded into PhantomJS, and as such doesn't have any PhantomJS->Grunt code in it. That communication code, aka. the "bridge", is dynamically injected into the html page.
If a Grunt task looked something like this:
``js
grunt.registerTask('mytask', 'Integrate with phantomjs.', function() {
var phantomjs = require('grunt-lib-phantomjs').init(grunt);
var errorCount = 0;
// Handle any number of namespaced events like so.
phantomjs.on('mytask.ok', function(msg) {
grunt.log.writeln(msg);
});
phantomjs.on('mytask.error', function(msg) {
errorCount++;
grunt.log.error(msg);
});
// Create some kind of "all done" event.
phantomjs.on('mytask.done', function() {
phantomjs.halt();
});
// Built-in error handlers.
phantomjs.on('fail.load', function(url) {
phantomjs.halt();
grunt.warn('PhantomJS unable to load URL.');
});
phantomjs.on('fail.timeout', function() {
phantomjs.halt();
grunt.warn('PhantomJS timed out.');
});
// This task is async.
var done = this.async();
// Spawn phantomjs
phantomjs.spawn('test.html', {
// Additional PhantomJS options.
options: {},
// Complete the task when done.
done: function(err) {
done(err || errorCount === 0);
}
});
});
`
And test.html looked something like this (note the "bridge" is hard-coded into this page and not injected):
`html
// Send messages to the parent PhantomJS process via alert! Good times!!
function sendMessage() {
var args = [].slice.call(arguments);
alert(JSON.stringify(args));
}
sendMessage('mytask.ok', 'Something worked.');
sendMessage('mytask.error', 'Something failed.');
sendMessage('mytask.done');
Then running Grunt would behave something like this:
`shell
$ grunt mytask
Running "mytask" task
Something worked.
>> Something failed.
Warning: Task "mytask" failed. Use --force to continue.Aborted due to warnings.
`
API
$3
Call this when everything has finished successfully, or when something horrible happens, and you need to clean up and abort.
$3
Spawn a
PhantomJS process. The method returns a reference to the spawned process.
This method has the following arguments:#### pageURL
Type:
string
Default: no default value, the user has to set it explicitly.URL or path to the page .html test file to run.
#### Options
Type:
objectThe options object has these possible properties:
##### done
Type:
function
Default: no default value, the user has to set it explicitly.The callback to call when the task is done.
##### failCode
Type:
number
Default: 0The error code to exit with when an Error occurs.
##### killTimeout
Type:
number
Default: 1000 msThe timeout in milliseconds after which the PhantomJS process will be killed.
##### options (PhantomJS options)
Type:
object
Default: {}Additional options to passe to
PhantomJS. This object has the following properties:###### timeout
Type:
number
Default: undefinedPhantomJS' timeout, in milliseconds.
###### inject
Type:
string|array
Default: undefinedOne or multiple (array) JavaScript file names to inject into the page.
###### page
Type:
object
Default: undefinedpage object.###### screenshot
Type:
boolean
Default: undefinedSaves a screenshot on failure
OS Dependencies
PhantomJS requires these dependencies on Ubuntu/Debian:
`
apt-get install libfontconfig1 fontconfig libfontconfig1-dev libfreetype6-dev
``