WebPageTest is an incredibly useful and nuanced open-source tool that enables engineers to probe into all aspects of a website’s performance.
WebPageTest-API is a node.js-based command-line interface for WebPageTest, which allows large numbers of tests to be automated against public or private WebPageTest servers.
Today, we are open-sourcing WebPageTest-mapper, a wrapper for WebPageTest-API that transforms the JSON result data into intuitive and informative human-readable formats.
into the tool:
generates an HTML document
plotting the distribution
for each metric.
Histograms are great
for quickly understanding
the distribution of your data;
how values are clustered
and what the outliers are.
generates a document
that uses HTML tables
and SVG bar charts
to compare median metrics
between different pages
in a set of tests.
can help to
the causes of
between web pages.
generates an Open Document Format spreadsheet
that contains raw data
for each test run,
along with statistical functions
applied to each metric.
are a handy starting-point
from which to play with the data
and better understand
any aspects that
may be of interest.
A key feature of WebPageTest-mapper is its extensibility. As well as the built-in mappers, it is easy to run the tool and specify the path to your own mapper instead.
and interpreted by node.js,
so have the entire
at their disposal.
The mapper interface
exposes one function
an options object
and the JSON result data
Mappers should return
containing the mapped data
as their result.
for more detail.
Running WebPageTest-mapper from the command line
First you must install node.js. You can then install WebPageTest-mapper globally using npm:
make an executable file
available on your path.
At the time of writing, valid options are:
--uri <URI>: Base URI of the WebPageTest instance. The default value is
--key <key>: WebPageTest API key.
--location <location>: WebPageTest location. The default value is
--connection <connection>: WebPageTest connection speed. The default value is
--tests <path>: Path to the test definitions file. An example file can be found here. The default value is
--count <number>: Number of times to run each test. The default value is
--email <address>: Email address to notify when tests are finished.
--wait <interval>: Number of seconds to wait between attempts to fetch the result data. The default value is
--output <path>: Path to the output file, which will contain the mapped result. The default value is stdout.
--dump <path>: Path to the intermediate file, which will contain the raw JSON data from WebPageTest-API. This option is useful if you want to run multiple mappers against the same set of result data.
--results <path>: Path from which to read the intermediate results, previously saved with
--dump. Passing this option skips the phase of actually running the tests with WebPageTest.
--mapper <path>: Mapper to use. The default value is
--silent: Disable logging.
--syslog <facility>: Send logs to syslog, using the specified facility.
--config <path>: Attempt to read these configuration options from a JSON file. The default value is
.wptrc, an example can be found here.
Calling WebPageTest-mapper from your own code
It is also possible to invoke WebPageTest-mapper programmatically from another node.js project.
From your project’s directory, run:
You can then
the returned object’s
More detail about these methods can be found in the readme.
We welcome contributions in the form of pull requests and issues.
If you would like to hack on the code, clone the git repo:
From the project root, you can then install the dependencies:
Lint the code:
Run the unit tests:
Please ensure that you have adhered to the contribution guidelines before submitting pull requests.