Documentation / WebPageTest


Using WebPageTest #

To use WebPageTest you need to install the WebPageTest plugin or run the Docker sitespeedio/ container.

To use WPT you need to setup your own WebPageTest instance (read how Wikimedia setup an instance using AWS) or have one of those (old) keys for the public instance.

Configuration #

The plugin 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 your 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: So 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 prefixing webpagetest like so --webpagetest.useragent in the cli.

docker run --rm -v "$(pwd):/" sitespeedio/sitespeed.io16.9.2-webpagetest --plugins.add /webpagetest --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 easily automate a multi-step test (e.x. 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. Now run with the additional parameters:

docker run --rm -v "$(pwd):/" sitespeedio/ --plugins.add /webpagetest --webpagetest.file /

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.

docker run --rm -v "$(pwd):/" sitespeedio/ --plugins.add /webpagetest --webpagetest.script "navigate \t \n navigate \t {{{URL}}}}"

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 to pick up the new custom metrics:

docker run --rm -v "$(pwd):/" sitespeedio/ --plugins.add /webpagetest --webpagetest.custom /

Run WebPageTest without Browsertime #

Sometimes you want to only collect data from WebPageTest and not from Browsertime. The best way to do that is to disable the Browsertime plugin with –plugins.remove browsertime

docker run --rm -v "$(pwd):/" sitespeedio/ --plugins.add /webpagetest --plugins.remove browsertime