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:

Name	Purpose	Type	Required?	Default Value	Configurable in...
url	Specifies the URL of the page to test	String	Yes	none	Per-page only
repetitions	Specifies the number of times a given URL should be tested	Number	No	3	Per-page & Defaults
timeout	Specifies a time in seconds after which to terminate the browser	Number	No	30	Per-page & Defaults
getRequestStatsFor	Specifies a regular expression to obtain stats for matching network requests	String	No	undefined	Per-page & Defaults
viewPort	An object that specifies the viewport height & width to use for the test/s	Object	No	{ width: 1440, height: 900 }	Per-page & Defaults
pageWaitOnLoad	Specifies how many seconds to keep a page open after page load before capturing stats	Number	No	2	Per-page & Defaults
headless	Specifies whether to run the tests with/without a visible user interface	Boolean	No	false	Per-page & Defaults
showDevTools	Specifies whether to auto-open Chrome Dev Tools for the test	Boolean	No	false	Per-page & Defaults
cookie	Specifies a cookie to set for the page/s under test	Object	No	undefined	Per-page & Defaults
lighthouse	Specifies an array of lighthouse config objects	Array	No	[]	Defaults only
ppc	Specifies an array of page-performance-capture config objects	Array	No	[{ emulateMobile: false, throttle: false } }]	Defaults only

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).