WebPageTest API Wrapper for NodeJS 
WebPageTest API Wrapper is a NPM package that wraps WebPageTest API for NodeJS as a module and a command-line tool.
Getting started
$ npm install webpagetest -g
Basics
Command line
$ webpagetest test http://twitter.com/marcelduran
Module
var WebPageTest = require('webpagetest');
var wpt = new WebPageTest('www.webpagetest.org');
wpt.runTest('http://twitter.com/marcelduran', function (err, data) {
if (err) throw err;
console.log(data);
});
API Console Demo
marcelduran.com/webpagetest-api
Command Line
Help
$ webpagetest --help
Commands
- status <id>: check test status
- results <id>: get test results
- locations: list locations and the number of pending tests
- testers: list testers status and details
- test [options] <url_or_script>: run test, <url_or_script> can also be a path to a script file
- cancel <id>: cancel running/pending test
- har <id>: get the HTTPS Archive (HAR) from test
- pagespeed [options] <id>: get the Google Page Speed results (if available) from test
- utilization [options] <id>: get the CPU, bandwidth and memory utilization data from test
- request [options] <\id>: get the request data from test
- timeline [options] <id>: get the Chrome Developer Tools Timeline data (if available) from test
- netlog [options] <id>: get the Chrome Developer Tools Net log data (if available) from test
- console [options] <id>: get the browser console log data (if available) from test
- testinfo <id>: get test request info/details
- waterfall [options] <id>: get the waterfall PNG image
- screenshot [options] <id>: get the fully loaded page screenshot in JPG format (PNG if in full resolution)
- listen [port]: start webpagetest-api server on port [7791]
Options
Common (works for all commands)
- -s, --server <server>: the WPT server URL [http://www.webpagetest.org]
- -d, --dryrun: just return the RESTful API URL
- -o, --out <file>: place the output into <file>. Defaults to stdout
The default WPT server can also be specified via environment variable WEBPAGETEST_SERVER
Test (works for test command only)
- -k, --key <api_key>:API key (if assigned). Contact the WebPageTest server administrator for a key if required
- -l, --location <location>: location to test from
- -r, --runs <number>: number of test runs [1]
- -f, --first: skip the Repeat View test
- -L, --label <label>: label for the test
- -p, --private: keep the test hidden from the test log
- -v, --video: capture video
- -y, --connectivity <profile>: connectivity profile (DSL|FIOS|Dial|custom) [DSL]
- -m, --dom <element>: DOM element to record for sub-measurement
- -c, --connections <number>: override the number of concurrent connections
- -i, --onload: force the test to stop at window.onload
- -t, --sensitive: discard script and http headers in the result
- -b, --block <urls>: space-delimited list of urls to block (substring match)
- -g, --login <username>: username for authenticating tests (http authentication)
- -w, --password <password>: password for authenticating tests (http authentication)
- -a, --authtype <type>: type of authentication: 0 = Basic, 1 = SNS [0]
- -e, --request <id>: echo request ID, useful to track asynchronous requests
- -n, --notify <e-mail>: e-mail address to notify with the test results
- -B, --pingback <url>: URL to ping when the test is complete (the test ID will be passed as an "id" parameter)
- -D, --bwdown <bandwidth>: download bandwidth in Kbps (used when specifying a custom connectivity profile)
- -U, --bwup <bandwidth>: upload bandwidth in Kbps (used when specifying a custom connectivity profile)
- -Y, --latency <time>: first-hop Round Trip Time in ms (used when specifying a custom connectivity profile)
- -P, --plr <percentage>: packet loss rate - percent of packets to drop (used when specifying a custom connectivity profile)
- -u, --tcpdump: enable tcpdump capture
- -z, --noopt: disable optimization checks (for faster testing)
- -I, --noimages: disable screen shot capturing
- -H, --noheaders: disable saving of the http headers (as well as browser status messages and CPU utilization)
- -F, --full: save a full-resolution version of the fully loaded screen shot as a PNG
- -j, --jpeg <level>: jpeg compression level (30-100) for the screen shots and video capture
- -S, --noscript: disable javascript (IE, Chrome, Firefox)
- -R, --ignoressl: ignore SSL certificate errors, e.g. name mismatch, self-signed certificates, etc
- -T, --standards: forces all pages to load in standards mode (IE only)
- -O, --bodies: save response bodies for text resources
- -K, --keepua: do not add PTST to the original browser User Agent string
- -N, --duration <seconds>: minimum test duration in seconds
- -A, --noads: block ads defined by adblockrules.org
- -E, --aft: (experimental) measure above-the-fold rendering time
- -M, --timeline: capture Developer Tools Timeline (Chrome only)
- -G, --netlog: capture Network Log (Chrome only)
- -Z, --spof <domains>: space-delimited list of domains to simulate failure by re-routing to blackhole.webpagetest.org to silently drop all requests
Run (works for pagespeed, utilization, request, timeline, netlog, console, waterfall and screenshot commands)
- -r, --run <number>: which run number on a multiple runs test [1]
- -c, --cached: get the Repeat View (cached view) instead of default First View (primed cache)
Image (works for waterfall and screenshot commands)
- -t, --thumbnail: get the thumbnail of actual image
- -u, --uri: return the base64 string representation (inline) of actual image
Screenshot (works for screenshot command only)
- -f, --full: get full resolution screenshot in PNG format if available
- -n, --render: get the page screenshot at the Start Render point (i.e.: when something was first displayed on screen)
- -p, --complete: get the page screenshot at the Document Complete point (i.e.: when window.onload was fired)
Examples
1. Get available locations
$ webpagetest locations
{
"response": {
"statusCode": 200, "statusText": "Ok",
"data": {
"location": [
...
{
"id": "SanJose_IE9",
"Label": "San Jose, CA USA (IE 9,Chrome,Firefox)",
"location": "SanJose_IE9",
"Browser": "IE 9",
"PendingTests": {
"p1": 0, "p2": 0, "p3": 0, "p4": 0, "p5": 2, "p6": 2, "p7": 0,
"p8": 0, "p9": 0, "Total": 7, "HighPriority": 2, "LowPriority": 4,
"Testing": 1, "Idle": 0
}
},
...
]
}
}
}
$ webpagetest test http://twitter.com/marcelduran --key 1F2A3K4E5 --location SanJose_IE9
{
"statusCode": 200,
"statusText": "Ok",
"data": {
"testId": "121025_PT_N8K",
"ownerKey": "868cb2813a0f376a977dd1a24ab041b4f12361b3",
"jsonUrl": "http://localhost/results.php?test=121025_PT_N8K&f=json",
"xmlUrl": "http://localhost/xmlResult.php?test=121025_PT_N8K",
"userUrl": "http://localhost/results.php?test=121025_PT_N8K",
"summaryCSV": "http://localhost/csv.php?test=121025_PT_N8K",
"detailCSV": "http://localhost/csv.php?test=121025_PT_N8K&requests=1"
}
}
3. Check current test status
$ webpagetest status 121025_PT_N8K
{
"statusCode": 101,
"statusText": "Test Pending",
"data": {
"statusCode": 101,
"statusText": "Test Pending",
"testId": "121025_PT_N8K",
"runs": 1,
"fvonly": 0,
"location": "SanJose_IE9"
}
}
4. Get test results
$ webpagetest results 121025_PT_N8K
{
"response": {
"statusCode": 200, "statusText": "Ok",
"data": {
"testId": "121025_PT_N8K",
"summary": "http://www.webpagetest.org/result/121025_PT_N8K/",
"testUrl": "http://twitter.com/marcelduran",
"location": "SanJose_IE9",
"connectivity": "DSL",
"bwDown": 1500, "bwUp": 384, "latency": 50, "plr": 0,
"completed": "Thu, 25 Oct 2012 23:42:11 +0000",
"runs": 1, "successfulFVRuns": 1,
"average": {
"firstView": {
"loadTime": 3942, "TTFB": 1518,
"bytesIn": 963405, "bytesInDoc": 431612,
"requests": 32, "requestsDoc": 19,
"render": 2509, "fullyLoaded": 7765,
"docTime": 3942, "domTime": 0,
"titleTime": 1641, "avgRun": 1
}
},
...
}
}
}
5. Get test waterfall thumbnail from repeat view as data URI
$ webpagetest waterfall 121025_PT_N8K --thumbnail --cached --uri
{
"type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgA...RK5CYII="
}
Module
Methods
getTestStatus(id, options, callback)getTestResults(id, options, callback)getLocations(options, callback)getTesters(options, callback)runTest(url_or_script, options, callback)cancelTest(id, options, callback)getHARData(id, options, callback)getPageSpeedData(id, options, callback)getUtilizationData(id, options, callback)getRequestData(id, options, callback)getTimelineData(id, options, callback)getNetLogData(id, options, callback)getConsoleLogData(id, options, callback)getTestInfo(id, options, callback)getWaterfallImage(id, options, callback)getScreenshotImage(id, options, callback)listen(port, callback)scriptToString(script)
Parameters
- id: test ID string required
- options: parameters object optional, see below
- callback: the callback
function(error, data) optional - url_or_script: decoded url or script string required
- port: port number optional [default: 7791]
- script: script array in the format:
[
{command1: 'value1'},
{command2: 123},
{command3: ['value1', 'value2', ... , 'valueN']},
...
'commandN'}
]
Notes
getWaterfallImage and getScreenshotImage callback function has a third parameter info which is an object with {type: 'image/jpeg or png', encoding: 'utf8 or binary'}scriptToString script array values 1-N are optional. e.g:
var script = wpt.scriptToString([
{logData: 0},
{navigate: 'http://foo.com/login'},
{logData: 1},
{setValue: ['name=username', 'johndoe']},
{setValue: ['name=password', '12345']},
{submitForm: 'action=http://foo.com/main'},
'waitForComplete'
]);
wpt.runTest(script, function (err, data) {console.log(err || data);});
Options
Common (works for all methods with options parameter)
- dryRun: Boolean, if
true, method does not make an actual request to the API Server but rather returns an object with url which contains the actual URL to make the GET request to WebPageTest API Server - server: String, if specified, overrides the WebPageTest server informed in the constructor only for that method call
Test (works for runTest method only)
- key: String, API key (if assigned). Contact the WebPageTest server administrator for a key if required
- location: String, location to test from
- runs: Number, number of test runs [1]
- firstViewOnly: Boolean, skip the Repeat View test
- label: String, label for the test
- private: Boolean, keep the test hidden from the test log
- video: Boolean, capture video
- connectivity: String, connectivity profile (DSL|FIOS|Dial|custom) [DSL]
- domElement: String, DOM element to record for sub-measurement
- connections: Number, override the number of concurrent connections
- stopAtDocumentComplete: Boolean, force the test to stop at window.onload
- sensitive: Boolean, discard script and http headers in the result
- block: [String], array of string of urls to block (substring match)
- login: String, username for authenticating tests (http authentication)
- password: String, password for authenticating tests (http authentication)
- authenticationType: Number, type of authentication: 0 = Basic, 1 = SNS [0]
- requestId: String, echo request ID, useful to track asynchronous requests
- notifyEmail: String, e-mail address to notify with the test results
- pingback: String, URL to ping when the test is complete (the test ID will be passed as an "id" parameter)
- bandwidthDown: String, download bandwidth in Kbps (used when specifying a custom connectivity profile)
- bandwidthUp: String, upload bandwidth in Kbps (used when specifying a custom connectivity profile)
- latency: String, first-hop Round Trip Time in ms (used when specifying a custom connectivity profile)
- packetLossRate: Number, packet loss rate - percent of packets to drop (used when specifying a custom connectivity profile)
- tcpDump: Boolean, enable tcpdump capture
- disableOptimization: Boolean, disable optimization checks (for faster testing)
- disableScreenshot: Boolean, disable screen shot capturing
- disableHTTPHeaders: Boolean, disable saving of the http headers (as well as browser status messages and CPU utilization)
- fullResolutionScreenshot: Boolean, save a full-resolution version of the fully loaded screen shot as a PNG
- jpegQuality: Number, jpeg compression level (30-100) for the screen shots and video capture
- disableJavaScript: Boolean, disable javascript (IE, Chrome, Firefox)
- ignoreSSL: Boolean, ignore SSL certificate errors, e.g. name mismatch, self-signed certificates, etc
- disableCompatibilityView: Boolean, forces all pages to load in standards mode (IE only)
- saveResponseBodies: Boolean, save response bodies for text resources
- keepOriginalUserAgent: Boolean, do not add PTST to the original browser User Agent string
- minimumDuration: String, minimum test duration in seconds
- blockAds: Boolean, block ads defined by adblockrules.org
- aftRenderingTime: Boolean, (experimental) measure above-the-fold rendering time
- timeline: Boolean, capture Developer Tools Timeline (Chrome only)
- netLog: Boolean, capture Network Log (Chrome only)
- spof: [String], array of string of domains to simulate failure by re-routing to blackhole.webpagetest.org to silently drop all requests
Run (works for getPageSpeedData, getUtilizationData, getRequestData, getTimelineData, getNetLogData, getConsoleLogData, getWaterfallImage and getScreenshotImage methods)
- run: Number, the test run number for multiple runs tests (default: 1, first test)
- repeatView: Boolean, if
true returns the repeat view (cached) data
Image (works for getWaterfallImage and getScreenshotImage methods)
- thumbnail: Boolean, returns the thumbnail of actual image
- dataURI: Boolean, returns the base64 string representation (inline) of actual image
Screenshot (works for getScreenshotImage method only)
- fullResolution: Boolean, returns the full resolution screenshot in PNG format if available
- startRender: Boolean, returns the page screenshot at the Start Render point (i.e.: when something was first displayed on screen)
- documentComplete: Boolean, returns the page screenshot at the Document Complete point (i.e.: when
window.onload was fired)
Examples
1. Instantiating
var WebPageTest = require('webpagetest');
var wpt = new WebPageTest('my-wpt.foo.com');
var wptPublic = new WebPageTest('www.webpagetest.org', 'MY_API_KEY');
2. Get available locations
wpt.getLocations(function (err, data) {
if (err) throw err;
console.log(data);
});
wpt.runTest('http://twitter.com/marcelduran', {location: 'SanJose_IE9'}, function (err, data) {
if (err) throw err;
console.log(data);
});
4. Check current test status
wpt.getTestStatus('121025_PT_N8K', function (err, data) {
if (err) throw err;
console.log(data);
});
5. Get test results
wpt.getTestResults('121025_PT_N8K', function (err, data) {
if (err) throw err;
console.log(data);
});
6. Get test waterfall thumbnail from repeat view as data URI
wpt.getWaterfallImage('121025_PT_N8K', {
thumbnail: true,
repeatView: true,
dataURI: true
}, function (err, data, info) {
if (err) throw err;
console.log(data, info);
}
);
Server mode
WebPageTest API Wrapper comes with a handy RESTful API proxy
Command Line
$ webpagetest listen 8080 --server wpt.foo.com
server listening on port 8080
http://localhost:8080
$ curl http://localhost:8080/help
$ curl http://localhost:8080/test/twitter.com/?location=SanJose_IE9
Notes
- port 8080 is optional, default port is 7791
wpt.foo.com is overriding the default www.webpagetest.org server but can still be overridden with server option
Module
var server = wpt.listen(8080, function(err, data) {
if (err) throw err;
console.log('listening on ' + data.url);
});
setTimeout(function() {
server.close(function() {
console.log('listening done');
});
}, 10000);
Issues
Have a bug/feature request? Please create an issue here on GitHub!
https://github.com/marcelduran/webpagetest-api/issues
Author
Marcel Duran
License
Copyright 2013 Twitter, Inc. and other contributors
Licensed under the MIT License
