Documentation / WebPageTest


Using WebPageTest

We still love WebPageTest (WPT), so you can drive WebPageTest through You will get a WebPageTest tab for each result and if you are using Graphite, WebPageTest metrics will be automagically sent.

To use WPT you can either get an API key (sponsored by Akamai) for the global version or follow Pat Meenans instructions on how to get a private version up and running in 5 minutes. Or read how WikiMedia setup an instance using AWS.


Internally uses the WebPageTest API so you can do almost all the same thing as with the standalone API.

By default we have the following configuration options:          The domain of your WebPageTest instance.
--webpagetest.key           The API key for you WebPageTest instance.
--webpagetest.location      The location for the test
--webpagetest.connectivity  The connectivity for the test.
--webpagetest.runs          The number of runs per URL.
--webpagetest.custom        Execute arbitrary Javascript at the end of a test to collect custom metrics.
--webpagetest.script        Direct WebPageTest script as a string
--webpagetest.file          Path to a script file

If you need anything else adding your own CLI parameter will propagate to the WebPageTest API. Checkout the different options for the API.

Example: Say that you want to change the user agent of your test. In the API you can do that with --useragent. Pass the same to by adding --webpagetest.useragent in the cli.

$ --webpagetest.useragent "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.59 Safari/537.36"

Default configurations

The default configuration for WebPageTest looks like this:

  pollResults: 10,
  timeout: 600,
  includeRepeatView: false,
  private: true,
  aftRenderingTime: true,
  location: 'Dulles:Chrome',
  connectivity: 'Cable',
  video: true

You can override these with parameters. If you want to change the location, just pass --webpagetest.location mylocation and your new location will be used.

WebPageTest scripting

WebPageTest has scripting capability where you can automate a multi-step test (login as a user and do some interaction). That is supported by by supplying the script. You can do so like this:

You can create your script file (checkout WebPageTest documentation for what you can do). It can look something like this (wptScript.txt):

logData    0

// put any urls you want to navigate

logData    1

// this step will get recorded

Then change your URL you want test (probably the last one) to {{{URL}}} and then all occurrences of {{{URL}}} will then be replaced with the current URL that should be tested. Then run (and add the parameters as you usually do): --webpagetest.file wptScript.txt

It is also possible to pass the WebPageTest script as a string into the --webpagetest.script flag. You can use the scriptToString() method provided in webpagetest-api to create a string from a JSON object. --webpagetest.script "navigate \t \n navigate \t }"

Custom metrics

Hey we love custom metrics and you can fetch them using WPT. Checkout the metrics docs for WPT and then create a file containing your metrics:

return document.getElementsByTagName("iframe").length;

return document.getElementsByTagName("script").length;

var viewport = undefined;
var metaTags=document.getElementsByTagName("meta");
for (var i = 0; i < metaTags.length; i++) {
    if (metaTags[i].getAttribute("name") == "viewport") {
        viewport = metaTags[i].getAttribute("content");
return viewport;

You can then run like this to pick up the new custom metrics:

$ --webpagetest.custom myScriptFile.txt