diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d8d02ebd00b2..38f97dff44ca 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ We'd love your help! This doc covers how to become a contributor and submit code ## Follow the coding style -The `.eslintrc` file defines all. We use [JSDoc](http://usejsdoc.org/) along with [closure annotations](https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler). Annotations are encouraged for all contributions. +The `.eslintrc` file defines all. We use [JSDoc](http://usejsdoc.org/) with [TypeScript](https://github.com/Microsoft/TypeScript/wiki/JSDoc-support-in-JavaScript). Annotations are encouraged for all contributions. ## Pull request titles diff --git a/docs/architecture.md b/docs/architecture.md index 89c36edae6af..cdbd44871073 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -84,6 +84,6 @@ Tracing processor takes the output of trace of tab and identifies the top-level ## Audits -The return value of each audit [takes this shape](https://github.com/GoogleChrome/lighthouse/blob/b354890076f2c077c5460b2fa56ded546cca72ee/lighthouse-core/closure/typedefs/AuditResult.js#L23-L55). +The return value of each audit [takes this shape](https://github.com/GoogleChrome/lighthouse/blob/8f500e00243e07ef0a80b39334bedcc8ddc8d3d0/typings/audit.d.ts#L117-L130). The `details` object is parsed in report-renderer.js. View other audits for guidance on how to structure `details`. diff --git a/docs/configuration.md b/docs/configuration.md index b85e91a7a91f..d3bd386597d1 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -11,20 +11,16 @@ You can specify a custom config file when using Lighthouse through the CLI or co **custom-config.js** ```js module.exports = { - passes: [{ - recordTrace: true, - pauseAfterLoadMs: 5000, - useThrottling: true, - gatherers: [], - }], - - audits: [ - 'first-meaningful-paint', - 'speed-index-metric', - 'estimated-input-latency', - 'first-interactive', - 'consistently-interactive', - ] + extends: 'lighthouse:default', + settings: { + onlyAudits: [ + 'first-meaningful-paint', + 'speed-index-metric', + 'estimated-input-latency', + 'first-interactive', + 'consistently-interactive', + ], + }, }; ``` @@ -77,6 +73,8 @@ The settings property controls various aspects of running Lighthouse such as CPU ``` #### Options +For full list see [our default config settings](https://github.com/GoogleChrome/lighthouse/blob/8f500e00243e07ef0a80b39334bedcc8ddc8d3d0/lighthouse-core/config/constants.js#L30-L48). + | 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. | @@ -89,6 +87,7 @@ The passes property controls how to load the requested URL and what information 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 @@ -96,15 +95,13 @@ Each `passes` entry defines basic settings such as how long to wait for the page passes: [ { passName: 'fastPass', - recordTrace: true, - useThrottling: false, - networkQuietThresholdMs: 0, gatherers: ['fast-gatherer'], }, { passName: 'slowPass', recordTrace: true, useThrottling: true, + networkQuietThresholdMs: 5000, gatherers: ['slow-gatherer'], } ] @@ -141,7 +138,7 @@ The audits property controls which audits to run and include with your Lighthous ### `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 `reportCategories` property of Lighthouse's output. The category output contains the child audit results along with an overall score for the category. +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. @@ -150,9 +147,9 @@ The categories property controls how to score and organize the audit results in { categories: { performance: { - name: 'Performance', + title: 'Performance', description: 'This category judges your performance', - audits: [ + auditRefs: [ {id: 'first-meaningful-paint', weight: 2, group: 'metrics'}, {id: 'first-interactive', weight: 3, group: 'metrics'}, {id: 'consistently-interactive', weight: 5, group: 'metrics'}, @@ -165,12 +162,12 @@ The categories property controls how to score and organize the audit results in #### Options | Name | Type | Description | | -- | -- | -- | -| name | `string` | The display name of the category. | +| title | `string` | The display name of the category. | | description | `string` | The displayed description of the category. | -| audits | `Object[]` | The audits to include in the category. | -| audits[$i].id | `string` | The ID of the audit to include. | -| audits[$i].weight | `number` | The weight of the audit in the scoring of the category. | -| audits[$i].group | `string` (optional) | The ID of the [display group](#groups-objectundefined) of the audit. | +| 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` @@ -183,7 +180,7 @@ The groups property controls how to visually group audits within a category. For { categories: { performance: { - audits: [ + auditRefs: [ {id: 'my-performance-metric', weight: 2, group: 'metrics'}, ], } @@ -208,7 +205,7 @@ The stock Lighthouse configurations can be extended if you only need to make sma 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/plots-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/plots-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/master/lib/lh-config.ts) diff --git a/docs/headless-chrome.md b/docs/headless-chrome.md index 367887e49c9e..9600eb7e9ea3 100644 --- a/docs/headless-chrome.md +++ b/docs/headless-chrome.md @@ -27,8 +27,8 @@ lighthouse --chrome-flags="--headless" https://github.com Alternatively, you can run full Chrome + xvfb instead of headless mode. These steps worked on Debian Jessie: ```sh -# get node 6 -curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash - +# get node 8 +curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash - sudo apt-get install -y nodejs # get chromium (stable) and Xvfb diff --git a/docs/lantern.md b/docs/lantern.md index 710835ba14a9..bb2f79ab44c4 100644 --- a/docs/lantern.md +++ b/docs/lantern.md @@ -29,7 +29,7 @@ Stats were collected using the [trace-evaluation](https://github.com/patrickhulc We conclude that Lantern is ~6-13% more inaccurate than DevTools throttling. When evaluating rank performance, Lantern achieves correlations within ~.04-.07 of DevTools throttling. * For the single view use case, our original conclusion that Lantern's inaccuracy is roughly equal to the inaccuracy introduced by expected variance seems to hold. The standard deviation of single observations from DevTools throttling is ~9-13%, and given Lantern's much lower variance, single observations from Lantern are not significantly more inaccurate on average than single observations from DevTools throttling. -* For the repeat view use case, we can conclude that Lantern is systematically off by ~6-13% more than DevTools throttling. +* For the repeat view use case, we can conclude that Lantern is systematically off by ~6-13% more than DevTools throttling. ### Metric Variability Conclusions The reference stats demonstrate that there is high degree of variability with the user-centric metrics and strengthens the position that every load is just an observation of a point drawn from a distribution and to understand the entire experience, multiple draws must be taken, i.e. multiple runs are needed to have sufficiently small error bounds on the median load experience. diff --git a/docs/puppeteer.md b/docs/puppeteer.md index 5e880e072671..a57f28dad1ca 100644 --- a/docs/puppeteer.md +++ b/docs/puppeteer.md @@ -45,13 +45,13 @@ browser.on('targetchanged', async target => { // Lighthouse will open URL. Puppeteer observes `targetchanged` and sets up network conditions. // Possible race condition. -const lhr = await lighthouse(url, { +const {lhr} = await lighthouse(url, { port: (new URL(browser.wsEndpoint())).port, output: 'json', logLevel: 'info', }); -console.log(`Lighthouse scores: ${lhr.reportCategories.map(c => c.score).join(', ')}`); +console.log(`Lighthouse scores: ${Object.values(lhr.categories).map(c => c.score).join(', ')}`); await browser.close(); })(); @@ -89,8 +89,8 @@ 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: ${lhr.reportCategories.map(c => c.score).join(', ')}`); +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(); diff --git a/docs/readme.md b/docs/readme.md index 621dd9250c20..7e4085aa291c 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -15,9 +15,11 @@ function launchChromeAndRunLighthouse(url, opts, config = null) { return chromeLauncher.launch({chromeFlags: opts.chromeFlags}).then(chrome => { opts.port = chrome.port; return lighthouse(url, opts, config).then(results => { - // The gathered artifacts are typically removed as they can be quite large (~50MB+) - delete results.artifacts; - return chrome.kill().then(() => results) + // use results.lhr for the JS-consumeable output + // https://github.com/GoogleChrome/lighthouse/blob/master/typings/lhr.d.ts + // use results.report for the HTML/JSON/CSV output as a string + // use results.artifacts for the trace/screenshots/other specific case you need (rarer) + return chrome.kill().then(() => results.lhr) }); }); } @@ -39,13 +41,31 @@ 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 perfConfig = require('lighthouse/lighthouse-core/config/perf-config.js'); // ... -launchChromeAndRunLighthouse(url, flags, perfConfig).then( // ... +const flags = {onlyCategories: ['performance']}; +launchChromeAndRunLighthouse(url, flags).then( // ... ``` You can also craft your own config (e.g. [mixed-content-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/mixed-content-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/8f500e00243e07ef0a80b39334bedcc8ddc8d3d0/typings/externs.d.ts#L68). 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 `opn` 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 @@ -56,7 +76,7 @@ the `logLevel` flag when calling `lighthouse`. ```javascript const log = require('lighthouse-logger'); -const flags = {logLevel: 'info', output: 'json'}; +const flags = {logLevel: 'info'}; log.setLevel(flags.logLevel); launchChromeAndRunLighthouse('https://example.com', flags).then(...); diff --git a/docs/scoring.md b/docs/scoring.md index 73b1ebe49c97..eb1a52eea734 100644 --- a/docs/scoring.md +++ b/docs/scoring.md @@ -6,7 +6,7 @@ Note 1: if you want a **nice spreadsheet** version of this doc to understand wei ![alt text](https://user-images.githubusercontent.com/39191/32397461-2d20c87a-c0a7-11e7-99d8-61576113a710.png) *Screenshot of the [scoring spreadsheet](https://docs.google.com/spreadsheets/d/1Cxzhy5ecqJCucdf1M0iOzM8mIxNc7mmx107o5nj38Eo/edit#gid=0)* -Note 2: if you receive a **score of 0** in any Lighthouse category, that usually indicates an error on our part. Please file an [issue](https://github.com/GoogleChrome/lighthouse/issues) so our team can look into it. +Note 2: receiving a **score of ?** in any Lighthouse category indicates an error occurred. Please file an [issue](https://github.com/GoogleChrome/lighthouse/issues) so our team can look into it. # Performance @@ -30,11 +30,12 @@ The performance score is determined from the **performance metrics only**. The O The metric results are not weighted equally. Currently the weights are: -* 5X - first meaningful paint -* 5X - first interactive +* 3X - first contentful paint +* 1X - first meaningful paint +* 3X - first cpu idle * 5X - consistently interactive -* 1X - perceptual speed index -* 1X - estimated input latency +* 4X - speed index +* 0X - estimated input latency These weights are heuristics, and the Lighthouse team is working on formalizing the weighting system through more field data. @@ -47,7 +48,7 @@ Once we finish computing the percentile equivalent of your raw performance score - Green (good): 75-100. ### What can developers do to improve their performance score? -*Note: we've built [a little calculator](https://docs.google.com/spreadsheets/d/1dXH-bXX3gxqqpD1f7rp6ImSOhobsT1gn_GQ2fGZp8UU/edit?ts=59fb61d2#gid=283330180) that can help you understand what thresholds you should be aiming for achieving a certain Lighthouse performance score. * +*Note: we've built [a little calculator](https://docs.google.com/spreadsheets/d/1Cxzhy5ecqJCucdf1M0iOzM8mIxNc7mmx107o5nj38Eo/edit#gid=283330180) that can help you understand what thresholds you should be aiming for achieving a certain Lighthouse performance score. * Lighthouse has a whole section in the report on improving your performance score under the “Opportunities” section. There are detailed suggestions and documentation that explains the different suggestions and how to implement them. Additionally, the diagnostics section lists additional guidance that developers can explore to further experiment and tweak with their performance. diff --git a/docs/throttling.md b/docs/throttling.md index d4d3cbcaf623..104f7df35809 100644 --- a/docs/throttling.md +++ b/docs/throttling.md @@ -7,11 +7,12 @@ This is the standard recommendation for 3G throttling: - Throughput: 1.6Mbps down / 750 Kbps up. - Packet loss: none. -These exact figures are used as the [WebPageTest "Mobile 3G - Fast" preset](https://github.com/WPO-Foundation/webpagetest/blob/master/www/settings/connectivity.ini.sample) and [Lighthouse's throttling default](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/lib/emulation.js). +These exact figures are used as the [WebPageTest "Mobile 3G - Fast" preset](https://github.com/WPO-Foundation/webpagetest/blob/master/www/settings/connectivity.ini.sample) and [Lighthouse's throttling default](https://github.com/GoogleChrome/lighthouse/blob/8f500e00243e07ef0a80b39334bedcc8ddc8d3d0/lighthouse-core/config/constants.js#L19-L26). ## Throttling basics -1. The DevTools network throttling, which Lighthouse uses, is implemented within Chrome at the _request-level_. As a result, it has some downsides that are now summarized in this doc: [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/1uS9SH1KpVH31JAmf-iIZ61VazwAF9MrCVwETshBC4UQ/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. Simulated throttling, which Lighthouse uses by default, is computed throttling _after a trace has been recorded_ which makes it 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. The DevTools network throttling, which Lighthouse uses for `throttlingMethod='devtools'`, is implemented within Chrome at the _request-level_. As a result, it has some downsides that are now summarized in this doc: [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/1uS9SH1KpVH31JAmf-iIZ61VazwAF9MrCVwETshBC4UQ/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 not recommended. 1. _Packet-level_ throttling tools are able to make the most accurate network simulation. diff --git a/docs/understanding-results.md b/docs/understanding-results.md index 8146d95aa0a4..e9fe1128ae64 100644 --- a/docs/understanding-results.md +++ b/docs/understanding-results.md @@ -6,6 +6,8 @@ The result object contains all the audit information Lighthouse determined about 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/typings/lhr.d.ts). + ### Properties | Name | Description | @@ -16,11 +18,10 @@ The top-level Lighthouse Result object (LHR) is what the lighthouse node module | 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. | -| [runtimeConfig](#runtime-config) | An object containing information about the configuration used by Lighthouse. | +| [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. | -| [reportCategories](#report-categories) | An array containing the different categories, their scores, and the results of the audits that comprise them. | -| [reportGroups](#report-groups) | An object containing the display groups of audits for the report. | -| [artifacts](#artifacts) | *(PROGRAMMATIC USE ONLY)* An object containing gatherer results. | +| [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. | ### Example ```json @@ -32,10 +33,10 @@ The top-level Lighthouse Result object (LHR) is what the lighthouse node module "finalUrl": "https://www.example.com/", "score": 50, "audits": {...}, - "runtimeConfig": {...}, + "configSettings": {...}, "timing": {...}, - "reportCategories": [{...}], - "reportGroups": {...}, + "categories": {...}, + "categoryGroups": {...}, } ``` @@ -48,61 +49,45 @@ An object containing the results of the audits, keyed by their name. ### Audit Properties | Name | Type | Description | | -- | -- | -- | -| name | `string` | The string identifier of the audit in kebab case. | -| description | `string` | The brief description of the audit. The text can change depending on if the audit passed or failed. It may contain markdown code. | -| helpText | `string` | A more detailed description that describes why the audit is important and links to Lighthouse documentation on the audit, markdown links supported. | -| debugString | string|undefined | A string indicating some additional information to the user explaining an unusual circumstance or reason for failure. | -| error | `boolean` | Set to true if there was an an exception thrown within the audit. The error message will be in `debugString`. +| 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 | string|undefined | A string indicating the reason for audit failure. | +| warnings | string[]|undefined | Messages identifying potentially invalid cases | +| errorMessage | string|undefined | A message set | | rawValue | boolean|number | 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 | `string` | 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 | number | The scored value determined by the audit as a number `0-1`, representing displayed scores of 0-100. | -| scoreDisplayMode | "binary"|"numeric" | A string identifying how the score should be interpreted i.e. is the audit pass/fail (score of 1 or 0), or are there shades of gray (scores between 0-1 inclusive). | -| 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 is somewhat stable between minor version bumps as this object is used to render the HTML report. -| extendedInfo | `Object` | Extra information found by the audit. The structure of this object varies from audit to audit and is generally for programmatic consumption and debugging, though there is typically overlap with `details`. *WARNING: The structure of this object is not stable and cannot be trusted to follow semver* | -| manual | `boolean` | Indicator used for display that the audit does not have results and is a placeholder for the user to conduct manual testing. | -| informative | `boolean` | Indicator used for display that the audit is intended to be informative only. It cannot be passed or failed. | -| notApplicable | `boolean` | Indicator used for display that the audit doesn't apply to the page. (e.g. A images audit on a page without images). | +| scoreDisplayMode | "binary"|"numeric"|"error"|"manual"|"not-applicable"|"informative" | 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). | +| 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 is somewhat stable between minor version bumps as this object is used to render the HTML report. | ### Example ```json { "is-on-https": { - "name": "is-on-https", - "category": "Security", - "description": "Uses HTTPS", - "failureDescription": "Does not use HTTPS", - "helpText": "HTTPS is the best. [Learn more](https://learn-more)", - "score": 0, - "rawValue": false, - "displayValue": "2 insecure requests found", - "scoreDisplayMode": "binary", - "details": { - "type": "list", - "header": { - "type": "text", - "text": "Insecure URLs:" - }, - "items": [ - { - "type": "url", - "text": "http://example.com/" - }, - { - "type": "url", - "text": "http://example.com/favicon.ico" - } - ] - }, - "extendedInfo": { - "value": [ - { - "url": "http://example.com/" - }, - { - "url": "http://example.com/favicon.ico" - } - ] + "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", + "rawValue": false, + "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": { @@ -113,38 +98,36 @@ An object containing the results of the audits, keyed by their name. ``` - -## `runtimeConfig` + +## `configSettings` An object containing information about the configuration used by Lighthouse. -### Properties -| Name | Type | Description | -| -- | -- | -- | -| blockedUrlPatterns | `string[]` | The network request patterns that Lighthouse blocked while loading the page. | -| environment | `Object[]` | The environment settings used such as CPU and network throttling and device emulation. - ### Example ```json { - "blockedUrlPatterns": ["bad-script.js"], - "environment": [ - { - "name": "Device Emulation", - "enabled": true, - "description": "Nexus 5X" - }, - { - "name": "Network Throttling", - "enabled": true, - "description": "562.5ms RTT, 1.4Mbps down, 0.7Mbps up" - }, - { - "name": "CPU Throttling", - "enabled": true, - "description": "4x slowdown" - } - ] + "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, + "disableDeviceEmulation": false, + "blockedUrlPatterns": null, + "additionalTraceCategories": null, + "extraHeaders": null, + "onlyAudits": null, + "onlyCategories": null, + "skipAudits": null } ``` @@ -165,8 +148,8 @@ An object containing information about how long Lighthouse spent auditing. } ``` - -## `reportCategories` + +## `categories` An array containing the different categories, their scores, and the results of the audits in the categories. @@ -174,46 +157,38 @@ An array containing the different categories, their scores, and the results of t | Name | Type | Description | | -- | -- | -- | | id | `string` | The string identifier of the category. | -| name | `string` | The human-friendly name 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 | `string` | The overall score of the category, the weighted average of all its audits. | -| weight | `string` | The weight of the category in the overall Lighthouse score. | -| audits | `AuditEntry[]` | An array of all the audit results in the category. | +| 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. | -| result | `Object` | The actual audit result, a copy of the audit object found in [audits](#audits). *NOTE: this property will likely be removed in upcoming releases; use the `id` property to lookup the result in the `audits` property.* | +| group | `string` | | ### Example ```json -[ - { +{ + "pwa": { "id": "pwa", - "name": "Progressive Web App", + "title": "Progressive Web App", "description": "PWAs are awesome. [Learn more](...)", - "score": 54, - "weight": 1, - "audits": [ + "score": 0.54, + "auditRefs": [ { "id": "is-on-https", - "score": 0, - "weight": 1, - "result": { - "name": "is-on-https", - "score": 0, - ... - } + "weight": 1 } ] } -] +} ``` - -## `reportGroups` + +## `categoryGroups` An object containing the display groups of audits for the report, keyed by the group ID found in the config. @@ -232,17 +207,3 @@ An object containing the display groups of audits for the report, keyed by the g }, } ``` - - -## `artifacts` - -An object containing gatherer results keyed by gatherer class name. The structure varies by artifact and is not stable. The values of artifacts are subject to change. This property is only available when consuming Lighthouse results programmatically as the artifacts contain trace data and can be quite large (>50MB). - -### Example -```json -{ - "Offline": 200, - "HTTPRedirect": {"value": true}, - ... -} -``` diff --git a/readme.md b/readme.md index f473085831a3..aa832f87c50f 100644 --- a/readme.md +++ b/readme.md @@ -8,9 +8,9 @@ Lighthouse is integrated directly into the Chrome Developer Tools, under the "Au **Installation**: install [Chrome](https://www.google.com/chrome/browser). -**Run it**: open Chrome DevTools, select the Audits panel, and hit "Perform an Audit...". +**Run it**: open Chrome DevTools, select the Audits panel, and hit "Run audits". -Lighthouse integration in Chrome DevTools +Lighthouse integration in Chrome DevTools ## Using the Chrome extension @@ -20,7 +20,7 @@ Lighthouse is integrated directly into the Chrome Developer Tools, under the "Au ## Using the Node CLI -_Lighthouse requires Node 6 or later._ +_Lighthouse requires Node 8 LTS (8.9) or later._ **Installation**: @@ -139,13 +139,13 @@ lighthouse --output-path=./report.json --output json You can run a subset of Lighthouse's lifecycle if desired via the `--gather-mode` (`-G`) and `--audit-mode` (`-A`) CLI flags. ```sh -lighthouse -G http://example.com +lighthouse http://example.com -G # launches browser, collects artifacts, saves them to disk (in `./latest-run/`) and quits -lighthouse -A http://example.com +lighthouse http://example.com -A # skips browser interaction, loads artifacts from disk (in `./latest-run/`), runs audits on them, generates report -lighthouse -GA http://example.com +lighthouse http://example.com -GA # Normal gather + audit run, but also saves collected artifacts to disk for subsequent -A runs. @@ -164,7 +164,7 @@ Lighthouse can produce a report as JSON or HTML. HTML report: -![Lighthouse report](https://cloud.githubusercontent.com/assets/238208/26369813/abea39e4-3faa-11e7-8d5c-e116696518b4.png) +![Lighthouse report](https://user-images.githubusercontent.com/2301202/40556754-b9361c66-6002-11e8-8957-68c7bac85fa4.png) ### Online Viewer @@ -197,10 +197,14 @@ Useful documentation, examples, and recipes to get you started. **Videos** +The session from Google I/O 2018 covers the new performance engine, upcoming Lighthouse REST API, and using the Chrome UX report to evaluate real-user data. + +[![Lighthouse @ Google I/O 2018](https://img.youtube.com/vi/UvK9zAsSM8Q/0.jpg)](https://www.youtube.com/watch?v=UvK9zAsSM8Q) + The session from Google I/O 2017 covers architecture, writing custom audits, GitHub/Travis/CI integration, headless Chrome, and more: -[![Lighthouse @ Google I/O](https://img.youtube.com/vi/NoRYn6gOtVo/0.jpg)](https://www.youtube.com/watch?v=NoRYn6gOtVo) +[![Lighthouse @ Google I/O 2017](https://img.youtube.com/vi/NoRYn6gOtVo/0.jpg)](https://www.youtube.com/watch?v=NoRYn6gOtVo) _click to watch the video_ @@ -248,10 +252,8 @@ yarn lint yarn unit yarn smoke -## run closure compiler (on whitelisted files) -yarn closure -## import your report renderer into devtools-frontend and run devtools closure compiler -yarn compile-devtools +## run tsc compiler +yarn type-check ``` ## Lighthouse Integrations @@ -278,6 +280,7 @@ Other awesome open source projects that use Lighthouse. * **[lighthouse-cron](https://github.com/thearegee/lighthouse-cron)** - Cron multiple batch Lighthouse audits and emit results for sending to remote server. * **[lightcrawler](https://github.com/github/lightcrawler)** - Crawl a website and run each page found through Lighthouse. * **[lighthouse-lambda](https://github.com/joytocode/lighthouse-lambda)** - Run Lighthouse on AWS Lambda with prebuilt stable desktop Headless Chrome. +* **[lighthouse-security](https://github.com/voorhoede/lighthouse-security#readme)** - Run a set of security audits along with Lighthouse. * **[Garie](https://github.com/boyney123/garie)** — An open source tool for monitoring performance using Lighthouse, PageSpeed Insights, [Prometheus](https://prometheus.io/), [Grafana](https://grafana.com/) and [Docker](https://www.docker.com/). ## FAQ @@ -295,7 +298,7 @@ Yes! Details in [Lighthouse configuration](./docs/configuration.md). Good question. Network and CPU throttling are applied by default in a Lighthouse run. The network attempts to emulate 3G and the CPU is slowed down 4x from your machine's default speed. If you prefer to run Lighthouse without throttling, you'll have to use the CLI and disable it with the -`--disable-*` flags mentioned above. +`--throttling.*` flags mentioned above. Read more in our [guide to network throttling](./docs/throttling.md). diff --git a/typings/externs.d.ts b/typings/externs.d.ts index 1b6a67dc16b5..f760ce916cdd 100644 --- a/typings/externs.d.ts +++ b/typings/externs.d.ts @@ -66,25 +66,25 @@ declare global { } export interface Flags extends SharedFlagsSettings { - _: string[]; + // Used by both core/ and cli/ port: number; - chromeFlags: string; + hostname: string; output: any; + logLevel: 'silent'|'error'|'info'|'verbose'; + + // Just used by cli/ + _: string[]; + chromeFlags: string; outputPath: string; saveAssets: boolean; view: boolean; - logLevel: string; - hostname: string; enableErrorReporting: boolean; listAllAudits: boolean; listTraceCategories: boolean; configPath?: string; preset?: 'full'|'mixed-content'|'perf'; - perf: boolean; - mixedContent: boolean; verbose: boolean; quiet: boolean; - extraHeaders?: string; }