lighthouse 8.0.0-dev.20210709 → 8.0.0

package/docs/plugins.md

@@ -0,0 +1,374 @@
+# Plugin Handbook
+
+## Table of Contents
+
+1. [Introduction](#introduction)
+   1. [What is a Lighthouse Plugin?](#what-is-a-lighthouse-plugin)
+   1. [Comparing a Plugin vs. Custom Config](#comparing-a-plugin-vs-custom-config)
+   1. [Getting Started](#getting-started)
+1. [API](#api)
+   1. [Plugin Config](#plugin-config)
+   1. [Plugin Audits](#plugin-audits)
+1. [Best Practices](#best-practices)
+   1. [Naming](#naming)
+   1. [Scoring](#scoring)
+   1. [Common Mistakes](#common-mistakes)
+1. [Examples](#examples)
+
+## Introduction
+
+If you're new to Lighthouse development, start by reading up on the overall [architecture](./architecture.md), how [configuration](./configuration.md) works, and what makes a [good audit](./new-audits.md) before continuing.
+
+### What is a Lighthouse Plugin?
+
+Lighthouse plugins are a way to extend the functionality of Lighthouse with insight from domain experts (that's you!) and easily share this extra functionality with other Lighthouse users. At its core, a plugin is a node module that implements a set of checks that will be run by Lighthouse and added to the report as a new category.
+
+![picture of Lighthouse plugin results in the HTML report](https://user-images.githubusercontent.com/2301202/57053947-24fc9b80-6c57-11e9-8853-df3a174fcf2c.png)
+
+### Comparing a Plugin vs. Custom Config
+
+Plugins are easily shared and have a stable API that won't change between minor version bumps but are also more limited in scope than a [custom Lighthouse configuration](./configuration.md). Before getting started with plugins, think about your current needs, and consult the table below to decide which is best for you.
+
+| Capability                                   | Plugin | Custom Config |
+| -------------------------------------------- | ------ | ------------- |
+| Include your own custom audits               | ✅     | ✅            |
+| Add a custom category                        | ✅     | ✅            |
+| Easily shareable and extensible on NPM       | ✅     | ❌            |
+| Semver-stable API                            | ✅     | ❌            |
+| Gather custom data from the page (artifacts) | ❌     | ✅            |
+| Modify core categories                       | ❌     | ✅            |
+| Modify `config.settings` properties          | ❌     | ✅            |
+
+### Getting Started
+
+To develop a Lighthouse plugin, you'll need to write three things:
+
+1. A `package.json` file to define your plugin's dependencies and point to your `plugin.js` file.
+1. A `plugin.js` file to declare your plugin's audits, category name, and scoring.
+1. Custom audit files that will contain the primary logic of the checks you want to perform.
+
+To see a fully functioning example, see our [plugin recipe](./recipes/lighthouse-plugin-example/readme.md).
+
+#### `package.json`
+
+A Lighthouse plugin is just a node module with a name that starts with `lighthouse-plugin-`. Any dependencies you need are up to you. However, do not depend on Lighthouse directly, use [`peerDependencies`](http://npm.github.io/using-pkgs-docs/package-json/types/peerdependencies.html) to alert dependents, and `devDependencies` for your own local development:
+
+**Example `package.json`**
+
+```json
+{
+  "name": "lighthouse-plugin-cats",
+  "main": "plugin.js",
+  "peerDependencies": {
+    "lighthouse": "^8.0.0"
+  },
+  "devDependencies": {
+    "lighthouse": "^8.0.0"
+  }
+}
+```
+
+#### `plugin.js`
+
+This file contains the configuration for your plugin. It can be called anything you like, just ensure it is referenced by the `"main"` property in your `package.json`.
+
+**Example `plugin.js`**
+
+```js
+module.exports = {
+  // Additional audits to run on information Lighthouse gathered.
+  audits: [{path: 'lighthouse-plugin-cats/audits/has-cat-images.js'}],
+
+  // A new category in the report for the plugin output.
+  category: {
+    title: 'Cats',
+    description:
+      'When integrated into your website effectively, cats deliver delight and bemusement.',
+    auditRefs: [{id: 'has-cat-images-id', weight: 1}],
+  },
+};
+```
+
+#### Custom Audits
+
+These files contain the logic that will generate results for the Lighthouse report. An audit is a class with two important properties:
+
+1. `meta` - This contains important information about how the audit will be referenced and how it will be displayed in the HTML report.
+2. `audit` - This is a function that should return the audit's results. See [API > Plugin Audits](#plugin-audits).
+
+**Example `audits/has-cat-images.js`**
+
+```js
+const Audit = require('lighthouse').Audit;
+
+class CatAudit extends Audit {
+  static get meta() {
+    return {
+      id: 'has-cat-images-id',
+      title: 'Page has least one cat image',
+      failureTitle: 'Page does not have at least one cat image',
+      description:
+        'Pages should have lots of cat images to keep users happy. ' +
+        'Consider adding a picture of a cat to your page improve engagement.',
+      requiredArtifacts: ['ImageElements'],
+    };
+  }
+
+  static audit(artifacts) {
+    // Artifacts requested in `requiredArtifacts` above are passed to your audit.
+    // See the "API -> Plugin Audits" section below for what artifacts are available.
+    const images = artifacts.ImageElements;
+    const catImages = images.filter(image => image.src.toLowerCase().includes('cat'));
+
+    return {
+      // Give users a 100 if they had a cat image, 0 if they didn't.
+      score: catImages.length > 0 ? 1 : 0,
+      // Also return the total number of cat images that can be used by report JSON consumers.
+      numericValue: catImages.length,
+    };
+  }
+}
+
+module.exports = CatAudit;
+```
+
+#### Run the plugin locally in development
+
+```sh
+# be in your plugin directory, and have lighthouse as a devDependency.
+NODE_PATH=.. yarn lighthouse https://example.com --plugins=lighthouse-plugin-example --only-categories=lighthouse-plugin-example --view
+# Note: we add the parent directory to NODE_PATH as a hack to allow Lighthouse to find this plugin.
+# This is useful for local development, but is not necessary when your plugin consuming from NPM as
+# a node module.
+```
+
+## API
+
+### Plugin Config
+
+The plugin config file (see `plugin.js` in the [example](#pluginjs) and [recipe](./recipes/lighthouse-plugin-example/plugin.js)) is a subset of the available [configuration](./configuration.md) for full custom Lighthouse config files.
+
+A plugin config is an object that has at least two properties: `audits` and `category`.
+
+#### `audits`
+
+Defines the new audits the plugin adds. It is an array of string paths to the audit files. Each path should be treated as an absolute string a user of your module might pass to `require`, so use paths of the form `lighthouse-plugin-<your plugin>/path/to/audits/audit-file.js`.
+
+**Type**: `Array<{path: string}>`
+
+#### `category`
+
+Defines the display strings of the plugin's category and configures audit scoring and grouping. It is an object with at least two properties `title` and `auditRefs`.
+
+- `title: string` **REQUIRED** - The display name of the plugin's category in the report.
+- `description: string` _OPTIONAL_ - A more detailed description of the category's purpose.
+- `manualDescription: string` _OPTIONAL_ - A more detailed description of all of the manual audits in a plugin. Only use this if you've added manual audits.
+- `auditRefs: Array<{id: string, weight: number, group?: string}>` **REQUIRED** - The list of audits to include in the plugin category along with their overall weight in the score of the plugin category. Each audit ref may optionally reference a group ID from `groups`.
+
+#### `groups`
+
+Defines the audit groups used for display in the HTML report.
+
+It is an object whose keys are the group IDs and whose values are objects with the following properties:
+
+- `title: string` **REQUIRED** - The display name of the group in the report.
+- `description: string` _OPTIONAL_ - A more detailed description of the group's purpose.
+
+**Example of Category with Groups**
+
+<img alt="audit group with groups" src="https://user-images.githubusercontent.com/2301202/56936017-86d3ce80-6aba-11e9-9a43-39bf3810b551.png" width=550>
+
+**Example of Category _without_ Groups**
+
+<img alt="audit group without groups" src="https://user-images.githubusercontent.com/2301202/56936043-c0a4d500-6aba-11e9-9e37-0bc131010a37.png" width=550>
+
+### Plugin Audits
+
+A plugin audit is a class that implements at least two properties: `meta` and `audit()`.
+
+#### `meta`
+
+The `meta` property is a static getter for the metadata of an [audit](#custom-audits). It should return an object with the following properties:
+
+- `id: string` **REQUIRED** - The string identifier of the audit, in kebab case, typically matching the file name.
+- `title: string` **REQUIRED** - Short, user-visible title for the audit when successful.
+- `failureTitle: string` _OPTIONAL_ - Short, user-visible title for the audit when failing.
+- `description: string` **REQUIRED** - A more detailed description that describes why the audit is important and links to Lighthouse documentation on the audit; markdown links supported.
+- `requiredArtifacts: Array<string>` **REQUIRED** - A list of artifacts that must be present for the audit to execute. See [Available Artifacts](#available-artifacts) for what's available to plugins.
+- `scoreDisplayMode: "numeric" | "binary" | "manual" | "informative"` _OPTIONAL_ - A string identifying how the score should be interpreted for display.
+
+See [Best Practices > Naming](#naming) for best practices on the display strings.
+
+#### `audit(artifacts, context)`
+
+The `audit()` property is a function the computes the audit results for the report. It accepts two arguments: `artifacts` and `context`. `artifacts` is an object whose keys will be the values you passed to `requiredArtifacts` in the `meta` object. `context` is an internal object whose primary use in plugins is to derive network request information (see [Using Network Requests](#using-network-requests)).
+
+The primary objective of the audit function is to return a `score` from `0` to `1` based on the data observed in `artifacts`. There are several other properties that can be returned by an audit to control additional display features. For the complete list, see the [audit results documentation](./understanding-results.md#audit-properties) and [type information](https://github.com/GoogleChrome/lighthouse/blob/623b789497f6c87f85d366b4038deae5dc701c90/types/audit.d.ts#L69-L87).
+
+#### Available Artifacts
+
+The following artifacts are available for use in the audits of Lighthouse plugins. For more detailed information on their usage and purpose, see the [type information](https://github.com/GoogleChrome/lighthouse/blob/623b789497f6c87f85d366b4038deae5dc701c90/types/artifacts.d.ts#L20-L70).
+
+- `devtoolsLogs`
+- `fetchTime`
+- `settings`
+- `traces`
+- `BenchmarkIndex`
+- `ConsoleMessages`
+- `HostUserAgent`
+- `ImageElements`
+- `LinkElements`
+- `MetaElements`
+- `NetworkUserAgent`
+- `RuntimeExceptions`
+- `ScriptElements`
+- `Stacks`
+- `Timing`
+- `URL`
+- `ViewportDimensions`
+- `WebAppManifest`
+
+While Lighthouse has more artifacts with information about the page than are in this list, those artifacts are considered experimental and their structure or existence could change at any time. Only use artifacts not on the list above if you are comfortable living on the bleeding edge and can tolerate unannounced breaking changes.
+
+If you're interested in other page information not mentioned here, please file an issue. We'd love to help.
+
+#### Using Network Requests
+
+You might have noticed that a simple array of network requests is missing from the list above. The source information for network requests made by the page is actually contained in the `devtoolsLogs` artifact, which contains all the of DevTools Protocol traffic recorded during page load. The network request objects are derived from this message log at audit time.
+
+See below for an example of an audit that processes network requests.
+
+```js
+const {Audit, NetworkRecords} = require('lighthouse');
+
+class HeaderPoliceAudit {
+  static get meta() {
+    return {
+      id: 'header-police-audit-id',
+      title: 'All headers stripped of debug data',
+      failureTitle: 'Headers contained debug data',
+      description: 'Pages should mask debug data in production.',
+      requiredArtifacts: ['devtoolsLogs'],
+    };
+  }
+
+  static async audit(artifacts, context) {
+    // Lighthouse loads the page multiple times: while offline, without javascript, etc.
+    // Use the devtools log from the default pass of the page.
+    const devtoolsLog = artifacts.devtoolsLogs[Audit.DEFAULT_PASS];
+    // Request the network records from the devtools log.
+    // The `context` argument is passed in to allow Lighthouse to cache the result and not re-compute the network requests for every audit that needs them.
+    const requests = await NetworkRecords.request(devtoolsLog, context);
+
+    // Do whatever you need to with the network requests.
+    const badRequests = requests.filter(request =>
+      request.responseHeaders.some(header => header.name.toLowerCase() === 'x-debug-data')
+    );
+
+    return {
+      score: badRequests.length === 0 ? 1 : 0,
+    };
+  }
+}
+
+module.exports = HeaderPoliceAudit;
+```
+
+## Best Practices
+
+### Naming
+
+> There are only two hard things in Computer Science: cache invalidation and naming things.
+> Phil Karlton
+
+There are several display strings you will need to write in the course of plugin development. To ensure your plugin users have a consistent experience with the rest of the Lighthouse report, follow these guidelines.
+
+#### Category Titles
+
+Write category titles that are short (fewer than 20 characters), ideally a single word or acronym. Avoid unnecessary prefixes like "Lighthouse" or "Plugin" which will already be clear from the context of the report.
+
+#### Category Descriptions
+
+Write category descriptions that provide context for your plugin's audits and link to where users can learn more or ask questions about their advice.
+
+#### Audit Titles
+
+Write audit titles in the _present_ tense that _describe_ what the page is successfully or unsuccessfully doing.
+
+**DO**
+
+> Document has a `<title>` element
+
+> Document does not have a `<title>` element
+
+> Uses HTTPS
+
+> Does not use HTTPS
+
+> Tap targets are sized appropriately
+
+> Tap targets are not sized appropriately
+
+**DON'T**
+
+> Good job on `alt` attributes
+
+> Fix your headers
+
+#### Audit Descriptions
+
+Write audit descriptions that provide brief context for why the audit is important and link to more detailed guides on how to follow its advice. Markdown links are supported, so use them!
+
+**DO**
+
+> Interactive elements like buttons and links should be large enough (48x48px), and have enough space around them, to be easy enough to tap without overlapping onto other elements. [Learn more](https://developers.google.com/web/fundamentals/accessibility/accessible-styles#multi-device_responsive_design).
+
+> All sites should be protected with HTTPS, even ones that don\'t handle sensitive data. HTTPS prevents intruders from tampering with or passively listening in on the communications between your app and your users, and is a prerequisite for HTTP/2 and many new web platform APIs. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/https).
+
+**DON'T**
+
+> Images need alt attributes.
+
+> 4.8.4.4 Requirements for providing text to act as an alternative for images
+> Except where otherwise specified, the alt attribute.... 10,000 words later... and that is everything you need to know about the `alt` attribute!
+
+### Scoring
+
+1. Weight each audit by its importance.
+1. Differentiate scores within an audit by returning a number _between_ `0` and `1`. Scores greater than `0.9` will be hidden in "Passed Audits" section by default.
+1. Avoid inflating scores unnecessarily by marking audits as not applicable. When an audit's advice doesn't apply, simply `return {score: null, notApplicable: true}`.
+
+### Common Mistakes
+
+The web is a diverse place, and your plugin will be run on pages you never thought existed. Here are a few things to keep in mind when writing your audit to avoid common bugs. The Lighthouse team has made all of these mistakes below, so you're in good company!
+
+#### Forgetting to Filter
+
+Most audits will have a specific use case in mind that will apply to most elements or requests, but there are corner cases that come up fairly frequently that are easy to forget.
+
+**Examples:**
+
+- Non-network network requests (`blob:`, `data:`, `file:`, etc)
+- Non-javascript scripts (`type="x-shader/x-vertex"`, `type="application/ld+json"`, etc)
+- Tracking pixel images (images with size 1x1, 0x0, etc)
+
+#### Forgetting to Normalize
+
+Most artifacts will try to represent as truthfully as possible what was observed from the page. When possible, the values are normalized according to the spec as you would access them from the DOM, but typically no transformation beyond this is done. This means that some values will have leading or trailing whitespace, be mixed-case, potentially missing, relative URLs instead of absolute, etc.
+
+**Examples:**
+
+- Header names and values
+- Script `type` values
+- Script `src` values
+
+## Examples
+
+- [Cinememe Plugin](https://github.com/exterkamp/lighthouse-plugin-cinememe) - Find and reward dank cinememes (5MB+ animated GIFs ;)
+- [YouTube Embed](https://github.com/connorjclark/lighthouse-plugin-yt) - Identifies YouTube embeds
+- [Lighthouse Plugin Recipe](./recipes/lighthouse-plugin-example)
+- [Field Performance](https://github.com/treosh/lighthouse-plugin-field-performance) - A plugin to gather and display Chrome UX Report field data
+- [Publisher Ads Audits](https://github.com/googleads/pub-ads-lighthouse-plugin) - a well-written, but complex, plugin
+- [Green Web Foundation](https://github.com/thegreenwebfoundation/lighthouse-plugin-greenhouse) - A plugin to see which domains run on renewable power.
+- [requests-content-md5](https://www.npmjs.com/package/lighthouse-plugin-md5) - Generates MD5 hashes from the content of network requests..
+

package/docs/puppeteer.md

@@ -0,0 +1,95 @@
+# Using Puppeteer with Lighthouse
+
+## Recipes
+
+### [Using Puppeteer for authenticated pages](./recipes/auth/README.md)
+
+### [Using Puppeteer in a custom gatherer](https://github.com/GoogleChrome/lighthouse/tree/master/docs/recipes/custom-gatherer-puppeteer)
+
+## General Process
+
+### Option 1: Launch Chrome with Puppeteer and handoff to Lighthouse
+
+The example below shows how to inject CSS into the page before Lighthouse audits the page.
+A similar approach can be taken for injecting JavaScript.
+
+```js
+const puppeteer = require('puppeteer');
+const lighthouse = require('lighthouse');
+const {URL} = require('url');
+
+(async() => {
+const url = 'https://www.chromestatus.com/features';
+
+// Use Puppeteer to launch headful Chrome and don't use its default 800x600 viewport.
+const browser = await puppeteer.launch({
+  headless: false,
+  defaultViewport: null,
+});
+
+// Wait for Lighthouse to open url, then inject our stylesheet.
+browser.on('targetchanged', async target => {
+  const page = await target.page();
+  if (page && page.url() === url) {
+    await page.addStyleTag({content: '* {color: red}'});
+  }
+});
+
+// Lighthouse will open the URL.
+// Puppeteer will observe `targetchanged` and inject our stylesheet.
+const {lhr} = await lighthouse(url, {
+  port: (new URL(browser.wsEndpoint())).port,
+  output: 'json',
+  logLevel: 'info',
+});
+
+console.log(`Lighthouse scores: ${Object.values(lhr.categories).map(c => c.score).join(', ')}`);
+
+await browser.close();
+})();
+```
+
+### Option 2: Launch Chrome with Lighthouse/chrome-launcher and handoff to Puppeteer
+
+When using Lighthouse programmatically, you'll often use chrome-launcher to launch Chrome.
+Puppeteer can reconnect to this existing browser instance like so:
+
+```js
+const chromeLauncher = require('chrome-launcher');
+const puppeteer = require('puppeteer');
+const lighthouse = require('lighthouse');
+const request = require('request');
+const util = require('util');
+
+(async() => {
+
+const URL = 'https://www.chromestatus.com/features';
+
+const opts = {
+  //chromeFlags: ['--headless'],
+  logLevel: 'info',
+  output: 'json'
+};
+
+// Launch chrome using chrome-launcher.
+const chrome = await chromeLauncher.launch(opts);
+opts.port = chrome.port;
+
+// Connect to it using puppeteer.connect().
+const resp = await util.promisify(request)(`http://localhost:${opts.port}/json/version`);
+const {webSocketDebuggerUrl} = JSON.parse(resp.body);
+const browser = await puppeteer.connect({browserWSEndpoint: webSocketDebuggerUrl});
+
+// Run Lighthouse.
+const {lhr}  = await lighthouse(URL, opts, null);
+console.log(`Lighthouse scores: ${Object.values(lhr.categories).map(c => c.score).join(', ')}`);
+
+await browser.disconnect();
+await chrome.kill();
+
+})();
+```
+
+--------------
+
+**Note**: https://github.com/GoogleChrome/lighthouse/issues/3837 tracks the overall discussion for making Lighthouse work in concert with Puppeteer. Some things, like A/B testing the perf of UI changes, are tricky or not yet possible.

package/docs/readme.md

@@ -0,0 +1,164 @@
+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 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.
+
+```js
+// ...
+const flags = {onlyCategories: ['performance']};
+launchChromeAndRunLighthouse(url, flags).then( // ...
+```
+
+You can also craft your own config (e.g. [experimental-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/experimental-config.js)) for custom runs. Also see the [basic custom audit recipe](https://github.com/GoogleChrome/lighthouse/tree/master/docs/recipes/custom-audit).
+
+### 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](https://github.com/GoogleChrome/lighthouse/blob/888bd6dc9d927a734a8e20ea8a0248baa5b425ed/typings/externs.d.ts#L82-L119). 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`.
+
+```javascript
+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:**
+```js
+{
+  extends: 'lighthouse:default',
+  settings: {
+    onlyAudits: [
+      'first-meaningful-paint',
+      'speed-index',
+      'interactive',
+    ],
+  },
+}
+```
+
+You can extend base configuration from [lighthouse:default](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/default-config.js), 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](https://github.com/GoogleChrome/lighthouse/blob/master/docs/configuration.md).
+
+## 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.
+
+1. Run `chrome-debug`. This will log the debugging port of your Chrome instance
+1. Navigate to your site and log in.
+1. 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](https://www.chromium.org/Home/chromium-security/education/tls#TOC-What-security-properties-does-TLS-give-me-). 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)](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 `--screenEmulation.disabled --throttling.cpuSlowdownMultiplier=1` to disable any additional emulation.
+
+```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 --port=9222 --screenEmulation.disabled --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](https://sites.google.com/a/chromium.org/chromedriver/capabilities#TOC-perfLoggingPrefs-object)).
+
+As an example, here's a trace-only run that reports on user timings and critical request chains:
+
+### `config.json`
+
+```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`