-
Notifications
You must be signed in to change notification settings - Fork 9.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Docs: update readme, add docs/readme, modernize a bit (#2341)
* Docs: update readme, add docs/readme, modernize a bit * feedback * feedback * feedback * add back not on extending default.js * typo * tweaks * remove filename
- Loading branch information
Showing
3 changed files
with
217 additions
and
188 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,114 @@ | ||
This directory contains useful documentation, examples (keep reading), | ||
and [recipes](./recipes/) to get you started. For an overview of Lighthouse's | ||
internals, see [Lighthouse Architecture](architecture.md). | ||
|
||
## 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`). | ||
|
||
```javascript | ||
const lighthouse = require('lighthouse'); | ||
const chromeLauncher = require('lighthouse/chrome-launcher/chrome-launcher'); | ||
|
||
function launchChromeAndRunLighthouse(url, flags, config = null) { | ||
return chromeLauncher.launch().then(chrome => { | ||
flags.port = chrome.port; | ||
return lighthouse(url, flags, config).then(results => | ||
chrome.kill().then(() => results) | ||
); | ||
}); | ||
} | ||
|
||
const flags = {output: 'json'}; | ||
|
||
// Usage: | ||
launchChromeAndRunLighthouse('https://example.com', flags).then(results => { | ||
// Use results! | ||
}); | ||
``` | ||
|
||
### Turn on logging | ||
|
||
If you want to see log output as Lighthouse runs, include the `log` module | ||
and set an appropriate logging level in your code. You'll also need to pass | ||
the `logLevel` flag when calling `lighthouse`. | ||
|
||
```javascript | ||
const log = require('lighthouse/lighthouse-core/lib/log'); | ||
|
||
const flags = {logLevel: 'info', output: 'json'}; | ||
log.setLevel(flags.logLevel); | ||
|
||
launchChromeAndRunLighthouse('https://example.com', flags).then(...); | ||
``` | ||
|
||
## 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` | ||
- navigate to and log in to your site | ||
- in a separate terminal tab `lighthouse http://mysite.com` | ||
|
||
## Testing on a mobile device | ||
|
||
Lighthouse can run against a real mobile device. You can follow the [Remote Debugging on Android (Legacy Workflow)](https://developer.chrome.com/devtools/docs/remote-debugging-legacy) 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 `--disable-device-emulation --disable-cpu-throttling` and potentially `--disable-network-throttling`. | ||
|
||
```sh | ||
$ 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 --disable-device-emulation --disable-cpu-throttling https://mysite.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. The `devtoolsLogs` array is captured from the `Network` and `Page` domains (a la ChromeDriver's [enableNetwork and enablePage options]((https://sites.google.com/a/chromium.org/chromedriver/capabilities#TOC-perfLoggingPrefs-object)). | ||
|
||
As an example, here's a trace-only run that's reporting on user timings and critical request chains: | ||
|
||
### `config.json` | ||
|
||
```json | ||
{ | ||
"audits": [ | ||
"user-timings", | ||
"critical-request-chains" | ||
], | ||
|
||
"artifacts": { | ||
"traces": { | ||
"defaultPass": "/User/me/lighthouse/lighthouse-core/test/fixtures/traces/trace-user-timings.json" | ||
}, | ||
"devtoolsLogs": { | ||
"defaultPass": "/User/me/lighthouse/lighthouse-core/test/fixtures/traces/perflog.json" | ||
} | ||
}, | ||
|
||
"aggregations": [{ | ||
"name": "Performance Metrics", | ||
"description": "These encapsulate your app's performance.", | ||
"scored": false, | ||
"categorizable": false, | ||
"items": [{ | ||
"audits": { | ||
"user-timings": { "expectedValue": 0, "weight": 1 }, | ||
"critical-request-chains": { "expectedValue": 0, "weight": 1} | ||
} | ||
}] | ||
}] | ||
} | ||
``` | ||
|
||
Then, run with: `lighthouse --config-path=config.json http://www.random.url` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,11 +1,32 @@ | ||
# Basic custom audit recipe for Lighthouse | ||
# Basic Custom Audit Recipe | ||
|
||
A hypothetical site measures the time from navigation start to when the page has initialized and the main search box is ready to be used. It saves that value in a global variable, `window.myLoadMetrics.searchableTime`. | ||
> **Tip**: see [Lighthouse Architecture](../../../docs/architecture.md) for information | ||
on terminology and architecture. | ||
|
||
This Lighthouse [gatherer](searchable-gatherer.js)/[audit](searchable-audit.js) pair will take that value from the context of the page and test whether or not it stays below a test threshold. | ||
## What this example does | ||
|
||
The config file tells Lighthouse where to find the gatherer and audit files, when to run them, and how to incorporate their output into the Lighthouse report. | ||
This example shows how to write a custom Lighthouse audit for a hypothetical search page. The page is considered fully initialized when the main search box (the page's "hero element") is ready to be used. When this happens, the page uses `performance.now()` to find the time since navigation start and saves the value in a global variable called `window.myLoadMetrics.searchableTime`. | ||
|
||
## Run | ||
With site running: | ||
`lighthouse --config-path=custom-config.js https://test-site.url` | ||
## The Audit, Gatherer, and Config | ||
|
||
- [searchable-gatherer.js](searchable-gatherer.js) - a [Gatherer](https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#components--terminology) that collects `window.myLoadMetrics.searchableTime` | ||
from the context of the page. | ||
|
||
- [searchable-audit.js](searchable-audit.js) - an [Audit](https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#components--terminology) that tests whether or not `window.myLoadMetrics.searchableTime` | ||
stays below a 4000ms threshold. In other words, Lighthouse will consider the audit "passing" | ||
in the report if the search box initializes within 4s. | ||
|
||
- [custom-config.js](custom-config.js) - this file tells Lighthouse where to | ||
find the gatherer and audit files, when to run them, and how to incorporate their | ||
output into the Lighthouse report. This example extends [Lighthouse's | ||
default configuration](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/default.js). | ||
|
||
**Note**: when extending the default configuration file, passes with the same name are merged together, all other arrays will be concatenated, and primitive values will override the defaults. | ||
|
||
## Run the configuration | ||
|
||
Run Lighthouse with the custom audit by using the `--config-path` flag with your configuration file: | ||
|
||
```sh | ||
lighthouse --config-path=custom-config.js https://example.com | ||
``` |
Oops, something went wrong.