Puppeteer Performance Gatherer

Installation

npm i puppeteer-performance-gatherer --save

Usage

Basic

const puppeteer = require("puppeteer");
const Gatherer = require("puppeteer-performance-gatherer");

let browser = await puppeteer.launch(opts);
let page = await browser.newPage();

// initialize the gatherer with the puppeteer page
let gatherer = new Gatherer(page, {url: "www.example.com", name: "example"});

// run lighthouse on the given url and capture tracing of the given page
await gatherer.start({"lighthouse": true, "tracing": true});

// do stuff that is captured by the tracing
await page.goto("www.example.com");

// stop tracing
await gatherer.stop();

A gatherer always needs a puppeteer page, the url and name are optional:

• url: The endpoint that lighthouse will use to run an audit. If this is null, lighthouse will use page.url();
• name: The tracing output file name

gatherer.start() also accepts lighthouse and tracing options:

// port and output are always overriden by the gatherer
let lighthouseOptions = {
    disableStorageReset: true,
    disableDeviceEmulation: true,
    emulatedFormFactor: 'desktop'
}

// name and dir are custom settings that have precedence over path
// The default dir is traces
let tracingOptions = {
    path: "traces/trace.json",
    name: "trace",
    dir: "traces",
    screenshots: false,
    categories: [],
}

await gatherer.start({lighthouse: lighthouseOptions, tracing: tracingOptions});

You don't need to use gatherer.start(). You can run lighthouse and tracing manually:

await gatherer.runLighthouse(options, config);

await gatherer.captureTracing(options);
await gatherer.stopTracing();

Lighthouse

A gatherer can only have one lighthouse result that can be accessed by using gatherer.lighthouse

Using the gatherer.lighthouseAudits and gatherer.lighthouseCategories methods, you can easily get the lighthouse audit results, perfect for testing:

const accessibilityScore = gatherer.lighthouseCategories.get('accessibility');
expect(accessibilityScore).to.be.at.least(90);

const performanceScore = gatherer.lighthouseCategories.get('performance');
expect(performanceScore).to.be.at.least(75);

const contrastCheck = gatherer.lighthouseAudits.get('color-contrast');
expect(contrastCheck).to.equal('Pass');

const pageSpeedScore = gatherer.lighthouseAudits.get('speed-index');
expect(pageSpeedScore).to.be.at.least(75);

Performance

The gatherer can also extract performance entries from the page (https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEntry)

Some examples:

const resourceTimings = await gatherer.extractResourceTimings();

const [navigationTiming] = await gatherer.extractNavigationTimings();
console.log(navigationTiming["domInteractive"]);

const paintTimings = await gatherer.extractPerformanceTimingsByType("paint");

const [measure] = await gatherer.extractPerformanceTimingsByName("name", "measure");
console.log(measure.duration);

const performanceTimeline = await gatherer.extractPerformanceTimings();

Emulation

const { NETWORK_PRESETS } = require("puppeteer-performance-gatherer/utils/emulation");

// gatherer.emulate(network_preset, cpuThrottleRate)
await gatherer.emulate(NETWORK_PRESETS.Regular2G, 2);

await gatherer.emulate({
    'offline': false,
    'downloadThroughput': 30 * 1024 * 1024 / 8,
    'uploadThroughput': 15 * 1024 * 1024 / 8,
    'latency': 2
}, 0);

Asynchronous performance testing

Imagine that we have a website with a button that asynchronously loads some data, we can get the loadtime by doing the following:

let button = await page.$('#button');

await button.click().then(async () => await gatherer.waitUntilDomSilent(".content", 1000, "exampleID"));

const [measure] = await gatherer.extractPerformanceTimingsByName("exampleID", "measure");
console.log(measure.duration);

How does gatherer.waitUntilDomSilent(selector, timeout, measureID) work?

The gatherer will use a mutationobserver to observe the given selector for changes. If the given selector doesn't change for the duration of the timeout, we consider the selector loaded. The gatherer will create a performance entry with the given measureID so you can retrieve the time needed to load the data. In the example this will be the time needed to fetch the new data and populate the DOM node for the given selector.

Final notes

I've made this package during my internship at Info Support to be able to test performance of asynchronous applications using puppeteer, lighthouse and mocha.