Documentation / Browsers


You can fetch timings and execute your own Javascript. The following browsers are supported: Firefox, Chrome and Chrome on Android.


You will need Firefox 48+. We use the new Geckodriver and it works only version 48 or later.


Chrome should work out of the box.

Change connectivity

You can throttle the connection to make the connectivity slower to make it easier to catch regressions. The best way to do that is to setup a network bridge in Docker.

Default we use TSProxy because it’s only dependency is Python 2.7 but we have a problem with that together with Selenium, so that it is kind of unusable right now. Help us fix that in #229.

If you run Docker you can use tc as connectivity engine but that will only set the latency, if you want to set the download speed you need to create a network bridge in Docker.

Here’s an full example to setup up Docker network bridges on a server that has tc installed:

echo 'Starting Docker networks'
docker network create --driver bridge --subnet= --gateway= --opt ""="docker1" 3g
tc qdisc add dev docker1 root handle 1: htb default 12
tc class add dev docker1 parent 1:1 classid 1:12 htb rate 1.6mbit ceil 1.6mbit
tc qdisc add dev docker1 parent 1:12 netem delay 300ms

docker network create --driver bridge --subnet= --gateway= --opt ""="docker2" cable
tc qdisc add dev docker2 root handle 1: htb default 12
tc class add dev docker2 parent 1:1 classid 1:12 htb rate 5mbit ceil 5mbit
tc qdisc add dev docker2 parent 1:12 netem delay 28ms

docker network create --driver bridge --subnet= --gateway= --opt ""="docker3" 3gfast
tc qdisc add dev docker3 root handle 1: htb default 12
tc class add dev docker3 parent 1:1 classid 1:12 htb rate 1.6mbit ceil 1.6mbit
tc qdisc add dev docker3 parent 1:12 netem delay 150ms

docker network create --driver bridge --subnet= --gateway= --opt ""="docker4" 3gem
tc qdisc add dev docker4 root handle 1: htb default 12
tc class add dev docker4 parent 1:1 classid 1:12 htb rate 0.4mbit ceil 0.4mbit
tc qdisc add dev docker4 parent 1:12 netem delay 400ms

Then when you run your container you add the network with --network cable. You should also tell Browsertime that you set the connectivity external from BT. A full example running running with cable:

$ docker run --privileged --shm-size=1g --network=cable --rm sitespeedio/ -c cable --browsertime.connectivity.engine external

And using the 3g network:

$ docker run --privileged --shm-size=1g --network=3g --rm sitespeedio/ -c 3g --browsertime.connectivity.engine external

And if you want to remove the networks:

echo 'Stopping Docker networks'
docker network rm 3g
docker network rm 3gfast
docker network rm 3gem
docker network rm cable

Choose when to end your test

By default the browser will collect data until window.performance.timing.loadEventEnd happens + aprox 2 seconds more. That is perfectly fine for most sites, but if you do Ajax loading and you mark them with user timings, you probably want to include them in your test. Do that by changing the script that will end the test (–browsertime.pageCompleteCheck). When the scripts returns true the browser will close or if the timeout time will be reached.

In this we wait 10 seconds until loadEventEnd happens but you can also choose to trigger it at a specific event.

$ --browsertime.pageCompleteCheck 'return (function() {try { return ( - window.performance.timing.loadEventEnd) > 10000;} catch(e) {} return true;})()'

We use Selenium in the backend to drive the browsers and right now Selenium/drivers doesn’t support the pageLoadStrategies where you can change when Selenium will give control to the user. Right now we always wait on the pageLoadEvent, meaning pages that doesn’t fire that event will fail. Track the progress to fix that here.

Custom metrics

You can collect your own metrics in the browser by supplying Javascript file(s). By default we collect all metrics inside these folders but you might have something else you want to collect.

Each javascript file need to return a metric/value which will be picked up and returned in the JSON. If you return a number, statistics will automatically be generated for the value (like median/percentiles etc).

Say we have one file called scripts.js that checks how many scripts tags exist on a page. The script looks like this:

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

Then to pick up the script, run like this: --browsertime.script scripts.js -b firefox

You will get a custom script section in the Browsertime tab. Custom scripts individual page

And in the summary and detailed summary section. Summary page

One more thing: All custom scripts values will be sent to Graphite, no extra configuration needed!

Visual Metrics

Visual metrics (Speed Index, Perceptual Speed Index, first and last visual change) can be collected if you also record a video of the screen. This will work on desktop for Firefox & Chrome. And use our Docker container so you automagically get all the extra software needed.

$ docker run --privileged --shm-size=1g --rm -v "$(pwd)":/ sitespeedio/ --speedIndex --video

Using Browsertime

Everything you can do in Browsertime, you can also do in Prefixing browsertime to a CLI parameter will pass that parameter on to Browsertime.

You can check what Browsertime can do here.

For example you wanna pass on an extra Chrome arguments to Chrome. In standalone Browsertime you do that with --chrome.args. If you wanna do that through you just prefix browsertime to the param: Yes we know, pretty sweet! :)