Access web pages programmatically with PhantomJS, for running tests or scraping information.
var truffler = ;var test =;test;
Table Of Contents
Install Truffler with npm:
npm install truffler
Require in Truffler:
var truffler = ;
Create a test runner by initialising Truffler with a test function. This test function has access to a PhantomJS browser and page instance, as well as a copy of all the passed in options. The test function must accept a third argument which is a callback:
var test =;
Within this function, you have access to all of the behaviour in PhantomJS.
You can also instantiate Truffler with some default options if you wish. This allows you to change the way PhantomJS and your page is loaded:
var test =;
test.run function can then be used to run your test function against a URL:
results parameters contain errors and results from the PhantomJS run against your page. The results can be any object you like. Here's an example test function which returns the page title if it has one, or errors if not.
var test =;test;
Truffler has lots of options you can use to change the way PhantomJS runs, or the way your page is loaded. Options can be set either on the Truffler instance when it's created or the individual test runs. This allows you to set some defaults which can be overridden per-test:
// Set the default Foo header to "bar"var test =;// Run a test with the Foo header set to "bar"test;// Run a test with the Foo header overriddentest;
Below is a reference of all the options that are available:
An object which implments the methods
info which will be used to report errors and test information.
Each of these defaults to an empty function.
A key-value map of request headers to send when testing a web page.
Defaults to an empty object.
A key-value map of settings to add to the PhantomJS page. For a full list of available settings, see the PhantomJS page settings documentation.
resourceTimeout: 30000userAgent: 'truffler/<version>'
The viewport width and height in pixels. The
viewport object must have both
width: 1024height: 768
A key-value map of settings to initialise PhantomJS with. This is passed directly into the
phantom module – documentation can be found here. You can pass PhantomJS command-line parameters in the
phantom.parameters option as key-value pairs.
Defaults to an empty object. If
phantom.port is not specified, a random available port will be used.
The maximum time (in milliseconds) that Truffler should run for. This timeout can sometimes be exceeded, if a long-running task has started within PhantomJS itself. This is rare, but you shouldn't rely on exact timing.
If the timeout is exceeded, the test function will callback with an error and no results.
30000 (30 seconds).
Run Truffler on a URL and output the page title:
Use async to run Truffler on multiple URLs in series, and output the page titles:
To contribute to Truffler, clone this repo locally and commit your code on a separate branch.
Please write unit tests for your code, and check that everything works by running the following before opening a pull-request:
Support and Migration
Truffler major versions are normally supported for 6 months after their last minor release. This means that patch-level changes will be added and bugs will be fixed. The table below outlines the end-of-support dates for major versions, and the last minor release for that version.
We also maintain a migration guide to help you migrate.
|❔||Major Version||Last Minor Release||Node.js Versions||Support End Date|
If you're opening issues related to these, please mention the version that the issue relates to.
Truffler is licensed under the MIT license.
Copyright © 2015, Springer Nature