a58510583a | ||
---|---|---|
.. | ||
recipes | ||
architecture.md | ||
authenticated-pages.md | ||
bug-labels.md | ||
configuration.md | ||
error-reporting.md | ||
hacking-tips.md | ||
headless-chrome.md | ||
lantern.md | ||
new-audits.md | ||
performance-budgets.md | ||
plugins.md | ||
puppeteer.md | ||
readme.md | ||
releasing.md | ||
scoring.md | ||
throttling.md | ||
understanding-results.md | ||
variability.md |
readme.md
This directory contains useful documentation, examples (keep reading), and recipes to get you started. For an overview of Lighthouse's internals, see Lighthouse Architecture.
Using programmatically
The example below shows how to run Lighthouse programmatically as a Node module. It
assumes you've installed Lighthouse as a dependency (yarn add --dev lighthouse
).
const fs = require('fs');
const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');
(async () => {
const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
const options = {logLevel: 'info', output: 'html', onlyCategories: ['performance'], port: chrome.port};
const runnerResult = await lighthouse('https://example.com', options);
// `.report` is the HTML report as a string
const reportHtml = runnerResult.report;
fs.writeFileSync('lhreport.html', reportHtml);
// `.lhr` is the Lighthouse Result as a JS object
console.log('Report is done for', runnerResult.lhr.finalUrl);
console.log('Performance score was', runnerResult.lhr.categories.performance.score * 100);
await chrome.kill();
})();
Performance-only Lighthouse run
Many modules consuming Lighthouse are only interested in the performance numbers. You can limit the audits you run to a particular category or set of audits.
// ...
const flags = {onlyCategories: ['performance']};
launchChromeAndRunLighthouse(url, flags).then( // ...
You can also craft your own config (e.g. experimental-config.js) for custom runs. Also see the basic custom audit recipe.
Differences from CLI flags
Note that some flag functionality is only available to the CLI. The set of shared flags that work in both node and CLI can be found in our typedefs. In most cases, the functionality is not offered in the node module simply because it is easier and more flexible to do it yourself.
CLI Flag | Differences in Node |
---|---|
port |
Only specifies which port to use, Chrome is not launched for you. |
chromeFlags |
Ignored, Chrome is not launched for you. |
outputPath |
Ignored, output is returned as string in .report property. |
saveAssets |
Ignored, artifacts are returned in .artifacts property. |
view |
Ignored, use the open npm module if you want this functionality. |
enableErrorReporting |
Ignored, error reporting is always disabled for node. |
listAllAudits |
Ignored, not relevant in programmatic use. |
listTraceCategories |
Ignored, not relevant in programmatic use. |
configPath |
Ignored, pass the config in as the 3rd argument to lighthouse . |
preset |
Ignored, pass the config in as the 3rd argument to lighthouse . |
verbose |
Ignored, use logLevel instead. |
quiet |
Ignored, use logLevel instead. |
Turn on logging
If you want to see log output as Lighthouse runs, set an appropriate logging level in your code and pass
the logLevel
flag when calling lighthouse
.
const flags = {logLevel: 'info'};
launchChromeAndRunLighthouse('https://example.com', flags).then(...);
Configuration
In order to extend the Lighthouse configuration programmatically, you need to pass the config object as the 3rd argument. If omitted, a default configuration is used.
Example:
{
extends: 'lighthouse:default',
settings: {
onlyAudits: [
'first-meaningful-paint',
'speed-index',
'first-cpu-idle',
'interactive',
],
},
}
You can extend base configuration from lighthouse:default, or you can build up your own configuration from scratch to have complete control.
For more information on the types of config you can provide, see Lighthouse Configuration.
Testing on a site with authentication
When installed globally via npm i -g lighthouse
or yarn global add lighthouse
,
chrome-debug
is added to your PATH
. This binary launches a standalone Chrome
instance with an open debugging port.
- Run
chrome-debug
. This will log the debugging port of your Chrome instance - Navigate to your site and log in.
- In a separate terminal tab, run
lighthouse http://mysite.com --port port-number
using the port number from chrome-debug.
Testing on a site with an untrusted certificate
When testing a site with an untrusted certificate, Chrome will be unable to load the page and so the Lighthouse report will mostly contain errors.
If this certificate is one you control and is necessary for development (for instance, localhost
with a self-signed certificate for local HTTP/2 testing), we recommend you add the certificate to your locally-trusted certificate store. In Chrome, see Settings
> Privacy and Security
> Manage certificates
or consult instructions for adding to the certificate store in your operating system.
Alternatively, you can instruct Chrome to ignore the invalid certificate by adding the Lighthouse CLI flag --chrome-flags="--ignore-certificate-errors"
. However, you must be as careful with this flag as it's equivalent to browsing the web with TLS disabled. Any content loaded by the test page (e.g. third-party scripts or iframed ads) will also not be subject to certificate checks, opening up avenues for MitM attacks. For these reasons, we recommend the earlier solution of adding the certificate to your local cert store.
Testing on a mobile device
Lighthouse can run against a real mobile device. You can follow the Remote Debugging on Android (Legacy Workflow) up through step 3.3, but the TL;DR is install & run adb, enable USB debugging, then port forward 9222 from the device to the machine with Lighthouse.
You'll likely want to use the CLI flags --emulated-form-factor=none --throttling.cpuSlowdownMultiplier=1
to disable any additional emulation.
$ adb kill-server
$ adb devices -l
* daemon not running. starting it now on port 5037 *
* daemon started successfully *
00a2fd8b1e631fcb device usb:335682009X product:bullhead model:Nexus_5X device:bullhead
$ adb forward tcp:9222 localabstract:chrome_devtools_remote
$ lighthouse --port=9222 --emulated-form-factor=none --throttling.cpuSlowdownMultiplier=1 https://example.com
Lighthouse as trace processor
Lighthouse can be used to analyze trace and performance data collected from other tools (like WebPageTest and ChromeDriver). The traces
and devtoolsLogs
artifact items can be provided using a string for the absolute path on disk if they're saved with .trace.json
and .devtoolslog.json
file extensions, respectively. The devtoolsLogs
array is captured from the Network
and Page
domains (a la ChromeDriver's enableNetwork and enablePage options).
As an example, here's a trace-only run that reports on user timings and critical request chains:
config.json
{
"settings": {
"auditMode": "/User/me/lighthouse/lighthouse-core/test/fixtures/artifacts/perflog/",
},
"audits": [
"user-timings",
"critical-request-chains"
],
"categories": {
"performance": {
"name": "Performance Metrics",
"description": "These encapsulate your web app's performance.",
"audits": [
{"id": "user-timings", "weight": 1},
{"id": "critical-request-chains", "weight": 1}
]
}
}
}
Then, run with: lighthouse --config-path=config.json http://www.random.url