Introducing WebPageTest-mapper

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.

Output formats

Currently, mappers for three different output formats are built into the tool: html-distribution, html-comparison and odf-spreadsheet.

The html-distribution mapper generates an HTML document that contains SVG histograms 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.

Screenshot of histograms rendered by the html-distribution mapper

Each bar on the histogram represents one standard deviation from the mean. A green bar indicates data that is less than the mean and red bars are for figures greater than the mean. The charts don’t require JavaScript to render and they are accessible to screen-readers.

The html-comparison mapper generates a document that uses HTML tables and SVG bar charts to compare median metrics between different pages in a set of tests. These elements can help to visually identify the causes of performance differences between web pages.

Screenshot of a bar chart rendered by the html-comparison mapper

Throughout the document, colours are used consistently to identify different tests and help to pick out trends in the data. Cells in the tables link through to the equivalent section in the WebPageTest result details and, once again, all of the charts are accessible and rendered as static markup with no JavaScript dependencies.

The odf-spreadsheet mapper generates an Open Document Format spreadsheet that contains raw data for each test run, along with statistical functions applied to each metric. These spreadsheets are a handy starting-point from which to play with the data and better understand any aspects that may be of interest.

Screenshot of a spreadsheet rendered by the odf-spreadsheet mapper

Extensibility

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.

Mappers are implemented in JavaScript and interpreted by node.js, so have the entire node ecosystem at their disposal. The mapper interface exposes one function called map, which takes an options object and the JSON result data as arguments. Mappers should return a string or buffer containing the mapped data as their result. See the mapper implementations for more detail.

We are also happy to incorporate improvements or additions to the current set of built-in mappers. Pull requests and issues are highly encouraged.

Running WebPageTest-mapper from the command line

First you must install node.js. You can then install WebPageTest-mapper globally using npm:

npm install -g webpagetest-mapper

This will make an executable file called wptmap available on your path. To list the available command-line options, run:

wptmap --help

At the time of writing, valid options are:

--uri <URI>: Base URI of the WebPageTest instance. The default value is www.webpagetest.org.
--key <key>: WebPageTest API key.
--location <location>: WebPageTest location. The default value is Dulles:Chrome.
--connection <connection>: WebPageTest connection speed. The default value is Native Connection.
--tests <path>: Path to the test definitions file. An example file can be found here. The default value is tests.json.
--count <number>: Number of times to run each test. The default value is 9.
--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 600 (10 minutes).
--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 html-comparison.
--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:

npm install webpagetest-mapper --save

You can then require WebPageTest-mapper and call the returned object’s fetch, map or run methods:

var wpt = require('webpagetest-mapper');

wpt.fetch(options).then(map.bind(null, options));

More detail about these methods can be found in the readme.

Development

We welcome contributions in the form of pull requests and issues.

If you would like to hack on the code, clone the git repo:

git clone git@github.com:nature/webpagetest-mapper.git

From the project root, you can then install the dependencies:

npm install

Lint the code:

npm run lint

Run the unit tests:

npm test

Please ensure that you have adhered to the contribution guidelines before submitting pull requests.