lighthouse 8.0.0-dev.20210709 → 8.0.0

package/docs/releasing.md

@@ -0,0 +1,164 @@
+### Release guide for maintainers
+
+This doc is only relevant to core member.
+
+## Release Policy
+
+### Cadence
+
+We aim to release every 3 weeks. Our schedule is set as follows: Two days before the [expected Chromium branch point](https://www.chromium.org/developers/calendar) (which is every six weeks) and again exactly 3 weeks after that day. These are Tuesdays.
+
+For example, following this schedule, we will attempt a release on these dates:
+
+* _Sep 29 2020_ (M87)
+* Oct 20 2020
+* _Nov 10 2020_ (M88)
+* Dec 1 2020
+* ...
+
+Italicized dates are two days before the expected Chromium branch point.
+
+The planned ship dates are added to the internal Lighthouse calendar.
+
+If a release is necessary outside these scheduled dates, we may choose to skip the next scheduled release.
+
+In general, the above release dates are when new versions will be available in npm. Within 2 weeks, it will be reflected in LR / PSI. Some 10 weeks later, it will be available in Stable Chrome.
+
+### Release manager
+
+Release manager is appointed, according to the list below. However, if the appointed manager is absent, the next engineer in line in the list would own it.
+
+    @cjamcl, @adamraine
+
+Release manager follows the below _Release Process_.
+
+### Release publicity
+
+Note: actively undergoing changes by @exterkamp and @egsweeny.
+
+1. Release mgr copies changelog to a new [Releases](https://github.com/GoogleChrome/lighthouse/releases). Tags and ships it.
+1. Release mgr tells the _LH public_ Hangout chat about the new version.
+1. V & Kayce write and publish the [/updates](https://developers.google.com/web/updates/) blog post
+1. Addy writes the tweet (linking the /updates post) and sends it on [@____lighthouse](https://twitter.com/____lighthouse).
+
+### Versioning
+
+We follow [semver](https://semver.org/) versioning semantics (`vMajor.Minor.Patch`). Breaking changes will bump the major version. New features or bug fixes will bump the minor version. If a release contains no new features, then we'll only bump the patch version.
+
+## Release Process
+
+### On the scheduled release date
+
+Before starting, you should announce to the LH eng channel that you are releasing,
+and that no new PRs should be merged until you are done.
+
+```sh
+# Run the tests.
+bash ./lighthouse-core/scripts/release/test.sh
+```
+
+Confirm DevTools integration will work:
+```sh
+# Change into the newly-created pristine folder.
+cd ../lighthouse-pristine
+
+yarn test-devtools
+
+# Do some manual testing on a number of sites.
+yarn open-devtools
+
+# Done with DevTools for now, will open a CL later.
+
+# Leave pristine folder.
+cd ../lighthouse
+```
+
+### Lightrider
+
+Confirm Lightrider integration will work.
+
+1. See the internal README for updating Lighthouse: go/lightrider-doc
+1. Roll to the canary feed in a workspace
+1. Run the tests
+1. Update/fix any failing tests
+1. All good: Hold on submitting a CL until after cutting a release
+
+### Open the PR
+
+Now that the integrations are confirmed to work, go back to `lighthouse` folder.
+
+```sh
+# Prepare the commit, replace x.x.x with the desired version
+bash ./lighthouse-core/scripts/release/prepare-commit.sh x.x.x
+
+# Rebaseline DevTools tests one more time (only version number should change).
+yarn build-devtools && yarn update:test-devtools
+```
+
+1. Edit changelog.md before opening the PR
+1. Open the PR with title `vx.x.x`
+1. Hold until approved and merged
+
+### Cut the release
+
+```sh
+# One last test (this script uses origin/master, so we also get the commit with the new changelog - that commit should be HEAD).
+bash ./lighthouse-core/scripts/release/test.sh
+# Package everything for publishing
+bash ./lighthouse-core/scripts/release/prepare-package.sh
+
+# Make sure you're in the Lighthouse pristine repo we just tested.
+cd ../lighthouse-pristine
+
+# Last chance to abort.
+git status
+git log
+
+# Publish tag.
+git push --follow-tags
+
+# Publish to npm.
+npm publish
+
+# Publish viewer and treemap.
+yarn deploy-viewer
+yarn deploy-treemap
+```
+
+### Extensions
+
+If the extensions changed, publish them.
+
+```sh
+# Publish the extensions (if it changed).
+open https://chrome.google.com/webstore/developer/edit/blipmdconlkpinefehnmjammfjpmpbjk
+cd dist/extension-package/
+echo "Upload the package zip to CWS dev dashboard..."
+# Be in lighthouse-extension-owners group
+# Open <https://chrome.google.com/webstore/developer/dashboard>
+# Click _Edit_ on lighthouse
+# _Upload Updated Package_
+# Select `lighthouse-X.X.X.X.zip`
+# _Publish_ at the bottom
+
+# For Firefox: https://addons.mozilla.org/en-US/developers/addon/google-lighthouse/versions/submit/
+
+# * Tell the world!!! *
+echo "Complete the _Release publicity_ tasks documented above"
+
+# Roll the tagged commit to Chromium and update the CL you made. Do not land, see next section.
+# Roll the tagged commit to LR and land the CL.
+```
+
+### Chromium CL
+
+```sh
+git checkout vx.x.x # Checkout the specific version.
+yarn build-devtools
+yarn devtools ~/src/devtools/devtools-frontend
+
+cd ~/src/devtools/devtools-frontend
+git new-branch rls
+git commit -am "[Lighthouse] Roll Lighthouse x.x.x"
+git cl upload -b 772558
+```

package/docs/scoring.md

@@ -0,0 +1,79 @@
+# Lighthouse Scores
+
+## How is the Performance score calculated?
+
+➡️ Please read [Lighthouse Performance Scoring at web.dev](https://web.dev/performance-scoring/).
+
+## How is the PWA (Progressive Web App) score calculated?
+
+The PWA category doesn't get a 0-100 score, but instead is evaluated in 3 separate groups (Fast and reliable, Installable, and PWA Optimized). In order to satisfy each grouping (and get the associated badge), every audit within the group must be passing.
+
+![Lighthouse PWA badge - states](https://user-images.githubusercontent.com/39191/80662283-c292d280-8a45-11ea-84e8-7f8248657acf.png)
+
+Note on https redirects: some metrics in this category have issues with https redirects because of TLS-handshake errors. More specifically you will run into this when using the ```simplehttp2server``` npm package. Subsequent metrics will fail after the https redirects (see [#1217](https://github.com/GoogleChrome/lighthouse/issues/1217), [#5910](https://github.com/GoogleChrome/lighthouse/issues/5910)).
+
+## How is the Best Practices score calculated?
+
+All audits in the Best Practices category are equally weighted. Therefore, implementing each audit correctly will increase your overall score by ~6 points.
+
+## How is the SEO score calculated?
+
+All audits in the SEO category are [equally weighted](https://github.com/GoogleChrome/lighthouse/blob/080c6b4b9fec6dfcaf8e0cd8d09c3224465e4fd3/lighthouse-core/config/default-config.js#L531-L547), with the exception ofStructured Data, which is an unscored manual audit. Therefore, implementing each audit correctly will increase your overall score by ~8 points.
+
+
+## How is the accessibility score calculated?
+
+<!-- To regnerate score weights, run `node lighthouse-core/scripts/print-a11y-scoring.js`-->
+
+The accessibility score is a weighted average. The specific weights for v7 are as follows:
+
+(See the [v6 scoring explanation](https://github.com/GoogleChrome/lighthouse/blob/v6.5.0/docs/scoring.md#how-is-the-accessibility-score-calculated))
+
+| audit id | weight |
+|-|-|
+ | aria-allowed-attr | 4.1% |
+ | aria-hidden-body | 4.1% |
+ | aria-required-attr | 4.1% |
+ | aria-required-children | 4.1% |
+ | aria-required-parent | 4.1% |
+ | aria-roles | 4.1% |
+ | aria-valid-attr-value | 4.1% |
+ | aria-valid-attr | 4.1% |
+ | button-name | 4.1% |
+ | duplicate-id-aria | 4.1% |
+ | image-alt | 4.1% |
+ | input-image-alt | 4.1% |
+ | label | 4.1% |
+ | meta-refresh | 4.1% |
+ | meta-viewport | 4.1% |
+ | video-caption | 4.1% |
+ | accesskeys | 1.2% |
+ | aria-command-name | 1.2% |
+ | aria-hidden-focus | 1.2% |
+ | aria-input-field-name | 1.2% |
+ | aria-meter-name | 1.2% |
+ | aria-progressbar-name | 1.2% |
+ | aria-toggle-field-name | 1.2% |
+ | aria-tooltip-name | 1.2% |
+ | aria-treeitem-name | 1.2% |
+ | bypass | 1.2% |
+ | color-contrast | 1.2% |
+ | definition-list | 1.2% |
+ | dlitem | 1.2% |
+ | document-title | 1.2% |
+ | duplicate-id-active | 1.2% |
+ | frame-title | 1.2% |
+ | html-has-lang | 1.2% |
+ | html-lang-valid | 1.2% |
+ | link-name | 1.2% |
+ | list | 1.2% |
+ | listitem | 1.2% |
+ | object-alt | 1.2% |
+ | tabindex | 1.2% |
+ | td-headers-attr | 1.2% |
+ | th-has-data-cells | 1.2% |
+ | valid-lang | 1.2% |
+ | form-field-multiple-labels | 0.8% |
+ | heading-order | 0.8% |
+
+Each audit is a pass/fail, meaning there is no room for partial points for getting an audit half-right. For example, that means if half your buttons have screenreader friendly names, and half do not, you don't get "half" of the weighted average - you get a 0 because it needs to be implemented correctly *throughout* the page.

package/docs/throttling.md

@@ -0,0 +1,150 @@
+# Network Throttling
+
+Lighthouse applies network throttling to emulate the ~85th percentile mobile connection speed even when run on much faster fiber connections.
+
+## The mobile network throttling preset
+
+This is the standard recommendation for mobile throttling:
+
+- Latency: 150ms
+- Throughput: 1.6Mbps down / 750 Kbps up.
+- Packet loss: none.
+
+These exact figures are [defined in the Lighthouse configuration](https://github.com/GoogleChrome/lighthouse/blob/v6.4.1/lighthouse-core/config/constants.js#L22-L29) and used as [Lighthouse's throttling default](https://github.com/GoogleChrome/lighthouse/blob/v6.4.1/lighthouse-core/config/constants.js#L59).
+They represent roughly the bottom 25% of 4G connections and top 25% of 3G connections (in Lighthouse this configuration is currently called "Slow 4G" but used to be labeled as "Fast 3G").
+This preset is identical to the [WebPageTest's "Mobile 3G - Fast"](https://github.com/WPO-Foundation/webpagetest/blob/master/www/settings/connectivity.ini.sample) and, due to a lower latency, slightly faster for some pages than the [WebPageTest "4G" preset](https://github.com/WPO-Foundation/webpagetest/blob/master/www/settings/connectivity.ini.sample).
+
+## Types of network throttling
+
+Within web performance testing, there are four typical styles of network throttling:
+
+1. **_Simulated throttling_**, which Lighthouse uses by **default**, uses a simulation of a page load, based on the data observed in the initial unthrottled load. This approach makes it both very fast and deterministic. However, due to the imperfect nature of predicting alternate execution paths, there is inherent inaccuracy that is summarized in this doc: [Lighthouse Metric Variability and Accuracy](https://docs.google.com/document/d/1BqtL-nG53rxWOI5RO0pItSRPowZVnYJ_gBEQCJ5EeUE/edit). The TLDR: while it's roughly as accurate or better than DevTools throttling for most sites, it suffers from edge cases and a deep investigation to performance should use _Packet-level_ throttling tools.
+1. **_Request-level throttling_** , also referred to as **_Applied throttling_** in the Audits panel or _`devtools` throttling_ in Lighthouse configuration, is how throttling is implemented with Chrome DevTools. In real mobile connectivity, latency affects things at the packet level rather than the request level. As a result, this throttling isn't highly accurate. It also has a few more downsides that are summarized in [Network Throttling & Chrome - status](https://docs.google.com/document/d/1TwWLaLAfnBfbk5_ZzpGXegPapCIfyzT4MWuZgspKUAQ/edit). The TLDR: while it's a [decent approximation](https://docs.google.com/document/d/10lfVdS1iDWCRKQXPfbxEn4Or99D64mvNlugP1AQuFlE/edit), it's not a sufficient model of a slow connection. The [multipliers used in Lighthouse](https://github.com/GoogleChrome/lighthouse/blob/3be483287a530fb560c843b7299ef9cfe91ce1cc/lighthouse-core/lib/emulation.js#L33-L39) attempt to correct for the differences.
+1. **_Proxy-level_** throttling tools do not affect UDP data, so they're decent, but not ideal.
+1. **_Packet-level_** throttling tools are able to make the most accurate network simulation. While this approach can model real network conditions most effectively, it also can introduce [more variance](https://docs.google.com/document/d/1BqtL-nG53rxWOI5RO0pItSRPowZVnYJ_gBEQCJ5EeUE/edit) than request-level or simulated throttling. [WebPageTest uses](https://github.com/WPO-Foundation/wptagent/blob/master/docs/remote_trafficshaping.md) packet-level throttling.
+
+Lighthouse, by default, uses simulated throttling as it provides both quick evaluation and minimized variance. However, some may want to experiment with more accurate throttling... [Learn more about these throttling types and how they behave in in different scenarios](https://www.debugbear.com/blog/network-throttling-methods).
+
+## DevTools' Lighthouse Panel Throttling
+
+In Chrome 79 and earlier, you could choose between [the throttling types](#types-of-throttling) of Simulated, Applied, and none.
+
+Starting with Chrome 80, the Audits panel is simplifying the throttling configuration:
+
+1. _Simulated throttling_ remains the default setting. This matches the setup of PageSpeed Insights and the Lighthouse CLI default, so this provides cross-tool consistency.
+1. _No throttling_ is removed as it leads to innacurate scoring and misleading metric results.
+1. Within the Audits panel settings, you can uncheck the _Simulated throttling_ checkbox to use _Applied throttling_. For the moment, we are keeping this _Applied throttling_ option available for users of the [`View Trace` button](https://developers.google.com/web/updates/2018/04/devtools#traces). Under applied throttling, the trace matches the metrics values, whereas under Simulated things do not currently match up.
+
+We plan to improve the experience of viewing a trace under simulated throttling. At that point, the _Applied throttling_ option will be removed and _Simulated throttling_ will be the only option within the DevTools Audits panel. Of course, CLI users can still control the exact [configuration](../readme.md#cli-options) of throttling.
+
+## How do I get packet-level throttling?
+
+This Performance Calendar article, [Testing with Realistic Networking Conditions](https://calendar.perfplanet.com/2016/testing-with-realistic-networking-conditions/), has a good explanation of packet-level traffic shaping (which applies across TCP/UDP/ICMP) and recommendations.
+
+The `throttle` npm package appears to be the most usable Mac/Linux commandline app for managing your network connection. Important to note: it changes your **entire** machine's network interface. Also, **`throttle` requires `sudo`** (as all packet-level shapers do).
+
+**Windows?** As of today, there is no single cross-platform tool for throttling. But there are two recommended **Windows 7** network shaping utilities: [WinShaper](https://calendar.perfplanet.com/2016/testing-with-realistic-networking-conditions/#introducing_winshaper) and [Clumsy](http://jagt.github.io/clumsy/).
+
+For **Windows 10** [NetLimiter](https://www.netlimiter.com/buy/nl4lite/standard-license/1/0) (Paid option) and [TMeter](http://www.tmeter.ru/en/) (Freeware Edition) are the most usable solutions.
+
+### `throttle` set up
+
+```sh
+# Install with npm
+npm install @sitespeed.io/throttle -g
+# Ensure you have Node.js installed and npm is in your $PATH (https://nodejs.org/en/download/)
+
+# To use the recommended throttling values:
+throttle --up 768 --down 1638 --rtt 150
+
+# or even simpler (using a predefined profile)
+throttle 3gfast
+
+# To disable throttling
+throttle --stop
+```
+
+For more information and a complete list of features visit the documentation on [sitespeed.io website](https://www.sitespeed.io/documentation/throttle/).
+
+### Using Lighthouse with `throttle`
+
+```sh
+# Enable system traffic throttling
+throttle 3gfast
+
+# Run Lighthouse with its own network throttling disabled (while leaving CPU throttling)
+lighthouse --throttling-method=devtools \
+  --throttling.requestLatencyMs=0 \
+  --throttling.downloadThroughputKbps=0 \
+  --throttling.uploadThroughputKbps=0 \
+  https://example.com
+
+# Disable the traffic throttling once you see "Gathering trace"
+throttle --stop
+```
+
+# CPU Throttling
+
+Lighthouse applies CPU throttling to emulate a mid-tier mobile device even when run on far more powerful desktop hardware.
+
+## Benchmarking CPU Power
+
+Unlike network throttling where objective criteria like RTT and throughput allow targeting of a specific environment, CPU throttling is expressed relative to the performance of the host device. This poses challenges to [variability in results across devices](./variability.md), so it's important to calibrate your device before attempting to compare different reports.
+
+Lighthouse computes and saves a `benchmarkIndex` as a rough approximation of the host device's CPU performance with every report. You can find this value under the title "CPU/Memory Power" at the bottom of the Lighthouse report:
+
+<img src="https://user-images.githubusercontent.com/2301202/96950078-1b03d380-14af-11eb-9583-fbf8133315b2.png" alt="Screenshot of CPU/Memory Power in Lighthouse report" width=600 border=1 />
+
+**NOTE:** In Lighthouse 6.3 BenchmarkIndex changed its definition to better align with changes in Chrome 86. Benchmark index values prior to 6.3 and Chrome 86 may differ.
+
+Below is a table of various device classes and their approximate ranges of `benchmarkIndex` as of Chrome m86 along with a few other benchmarks. The amount of variation in each class is quite high. Even the same device can be purchased with multiple different processors and memory options.
+
+| -                                   | High-End Desktop | Low-End Desktop | High-End Mobile | Mid-Tier Mobile | Low-End Mobile    |
+| ----------------------------------- | ---------------- | --------------- | --------------- | --------------- | ----------------- |
+| Example Device                      | 16" Macbook Pro  | Intel NUC i3    | Samsung S10     | Moto G4         | Samsung Galaxy J2 |
+| **Lighthouse BenchmarkIndex**           | 1500-2000        | 1000-1500       | 800-1200        | 125-800         | <125              |
+| Octane 2.0                          | 30000-45000      | 20000-35000     | 15000-25000     | 2000-20000      | <2000             |
+| Speedometer 2.0                     | 90-200           | 50-90           | 20-50           | 10-20           | <10               |
+| JavaScript Execution of a News Site | 2-4s             | 4-8s            | 4-8s            | 8-20s           | 20-40s            |
+
+
+## Calibrating the CPU slowdown
+
+By default, Lighthouse uses **a constant 4x CPU multiplier** which moves a typical run in the high-end desktop bracket somewhere into the mid-tier mobile bracket. 
+
+You may choose to calibrate if your benchmarkIndex is in a different range than the above table would expect. Additionally, when Lighthouse is run from the CLI with default settings on an underpowered device, a warning will be added to the report suggesting you calibrate the slowdown:
+
+![image](https://user-images.githubusercontent.com/39191/101437249-99cc9880-38c4-11eb-8122-76f2c73d9283.png)
+
+The `--throttling.cpuSlowdownMultiplier` CLI flag allows you to configure the throttling level applied. On a weaker machine, you can lower it from the default of 4x  to something more appropriate. 
+
+The [Lighthouse CPU slowdown calculator webapp](https://lighthouse-cpu-throttling-calculator.vercel.app/) will compute what mutiplier to use from the  `CPU/Memory Power` value from the bottom of the report.
+
+<a href="https://lighthouse-cpu-throttling-calculator.vercel.app/">
+<img src="https://user-images.githubusercontent.com/39191/101436708-8a991b00-38c3-11eb-89c5-7d43752932e9.png" width=300>
+</a>
+
+Alternatively, consider the below table of the various `cpuSlowdownMultiplier`s you might want to use to target different devices along with the possible range:
+
+| -                | High-End Desktop | Low-End Desktop | High-End Mobile | Mid-Tier Mobile | Low-End Mobile |
+| ---------------- | ---------------- | --------------- | --------------- | --------------- | -------------- |
+| High-End Desktop | 1x               | 2x (1-4)        | 2x (1-4)        | 4x (2-10)       | 10x (5-20)     |
+| Low-End Desktop  | -                | 1x              | 1x              | 2x (1-5)        | 5x (3-10)      |
+| High-End Mobile  | -                | -               | 1x              | 2x (1-5)        | 5x (3-10)      |
+| Mid-Tier Mobile  | -                | -               | -               | 1x              | 2x (1-5)       |
+| Low-End Mobile   | -                | -               | -               | -               | 1x             |
+
+
+If your device's BenchmarkIndex falls on the _higher_ end of its bracket, use a _higher_ multiplier from the range in the table. If your device's BenchmarkIndex falls on the _lower_ end of its bracket, use a _lower_ multiplier from the range in the table. If it's somewhere in the middle, use the suggested multiplier.
+
+```bash
+# Run Lighthouse with a custom CPU slowdown multiplier
+lighthouse --throttling.cpuSlowdownMultiplier=6 https://example.com
+```
+
+## Types of CPU Throttling
+
+Within web performance testing, there are two typical styles of CPU throttling:
+
+1. **_Simulated throttling_**, which Lighthouse uses by **default**, uses a simulation of a page load, based on the data observed in the initial unthrottled load. This approach makes it very fast. However, due to the imperfect nature of predicting alternate execution paths, there is inherent inaccuracy that is summarized in this doc: [Lighthouse Metric Variability and Accuracy](https://docs.google.com/document/d/1BqtL-nG53rxWOI5RO0pItSRPowZVnYJ_gBEQCJ5EeUE/edit). The TLDR: while it's fairly accurate for most circumstances, it suffers from edge cases and a deep investigation to performance should use _applied_ CPU throttling tools.
+1. **_Applied throttling_** , also called _`devtools` throttling_ in Lighthouse configuration. This method actually interrupts execution of CPU work at periodic intervals to emulate a slower processor. It is [fairly accurate](https://docs.google.com/document/d/1jGHeGjjjzfTAE2WHXipKF3aqwF2bFA6r0B877nFtBpc/edit) and much easier than obtaining target hardware. The same underlying principle can be used by [linux cgroups](https://www.kernel.org/doc/html/latest/scheduler/sched-bwc.html) to throttle any process, not just the browser. Other tools like [WebPageTest use applied CPU throttling](https://github.com/WPO-Foundation/wptagent/commit/f7fe0d6b5b01bd1b042a1fe3144c68a6bff846a6) offered by DevTools.

package/docs/understanding-results.md

@@ -0,0 +1,209 @@
+# Understanding the Results
+
+The result object contains all the audit information Lighthouse determined about the page. In fact, everything you see in the HTML report, even the screenshots, is a rendering of information contained in the result object. You might need to work directly with the result object if you use [Lighthouse programmatically](https://github.com/GoogleChrome/lighthouse/blob/master/docs/readme.md#using-programmatically), consume the JSON output of the [CLI](https://github.com/GoogleChrome/lighthouse#using-the-node-cli), explore [Lighthouse results in HTTPArchive](https://github.com/GoogleChrome/lighthouse#lighthouse-integrations), or work on the report generation code that reads the Lighthouse JSON and outputs HTML.
+
+## Lighthouse Result Object (LHR)
+
+The top-level Lighthouse Result object (LHR) is what the lighthouse node module returns and the entirety of the JSON output of the CLI. It contains some metadata about the run and the results in the various subproperties below.
+
+For an always up-to-date definition of the LHR, take a look [at our typedefs](https://github.com/GoogleChrome/lighthouse/blob/master/types/lhr.d.ts).
+
+### Properties
+
+| Name | Description |
+| - | - |
+| lighthouseVersion | The version of Lighthouse with which this result was generated. |
+| fetchTime | The ISO-8601 timestamp of when the result was generated. |
+| userAgent | The user agent string of the version of Chrome that was used by Lighthouse. |
+| requestedUrl | The URL that was supplied to Lighthouse and initially navigated to. |
+| finalUrl | The URL that Lighthouse ended up auditing after redirects were followed. |
+| [audits](#audits) | An object containing the results of the audits. |
+| [configSettings](#config-settings) | An object containing information about the configuration used by Lighthouse. |
+| [timing](#timing) | An object containing information about how long Lighthouse spent auditing. |
+| [categories](#categories) | An object containing the different categories, their scores, and references to the audits that comprise them. |
+| [categoryGroups](#category-groups) | An object containing the display groups of audits for the report. |
+| runtimeError | An object `{code: string, message: string};` providing a top-level error message that, if present, indicates a serious enough problem that this Lighthouse result may need to be discarded. |
+| runWarnings | Array of top-level warnings for this Lighthouse run. |
+
+### Example
+```json
+{
+  "lighthouseVersion": "5.1.0",
+  "fetchTime": "2019-05-05T20:50:54.185Z",
+  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/66.0.3358.0 Safari/537.36",
+  "requestedUrl": "http://example.com",
+  "finalUrl": "https://www.example.com/",
+  "audits": {...},
+  "configSettings": {...},
+  "timing": {...},
+  "categories": {...},
+  "categoryGroups": {...},
+}
+```
+
+
+<a name="audits"></a>
+## `audits`
+
+An object containing the results of the audits, keyed by their name.
+
+### Audit Properties
+| Name | Type | Description |
+| -- | -- | -- |
+| id  | `string` | The string identifier of the audit in kebab case.  |
+| title | `string` | The display name of the audit. The text can change depending on if the audit passed or failed. It may contain markdown code. |
+| description | `string` | A more detailed description that describes why the audit is important and links to Lighthouse documentation on the audit, markdown links supported. |
+| explanation | <code>string&#124;undefined</code> | A string indicating the reason for audit failure. |
+| warnings | <code>string[]&#124;undefined</code> | Messages identifying potentially invalid cases |
+| errorMessage | <code>string&#124;undefined</code> | A message set |
+| numericValue | <code>number&#124;undefined</code> | The unscored value determined by the audit. Typically this will match the score if there's no additional information to impart. For performance audits, this value is typically a number indicating the metric value. |
+| displayValue | <code>string&#124;undefined</code> | The string to display in the report alongside audit results. If empty, nothing additional is shown. This is typically used to explain additional information such as the number and nature of failing items. |
+| score | <code>number&#124;null</code> | The scored value determined by the audit provided in the numeric range `0-1`, or null if `scoreDisplayMode` indicates not scored. |
+| scoreDisplayMode | <code>"binary" &#124; "numeric" &#124; "error" &#124; "manual" &#124; "notApplicable" &#124; "informative"</code> | A string identifying how the score should be interpreted for display i.e. is the audit pass/fail (score of 1 or 0), did it fail, should it be ignored, or are there shades of gray (scores between 0-1 inclusive). If set as `informative`, `notApplicable`, `manual`, or `error`, then `score` will be null and should be ignored. |
+| details | `Object` | Extra information found by the audit necessary for display. The structure of this object varies from audit to audit. The [structure of this object](https://github.com/GoogleChrome/lighthouse/blob/master/types/audit-details.d.ts) is somewhat stable between minor version bumps as this object is used to render the HTML report. |
+
+
+### Example
+```json
+{
+  "is-on-https": {
+      "id": "is-on-https",
+      "title": "Does not use HTTPS",
+      "description": "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).",
+      "score": 0,
+      "scoreDisplayMode": "binary",
+      "displayValue": "1 insecure request found",
+      "details": {
+        "type": "table",
+        "headings": [
+          {
+            "key": "url",
+            "itemType": "url",
+            "text": "Insecure URL"
+          }
+        ],
+        "items": [
+          {
+            "url": "http://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"
+          }
+        ]
+      }
+    },
+  },
+  "custom-audit": {
+    "name": "custom-audit",
+    ...
+  }
+}
+```
+
+
+<a name="config-settings"></a>
+## `configSettings`
+
+An object containing information about the configuration used by Lighthouse.
+
+### Example
+```json
+{
+  "output": [
+    "json"
+  ],
+  "maxWaitForLoad": 45000,
+  "throttlingMethod": "devtools",
+  "throttling": {
+    "rttMs": 150,
+    "throughputKbps": 1638.4,
+    "requestLatencyMs": 562.5,
+    "downloadThroughputKbps": 1474.5600000000002,
+    "uploadThroughputKbps": 675,
+    "cpuSlowdownMultiplier": 4
+  },
+  "gatherMode": false,
+  "disableStorageReset": false,
+  "formFactor": "mobile",
+  "blockedUrlPatterns": null,
+  "additionalTraceCategories": null,
+  "extraHeaders": null,
+  "onlyAudits": null,
+  "onlyCategories": null,
+  "skipAudits": null
+}
+```
+
+<a name="timing"></a>
+## `timing`
+
+An object containing information about how long Lighthouse spent auditing.
+
+### Properties
+| Name | Type | Description |
+| -- | -- | -- |
+| total | `number` | The total time spent in milliseconds loading the page and evaluating audits. |
+
+### Example
+```json
+{
+  "total": 32189
+}
+```
+
+<a name="categories"></a>
+## `categories`
+
+An array containing the different categories, their scores, and the results of the audits in the categories.
+
+### CategoryEntry Properties
+| Name | Type | Description |
+| -- | -- | -- |
+| id | `string` | The string identifier of the category. |
+| title | `string` | The human-friendly display name of the category. |
+| description | `string` | A brief description of the purpose of the category, supports markdown links. |
+| score | `number` | The overall score of the category, the weighted average of all its audits. |
+| auditRefs | `AuditEntry[]` | An array of all the audit results in the category. |
+
+### AuditEntry Properties
+| Name | Type | Description |
+| -- | -- | -- |
+| id | `string` | The string identifier of the category. |
+| weight | `number` | The weight of the audit's score in the overall category score. |
+| group | `string` |  |
+
+### Example
+```json
+{
+  "pwa": {
+    "id": "pwa",
+    "title": "Progressive Web App",
+    "description": "PWAs are awesome. [Learn more](...)",
+    "score": 0.54,
+    "auditRefs": [
+      {
+        "id": "is-on-https",
+        "weight": 1
+      }
+    ]
+  }
+}
+```
+
+<a name="category-groups"></a>
+## `categoryGroups`
+
+An object containing the display groups of audits for the report, keyed by the group ID found in the config.
+
+### GroupEntry Properties
+| Name | Type | Description |
+| -- | -- | -- |
+| title | `string` | The title of the display group. |
+| description | `string` | A brief description of the purpose of the display group. |
+
+### Example
+```json
+{
+  "metrics": {
+    "title": "Metrics",
+    "description": "These metrics are super cool."
+  },
+}
+```