web5design / webpagetest-api

WebPageTest API wrapper for NodeJS

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) {
  console.log(err || data);
});

API Console Demo

marcelduran.com/webpagetest-api

Command Line

Help

$ webpagetest --help

Commands

• status [options] <id>: check test status
• results [options] <id>: get test results
• locations [options]: list locations and the number of pending tests
• testers [options]: 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]
• batch <file>: run commands in batch, i.e. one command per line from <file> in parallel

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)

• -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]
• -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
• -Z, --spof <domains>: space-delimited list of domains to simulate failure by re-routing to blackhole.webpagetest.org to silently drop all requests
• -W, --mobile: (experimental) emulate mobile browser: Chrome mobile user agent, 640x960 screen, 2x scaling and fixed viewport (Chrome only)
• -M, --timeline: capture Developer Tools Timeline (Chrome only)
• -G, --netlog: capture Network Log (Chrome only)
• -C, --spdy3: force SPDY version 3 (Chrome only)
• -J, --swrender: force software rendering, disable GPU acceleration (Chrome only)
• -Q, --noparser: disable threaded HTML parser (Chrome only)
• -q, --spdynossl: use SPDY without SSL (Chrome only)
• --cmdline <switches>: use a list of custom command line switches (Chrome only)
• --poll [interval]: poll for results after test is scheduled at every <interva\l> seconds [5]
• --wait [hostname:port]: wait for test results informed by agent once complete listening on <hostname>:<port> [hostname:first port available above 8000]
• --timeout <seconds>: timeout for polling and waiting results [no timeout]

API Key (works for test and cancel commands)

• -k, --key <api_key>:API key (if assigned). Contact the WebPageTest server administrator for a key if required

Request (works for status, results, locations, testers and test commands)

• -e, --request <id>: echo request ID, useful to track asynchronous requests

Results (works for results and test commands)

• -b, --breakdown: include the breakdown of requests and bytes by mime type
• -D, --domains: include the breakdown of requests and bytes by domain
• -p, --pagespeed: include the PageSpeed score in the response (may be slower)
• -R, --requests: include the request data in the response (slower and results in much larger responses)
• -m, --median <metric>: set the metric used to calculate median for multiple runs tests [loadTime]
• -S, --specs <json_or_file>: set the specs for performance test suite
• -r, --reporter <name>: set performance test suite reporter output: [dot]|spec|tap|xunit|list|progress|min|nyan|landing|json|doc|markdown|teamcity

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)

Waterfall (works for waterfall command only)

• -T, --type <chart>: set the chart type: waterfall or connection [waterfall]
• -M, --mime: set chart coloring by MIME type [false]
• -w, --width <px>: chart image width in px (300-2000) [930]
• -m, --max <seconds>: set maximum time in seconds [automatic]
• -R, --requests <items>: filter requests (e.g.:1,2,3,4-9,8) [all]
• -C, --nocpu: hide CPU utilization [false]
• -b, --nobandwidth: hide bandwidth utilization [false]
• -e, --noellipsis: hide ellipsis (...) for missing items [false]
• -l, --nolabels: hide labels for requests (URL) [false]

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
          }
        },
        ...
      ]
    }
  }
}

2. Run test on http://twitter.com/marcelduran from San Jose on IE9

$ 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="
}

Run test on http://twitter.com/marcelduran and poll results every 5 seconds timing out in 60 seconds

$ webpagetest test http://twitter.com/marcelduran --poll 5 --timeout 60

Or run test on http://twitter.com/marcelduran and wait for results listening on localhost* port 8000**

$ webpagetest test http://twitter.com/marcelduran --wait 8000

{
  "response": {
    "statusCode": 200, "statusText": "Ok",
    "data": {
      "testId": "121025_PT_N8K",
      "testUrl": "http://twitter.com/marcelduran",
      ...
      "median": {
        "firstView": {
          "loadTime": 3942, "TTFB": 1518,
          "render": 2509, "fullyLoaded": 7765,
          ...
        }
      },
      ...
    }
  }
}

* hostname and port are optional, defaults to <system hostname>:<8000> ** localhost and port must be reacheable from WebPageTest server

Module

Methods and options (including the one letter shorthands) are the same when using as a Node module, however a more verbose version of both commands (methods) and options (parameters) are available and encouraged to use for code clarity.

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)

• 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]
• 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
• spof: [String], array of string of domains to simulate failure by re-routing to blackhole.webpagetest.org to silently drop all requests
• emulateMobile: Boolean, (experimental) emulate mobile browser: Chrome mobile user agent, 640x960 screen, 2x scaling and fixed viewport (Chrome only)
• timeline: Boolean, capture Developer Tools Timeline (Chrome only)
• netLog: Boolean, capture Network Log (Chrome only)
• forceSpdy3: Boolean, force SPDY version 3 (Chrome only)
• forceSoftwareRendering: Boolean, force software rendering, disable GPU acceleration (Chrome only)
• disableThreadedParser: Boolean, disable threaded HTML parser (Chrome only)
• spdyNoSSL: Boolean, use SPDY without SSL (Chrome only)
• commandLine: [String], use a list of custom command line switches (Chrome only)
• pollResults: Number, poll for results after test is scheduled at every seconds [5]
• waitResults: String, wait for test results informed by agent once complete listening on : [hostname:first port available above 8000]
• timeout: Number, timeout (in seconds) for pollResults and waitResults [no timeout]

API Key (works for runTest and cancelTest methods)

• key: String, API key (if assigned). Contact the WebPageTest server administrator for a key if required

Request (works for getTestStatus, getResults, getLocations, getTesters and runTest methods)

• requestId: String, echo request ID, useful to track asynchronous requests

Results (works for getResults and runTest methods)

• breakDown: Boolean, include the breakdown of requests and bytes by mime type
• domains: Boolean, include the breakdown of requests and bytes by domain
• pageSpeed: Boolean, include the PageSpeed score in the response (may be slower)
• requests: Boolean, include the request data in the response (slower and results in much larger responses)
• medianMetric: String, set the metric used to calculate median for multiple runs tests (default: loadTime)
• specs: String, set the specs for performance test suite
• reporter: String, set performance test suite reporter output: [dot]|spec|tap|xunit|list|progress|min|nyan|landing|json|doc|markdown|teamcity

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)

Waterfall (works for getWaterfallImage method only)

• chartType: String, set the chart type: waterfall or connection [waterfall]
• colorByMime: Boolean, set chart coloring by MIME type [false]
• chartWidth Number: chart image width in px (300-2000) [930]
• maxTime Number: set maximum time in seconds [automatic]
• requests String: filter requests (e.g.:1,2,3,4-9,8) [all]
• noCPU: Boolean, hide CPU utilization [false]
• noBandwidth: Boolean, hide bandwidth utilization [false]
• noEllipsis: Boolean, hide ellipsis (...) for missing items [false]
• noLabels: Boolean, hide labels for requests (URL) [false]

Examples

1. Instantiating

var WebPageTest = require('webpagetest');

var wpt = new WebPageTest('my-wpt.foo.com'); // default: www.webpagetest.org
var wptPublic = new WebPageTest('www.webpagetest.org', 'MY_API_KEY');

2. Get available locations

wpt.getLocations(function(err, data) {
  console.log(err || data);
});

3. Run test on http://twitter.com/marcelduran from San Jose on IE9

wpt.runTest('http://twitter.com/marcelduran', {location: 'SanJose_IE9'}, function(err, data) {
  console.log(err || data);
});

4. Check current test status

wpt.getTestStatus('121025_PT_N8K', function(err, data) {
  console.log(err || data);
});

5. Get test results

wpt.getTestResults('121025_PT_N8K', function(err, data) {
  console.log(err || 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) {
  console.log(err || data, info);
});

Run test on http://twitter.com/marcelduran and poll results every 5 seconds timing out in 60 seconds

wpt.runTest('http://twitter.com/marcelduran', {pollResults: 5, timeout: 60}, function(err, data) {
  console.log(err || data);
});

Or run test on http://twitter.com/marcelduran and wait results listening on localhost* port 8000**

wpt.runTest('http://twitter.com/marcelduran', {waitResults: 'localhost:8000'}, function(err, data) {
  console.log(err || data);
});

* hostname and port are optional, defaults to <system hostname>:<8000>

** localhost:8000 must be reacheable from WebPageTest server

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);
}); // listen on port 8080 (optional), default port is 7791

setTimeout(function() {
  server.close(function() {
    console.log('server closed');
  });
}, 10000); // wait for 10s before stop listening

Batch

Batch command is available as command line only and loads a batch file containing one WebPageTest CLI command with options per line. It runs all commands in paralell but returns and array of results in order as they appear in the batch file once all results are ready. The exit status code is the sum of all individual commands exit status code.

By running

$ webpagetest batch commands.txt

where commands.txt contains:

test twitter.com/marcelduran --first --location foo
test twitter.com/marcelduran --first --location bar

It schedules the 2 tests above returning an array of size 2 in the same order as in commands.txt file:

[
  {
    "statusCode": 200, "statusText": "Ok",
    "data": {
      "testId": "130715_AB_C1D",
      ...
    }
  },
  {
    "statusCode": 200, "statusText": "Ok",
    "data": {
      "testId": "130715_CD_E2F",
      ...
    }
  }
]

With exit status 0 in case none of commands returns an error:

$ echo $?
0

By running multiple sync tests, i.e. with either --poll or --wait, all tests are schedule and results are pulled or wait in paralell, it means if tests are set to run in different locations of same location with multiple agents, the final result might come together but the result array will only return once all tests are done. e.g.:

commands.txt:

test twitter.com/marcelduran --first --location foo --poll --timeout 60
test twitter.com/marcelduran --first --location bar --poll --timeout 60

Test Specs (Continuous Integration)

WebPageTest API Wrapper provides a simple seamless way to integrate WebPageTest with Continuous Integration tools.

See dedicated page

Tests

$ npm test

Changelog

• 0.2.0: Replaced jsonml by xml2js dependency
• 0.1.3: Test results extra data (breakdown, domains, requests, pagespeed)
• 0.1.0: Specs (CI); Run in batch; Node methods/options as command aliases; new Chrome test options
• 0.0.4: Sync test with results via --poll or --wait
• 0.0.3: Custom test results median metric; Custom waterfall; new Chrome test options
• 0.0.2: Minor bugs; 2 new commands: testers and testinfo
• 0.0.1: Initial release

Issues

Have a bug/feature request? Please create an issue here on GitHub!

https://github.com/marcelduran/webpagetest-api/issues

Author

Marcel Duran

• http://github.com/marcelduran

License

Copyright 2013 Twitter, Inc.
Copyright 2013 Marcel Duran and other contributors

Licensed under the MIT License