Webpagetest-mapper NPM

webpagetest-mapper

Maps JSON result data from marcelduran/webpagetest-api into human-readable document formats. Read more.

Why would I want that?

Perhaps you'd like to generate a report containing sprauncy visualizations of your website's performance. Or maybe you want to analyse all of the raw data behind WebPageTest's median-based summaries using a spreadsheet.

This tool can help you do both of those things. It can also be extended to map WebPageTest result data into any conceivable format.

What formats does it support?

Three data mappers are provided out of the box: html-comparison, html-distribution and odf-spreadsheet.

html-comparison

The html-comparison mapper generates an HTML document containing three sections:

A table summarising the salient metrics for each test. Each data cell in the table links to the equivalent results page on the WebPageTest instance. The page-title cells link to the page under test.
SVG charts that draw comparisons between various aspects of the test results. These charts are rendered from static markup, so will display correctly even if JavaScript is disabled in the viewer's web browser.
A table summarising the optimization scores that WebPageTest awards to each page. Each data cell in this table links to the optimization details.

Throughout the document, tests are identified consistently by colour, to help readers track trends from section to section.

Click here for an example.

Screenshot

html-distribution

The html-distribution mapper generates an HTML document containing SVG histograms that show the distribution of data. There is one histogram per metric per test.

Each bar on the histogram represents a standard deviation from the mean. The bars for data less than the mean are coloured green and the ones for figures greater than mean are red.

Click here for an example.

Screenshot

odf-spreadsheet

The odf-spreadsheet mapper generates an Open Document Format (ODF) spreadsheet.

For each test, a table is created in the spreadsheet which breaks down the salient metrics for every run. At the bottom of this table, a number of functions are applied to help show the distribution of the data.

Click here for an example.

Screenshot

Can I specify other formats?

Yes. Mappers are loaded with require, using a two-pass approach that enables custom extensions to be invoked.

Initially, mappers are speculatively loaded from the src/mappers sub-directory of the base installation. If that effort throws, a second attempt is made to load them from the specified module path verbatim. Thus, standard mappers are loaded at the first attempt and custom extensions are loaded at the second attempt.

Mappers are called with two arguments, options and results. They should return an ES6-compatible promise representing the mapped result.

Consult the standard mapper implementations for more information.

How do I install it?

If you're using npm:

npm install webpagetest-mapper --global

Or if you just want the git repo:

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

How do I use it?

From the command line

The executable name is wptmap.

For command-line help, run:

wptmap --help

Available options are:

--uri <URI>: Base URI of the WebPageTest instance. The default is www.webpagetest.org.
--key <key>: Your WebPageTest API key.
--location <location>: The WebPageTest location. The default is Dulles:Chrome.
--connection <connection>: The WebPageTest connection speed. The default is Native Connection.
--tests <path>: Path to the test definitions file. The default is tests.json.
--count <number>: The number of times to run each test. The default is 9.
--email <address>: The email address to notify when tests are finished.
--wait <interval>: The number of seconds to wait between attempts to fetch result data. The default is 600 (10 minutes).
--output <path>: File to write the mapped data to. The default is stdout.
--dump <path>: Path to a file, in which to dump intermediate results for later processing. Use this option if you need to run the same result data through more than one mapper.
--results <path>: Path to the intermediate results file, previously dumped using --dump. This option skips actually running the tests and re-uses result JSON from earlier runs.
--resultIds <ids>: Fetch results from WebPageTest using the comma-separated list of result ids and skip running the tests. Use this option when you want to map data from pre-existing WebPageTest runs.
--mapper <path>: The mapper to use. The default is html-comparison.
--silent: Disable logging. Overrides syslog.
--syslog <facility>: Send log data to syslog, using the specified facility level.
--config <path>: Attempt to read configuration options from a JSON file. The default is .wptrc. Click here for an example config file.

From a node.js project

Import the library using require:

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

Three functions are exported from the main module: fetch, map and run. They each take an options object as their first argument and return an ES6 promise representing their result.

fetch (options)

fetch asynchronously invokes WebPageTest and returns an ES6 promise that resolves to the following data structure:

{
    data: [ ... ],      // Result array from WebPageTest
    options: { ... },   // Cloned options object normalised with default values
    times: {
        begin: { ... }, // JavaScript Date instance representing the start time
        end: { ... }    // JavaScript Date instance representing the finish time
    }
}

The returned promise is only resolved when all of the tests have completed. It is never rejected.

Instead, if any tests fail, the equivalent item in the results.data array will have a property named error which contains the Error instance. Handling errors in this way prevents rogue network issues from failing an entire run, while still propagating error information for inspection by the caller.

fetch accepts an options object as its only argument, supporting the following properties:

uri: Base URI of the WebPageTest instance. The default is www.webpagetest.org.
key: Your WebPageTest API key.
location: The WebPageTest location. The default is Dulles:Chrome.
connection: The WebPageTest connection speed. The default is Native Connection.
tests: Path to the test definitions file or an array of test definitions. The default is tests.json.
count: The number of times to run each test. The default is 9.
wait: The number of seconds to wait between attempts to fetch result data. The default is 600 (10 minutes).
email: The email address to notify when tests are finished.
resultIds: Array of WebPageTest result ids to use instead of actually running the tests.
dump: Dump intermediate results to file.
silent: Disable logging. Overrides syslog and log.
syslog: Send log data to syslog, using the specified facility level. Overrides log.
log: Logging implementation. Needs the functions log.info(), log.warn() and log.error().
config: Attempt to read configuration options from a JSON file. The default is .wptrc.

Example

wpt.fetch({
    uri: 'example.com',
    location: 'London:Firefox',
    tests: path.join(__dirname, 'tests.json'),
    count: 25,
    silent: true
}).then(function (result) {
    result.data.forEach(function (datum, index) {
        var id = '#' + index + ' [' + datum.name + ']';

        if (!datum.error) {
            return console.log('Test ' + id + ' passed: ' + datum.id);
        }

        console.log('Test ' + id + ' failed, reason: ' + datum.error.message);
    });
});

map (options, results)

map is not asynchronous but still returns a promise, to maintain consistency with the rest of the API.

The value of the promise is dependent on the result of the specific mapper that is invoked. Of the built-in mappers, html-comparison returns a string containing the document markup and odf-spreadsheet returns a Buffer instance containing the binary content.

This promise will be rejected if an error is thrown from the mapper.

map accepts an options object as its first argument, supporting the following properties:

results: Read results object from file.
mapper: The mapper to use. The default is html-comparison.
silent: Disable logging. Overrides syslog and log.
syslog: Send log data to syslog, using the specified facility level. Overrides log.
log: Logging implementation. Needs the functions log.info(), log.warn() and log.error().
config: Attempt to read configuration options from a JSON file. The default is .wptrc.

The second argument to map is a results object, in the format returned by fetch.

Example

wpt.map({
    mapper: 'odf-spreadsheet',
    silent: true
}, results).then(function (mapped) {
    fs.writeFileSync(path.join(__dirname, 'results.ods'), mapped);
}).catch(function (error) {
    console.log(error.stack);
});

run (options)

run combines the actions from fetch and map, asynchronously invoking WebPageTest and returning a promise that represents the mapped data.

It accepts an options object as its only argument, supporting the aggregated properties from fetch and map.

Example

wpt.run({
    uri: 'example.com',
    location: 'London:Firefox',
    tests: path.join(__dirname, 'tests.json'),
    count: 25,
    mapper: 'odf-spreadsheet',
    silent: true
}).then(function (mapped) {
    fs.writeFileSync(path.join(__dirname, 'results.ods'), mapped);
}).catch(function (error) {
    console.log(error.stack);
});

What is the format of the test definitions file?

This is a very basic JSON file containing an array of test objects.

Each test object supports three properties, name, url and type:

The name property forms the basis of the WebPageTest label and is used to identify tests in the output from all mappers.
The url property is passed to WebPageTest as the URL to test and is also linked to in the output from the html-comparison mapper.
The type property is used to differentiate tests in the output from the html-comparison mapper. Currently it supports the values home and away, but these are open to change with feedback from more widespread usage.

Click here for an example test definitions file.

Is there a change log?

Yes.

How do I set up the dev environment?

The dev environment relies on node.js, JSHint, Mocha, Chai, Mockery and Spooks. Assuming that you already have node and NPM set up, you just need to run npm install to install all of the dependencies as listed in package.json.

You can lint the code with the command npm run lint.

You can run the unit tests with the command npm test.