Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add results object explainer #3495

Merged
merged 4 commits into from
Oct 11, 2017
Merged

docs: add results object explainer #3495

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
603b2bc
docs: add results object explainer
patrickhulce Oct 6, 2017
f6caecf
feedback
patrickhulce Oct 9, 2017
77bafe4
feedback
patrickhulce Oct 11, 2017
1430cdc
add caveat for overall score
patrickhulce Oct 11, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
248 changes: 248 additions & 0 deletions docs/understanding-results.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,248 @@
# Understanding the Results

The results 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 results object. You might need to work directly with the results 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 Results Object (LHR)

The top-level Lighthouse Results 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.

### Properties

| Name | Description |
| - | - |
| lighthouseVersion | The version of Lighthouse with which these results were generated. |
| generatedTime | The ISO-8601 timestamp of when the results were generated. |
| userAgent | The user agent string of the version of Chrome that was used by Lighthouse. |
| initialUrl | The URL that was supplied to Lighthouse and initially navigated to. |
| url | The URL that Lighthouse ended up auditing after redirects were followed. |
| score | The overall score `0-100`, a weighted average of all category scores. *NOTE: Only the PWA category has a weight by default* |
| [audits](#audits) | An object containing the results of the audits. |
| [runtimeConfig](#runtime-config) | 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. |

### Example
```json
{
"lighthouseVersion": "2.4.0",
"generatedTime": "2017-10-05T20:50:54.185Z",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3233.0 Safari/537.36",
"initialUrl": "http://example.com",
"url": "https://www.example.com/",
"score": 50,
"audits": {...},
"runtimeConfig": {...},
"timing": {...},
"reportCategories": [{...}],
"reportGroups": {...},
}
```


<a name="audits"></a>
## `audits`

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's successful state. |
| 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 | <code>string&#124;undefined</code> | A string indicating some additional information to the user explaining an unusual circumstance or reason for failure. |
| rawValue | <code>boolean&#124;number</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 | `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 | <code>boolean&#124;number</code> | The scored value determined by the audit as either boolean or a number `0-100`. If the audit is a boolean, the implication is `score ? 100 : 0`. |
| scoringMode | <code>"binary"&#124;"numeric"</code> | A string identifying how granular the score is meant to be indicating, i.e. is the audit pass/fail or are there shades of gray 0-100. *NOTE: This does not necessarily mean `typeof audit.score === audit.scoringMode`, an audit can have a score of 40 with a scoringMode of `"binary"` meant to indicate display should be failure.* |
| 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. |
| category | `string` | No longer used. *WARNING: Deprecated, will be removed in Lighthouse 3.0* |

### 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": false,
"rawValue": false,
"displayValue": "2 insecure requests found",
"scoringMode": "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"
}
]
},
},
"custom-audit": {
"name": "custom-audit",
...
}
}
```


<a name="runtime-config"></a>
## `runtimeConfig`

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"
}
]
}
```

<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="report-categories"></a>
## `reportCategories`

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. |
| name | `string` | The human-friendly 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. |

### AuditEntry Properties
| Name | Type | Description |
| -- | -- | -- |
| id | `string` | The string identifier of the category. |
| score | `number` | The numeric score `0-100` of the audit. Audits with a boolean score result are converted with `score ? 100 : 0`. |
| 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.* |

### Example
```json
[
{
"id": "pwa",
"name": "Progressive Web App",
"description": "PWAs are awesome. [Learn more](...)",
"score": 54,
"weight": 1,
"audits": [
{
"id": "is-on-https",
"score": 0,
"weight": 1,
"result": {
"name": "is-on-https",
"score": false,
...
}
}
]
}
]
```

<a name="report-groups"></a>
## `reportGroups`

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
{
"perf-metric": {
"title": "Metrics",
"description": "These metrics are super cool."
},
}
```

<a name="artifacts"></a>
## `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},
...
}
```
2 changes: 2 additions & 0 deletions readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,6 +235,8 @@ This section details projects that have integrated Lighthouse. If you're working

* **[Calibre](https://calibreapp.com)** - Calibre is a web performance monitoring tool running Lighthouse continuously or on-demand via an API. Test using emulated devices and connection speeds from a number of geographical locations. Set budgets and improve performance with actionable guidelines. Note that Calibre is a paid product with a free 14-day trial.

* **[HTTPArchive](http://httparchive.org/)** - HTTPArchive tracks how the web is built by crawling 500k pages with Web Page Test, including Lighthouse results, and stores the information in BigQuery where it is [publicly available](https://discuss.httparchive.org/t/quickstart-guide-to-exploring-the-http-archive/682).

* **[Treo](https://treo.sh)** - Treo is Lighthouse as a Service. It provides regression testing, geographical regions, custom networks, and integrations with Github & Slack. Treo is a paid product with plans for solo-developers and teams.

* **[Web Page Test](https://www.webpagetest.org)** — An [open source](https://github.com/WPO-Foundation/webpagetest) tool for measuring and analyzing the performance of web pages on real devices. Users can choose to produce a Lighthouse report alongside the analysis of WebPageTest results.
Expand Down