Lighthouse

Using Lighthouse in Chrome DevTools

Using the Chrome extension

Using the Node CLI

npm install -g lighthouse# or use yarn:# yarn global add lighthouse

CLI options

$ lighthouse --helplighthouse<url>Logging:  --verbose  Displays verbose logging                                                                                                      [boolean]  --quiet    Displays no progress, debug logs or errors                                                                                    [boolean]Configuration:  --save-assets                  Save the trace contents& screenshots to disk                                                             [boolean]  --list-all-audits              Prints a list of all available audits and exits                                                           [boolean]  --list-trace-categories        Prints a list of all required trace categories and exits                                                  [boolean]  --additional-trace-categories  Additional categories to capture with the trace (comma-delimited).  --config-path                  The path to the config JSON.  --chrome-flags                 Custom flags to pass to Chrome (space-delimited). For a full list of flags, see                                 http://peter.sh/experiments/chromium-command-line-switches/.                                 Environment variables:                                 CHROME_PATH: Explicit path of intended Chrome binary. Ifset must point to an executable of a build of                                 Chromium version 66.0 or later. By default, any detected Chrome Canary or Chrome (stable) will be launched.                                                                                                                                       [default:""]  --port                         The port to usefor the debugging protocol. Use 0for a random port                                    [default: 0]  --preset                       Use a built-in configuration.                                            [choices:"full","perf","mixed-content"]  --hostname                     The hostname to usefor the debugging protocol.                                              [default:"localhost"]  --max-wait-for-load            The timeout (in milliseconds) towait before the page is considereddone loading and the run should continue.                                 WARNING: Very high values can lead to large traces and instability                                 [default: 45000]  --enable-error-reporting       Enables error reporting, overriding any saved preference. --no-enable-error-reporting willdo the opposite. More:                                 https://git.io/vFFTO  --gather-mode, -G              Collect artifacts from a connected browser and save to disk. If audit-mode is not also enabled, the run will quit                                 early.                                                                                                    [boolean]  --audit-mode, -A               Process saved artifacts from disk                                                                         [boolean]Output:  --output       Reporterfor the results, supports multiple values                        [choices:"csv","json","html"] [default:"html"]  --output-path  The file path to output the results. Use'stdout' to write to stdout.                 If using JSON or CSV output, default is stdout.                 If using HTML output, default is a filein the working directory with a name based on thetest URL and date.                 If using multiple outputs, --output-path is ignored.                 Example: --output-path=./lighthouse-results.html  --view         Open HTML reportin your browser                                                                                          [boolean]Options:  --help                        Showhelp                                                                                                  [boolean]  --version                     Show version number                                                                                        [boolean]  --blocked-url-patterns        Block any network requests to the specified URL patterns                                                     [array]  --disable-storage-reset       Disable clearing the browser cache and other storage APIs before a run                                     [boolean]  --disable-device-emulation    Disable Nexus 5X emulation                                                                                 [boolean]  --throttling-method                  Controls throttling method         [choices:"devtools","provided","simulate"]  --throttling.rttMs                   Controls simulated network RTT (TCP layer)  --throttling.throughputKbps          Controls simulated network download throughput  --throttling.requestLatencyMs        Controls emulated network RTT (HTTP layer)  --throttling.downloadThroughputKbps  Controls emulated network download throughput  --throttling.uploadThroughputKbps    Controls emulated network upload throughput  --throttling.cpuSlowdownMultiplier   Controls simulated + emulated CPU throttling  --extra-headers               Set extra HTTP Headers to pass with request                                                                 [string]Examples:  lighthouse<url> --view                                                   Opens the HTML reportin a browser after the run completes  lighthouse<url> --config-path=./myconfig.js                              Runs Lighthouse with your own configuration: custom audits, report                                                                            generation, etc.  lighthouse<url> --output=json --output-path=./report.json --save-assets  Save trace, screenshots, and named JSON report.  lighthouse<url> --disable-device-emulation                               Disable device emulation and all throttling.    --throttling-method=provided  lighthouse<url> --chrome-flags="--window-size=412,732"                   Launch Chrome with a specific window size  lighthouse<url> --quiet --chrome-flags="--headless"                      Launch Headless Chrome, turn off logging  lighthouse<url> --extra-headers"{\"Cookie\":\"monster=blue\"}"          Stringify\'d JSON HTTP Header key/value pairs to sendin requests  lighthouse<url> --extra-headers=./path/to/file.json                      Path to JSON file of HTTP Header key/value pairs to sendin requestsFor more information on Lighthouse, see https://developers.google.com/web/tools/lighthouse/.

Output Examples

lighthouse# saves `./<HOST>_<DATE>.report.html`lighthouse --output json# json output sent to stdoutlighthouse --output html --output-path ./report.html# saves `./report.html`# NOTE: specifying an output path with multiple formats ignores your specified extension for *ALL* formatslighthouse --output json --output html --output-path ./myfile.json# saves `./myfile.report.json` and `./myfile.report.html`lighthouse --output json --output html# saves `./<HOST>_<DATE>.report.json` and `./<HOST>_<DATE>.report.html`lighthouse --output-path=~/mydir/foo.out --save-assets# saves `~/mydir/foo.report.html`# saves `~/mydir/foo-0.trace.json` and `~/mydir/foo-0.screenshots.html`lighthouse --output-path=./report.json --output json# saves `./report.json`

Lifecycle Examples

lighthouse http://example.com -G# launches browser, collects artifacts, saves them to disk (in `./latest-run/`) and quitslighthouse http://example.com -A# skips browser interaction, loads artifacts from disk (in `./latest-run/`), runs audits on them, generates reportlighthouse http://example.com -GA# Normal gather + audit run, but also saves collected artifacts to disk for subsequent -A runs.# You can optionally provide a custom folder destination to -G/-A/-GA. Without a value, the default will be `$PWD/latest-run`.lighthouse -GA=./gmailartifacts https://gmail.com

Notes on Error Reporting

Viewing a report

Online Viewer

Docs & Recipes

Develop

Setup

# yarn should be installed firstgit clone https://github.com/GoogleChrome/lighthousecd lighthouseyarnyarn install-allyarn build-all

Run

node lighthouse-cli http://example.com

Tests

# lint and test all filesyarntest# watch for file changes and run tests#   Requires http://entrproject.org : brew install entryarn watch## run linting, unit, and smoke tests separatelyyarn lintyarn unityarn smoke## run tsc compileryarn type-check

Lighthouse Integrations

Related Projects

FAQ

How does Lighthouse work?

Can I configure the lighthouse run?

How does Lighthouse use network throttling, and how can I make it better?

Are results sent to a remote server?

How do I author custom audits to extend Lighthouse?

How do I contribute?