russelyang / pwmetrics

Progressive web metrics at your fingertipz

pwmetrics

Progressive web metrics at your fingertipz. 💅

CLI tool and lib to gather performance metrics via Lighthouse. IN BETA.

Documentation on these metrics in the works. If you hit bugs in the metrics collection, report at Lighthouse issues.

Install

$ npm install --global pwmetrics
# or
$ npm install --save pwmetrics

CLI Usage

# --runs=n     Does n runs (eg. 3, 5), and reports the median run's numbers.
#              Median run selected by run with the median TTI.
pwmetrics http://example.com/ --runs=3

# --submit     Submits results to a google spreadsheet (requires some setup)
pwmetrics http://goat.com --submit

# --json       Reports json details to stdout.
pwmetrics --json http://example.com/

# returns...
# {runs: [{
#   "timings": [
#     {
#       "name": "First Contentful Paint",
#       "value": 289.642
#     },
#     {
#       "name": "First Meaningful Paint",
#       "value": 289.6
#     },
#     ...


# --config        Provide configuration. See _Defining config_ below.
pwmetrics --config=your-own-file.js
pwmetrics --config


##
## CLI options useful for CI
##

# --expectations  Assert metrics results against provides values. See _Defining expectations_ below.
pwmetrics --expectations --config=your-own-file.js
pwmetrics --expectations

##
## CLI options useful for submittiing data to services
##

# --submit       Submit results to Google Sheets. See _Defining submit_ below.
pwmetrics --submit --config=your-own-file.js
pwmetrics --submit

Defining config

# run pwmetrics with config in package.json
pwmetrics --config

package.json

...
  "pwmetrics": {
    "url": "http://example.com/",
    "sheets": {
      // sheets configurations
    },
    "expectations": {
      // expectations configurations
    }
  }
...

# run pwmetrics with config in your-own-file.js
pwmetrics --config=your-own-file.js

your-own-file.js

module.exports = {
  "url": "http://example.com/",
  "flags": {
    // submit: true, // submit metrics
    // expectations: true // assert against the provided metric thresholds
  },
  "sheets": {
    // sheets configuration
  },
  "expectations": {
    // expectations configuration
  }
}

Defining expectations

# run pwmetrics with config in package.json
pwmetrics --expectations

package.json

...
  "pwmetrics": {
    "url": "http://example.com/",
    "expectations": {
      "ttfmp": {
        "warn": ">=3000",
        "error": ">=5000"
      },
      "psi": {
        "warn": ">=1500",
        "error": ">=3200"
      }
    }
  }
...

# run pwmetrics with config in your-own-file.js
pwmetrics --expectations --config=your-own-file.js

your-own-file.js

module.exports = {
  url: 'http://example.com/',
  expectations: {
    ttfmp: {
      warn: '>=3000',
      error: '>=5000'
    },
    psi: {
      warn: '>=1500',
      error: '>=3200'
    }
  }
}

Defining submit

Instructions:

• Copy this spreadsheet.
• Copy the ID of the spreadsheet into the config as value of sheets.options.spreadsheetId property.
• Setup Google Developer project and get credentials. (everything in step 1 here)
• Take a client_secret and put it into the config as value of sheets.options.clientSecret property.

# run pwmetrics with config in package.json
pwmetrics --submit

package.json

...
  "pwmetrics": {
    "url": 'http://example.com/',
    "sheets": {
      "type": 'GOOGLE_SHEETS', // sheets service type. Available types: GOOGLE_SHEETS
      "options": {
        "spreadsheetId": "sheet_id",
        "tableName": "data",
        "clientSecret": {
          // Data object. Can be get by (using everything in step 1 here)[https://developers.google.com/sheets/api/quickstart/nodejs#step_1_turn_on_the_api_name]
        }
      }
    }
  }
...

# run pwmetrics with config in your-own-file.js
pwmetrics --submit --config=your-own-file.js

your-own-file.js

module.exports = {
  url: 'http://example.com/',
  sheets: {
    type: 'GOOGLE_SHEETS', // sheets service type. Available types: GOOGLE_SHEETS
    options: {
      spreadsheetId: 'sheet_id',
      tableName: 'data',
      clientSecret: {
        // Follow step 1 of https://developers.google.com/sheets/api/quickstart/nodejs#step_1_turn_on_the_api_name
        // Then paste resulting JSON payload as this clientSecret value
      }
    }
  }
}

Available metrics:

• ttfcp - First Contentful Paint
• ttfmp - First Meaningful Paint
• psi - Perceptual Speed Index
• fv - First Visual Change
• vc - Visually Complete 100%
• tti - Time to Interactive
• vc85 - Visually Complete 85%

Default Lighthouse options

• disableCpuThrottling is set false by default. It means that CPU throttling 5x is enabled. To turn it off, run pwmetrcis http:example.com --disableCpuThrottling

API

const PWMetrics = require('pwmetrics');

const pwMetrics = new PWMetrics('http://example.com/', opts);
pwMetrics.start(); // returns Promise

Options Parameter

flags [Object]

Feature flags. These are equal to CLI options. For example, if you want to get result in json format.

const PWMetrics = require('pwmetrics');

const pwMetrics = new PWMetrics('http://example.com/', { flags: { json: true } });
pwMetrics.start();

Default: { disableCpuThrottling: false }

expectations [Object]

Example:

const PWMetrics = require('pwmetrics');

const pwMetrics = new PWMetrics('http://example.com/', { 
  expectations: { 
    // expecations data 
  } 
});
pwMetrics.start();

See Defining expectations above.

Default: {}

sheets [Object]

Example:

const PWMetrics = require('pwmetrics');

const pwMetrics = new PWMetrics('http://example.com/', { 
  sheets: { 
    // sheets data 
  } 
});
pwMetrics.start();

See Defining submit above.

Default: {}

Recipes

• gulp

License

Apache 2.0. Google Inc.