Documentation / Configuration


Configuration is highly configurable, let’s check it out!

The options

You have the following options when running (run --help to get the list on your command line): [options] <url>/<file>

  --browsertime.browser, -b, --browser                         Choose which Browser to use when you test.                    [choices: "chrome", "firefox"] [default: "chrome"]
  --browsertime.iterations, -n                                 How many times you want to test each page                                                           [default: 3]
  --browsertime.connectivity.profile, -c, --connectivity       The connectivity profile.
                                                                             [choices: "3g", "3gfast", "3gslow", "3gem", "2g", "cable", "native", "custom"] [default: "native"]
  --browsertime.connectivity.downstreamKbps, --downstreamKbps  This option requires --connectivity be set to "custom".
  --browsertime.connectivity.upstreamKbps, --upstreamKbps      This option requires --connectivity be set to "custom".
  --browsertime.connectivity.latency, --latency                This option requires --connectivity be set to "custom".
  --browsertime.connectivity.tsproxy.port                      The port used for TSProxy                                                                        [default: 1080]
  --browsertime.connectivity.engine                            The engine for connectivity. TC (Linux Traffic Control) needs tc work but will only setup upload and latency.
                                                               Use external if you set the connectivity outside of Browsertime. The best way do to this is described in
                                                                                                                   [choices: "tc", "tsproxy", "external"] [default: "external"]
  --browsertime.pageCompleteCheck                              Supply a Javascript that decides when the browser is finished loading the page and can start to collect metrics.
                                                               The Javascript snippet is repeatedly queried to see if page has completed loading (indicated by the script
                                                               returning true). Use it to fetch timings happening after the loadEventEnd.
  --browsertime.script, --script                               Add custom Javascript that collect metrics and run after the page has finished loading. Note that --script can
                                                               be passed multiple times if you want to collect multiple metrics. The metrics will automatically be pushed to
                                                               the summary/detailed summary and each individual page + sent to Graphite/InfluxDB.
  --browsertime.selenium.url                                   Configure the path to the Selenium server when fetching timings using browsers. If not configured the supplied
                                                               NodeJS/Selenium version is used.
  --browsertime.viewPort                                       The browser view port size WidthxHeight like 400x300                                       [default: "1366x708"]
  --browsertime.userAgent                                      The full User Agent string, defaults to the User Agent used by the browsertime.browser option.
  --browsertime.preScript, --preScript                         Selenium script(s) to run before you test your URL (use it for login, warm the cache, etc). Note that
                                                               --preScript can be passed multiple times.
  --browsertime.postScript, --postScript                       Selenium script(s) to run after you test your URL (use it for logout etc). Note that --postScript can be passed
                                                               multiple times.
  --browsertime.delay                                          Delay between runs, in milliseconds. Use it if your web server needs to rest between runs :)
  --browsertime.speedIndex, --speedIndex                       Calculate SpeedIndex. Requires FFMpeg and python dependencies                                          [boolean], --video                                 Record a video. Requires FFMpeg to be installed                                                        [boolean]
  --browsertime.preURL, --preURL                               A URL that will be accessed first by the browser before the URL that you wanna analyze. Use it to fill the
  --browsertime.userTimingWhitelist, --userTimingWhitelist     This option takes a regex that will whitelist which userTimings to capture in the results. All userTimings are
                                                               captured by default. T
  --browsertime.firefox.preference                             Extra command line arguments to pass Firefox preferences by the format key:value To add multiple preferences,
                                                               repeat --browsertime.firefox.preference once per argument.
  --browsertime.firefox.includeResponseBodies                  Include response bodies in HAR when using Firefox.                                                     [boolean]                                    Extra command line arguments to pass to the Chrome process (e.g. --no-sandbox). To add multiple arguments to
                                                               Chrome, repeat once per argument.                    Collect Chromes traceCategories                                                                        [boolean]                         Run Chrome on your Android device. Set to for default Chrome version. You need to run adb
                                                               start-server before you start.                    Choose which device to use. If you do not set it, the first found device will be used.                           Collect network log from Chrome and save to disk.                                                      [boolean]                         Set the trace categories.                                                                               [string]
  --browsertime.requestheader, -r                              Request header that will be added to the request. Add multiple instances to add multiple request headers. Only
                                                               Chrome support for now.
  --browsertime.block                                          Domain to block. Add multiple instances to add multiple domains that will be blocked. Only Chrome support for

  --browsertime.proxy.http   Http proxy (host:port)                                                                                                                    [string]
  --browsertime.proxy.https  Https proxy (host:port)                                                                                                                   [string]

  --crawler.depth, -d     How deep to crawl (1=only one page, 2=include links from first page, etc.)
  --crawler.maxPages, -m  The max number of pages to test. Default is no limit.

Graphite                The Graphite host used to store captured metrics.
  --graphite.port                The Graphite port used to store captured metrics.                                                                              [default: 2003]
  --graphite.auth                The Graphite user and password used for authentication. Format: user:password
  --graphite.httpPort            The Graphite port used to access the user interface and send annotations event                                                 [default: 8080]
  --graphite.webHost             The graphite-web host. If not specified will be used.
  --graphite.namespace           The namespace key added to all captured metrics.                                                             [default: "sitespeed_io.default"]
  --graphite.includeQueryParams  Whether to include query parameters from the URL in the Graphite keys or not                                        [boolean] [default: false]
  --graphite.arrayTags           Send the tags as array or a string. In Graphite 1.0 the tags is a array.                                            [boolean] [default: false]

  --plugins.list     List all configured plugins in the log.                                                                                                          [boolean]
  --plugins.disable  Disable a plugin. Use it to disable generating html or screenshots.                                                                                [array]
  --plugins.load     Extra plugins that you want to run. Relative or absolute path to the plugin.                                                                       [array]

  --budget.configPath  Path to the JSON budget file.
  --budget.config      The JSON budget config as a string.
  --budget.output      The output format of the budget.                                                                                               [choices: "junit", "tap"]

  --influxdb.protocol            The protocol used to store connect to the InfluxDB host.                                                                     [default: "http"]                The InfluxDB host used to store captured metrics.
  --influxdb.port                The InfluxDB port used to store captured metrics.                                                                              [default: 8086]
  --influxdb.username            The InfluxDB username for your InfluxDB instance.
  --influxdb.password            The InfluxDB password for your InfluxDB instance.
  --influxdb.database            The database name used to store captured metrics.                                                                       [default: "sitespeed"]
  --influxdb.tags                A comma separated list of tags and values added to each metric                                                   [default: "category=default"]
  --influxdb.includeQueryParams  Whether to include query parameters from the URL in the InfluxDB keys or not                                        [boolean] [default: false]

  --metrics.list        List all possible metrics in the data folder (metrics.txt).                                                                  [boolean] [default: false]
  --metrics.filterList  List all configured filters for metrics in the data folder (configuredMetrics.txt)                                           [boolean] [default: false]
  --metrics.filter      Add/change/remove filters for metrics. If you want to send all metrics, use: *+ . If you want to remove all current metrics and send only the coach
                        score: *- coach.summary.score.*                                                                                                                 [array]

WebPageTest               The domain of your WebPageTest instance.                                                            [default: ""]
  --webpagetest.key                The API key for you WebPageTest instance.
  --webpagetest.location           The location for the test                                                                                         [default: "Dulles:Chrome"]
  --webpagetest.connectivity       The connectivity for the test.                                                                                            [default: "Cable"]
  --webpagetest.runs               The number of runs per URL.                                                                                                     [default: 3]
  --webpagetest.custom             Execute arbitrary Javascript at the end of a test to collect custom metrics.
  --webpagetest.file               Path to a script file
  --webpagetest.script             The WebPageTest script as a string.
  --webpagetest.includeRepeatView  Do repeat or single views                                                                                         [boolean] [default: false]
  --webpagetest.private            Wanna keep the runs private or not                                                                                 [boolean] [default: true]

  --gpsi.key  The key to use Google Page Speed Insight

  --slack.hookUrl       WebHook url for the Slack team (check https://<your team>
  --slack.userName      User name to use when posting status to Slack.                                                                                [default: ""]       The slack channel without the # (if something else than the default channel for your hook).
  --slack.type          Send summary for a run, metrics from all URLs, only on errors or all to Slack.             [choices: "summary", "url", "error", "all"] [default: "all"]
  --slack.limitWarning  The limit to get a warning in Slack using the limitMetric                                                                                 [default: 90]
  --slack.limitError    The limit to get a error in Slack using the limitMetric                                                                                   [default: 80]
  --slack.limitMetric   The metric that will be used to set warning/error                    [choices: "coachScore", "speedIndex", "firstVisualChange"] [default: "coachScore"]

  --s3.key                The S3 key
  --s3.secret             The S3 secret
  --s3.bucketname         Name of the S3 bucket
  --s3.path               Override the default folder path in the bucket where the results are uploaded. By default it's "DOMAIN_OR_FILENAME/TIMESTAMP", or the name of the
                          folder if --outputFolder is specified.
  --s3.region             The S3 region. Optional depending on your settings.
  --s3.removeLocalResult  Remove all the local result files after they have been uploaded to S3                                                      [boolean] [default: false]

  --html.showAllWaterfallSummary  Set to true to show all waterfalls on page summary HTML report                                                     [boolean] [default: false]
  --html.fetchHARFiles            Set to true to load HAR files using fetch instead of including them in the HTML. Turn this on if serve your pages using a server.
                                                                                                                                                     [boolean] [default: false]
  --html.logDownloadLink          Adds a link in the HTML so you easily can download the logs from the run. If your server is public, be careful so you don't log
                                  passwords etc                                                                                                      [boolean] [default: false]

  --summary         Show brief text summary to stdout                                                                                                [boolean] [default: false]
  --summary-detail  Show longer text summary to stdout                                                                                               [boolean] [default: false]

  --version, -V    Show version number                                                                                                                                [boolean]
  --debug          Debug mode logs all internal messages to the console.                                                                             [boolean] [default: false]
  --verbose, -v    Verbose mode prints progress messages to the console. Enter up to three times (-vvv) to increase the level of detail.                                [count]
  --mobile         Access pages as mobile a fake mobile device. Set UA and width/height. For Chrome it will use device Apple iPhone 6.               [boolean] [default: false]
  --resultBaseURL  The base URL to the server serving the HTML result. In the format of
  --gzipHAR        Compress the HAR files with GZIP.                                                                                                 [boolean] [default: false]
  --outputFolder   The folder where the result will be stored.
  --firstParty     A regex running against each request and categorize it as first vs third party URL. (ex: ".*sitespeed.*")
  --utc            Use Coordinated Universal Time for timestamps                                                                                     [boolean] [default: false]
  --config         Path to JSON config file
  --help, -h       Show help                                                                                                                                          [boolean]

Read the docs at

The basics

If you installed with the global option run the command else run the script bin/sitespeed.js. In the examples we will use the globally installed version.

You can analyze a site either by crawling or by feeding with a list URL:s you want to analyze.

Analyze by URLs

The simplest way to run is to give it a URL.


If you wanna test multiple URLs just feed them:


You can also use a plain text file with one URL on each line. Create a file called urls.txt:

Another feature of the plain text file is you can add aliases to the urls.txt file after each URL. To do this add a non-spaced string after each URL that you would like to alias. Important_Page Page2

Note: Spaces are used to delimit between the URL and the alias which is why the alias cannot contain one.

Aliases are great in combination with sending metrics to a TSDB such as graphite for shortening the key sent to make they more readable.

And run it:

$ urls.txt

Analyze by crawling

If you wanna find pages that are not so performant it’s a good idea to crawl. will start with the URL and fetch all links on that pages and continue to dig deeper into the site structure. You can choose how deep to crawl (1=only one page, 2=include links from first page, etc.):

$ -d 2

How many runs per URL?

When collecting timing metrics it’s good to test the URL more than one time (default is three times). You can configure how many runs like this (five runs):

$ -n 5

Choose browser

Choose which browser to use (default is Chrome):

$ -b firefox
$ -b chrome


You should throttle the connection when you are fetching metrics. The best way to do that is to add network to your Docker container:

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

And then when you run your Docker container, add --network cable to your Docker setup to use that network. You can also set the connectivity engine to external --browsertime.connectivity.engine external. A full example:

$ docker run --privileged --shm-size=1g --network cable --rm -v "$(pwd)":/ sitespeedio/ --browsertime.connectivity.engine external -c cable

Then you will use the network setup in your Docker network bridge, call it “cable” so that key will be used in HTML/graphite and set it the engine to external so that no connectivity is set inside the Docker container.

Read more here how to set different connectivities.

Viewport/user agent and mobile

You can set the viewport & user agent, so that you can fake testing a site as a mobile device.

Simplest way is to just add --mobile as a parameter. The viewport will be set to 360x640 and the User Agent will be Iphone6. If you use Chrome it will use the pre-set device Apple iPhone 6.

$ --mobile

You can also set specific viewport and User Agent:

$ --browsertime.viewPort 400x400 --browsertime.userAgent "UCWEB/2.0 (MIDP-2.0; U; Adr 4.4.4; en-US; XT1022) U2/1.0.0 UCBrowser/ U2/1.0.0 Mobile"

Mobile testing is always best on an actual mobile devices. You can test on Android phones using


You can fake the connectivity for the browser. By default we use TSProxy so you need Python 2.7 to work but you can also set the connectivity engine to tc if that works better for you.

Setting the connectivity to cable:

$ -c cable

Changing the engine type to tc (use tc when you run in Docker):

$ -c cable --browsertime.connectivity.engine tc

Speed Index and video

In 4.1 we released support for recording a video of the browser screen and use that to calculate visual metrics like Speed Index. Use our Docker containers for a easy setup.

If you only care about Speed Index and related metrics (first visual change etc) you can run like this:

$ docker run --privileged --shm-size=1g --rm -v "$(pwd)":/ sitespeedio/ --speedIndex will then analyze the video and then remove it. If you wanna keep the video, add the video flag (and you can see it in the Browsertime tab):

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

First party vs third party

You can categorize requests as first or third parties by adding a regexp. You will then get the size & requests by type both in HTML and sent to Graphite.

$ --firstParty ""

Output folder or where to store the result

You can change where you want the data to be stored by setting the --outputFolder parameter. That is good in scenarios where you wanna change the default behavior and put the output in specific place.

$ --outputFolder /my/folder ""

Configuration as JSON

You can keep all your configuration in a JSON file and then pass it on to sitespeed, and override with CLI parameters.

Create a config file and call it config.json:

  "browsertime": {
    "connectivity": {
      "engine": "tc",
      "profile": "cable"
    "iterations": 5,
    "browser": "chrome",
    "experimental": {
      "video": true
  "graphite": {
    "host": "",
    "namespace": "sitespeed_io.desktopFirstView"
"plugins": {
	"disable": ["html"]
  "utc": true

The run it like this:

$ --config config.json

If you wanna override and run the same configuration but using Firefox, you just override with the CLI parameter:

$ --config config.json -b firefox

CLI will always override your JSON config.



You can send the result of a run to Slack. First setup a webhook in the slack API ( and then configure it:

$ --slack.hookUrl

You can choose to send just a summary (the summary for all runs), individual runs (with url), only errors or all by choosing the slack.type.

$ --slack.hookUrl --slack.type summary


Login the user

We have added a special section for that!