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. TSProxy needs Python 2.7. TC (Linux Traffic Control) needs
                                                               tc work. If you run inside Docker use tc.[choices: "tc", "tsproxy"] [default: "tsproxy"]
  --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
  --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 cache.
  --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

  --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.namespace           The namespace key added to all captured metrics.                                     [default: "sitespeed_io.default"]
  --graphite.includeQueryParams  Whether to include query paramaters from the URL in the Graphite keys or not                [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"]

  --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.

  --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: 80]
  --slack.limitError    The limit to get a error in Slack using the limitMetric                                                           [default: 90]
  --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         The S3 bucketname
  --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]

  --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]
  --webpagetest.includeRepeatView  Do repeat or single views                                                                 [boolean] [default: false]
  --webpagetest.private            Wanna keep the runs private or not                                                         [boolean] [default: true]
  --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
  --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 sucha 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 can throttle the connection when you are fetching metrics using the browser. Choose between:

  • 3g - 1600/768 300 RTT
  • 3gfast - 1600/768 150 RTT
  • 3gslow - 780/330 200 RTT
  • 2g - 35/328 1300 RTT
  • cable - 5000/1000 28 RTT
  • native - your current connection

We use TSProxy by default, so you need Python 2.7 to be able to throttle the connection.

$ -c cable

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 paramater:

$ --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!