Metricsgrade

This tool measures any webpage for performances. This project uses Puppeteer to make painless automation.

Installation

To install metricsgrade:

git clone https://github.com/bell-lab-apps/metricsgrade.git
cd metricsgrade
npm install -g

Usage

metricsgrade <url>

Several options are available for ease of use. Use -h (--help) to display them.

➜ metricsgrade -h
  Usage: metricsgrade [options] <url ...>

  Measures webpage loading metrics

  Options:

    -r, --repeat [n]                     The number of times the page metrics are measured (default: 5)
    -w, --width [width]                  The viewport's width to set (default: 1920)
    -H, --height [height]                The viewport's height to set (default: 1080)
    -c, --custom-path [custom-path]      Path to custom path configuration file
    -o, --output-format [output-format]  The desired output format (default: table)
    --wait-until [wait-until]            The waitUntil value of the Page.reload options accepted by puppeteer
    --with-redirects                     Whether we want to test the timings of the whole redirect chain
    --output-file [output-file]          Whether we want to export data in a file, and the desired path to the file
    --no-headless                        Defines if we dont want to use puppeteer headless mode
    --no-sandbox                         Disable chrome sandbox mode, mandatory in some systems
    -h, --help                           Output usage information

Custom user path

A custom file path can be set in the cli options. That way, you can tell puppeteer what it should do before measuring any kind of metric.

This option can be useful if you need to be logged in before being able to access to your application.

To include your file into the process, just use -c <relative path to your file> option.

metricsgrade localhost:8000 -c '../../custom-path.js'

The custom-path.js file should contain an exported ES module.

// index.js: The custom path function is called like so :
if (customPath) {
    const customPathFunction = require(customPath);
    await customPathFunction(page, logInfo);
}
// custom-path.js: example of login process
const LOGIN_INPUT = 'input[type="login"]';
const PASSWORD_INPUT = 'input[type="password"]';
module.exports = async (page, logInfo) => {
    const login = 'my-secret-login';
    const password = 'my-really-secret-password';
    const loginUrl = 'http://localhost:8080/login';
    logInfo(`Loading ${loginUrl}`);
    // Go to the login page url, and wait for the selector to be ready.
    await page.goto(loginUrl);
    await page.waitForSelector(LOGIN_INPUT);
    logInfo('Logging in...');
    // Type credentials.
    await page.type(LOGIN_INPUT, login);
    await page.type(PASSWORD_INPUT, password);
    logInfo('Redirecting');
    // The process will continue once the redirect is resolved.
    return page.waitForNavigation();
};

Those functions have access to two arguments :

• page (The Page puppeteer object to be able to access the full puppeteer page instance API)
• logInfo (To log custom information)

Export data to a file

You can choose to export to multiple formats and export formatted data to a file. For now, only table, raw, json and csv are available. table and raw data will be exported to a txt file. To use it, just type :

metricsgrade localhost:8000 --output-format json --output-file ~/results.json

If you don't provide any filename, a file will automatically be created in your current directory.

"Wait until" option

To make a page reload, metricsgrade does a Page.reload() from puppeteer's Page object. This object accepts a waitUntil parameter, which defines when the page navigation has succeeded, and when the application should collect the metrics and reload the page. You can find more information about Page.reload() right here.

To use, just add the --wait-until flag and the desired options. Since Page.reload accepts either a Sring or an Array of Strings, if you want to add multiple values, just split them with a ,

For example:

metricsgrade localhost:8000 --wait-until networkidle0,load

Development

To contribute, just run the following commands :

git clone https://github.com/bell-lab-apps/metricsgrade.git
cd metricsgrade
npm install

Then, to use metricsgrade just run it via cli.js, for example :

./cli.js http://localhost:8000

Useful Resources

• Commander documentation
• Puppeteer API