Browsertime - Your browser, your page, your scripts!

Access the Web Performance Timeline, from your browser, in your terminal!

Browsertime allows you to:

1. Query timing data directly from the browser, to access Navigation Timing, User Timing, Resource Timing, first paint and RUM Speed Index.
2. Generate HAR files (using HAR Export trigger for Firefox and parsing the Chrome log for Chrome).
3. Run custom Javascript scripts in the browser and get statistics for each run.
4. Record a video of the screen and analyze the result to get First Visual Change, Speed Index, Visual Complete 85 % and Last Visual Change.

IMPORTANT! The master branch is now the coming 2.0.0 alpha release and 1.x is the latest stable release.

A simple example

Use our Docker image (with Chrome, Firefox, XVFB and the dependencies needed to record a video):

$ docker run --shm-size=1g --rm -v "$(pwd)":/browsertime sitespeedio/browsertime --video --speedIndex https://www.sitespeed.io/

Or using node:

$ bin/browsertime.js https://www.sitespeed.io

Load https://www.sitespeed.io/ in Chrome three times. Results are stored in a JSON file (browsertime.json) with the timing data, and a HAR file (browsertime.har) in browsertime-results/www.sitespeed.io/$date/

I want more examples

Checkout the examples.

Browsers

Browsertime supports Firefox and Chrome on desktop. On Android we support Chrome.

But we want to support Opera (on Android) and when(?!) iOS Safari supports WebDriver we will add that too.

How does it work

Browsertime uses Selenium NodeJS to drive the browser. It starts the browser, load a URL, executes configurable Javascripts to collect metrics, collect a HAR file.

To get the HAR from Firefox we use the HAR Export Trigger and Chrome we use Chrome-HAR to parse the timeline log and generate the HAR file.

Oh and you can run your own Selenium script before (--preScript) and after (--postScript) a URL is accessed so you can login/logout or do whatever you want.

Speed Index and video

It's easiest to run our ready made Docker container to be able to record a video and calculate SpeedIndex because then you get all dependencies needed for free to run VisualMetrics.

The default video will include a timer and showing when the metrics happens, but you can turn that off using --video.addTimer false.

Test using Docker

You can build and test changes using Docker locally.

$ docker build -t sitespeedio/browsertime .
$ docker run --shm-size=1g --rm -v "$(pwd)":/browsertime sitespeedio/browsertime -n 1 --video --speedIndex https://www.sitespeed.io/

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:

#!/bin/bash
echo 'Starting Docker networks'
docker network create --driver bridge --subnet=192.168.33.0/24 --gateway=192.168.33.10 --opt "com.docker.network.bridge.name"="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=192.168.34.0/24 --gateway=192.168.34.10 --opt "com.docker.network.bridge.name"="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=192.168.35.0/24 --gateway=192.168.35.10 --opt "com.docker.network.bridge.name"="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=192.168.36.0/24 --gateway=192.168.36.10 --opt "com.docker.network.bridge.name"="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 --shm-size=1g --network=cable --rm sitespeedio/browsertime -c cable --connectivity.engine external --speedIndex --video https://www.sitespeed.io/

And using the 3g network:

$ docker run --shm-size=1g --network=3g --rm sitespeedio/browsertime -c 3g --connectivity.engine external --speedIndex --video https://www.sitespeed.io/

And if you want to remove the networks:

#!/bin/bash
echo 'Stopping Docker networks'
docker network rm 3g
docker network rm 3gfast
docker network rm 3gem
docker network rm cable

Test on your mobile device

Browsertime supports Chrome on Android: Collecting SpeedIndex, HAR and video! This is still really new, let us know if you find any bugs.

You need to install adb and prepare your phone before you start.

If you want to set connectivity you need to use something like Micro device lab or TSProxy.

$ browsertime --chrome.android.package com.android.chrome https://www.sitespeed.io --video --speedIndex

If you are on Linux (we have tested Ubuntu 16) you can use our Docker container to drive your Android phone. A couple of things to remember:

• You need to run in privileged mode --privileged
• You need to share the USB ports -v /dev/bus/usb:/dev/bus/usb
• Add -e START_ADB_SERVER=true to start the adb server
• Turn of xvfb --xvfb false (we start that automatically)

If you use Docker you will automatically get support for video and SpeedIndex. You can get that without Docker but then need to install VisualMetrics dependencies yourself.

$ docker run --privileged -v /dev/bus/usb:/dev/bus/usb -e START_ADB_SERVER=true --shm-size=1g --rm -v "$(pwd)":/browsertime-results sitespeedio/browsertime -n 1 --chrome.android.package com.android.chrome --xvfb false --speedIndex --video https://en.m.wikipedia.org/wiki/Barack_Obama

Configuration

Run $ bin/browsertime.js --help and you can see the configuration options.

Send metrics to Graphite

The easiest way to send metrics is to install jq and use it to pick the values you wanna track.

Here's an example on how you can pickup the median SpeedIndex from Browsertime and send it to your Graphite instance.

echo "browsertime.your.key.SpeedIndex.median" $(cat /tmp/browsertime/browsertime.json | jq .statistics.visualMetrics.SpeedIndex.median) "`date +%s`" | nc -q0 my.graphite.com 2003