node package manager


It's browser time!

Build status Downloads Stars

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, generated by running a BrowserMob Proxy instance.
  3. Query custom Javascript in the browser and get statistics for each run.

Data from Browsertime is included in speed reports generated by

Note: Your browser need to support the Navigation Timing API, the User Timing API and the Resource Timing API for all the metrics to work (=Safari & PhantomJS don't).

Table of Contents


Browsertime supports Chrome, Firefox, IE (Windows only), Safari (8.x and will not generate a complete HAR) and PhantomJS (2.0 or later, however we use PhantomJS through Selenium with limited functionality).

A simple example

> browsertime -u

Load in Chrome three times. Results are stored in a json file ( with the timing data, and a har file (

Digging deeper

> browsertime -u -n 9 -b firefox -w 600x800 --filename sitespeed.json --harFile sitespeed.har

Start firefox and load nine times, to get a better statistical sample. Statistical median, percentiles and more are outputted to sitespeed.json, including all individual measurement values. The window size is fixed at 600 times 800 pixels.

Using the excellent tool jq, query the timing data to find the 99th percentile of the pageLoadTime metric; 4061 milliseconds.

> jq '.default.statistics.pageLoadTime.p99 ' -r  sitespeed.json
> 694

All available options for controlling Browsertime are documented when running

> browsertime -h

Choose when to end your test

By default the browser will collect data until the window.performance.timing.loadEventEnd happens. 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 (--waitScript). When the scripts returns true the browser will close or if the timeout time (default 60 seconds) will be reached:

> browsertime -u --waitScript 'return window.performance.timing.loadEventEnd>0'

Fetch your own metrics from the browser

You can collect your own metrics in the browser by supplying a directory with JavaScript files. Each file need to return a metric/value and it 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). Check out the scripts we use.

Say we have a folder called scripts and in there we have one file called scripts.js that checks how many javascript that is loaded. The script looks like this:

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

Then to pick up the script, run like this:

> browsertime -u --customScripts scripts

The basename of the file script will be used as the metric name in the json.

Simulate connection types

You can choose the speed by simulating different connection types. By default you can choose between mobile3g, mobile3gfast, cable or native (default).

> browsertime -u --connection cable

If you need to have a specific connection not listed in the above, you can configure it yourself with connectionRaw (and change $X, $Y and $Z to what you need.

> browsertime -u --connectionRaw {downstreamKbps: $X, upstreamKbps: $Y, latency: $Z}

Basic Auth

You can set basic auth user & password like this:

> browsertime -u --basicAuth username:password

Request headers

Set request headers by supplying a JSON:

> browsertime -u --headers '{ "name": "value", "name2": "value2"}'

Blacklist urls

Match urls that should return 404, e.g. block Facebook and Google Analytics

> browsertime -u  --blacklist ".*(facebook|google-analytics)\.com.*"'

Fake the user agent

Using Firefox and Chrome you can fake your user agent. Default is using the current browsers user agent.

> browsertime -u --userAgent "My super user agent string"


Browsertime is built using Node.js, and installed via npm.

> npm install browsertime -g


Follow Browsertime on Twitter: @browsertime

Copyright and license

Copyright 2014 Tobias Lidskog & Peter Hedenskog under the Apache 2.0 license.