Skip to content

Commit

Permalink
docs: add results object explainer
Browse files Browse the repository at this point in the history
  • Loading branch information
@patrickhulce
patrickhulce committed Oct 6, 2017
1 parent c71116b commit f058053
Show file tree
Hide file tree
Showing 2 changed files with 249 additions and 1 deletion.
246 changes: 246 additions & 0 deletions docs/understanding-results.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,246 @@
# 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.

## Top-level Object

The top-level object 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 timestamp at which 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. |
| [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. |
| category | `string` | No longer used. *WARNING: Deprecated, will be removed in Lighthouse 3.0* |
| description | `string` | The brief description of the audit's successful state. |
| failureDescription | `string` | The brief description of the audit's failure 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. |
| 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`. |
| 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. |
| scoringMode | `string` | 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 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* |

### 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 that comprise them.

### 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 that comprise the category. Each entry contains a copy of the audit's result in the top-level [audits](#audits) object. |

### 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). |

### 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.

### Example
```json
{
"Offline": 200,
"HTTPRedirect": {"value": true},
...
}
```
4 changes: 3 additions & 1 deletion readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,9 @@ yarn compile-devtools
## Lighthouse Integrations
This section details projects that have integrated Lighthouse. If you're working on a cool project integrating Lighthouse and would like to be featured here, file an issue to this repo or tweet at us [@_____lighthouse](https://twitter.com/____lighthouse?lang=en)

* **[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.
* **[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).

* **[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

0 comments on commit f058053

Please sign in to comment.