Documentation / WebPageTest


Using WebPageTest

We love WebPageTest (WPT), so we have integrated WebPageTest with (it’s a plugin). When including WPT you will get a tab for each result and if you are using Graphite, WebPageTest metrics will be automatically sent.

To use WPT you have a few options

You should use if you wanna need to run tests on browsers that WebPageTest supports but not (Safari on Iphone and Microsoft browsers).


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 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 --shm-size=1g --rm -v "$(pwd)":/ sitespeedio/ --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 --shm-size=1g --rm -v "$(pwd)":/ sitespeedio/ --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 --shm-size=1g --rm -v "$(pwd)":/ sitespeedio/ --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 --shm-size=1g --rm -v "$(pwd)":/ sitespeedio/ --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 --shm-size=1g --rm -v "$(pwd)":/ sitespeedio/ --plugins.remove browsertime

Advanced dashboards

If you use the grafana dashboards, you will notice that by default some of them can be empty. You must set to true two options

  • webpagetest.timeline : It activates chrome tracing, if you’re running chrome. It contains super useful metrics like the Navigation Timing API and chrome specific metrics like FirstMeaningfulPaint.