page-performance-capture v0.5.0

Page Performance Capture

Info

In short, a CLI tool for capturing simple performance metrics for a defined set of pages, able to output to json, markdown, or output in a terminal.

This uses puppeteer to launch a Chrome web browser and capture specific data (including averages.)

The data currently captured includes:

• DOM Content Loaded times
• Page load times
• No. network requests
• No. filtered network requests (given a user-defined Regular Expression)

Installation

To install, simply:

npm i -g page-performance-capture

Running

To run, provide a json file as the first argument in the following command:

ppc run <test_file>.json

Otherwise it will look for a ppc-config.json file by default when running only

ppc run

Each test in the test file should conform to the following structure (although only "url" is a required property):

{
    "repetitions": 2,
    "url": "https://www.example.com",
    "getRequestStatsFor": "/.*png.*/",
    "timeout": 20,
    "viewPort": {
        "width": 1440,
        "height": 500
    },
    "headless": false,
    "pageWaitOnLoad": 2,
    "showDevTools": false
}

This structure can be replicated across items in an array to specify the tests:

{
    "pages": [
        {
            "repetitions": 2,
            "url": "https://www.example.com",
            "getRequestStatsFor": "/.*png.*/",
            "timeout": 20,
            "viewPort": {
                "width": 1440,
                "height": 500
            },
            "headless": false,
            "pageWaitOnLoad": 2,
            "showDevTools": false
        },
        {
            "repetitions": 3,
            "url": "https://www.example.com/about",
            "getRequestStatsFor": "/.*png.*/",
            "timeout": 20,
            "viewPort": {
                "width": 1440,
                "height": 500
            },
            "headless": false,
            "pageWaitOnLoad": 2,
            "showDevTools": false,
            "cookie": {
                "name": "cookieName",
                "value": "value"
            }
        }
    ]
}

Note: pages is a required field.

The defaults are as follows:

You may wish to override these defaults if a lot of your test pages require the same configuration.

Thie can be achieved by using a root-level defaults object in the config, which conforms to the same structure as the per-page objects (the only difference being that there is no url property).

{
    "pages": [
        {
            "url": "http://example.com",
            "getRequestStatsFor": "/.*png.*/",
        },
        {
            "repetitions": 2,
            "url": "http://example.com/about",
        },
        {
            "repetitions": 1,
            "url": "http://example.com/contact",
        }
    ],
    "defaults": {
        "repetitions": 3,
        "getRequestStatsFor": "/.*jpeg.*/",
        "timeout": 20,
        "headless": false,
        "viewPort": {
            "width": 1440,
            "height": 500
        },
        "cookie": {
            "name": "cookieName",
            "value": "value",
            "domain": "example.com",
            "path": "/",
            "secure": false,
            "httpOnly": false,
        },
        "lighthouse": [
            { "emulateMobile": true },
            { "emulateMobile": false }
        ],
        "ppc": [
            { "emulateMobile": true, "throttle": false },
            { "emulateMobile": true, "throttle": true },
            { "emulateMobile": false, "throttle": false },
            { "emulateMobile": false, "throttle": true }
        ]
    }
}

You can pass additional flags to the programme.

-o or --output will allow you to specify an output file to write the results to (JSON and Markdown are the only types currently supported).

ppc run <test_file>.json -o <output_file>.md

A note on request size data

Unfortunately, the tools don't exist to obtain accurate results on network request sizes.

• Performance API requires Timings-Allow-Origin: * header on all page resources (of which some third party apps do not have this)
• Puppeteer can accurately capture the requests and allow for accurate counting, however there are discrepancies between the transferSize / dataLength / encodedDataLength / Content-Length values when compared at both a page level and (from what I found) on an individual resource basis.
• Attempted to re-request images directly via Node using the captured list from Puppeteer, however CORS policies will make obtaining accurate results impossible for real world sites.

The best recommendation I can make is to set the showDevTools to true and set the pageWaitOnLoad value to as many seconds as you need to capture the size data for network requests directly from the Chrome Dev Tools "Networks" tab.

Other notes

Currently lighthouse & ppc mobile emulation and throttling are only supported in an all-or-nothing way. That is they cannot yet be specified per-test, only in the default config (see the above table).