lighthouse 8.0.0-dev.20210709 → 8.0.0

package/docs/architecture.md

@@ -0,0 +1,101 @@
+# Architecture
+
+_Some incomplete notes_
+
+![Lighthouse Architecture](https://raw.githubusercontent.com/GoogleChrome/lighthouse/master/assets/architecture.png)
+
+## Components & Terminology
+
+* **Driver** - Interfaces with [Chrome Debugging Protocol](https://developer.chrome.com/devtools/docs/debugger-protocol)  ([API viewer](https://chromedevtools.github.io/debugger-protocol-viewer/))
+* **Gatherers** - Uses Driver to collect information about the page. Minimal post-processing.  Run Lighthouse with `--gather-mode` to see the 3 primary outputs from gathering:
+  1. `artifacts.json`: The output from all [gatherers](../lighthouse-core/gather/gatherers).
+  2. `defaultPass.trace.json`: Most performance characteristics come from here. You can view it in the DevTools Peformance panel.
+  3. `defaultPass.devtoolslog.json`: A log of all the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) events. Primary signal about network requests and page state.
+* **Audit** - The [audits](../lighthouse-core/audits) are tests for a single feature/optimization/metric. Using the Artifacts as input, an audit evaluates a test and resolves to a numeric score. See [Understanding Results](./understanding-results.md) for details of the LHR (Lighthouse Result object).
+  * **Computed Artifacts** - [Generated](../lighthouse-core/computed) on-demand from artifacts, these add additional meaning, and are often shared amongst multiple audits.
+* **Report** - The report UI, created client-side from the LHR. See [HTML Report Generation Overview](../lighthouse-core/report/html/readme.md) for details.
+
+### Audit/Report terminology
+* **Category** - Roll-up collection of audits and audit groups into a user-facing section of the report (eg. `Best Practices`). Applies weighting and overall scoring to the section. Examples: PWA, Accessibility, Best Practices.
+* **Audit title** - Short user-visible title for the successful audit. eg. “All image elements have `[alt]` attributes.”
+* **Audit failureTitle** - Short user-visible title for a failing audit. eg. “Some image elements do not have `[alt]` attributes.”
+* **Audit description** - Explanation of why the user should care about the audit. Not necessarily how to fix it, unless there is no external link that explains it. ([See description guidelines](../CONTRIBUTING.md#audit-description-guidelines)). eg. “Informative elements should aim for short, descriptive alternate text. Decorative elements can be ignored with an empty alt attribute. [Learn more].”
+
+## Protocol
+
+* _Interacting with Chrome:_ The Chrome protocol connection maintained via [WebSocket](https://github.com/websockets/ws) for the CLI [`chrome.debuggger` API](https://developer.chrome.com/extensions/debugger) when in the Chrome extension.
+* _Event binding & domains_: Some domains must be `enable()`d so they issue events. Once enabled, they flush any events that represent state. As such, network events will only issue after the domain is enabled. All the protocol agents resolve their `Domain.enable()` callback _after_ they have flushed any pending events. See example:
+
+```js
+// will NOT work
+driver.sendCommand('Security.enable').then(_ => {
+  driver.on('Security.securityStateChanged', state => { /* ... */ });
+})
+
+// WILL work! happy happy. :)
+driver.on('Security.securityStateChanged', state => { /* ... */ }); // event binding is synchronous
+driver.sendCommand('Security.enable');
+```
+
+* _Debugging the protocol_: Read [Better debugging of the Protocol](https://github.com/GoogleChrome/lighthouse/issues/184).
+
+## Understanding a Trace
+
+`lighthouse-core/lib/tracehouse/trace-processor.js` provides the core transformation of a trace into more meaningful objects. Each raw trace event has a monotonically increasing timestamp in microseconds, a thread ID, a process ID, a duration in microseconds (potentially), and other applicable metadata properties such as the event type, the task name, the frame, etc. [Learn more about trace events](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview).
+
+### Example Trace Event
+```js
+{
+  'pid': 41904, // process ID
+  'tid': 1295, // thread ID
+  'ts': 1676836141, // timestamp in microseconds
+  'ph': 'X', // trace event type
+  'cat': 'toplevel', // trace category from which this event came
+  'name': 'MessageLoop::RunTask', // relatively human-readable description of the trace event
+  'dur': 64, // duration of the task in microseconds
+  'args': {}, // contains additional data such as frame when applicable
+}
+```
+
+### Trace-of-Tab
+
+Trace-of-tab identifies trace events for key moments (navigation start, first meaningful paint, DOM content loaded, trace end, etc) and provides filtered views of just the main process and the main thread events. Because the timestamps are not necessarily interesting in isolation, trace-of-tab also calculates the times in milliseconds of key moments relative to navigation start, thus providing the typical interpretation of first meaningful paint in ms.
+
+```js
+{
+  processEvents: [/* all trace events in the main process */],
+  mainThreadEvents: [/* all trace events on the main thread */],
+  timings: {
+    timeOrigin: 0, // timeOrigin is always 0 ms
+    firstPaint: 150, // firstPaint time in ms after time origin
+    /* other key moments */
+    traceEnd: 16420, // traceEnd time in ms after time origin
+  },
+  timestamps: {
+    timeOrigin: 623000000, // timeOrigin timestamp in microseconds, marks the start of the navigation of interest
+    firstPaint: 623150000, // firstPaint timestamp in microseconds
+    /* other key moments */
+    traceEnd: 639420000, // traceEnd timestamp in microseconds
+  },
+}
+```
+
+### Tracing Processor
+
+Tracing processor takes the output of trace of tab and identifies the top-level main thread tasks, their durations, and corresponding impact on page responsiveness. Tracing processor also translates task timestamps to milliseconds since navigation start for easier interpretation in computed gatherers and audits.
+
+## Audits
+
+The return value of each audit [takes this shape](https://github.com/GoogleChrome/lighthouse/blob/623b789497f6c87f85d366b4038deae5dc701c90/types/audit.d.ts#L69-L87).
+
+The `details` object is parsed in report-renderer.js. View other audits for guidance on how to structure `details`.
+
+## Lighthouse-core internal module dependencies
+
+![image](https://user-images.githubusercontent.com/39191/86166329-786fb100-bac9-11ea-919a-d6c3b156d3a4.png)
+
+(Generated June 30, 2020 via `madge lighthouse-core/index.js --image arch.png --layout dot --exclude="(locales\/)|(stack-packs\/packs)"`)
+
+## Lantern
+
+[Lantern](./lantern.md) is how Lighthouse simulates network and cpu throttling.

package/docs/authenticated-pages.md

@@ -0,0 +1,44 @@
+# Running Lighthouse on Authenticated Pages
+
+Default runs of Lighthouse load a page as a "new user", with no previous session or storage data. This means that pages requiring authenticated access do not work without additional setup. You have a few options for running Lighthouse on pages behind a login:
+
+## Option 1: Script the login with Puppeteer
+
+[Puppeteer](https://pptr.dev) is the most flexible approach for running Lighthouse on pages requiring authentication.
+
+See [a working demo at /docs/recipes/auth](./recipes/auth).
+
+View our full documentation for using [Lighthouse along with Puppeteer](https://github.com/GoogleChrome/lighthouse/blob/master/docs/puppeteer.md).
+
+## Option 2: Leverage logged-in state with Chrome DevTools
+
+The Audits panel in Chrome DevTools will never clear your cookies, so you can log in to the target site and then run Lighthouse. If `localStorage` or `indexedDB` is important for your authentication purposes, be sure to uncheck `Clear storage`.
+
+## Option 3: Pass custom request headers with Lighthouse CLI
+
+CLI:
+```sh
+lighthouse http://www.example.com --view --extra-headers="{\"Authorization\":\"...\"}"
+```
+
+Node:
+```js
+const result = await lighthouse('http://www.example.com', {
+  extraHeaders: {
+    Authorization: '...',
+  },
+});
+```
+
+You could also set the `Cookie` header, but beware: it will [override any other Cookies you expect to be there](https://github.com/GoogleChrome/lighthouse/pull/9170). For a more flexible cookie-based approach, use [puppeteer (Option 1)](./recipes/auth/README.md) instead.
+
+## Option 4: Open a debug instance of Chrome and manually log in
+
+1. Globally install lighthouse: `npm i -g lighthouse` or `yarn global add lighthouse`. `chrome-debug` is now in your PATH. This binary launches a standalone Chrome instance with an open debugging port.
+1. Run chrome-debug. This logs the debugging port of your Chrome instance.
+1. Navigate to your site and log in.
+1. In a separate terminal, run `lighthouse http://mysite.com --disable-storage-reset --port port-number`, using the port number from chrome-debug.
+
+## Option 5: Reuse a prepared Chrome User Profile
+
+This option is currently under development. Track or join the discussion here: [#8957](https://github.com/GoogleChrome/lighthouse/issues/8957).

package/docs/bug-labels.md

@@ -0,0 +1,35 @@
+Given the new onslaught of issues that folks in the community are filing, we thought it might be good to explain some of our 
+bug labeling and triaging practices to the community. 
+
+## Bug Triaging Overview
+Every week, there is a new "bug sheriff" (assigned from the core Lighthouse team) and their job is to go through and triage incoming bugs and pay attention to bugs
+where we need more information from the reporter. Therefore, depending on the week, you might be hearing from a different 
+bug sheriff about your bug. 
+
+## Labeling Bugs
+
+Here are the different (actively used) labels and what they mean, organized by category bucket: 
+
+### Priority Labels
+- P0: Urgent issue- drop everything and deal with immediately
+- P1: We want to work on this in the next few weeks
+- P1.5: We want to work on this in the next few months
+- P2: We want to work on this in the next few quarters. 
+- P3: Good idea, useful for future thinking. 
+
+### Process labels 
+- Needs more information: issue that hasn't been prioritized yet because we need more information from the bug creator. If we don't hear back in 2 weeks, we will close out the bug. 
+- Pending close: issue that we will soon close. 
+- Needs priority: issue that needs to be prioritized by team (as P0, P1, P1.5, etc.)
+- Needs investigation: issue that we need to dig into to understand what is going on (mostly for bugs)
+
+### Type of incoming issue labels
+- Bug: something is wrong on our end and needs to be fixed. 
+- Feature: suggestion of new thing to implement. 
+- Internal cleanup: nothing is wrong but clean up and/or refactor of the existing way we're doing something. 
+- Question: question from community. Good fodder for new documentation that needs to be written. 
+
+### Other labels
+- Good first issue: for new external contributor, these issues can be useful for them to tackle. 
+- Help wanted: issues that could use help from the community. 
+

package/docs/configuration.md

@@ -0,0 +1,213 @@
+# Lighthouse Configuration
+
+The Lighthouse config object is the primary method of customizing Lighthouse to suit your use case. Using a custom config, you can limit the audits to run, add additional loads of the page under special conditions, add your own custom checks, tweak the scoring, and more.
+
+Read more about the [architecture of Lighthouse](./architecture.md).
+
+## Usage
+
+You can specify a custom config file when using Lighthouse through the CLI or consuming the npm module yourself.
+
+**custom-config.js file**
+```js
+module.exports = {
+  extends: 'lighthouse:default',
+  settings: {
+    onlyAudits: [
+      'first-meaningful-paint',
+      'speed-index',
+      'interactive',
+    ],
+  },
+};
+```
+
+**Use config file via CLI**
+```sh
+lighthouse --config-path=path/to/custom-config.js https://example.com
+```
+
+**Use config file via Node**
+```js
+const lighthouse = require('lighthouse');
+const config = require('./path/to/custom-config.js');
+lighthouse('https://example.com/', {port: 9222}, config);
+```
+
+## Properties
+
+| Name | Type |
+| - | - |
+| extends | <code>string&#124;undefined</code> |
+| settings | <code>Object&#124;undefined</code> |
+| passes | <code>Object[]</code> |
+| audits | <code>string[]</code> |
+| categories | <code>Object&#124;undefined</code> |
+| groups | <code>Object&#124;undefined</code> |
+
+### `extends: "lighthouse:default"|undefined`
+
+The `extends` property controls if your configuration should inherit from the default Lighthouse configuration. [Learn more.](#config-extension)
+
+#### Example
+```js
+{
+  extends: 'lighthouse:default',
+}
+```
+
+### `settings: Object|undefined`
+
+The settings property controls various aspects of running Lighthouse such as CPU/network throttling and which audits should run.
+
+#### Example
+```js
+{
+  settings: {
+    onlyCategories: ['performance'],
+    onlyAudits: ['works-offline'],
+  }
+}
+```
+
+#### Options
+For full list see [our config settings typedef](https://github.com/GoogleChrome/lighthouse/blob/575e29b8b6634bfb280bc820efea6795f3dd9017/types/externs.d.ts#L141-L186).
+
+| Name | Type | Description |
+| -- | -- | -- |
+| onlyCategories | `string[]` | Includes only the specified categories in the final report. Additive with `onlyAudits` and reduces the time to audit a page. |
+| onlyAudits | `string[]` | Includes only the specified audits in the final report. Additive with `onlyCategories` and reduces the time to audit a page. |
+| skipAudits | `string[]` | Excludes the specified audits from the final report. Takes priority over `onlyCategories`, not usable in conjuction with `onlyAudits`, and reduces the time to audit a page. |
+
+### `passes: Object[]`
+
+The passes property controls how to load the requested URL and what information to gather about the page while loading. Each entry in the passes array represents one load of the page (e.g. 4 entries in `passes` will load the page 4 times), so be judicious about adding multiple entries here to avoid extending run times.
+
+Each `passes` entry defines basic settings such as how long to wait for the page to load and whether to record a trace file. Additionally a list of **gatherers** to use is defined per pass. Gatherers can read information from the page to generate artifacts which are later used by audits to provide you with a Lighthouse report. For more information on implementing a custom gatherer and the role they play in building a Lighthouse report, refer to the [recipes](https://github.com/GoogleChrome/lighthouse/blob/master/docs/recipes/custom-audit). Also note that `artifacts.devtoolsLogs` will be automatically populated for every pass. Gatherers also have access to this data within the `afterPass` as `traceData.devtoolsLog` (However, most will find the higher-level `traceData.networkRecords` more useful).
+
+For list of default pass values, see [our config constants](https://github.com/GoogleChrome/lighthouse/blob/8f500e00243e07ef0a80b39334bedcc8ddc8d3d0/lighthouse-core/config/constants.js#L50-L61).
+
+#### Example
+```js
+{
+  passes: [
+    {
+      passName: 'fastPass',
+      gatherers: ['fast-gatherer'],
+    },
+    {
+      passName: 'slowPass',
+      recordTrace: true,
+      useThrottling: true,
+      networkQuietThresholdMs: 5000,
+      gatherers: ['slow-gatherer'],
+    }
+  ]
+}
+```
+
+#### Options
+| Name | Type | Description |
+| -- | -- | -- |
+| passName | `string` | A unique identifier for the pass used in audits and during config extension. |
+| recordTrace | `boolean` | Records a [trace](https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#understanding-a-trace) of the pass when enabled. Available to gatherers during `afterPass` as `traceData.trace` and to audits in `artifacts.traces`. |
+| useThrottling | `boolean` | Enables throttling of the pass when enabled. |
+| pauseAfterLoadMs | `number` | The number of milliseconds to wait after the load event before the pass can continue. Used to ensure the page has had time for post-load JavaScript to execute before ending a trace. (Default: 0) |
+| networkQuietThresholdMs | `number` | The number of milliseconds since the last network request to wait before the page should be considered to have reached 'network quiet'. Used to ensure the page has had time for the full waterfall of network requests to complete before ending a trace. (Default: 5000) |
+| pauseAfterNetworkQuietMs | `number` | The number of milliseconds to wait after 'network quiet' before the pass can continue. Used to ensure the page has had time for post-network-quiet JavaScript to execute before ending a trace. (Default: 0) |
+| blockedUrlPatterns | `string[]` | URLs of requests to block while loading the page. Basic wildcard support using `*`.  |
+| gatherers | `string[]` | The list of gatherers to run on this pass. This property is required and on extension will be concatenated with the existing set of gatherers. |
+
+### `audits: string[]`
+
+The audits property controls which audits to run and include with your Lighthouse report. See [more examples](#more-examples) to see how to add custom audits to your config.
+
+#### Example
+```js
+{
+  audits: [
+    'first-contentful-paint',
+    'byte-efficiency/uses-optimized-images',
+  ]
+}
+```
+
+
+### `categories: Object|undefined`
+
+The categories property controls how to score and organize the audit results in the report. Each category defined in the config will have an entry in the `categories` property of Lighthouse's output. The category output contains the child audit results along with an overall score for the category.
+
+**Note:** many modules consuming Lighthouse have no need to group or score all the audit results; in these cases, it's fine to omit a categories section.
+
+#### Example
+```js
+{
+  categories: {
+    performance: {
+      title: 'Performance',
+      description: 'This category judges your performance',
+      auditRefs: [
+        {id: 'first-meaningful-paint', weight: 2, group: 'metrics'},
+        {id: 'first-contentful-paint', weight: 3, group: 'metrics'},
+        {id: 'interactive', weight: 5, group: 'metrics'},
+      ],
+    }
+  }
+}
+```
+
+#### Options
+| Name | Type | Description |
+| -- | -- | -- |
+| title | `string` | The display name of the category. |
+| description | `string` | The displayed description of the category. |
+| auditRefs | `Object[]` | The audits to include in the category. |
+| auditRefs[$i].id | `string` | The ID of the audit to include. |
+| auditRefs[$i].weight | `number` | The weight of the audit in the scoring of the category. |
+| auditRefs[$i].group | `string` (optional) | The ID of the [display group](#groups-objectundefined) of the audit. |
+
+### `groups: Object|undefined`
+
+The groups property controls how to visually group audits within a category. For example, this is what enables the grouped rendering of metrics and accessibility audits in the report.
+
+**Note: The report-renderer has display logic that's hardcoded to specific audit group names. Adding arbitrary groups without additional rendering logic may not perform as expected.**
+
+#### Example
+```js
+{
+  categories: {
+    performance: {
+      auditRefs: [
+        {id: 'my-performance-metric', weight: 2, group: 'metrics'},
+      ],
+    }
+  },
+  groups: {
+    'metrics': {
+      title: 'Metrics',
+      description: 'These metrics encapsulate your web app\'s performance across a number of dimensions.'
+    },
+  }
+}
+```
+
+## Config Extension
+
+The stock Lighthouse configurations can be extended if you only need to make small tweaks, such as adding an audit or skipping an audit, but wish to still run most of what Lighthouse offers. When adding the `extends: 'lighthouse:default'` property to your config, the default passes, audits, groups, and categories will be automatically included, allowing you modify settings or add additional audits to a pass.
+
+Please note that the `extends` property only supports extension of `lighthouse:default`. Other internal configs found in the [lighthouse-core/config](https://github.com/GoogleChrome/lighthouse/tree/master/lighthouse-core/config) directory can be used by importing the config object from file reference, or by using the [`--preset`](https://github.com/GoogleChrome/lighthouse#cli-options) CLI flag.
+
+See [more examples below](#more-examples) to view different types of extensions in action.
+
+**Config extension is the recommended way to run custom Lighthouse**. If there's a use case that extension doesn't currently solve, we'd love to [hear from you](https://github.com/GoogleChrome/lighthouse/issues/new)!
+
+## More Examples
+
+The best examples are the ones Lighthouse uses itself! There are several reference configuration files that are maintained as part of Lighthouse.
+
+* [lighthouse-core/config/default-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/default-config.js)
+* [lighthouse-core/config/lr-desktop-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/lr-desktop-config.js)
+* [lighthouse-core/config/lr-mobile-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/lr-mobile-config.js)
+* [lighthouse-core/config/perf-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/perf-config.js)
+* [docs/recipes/custom-audit/custom-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/docs/recipes/custom-audit/custom-config.js)
+* [pwmetrics](https://github.com/paulirish/pwmetrics/blob/v4.1.1/lib/perf-config.ts)

package/docs/emulation.md

@@ -0,0 +1,32 @@
+
+# Emulation in Lighthouse
+
+In Lighthouse, "Emulation" refers to the screen/viewport emulation and UserAgent string spoofing.
+["Throttling"](./throttling.md) covers the similar topics around network and CPU throttling/simulation.
+
+With the default configuration, Lighthouse emulates a mobile device. There's [a `desktop` configuration](../lighthouse-core/config/desktop-config.js), available to CLI users with `--preset=desktop`, which applies a consistent desktop environment and scoring calibration. This is recommended as a replacement for `--emulated-form-factor=desktop`.
+
+### Advanced emulation setups
+
+Some products use Lighthouse in scenarios where emulation is applied outside of Lighthouse (e.g. by Puppeteer) or running against Chrome on real mobile devices.
+
+You must always set `formFactor`. It doesn't control emulation, but it determines how Lighthouse should interpret the run in regards to scoring performance metrics and skipping mobile-only tests in desktop.
+
+You can choose how `screenEmulation` is applied. It can accept an object of `{width: number, height: number, deviceScaleRatio: number, mobile: boolean, disabled: false}` to apply that screen emulation or an object of `{disabled: true}` if Lighthouse should avoid applying screen emulation. It's typically set to disabled if either emulation is applied outside of Lighthouse, or it's being run on a mobile device. The `mobile` boolean applies overlay scrollbars and a few other mobile-specific screen emulation characteristics.
+
+You can choose how to handle userAgent emulation. The `emulatedUserAgent` property accepts either a `string` to apply the provided userAgent or a `boolean` -- `true` if the default UA spoofing should be applied (default) or `false` if no UA spoofing should be applied. Typically `false` is used if UA spoofing is applied outside of Lighthouse or on a mobile device. You can also redundantly apply userAgent emulation with no risk.
+
+If you're using Lighthouse on a mobile device, you want to set `--screenEmulation.disabled` and `--throttling.cpuSlowdownMultiplier=1`. (`--formFactor=mobile` is the default already).
+
+### Changes made in v7
+
+In Lighthouse v7, most of the configuration regarding emulation changed to be more intuitive and clear. The [tracking issue](https://github.com/GoogleChrome/lighthouse/issues/10910
+) captures additional motivations.
+
+* Removed: The `emulatedFormFactor` property (which determined how emulation is applied).
+* Removed: The `TestedAsMobileDevice` artifact. Instead of being inferred, the explicit `formFactor` property is used.
+* Removed: The `internalDisableDeviceScreenEmulation` property. It's equivalent to the new `--screenEmulation.disabled=true`.
+* Added: The `formFactor` property.
+* Added: The `screenEmulation` property.
+* Added: The `emulatedUserAgent` property.
+* (`throttling` and `throttlingMethod` remain unchanged)

package/docs/error-reporting.md

@@ -0,0 +1,42 @@
+# Error Reporting Explained
+
+## What's going on?
+
+The Lighthouse team is constantly trying to improve the reliability of our tools, so we've added error tracking functionality to the CLI. Given your consent, we would like to anonymously report runtime exceptions using [Sentry](https://sentry.io/welcome/). We will use this information to detect new bugs and avoid regressions.
+
+Only CLI users are currently impacted. DevTools, extension, and node module users will not have errors reported.
+
+## What will happen if I opt-in?
+Runtime exceptions will be reported to the team along with information on your environment such as the URL you tested, your OS, and Chrome version. See [what data gets reported](#what-data-gets-reported).
+
+## What will happen if I do not opt-in?
+Runtime exceptions will not be reported to the team. Your ability to use Lighthouse will not be affected in any way.
+
+## What data gets reported?
+
+* The URL you tested
+* The runtime settings used (throttling enabled/disabled, emulation, etc)
+* The message, stack trace, and associated data of the error
+* The file path of Lighthouse node module on your machine
+* Your Lighthouse version
+* Your Chrome version
+* Your operating system
+
+[This code search](https://github.com/GoogleChrome/lighthouse/search?l=JavaScript&q=Sentry.&type=&utf8=%E2%9C%93) reveals where Sentry methods are used.
+
+## How do I opt-in?
+The first time you run the CLI you will be prompted with a message asking you if Lighthouse can anonymously report runtime exceptions. You can give a direct response of `yes` or `no` (`y`, `n`, and pressing enter which defaults to `no` are also acceptable responses), and you will not be prompted again. If no response is given within 20 seconds, a `no` response will be assumed and you will not be prompted again.
+
+Running Lighthouse with `--enable-error-reporting` will report errors regardless of the saved preference.
+
+## How do I keep error reporting disabled?
+As mentioned, if you do not respond to the CLI prompt within 20 seconds, a `no` response will be assumed and you will not be prompted again.
+
+Non-interactive terminal sessions (`process.stdout.isTTY === false`) and invocations with the `CI` environment variable (`process.env.CI === true`), common on CI providers like Travis and AppVeyor, will not be prompted and error reporting will remain disabled.
+
+Running Lighthouse with `--no-enable-error-reporting` will keep error reporting disabled regardless of the saved preference.
+
+## How do I change my opt-in preference?
+Your response to the prompt will be saved to your home directory `~/.config/configstore/lighthouse.json` and used on future runs. To trigger a re-prompt, simply delete this file and Lighthouse will ask again on the next run. You can also edit this json file directly.
+
+As mentioned above, any explicit `--[no-]enable-error-reporting` flags will override the saved preference.

package/docs/hacking-tips.md

@@ -0,0 +1,55 @@
+A few assorted scripts and tips to make hacking on Lighthouse a bit easier
+
+## Evaluate Lighthouse's runtime performance
+
+Lighthouse has instrumentation to collect timing data for its operations. The data is exposed at `LHR.timing.entries`.  You can generate a trace from this data for closer analysis.
+
+![image](https://user-images.githubusercontent.com/39191/47525915-3c477000-d853-11e8-90a2-27036f93e682.png)
+[View example trace](https://ahead-daughter.surge.sh/paulirish.json.timing.trace.html)
+
+To generate, run `yarn timing-trace` with the LHR json:
+```sh
+lighthouse http://example.com --output=json --output-path=lhr.json
+yarn timing-trace lhr.json
+```
+
+That will generate `lhr.json.timing.trace.json`. Then, drag 'n drop that file into `chrome://tracing`.
+
+## Unhandled promise rejections
+
+Getting errors like these?
+
+> (node:12732) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1)
+> (node:12732) DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.
+
+Use [`--trace-warnings`](https://medium.com/@jasnell/introducing-process-warnings-in-node-v6-3096700537ee) to get actual stack traces.
+
+```sh
+node --trace-warnings lighthouse-cli http://example.com
+```
+
+## Iterating on the report
+
+This will generate new reports from the same results json.
+
+```sh
+# capture some results first:
+lighthouse --output=json http://example.com > temp.report.json
+
+# quickly generate reports:
+node generate_report.js > temp.report.html; open temp.report.html
+```
+```js
+// generate_report.js
+'use strict';
+
+const ReportGenerator = require('./lighthouse-core/report/report-generator');
+const results = require('./temp.report.json');
+const html = ReportGenerator.generateReportHtml(results);
+
+console.log(html);
+```
+
+## Using Audit Classes Directly, Providing Your Own Artifacts
+
+See [gist](https://gist.github.com/connorjclark/d4555ad90ae5b5ecf793ad2d46ca52db).

package/docs/headless-chrome.md

@@ -0,0 +1,119 @@
+# Running Lighthouse using headless Chrome
+
+## CLI (headless)
+
+Setup:
+
+```sh
+# Lighthouse requires Node 12 LTS (12.x) or later.
+curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash - &&\
+sudo apt-get install -y nodejs npm
+
+# get chromium (stable)
+apt-get install chromium
+
+# install lighthouse
+npm i -g lighthouse
+```
+
+Kick off run of Lighthouse using headless Chrome:
+
+```sh
+lighthouse --chrome-flags="--headless" https://github.com
+```
+
+## CLI (xvfb)
+
+Alternatively, you can run full Chrome + xvfb instead of headless mode. These steps worked on Debian Jessie:
+
+```sh
+# get node 12
+curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
+sudo apt-get install -y nodejs npm
+
+# get chromium (stable) and Xvfb
+apt-get install chromium-browser xvfb
+
+# install lighthouse
+npm i -g lighthouse
+```
+
+Run it:
+
+```sh
+export DISPLAY=:1.5
+TMP_PROFILE_DIR=$(mktemp -d -t lighthouse.XXXXXXXXXX)
+
+# start up chromium inside xvfb
+xvfb-run --server-args='-screen 0, 1024x768x16' \
+    chromium-browser --user-data-dir=$TMP_PROFILE_DIR
+    --start-maximized \
+    --no-first-run \
+    --remote-debugging-port=9222 "about:blank"
+
+# Kick off Lighthouse run on same port as debugging port.
+lighthouse --port=9222 https://github.com
+```
+
+## Posting Lighthouse reports to GitHub Gists
+
+Be sure to replace `${GITHUB_OWNER}` and `${GITHUB_TOKEN}` with your own credentials. The code below is tested on Ubuntu. 
+
+```sh
+apt-get install -y nodejs npm chromium jq
+npm install -g lighthouse
+
+# Run lighthouse as JSON, pipe it to jq to wrangle and send it to GitHub Gist via curl 
+# so Lighthouse Viewer can grab it. 
+lighthouse "http://localhost" --chrome-flags="--no-sandbox --headless" \
+  --output json \
+| jq -r "{ description: \"YOUR TITLE HERE\", public: \"false\", files: {\"$(date "+%Y%m%d").lighthouse.report.json\": {content: (. | tostring) }}}" \
+| curl -sS -X POST -H 'Content-Type: application/json' \
+    -u ${GITHUB_OWNER}:${GITHUB_TOKEN} \
+    -d @- https://api.github.com/gists > results.gist
+
+# Let's be nice and add the Lighthouse Viewer link in the Gist description.
+GID=$(cat results.gist | jq -r '.id') && \
+curl -sS -X POST -H 'Content-Type: application/json' \
+  -u ${GITHUB_OWNER}:${GITHUB_TOKEN} \
+  -d "{ \"description\": \"YOUR TITLE HERE - Lighthouse: https://googlechrome.github.io/lighthouse/viewer/?gist=${GID}\" }" "https://api.github.com/gists/${GID}" > updated.gist
+```
+
+## Node module
+
+Install:
+
+```sh
+yarn add lighthouse
+```
+
+Run it:
+
+```javascript
+const lighthouse = require('lighthouse');
+const chromeLauncher = require('chrome-launcher');
+
+function launchChromeAndRunLighthouse(url, flags = {}, config = null) {
+  return chromeLauncher.launch(flags).then(chrome => {
+    flags.port = chrome.port;
+    return lighthouse(url, flags, config).then(results =>
+      chrome.kill().then(() => results));
+  });
+}
+
+const flags = {
+  chromeFlags: ['--headless']
+};
+
+launchChromeAndRunLighthouse('https://github.com', flags).then(results => {
+  // Use results!
+});
+```
+
+## Other resources
+
+Other resources you might find helpful:
+
+- [Getting Started with Headless Chrome](https://developers.google.com/web/updates/2017/04/headless-chrome)
+- Example [Dockerfile](https://github.com/ebidel/lighthouse-ci/blob/master/builder/Dockerfile)
+- Lighthouse's GitHub Actions [`.ci.yml`](https://github.com/GoogleChrome/lighthouse/blob/master/.github/workflows/ci.yml)