No Princess, Mario

    26.1.0 • Public • Published

    Unit tests Linux browsers Docker Windows Edge OSX Safari Downloads Docker Stars npm Changelog #212

    Website | Documentation | Changelog | Twitter

    Welcome to the wonderful world of web performance!

    What is is a complete web performance tool that helps you measure the performance of your website. What exactly does that mean?

    Before we start telling you all about you should just try it out:

    Using NodeJS/npm (you need Chrome, Firefox, Edge or Safari installed or Chrome/Firefox on Android)

    npm i -g &&

    Or using Docker:

    docker run --rm -v "$(pwd)":/ sitespeedio/

    Ok, now you have tried it, let us tell you more about We think of a complete web performance tool as having three key capabilities:

    • It test web sites using real browsers, simulating real users connectivity and collect important user centric metrics like Speed Index and First Visual Render.
    • It analyse how your page is built and give feedback how you can make it faster for the end user.
    • It collect and keep data how your pages is built so you easily can track changes.

    What is good for?

    It is usually used in two different areas:

    • Running in your continuous integration to find web performance regressions early: on commits or when you move code to your test environment
    • Monitoring your performance in production, alerting on regressions.

    To understand how does these things, let's talk about how it works.

    First a few key concepts:

    • is built upon a couple of other Open Source tools in the suite.
    • Browsertime is the tool that drives the browser and collect metrics.
    • The Coach knows how to build fast websites and analyse your page and give you feedback what you should change.
    • Visual Metrics is metrics collected from a video recording of the browser screen.
    • Everything in is a plugin and they communicate by passing messages on a queue.

    When you as user choose to test a URL, this is what happens on a high level:

    1. starts and initialise all configured plugins.
    2. The URL is passed around the plugins through the queue.
      1. Browsertime gets the URL and opens the browser.
      2. It starts to record a video of the browser screen.
      3. The browser access the URL.
      4. When the page is finished, Browsertime takes a screenshot of the page.
      5. Then run some JavaScripts to analyse the page (using Coach and Browsertime scripts).
      6. Stop the video and close the browser.
      7. Analyse the video to get Visual Metrics like First Visual Change and Speed Index.
      8. Browsertime passes all metrics and data on the queue so other plugins can use it.
    3. The HTML/Graphite/InfluxDB plugin collects the metrics in queue.
    4. When all URLs are tested, sitespeed sends a message telling plugins to summarise the metrics and then render it.
    5. Plugins pickup the render message and the HTML plugin writes the HTML to disk.

    Try it out

    Using Docker (use latest Docker):

    docker run --rm -v "$(pwd)":/ sitespeedio/

    Or install using npm:

    npm i -g

    Or clone the repo and test the latest changes:

    git clone
    npm install
    bin/sitespeed.js --help

    More details

    Using you can:

    • Test your web site against Web Performance best practices using the Coach.
    • Collect Navigation Timing API, User Timing API and Visual Metrics from Firefox/Chrome using Browsertime.
    • Run your custom-made JavaScript and collect whichever metric(s) you need.
    • Test one or multiple pages, across one or many runs to get more-accurate metrics.
    • Create HTML-result pages or store the metrics in Graphite.
    • Write your own plugins that can do whatever tests you want/need.

    See all the latest changes in the Changelog.

    Checkout our example

    A summary report in HTML:

    Individual page report:

    Collected metrics from a URL in Graphite/Grafana:

    And look at trends in Grafana:

    Video - easiest using Docker. This gif is optimized, the quality is much better IRL:

    Test using WebPageReplay

    We have a special Docker container that comes with WebPageReplay installed. This is a really early alpha release but we think you should try it out.

    WebPageReplay will let you replay your page locally (getting rid of server latency etc) and makes it easier to have stable metrics and find front end regressions.

    It works like this:

    1. WebPageReplay is started in record mode
    2. Browsertime access the URLs you choose one time (so it is recorded)
    3. WebPageReplay is closed down
    4. WebPageReplay in replay mode is started
    5. (using Browsertime) test the URL so many times you choose
    6. WebPageReplay in replay mode is closed down

    You can change latency by setting a Docker environment variable. Use REPLAY to turn on the replay functionality.

    Default browser is Chrome:

    docker run --cap-add=NET_ADMIN --rm -v "$(pwd)":/ -e REPLAY=true -e LATENCY=100 sitespeedio/ -n 5 -b chrome

    Use Firefox:

    docker run --cap-add=NET_ADMIN --rm -v "$(pwd)":/ -e REPLAY=true -e LATENCY=100 sitespeedio/ -n 11 -b firefox


    We have a Mac Mini sponsored by MacStadium and you too can sponsor us to help us keep running and making sure we can have the best test setup as possible. Read our sponsor page for more info.


    npm i

    DownloadsWeekly Downloads






    Unpacked Size

    27.3 MB

    Total Files


    Last publish


    • tobli
    • soulgalore
    • beenanner