Lighthouse CI

A useful wrapper around Google Lighthouse CLI

Install

$ npm install -g lighthouse-ci

Table of Contents

• Lighthouse CI
  • Install
  • Table of Contents
  • Usage
  • CLI
  • Lighthouse flags
    • Chrome flags
  • Configuration
  • Performance Budgets
  • Contributors
  • License

Usage

lighthouse-ci --help

CLI

$ lighthouse-ci --help

  Usage
    $ lighthouse-ci <target-url>

  Example
    $ lighthouse-ci https://example.com
    $ lighthouse-ci https://example.com -s
    $ lighthouse-ci https://example.com --score=75
    $ lighthouse-ci https://example.com --accessibility=90 --seo=80
    $ lighthouse-ci https://example.com --accessibility=90 --seo=80 --report=folder
    $ lighthouse-ci https://example.com --report=folder --config-path=configs.json

  Options
    -s, --silent                  Run Lighthouse without printing report log
    --report=<path>               Generate an HTML report inside a specified folder
    --filename=<filename>         Specify the name of the generated HTML report file (requires --report)
    -json, --jsonReport           Generate JSON report in addition to HTML (requires --report)
    --config-path                 The path to the Lighthouse config JSON (read more here: https://github.com/GoogleChrome/lighthouse/blob/master/docs/configuration.md)
    --budget-path                 The path to the Lighthouse budgets config JSON (read more here: https://developers.google.com/web/tools/lighthouse/audits/budgets)
    --score=<threshold>           Specify a score threshold for the CI to pass
    --performance=<threshold>     Specify a minimal performance score for the CI to pass
    --pwa=<threshold>             Specify a minimal pwa score for the CI to pass
    --accessibility=<threshold>   Specify a minimal accessibility score for the CI to pass
    --best-practice=<threshold>   [DEPRECATED] Use best-practices instead
    --best-practices=<threshold>  Specify a minimal best-practice score for the CI to pass
    --seo=<threshold>             Specify a minimal seo score for the CI to pass
    --budget.<counts|sizes>.<type>    Specify individual budget threshold (if --budget-path not set)

Lighthouse flags

In addition to listed lighthouse-ci configuration flags, it is also possible to pass any native lighthouse flags.

To see the full list of available flags, please refer to the official Google Lighthouse documentation.

eg.

# Launches browser, collects artifacts, saves them to disk (in `./test-report/`) and quits 
$ lighthouse-ci --gather-mode=test-report https://my.website.com
# skips browser interaction, loads artifacts from disk (in `./test-report/`), runs audits on them, generates report 
$ lighthouse-ci --audit-mode=test-report https://my.website.com

Chrome flags

In addition of the lighthouse flags, you can also specify extra chrome flags comma separated.

eg.

$ lighthouse-ci --chrome-flags=--cellular-only,--force-ui-direction=rtl https://my.website.com

eg.

$ lighthouse-ci --emulated-form-factor desktop --seo 92 https://my.website.com

Configuration

Lighthouse CI allows you to pass a custom Lighthouse configuration file. Read Lighthouse Configuration to learn more about the configuration options available.

Just generate your configuration file. For example this config.json

{
  "extends": "lighthouse:default",
  "audits": [
    "user-timings",
    "critical-request-chains"
  ],
 
  "categories": {
    "performance": {
      "name": "Performance Metrics",
      "description": "Sample description",
      "audits": [
        {"id": "user-timings", "weight": 1},
        {"id": "critical-request-chains", "weight": 1}
      ]
    }
  }
}

Then run Lighthouse CI with the --config-path flag

$ lighthouse-ci https://example.com --report=reports --config-path=config.json

The generated report inside reports folder will follow the custom configuration listed under the config.json file.

Performance Budget

Lighthouse CI allows you to pass a performance budget configuration file (see Lighthouse Budgets). There are several options to pass performance budget configs:

Option 1.

Add configurations to your config.json file like and use instructions above.

{
  "extends": "lighthouse:default",
  "settings": {
    "budgets": [
      {
        "resourceCounts": [
          { "resourceType": "total", "budget": 10 },
          ...
        ],
        "resourceSizes": [
          { "resourceType": "total", "budget": 100 },
          ...
        ]
      }
    ]
  }
}

Option 2.

Generate budget.json with content like:

[
  {
    "resourceCounts": [
      { "resourceType": "total", "budget": 10 },
      ...
    ],
    "resourceSizes": [
      { "resourceType": "total", "budget": 100 },
      ...
    ]
  }
]

Then run Lighthouse CI with the --budget-path flag

$ lighthouse-ci https://example.com --report=reports --budget-path=budget.json

Option 3.

Pass individual parameters via CLI

$ lighthouse-ci https://example.com --report=reports --budget.counts.total=20  --budget.sizes.fonts=100000

Contributors

Thanks goes to these wonderful people (emoji key):

Andrea Sonny 💬 💻 📖	Celso Santa Rosa 💻	Ben Hammond 🐛 💻	Alex Tenepere 🐛 💻	Michael Griffiths 💻	Connor Markwell 💻	Sebastian Engel 🐛 💻
Alex Smagin 💻 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT

Created with 🦄 by andreasonny83