docs(config): add config documentation #2592

patrickhulce · 2017-06-23T23:25:18Z

ebidel

Woot!

ebidel · 2017-06-23T23:34:39Z

docs/configuration.md

+
+**Node**
+```js
+const lighthouse = require('lighthouse')


ebidel · 2017-06-23T23:34:53Z

docs/configuration.md

+
+## Usage
+
+You can specify a custom config file when using lighthouse through the CLi or consuming the npm module yourself.


lighthouse -> Lighthouse
CLi -> CLI

ebidel · 2017-06-23T23:36:12Z

docs/configuration.md

@@ -0,0 +1,198 @@
+# Lighthouse Configuration
+
+The Lighthouse config object is the primary method of customizing a Lighthouse run to suit your use case. Using a custom config, you can limit the audits to run, add additional loads of the page under special conditions, add your own custom checks, tweak the scoring, and more.


customizing a Lighthouse run -> customizing Lighthouse

ebidel · 2017-06-23T23:36:35Z

docs/configuration.md

+  ]
+}
+
+lighthouse('http://example.com/', {port: 9222}, config)


http -> https

ebidel · 2017-06-23T23:38:04Z

docs/configuration.md

+```js
+const lighthouse = require('lighthouse')
+
+const config = {


instead of defining this inline, what about creating custom-config.js and telling users to read it in. At the very least, make the connect that this is the CLI example's custom-config.js above.

ebidel · 2017-06-24T02:10:34Z

docs/configuration.md

+#### Schema
+| Name | Type | Description |
+| -- | -- | -- |
+| onlyCategories | `string[]` | Limits the run to just what's required for the specified categories. Additive with `onlyAudits`. |


WDYT about simplifying a bit?

Includes only the specified categories in the final report. Additive with onlyAudits.
Includes only specified audits in the final report. Additive with onlyCategories.

yeah I was trying to go for something that conveyed the run will be short because passes/audits/gatherers will be filtered not just we don't put the results into the report, but this isn't super fluid, fine with yours if we don't really care about conveying that here

Ah cool. You could add that note to each. Like:

"Includes only the specified categories in the final report. Additive with onlyAudits and reduces the time to audit a page."

ebidel · 2017-06-24T02:24:08Z

docs/configuration.md

+
+The passes property controls how to load the requested URL and what information to gather about the page while loading. Each entry in the passes array represents one load of the page (e.g. 4 entries in `passes` will load the page 4 times), so be judicious about adding multiple entries here to avoid extending run times.
+
+Along with the basic settings on how long to wait for the page to load and whether to record a trace file you'll find a list of **gatherers** to use. 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/).


lighthouse -> Lighthouse

link to https://github.com/GoogleChrome/lighthouse/tree/master/docs/recipes/custom-audit

ebidel · 2017-06-24T02:28:16Z

docs/configuration.md

+#### Schema
+| Name | Type | Description |
+| -- | -- | -- |
+| passName | `string` | An identifier for the pass used in audits and during config extension. |


A unique identifier

ebidel · 2017-06-24T02:31:34Z

docs/configuration.md

+| recordTrace | `boolean` | Records a [trace](https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#understanding-a-trace) of the pass when enabled. |
+| useThrottling | `boolean` | Enables throttling of the pass when enabled. |
+| pauseAfterLoadMs | `number` | The number of milliseconds to wait after the load event before the pass can continue. |
+| networkQuietThresholdMs | `number` | The number of milliseconds since the last network request to wait before the page should be considered to have reached 'network quiet'. |


Maybe add a sentence to some of these non-obvious ones, when/why you'd use it.

good call, done

ebidel · 2017-06-24T02:34:30Z

docs/configuration.md

@@ -0,0 +1,198 @@
+# Lighthouse Configuration
+
+The Lighthouse config object is the primary method of customizing a Lighthouse run to suit your use case. Using a custom config, you can limit the audits to run, add additional loads of the page under special conditions, add your own custom checks, tweak the scoring, and more.


Lots of terminology in here. Throw in a link to https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md.

paulirish

this is awesome. I have a few suggestions on text to add in. wdyt?

paulirish · 2017-06-26T19:21:32Z

docs/configuration.md

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


how about adding a reminder about the optionality:

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.

ya good call done

paulirish · 2017-06-26T19:22:16Z

docs/configuration.md

+* [lighthouse-core/config/default.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/default.js)
+* [lighthouse-core/config/perf.json](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/perf.json)
+* [lighthouse-core/config/plots-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/plots-config.js)
+* [docs/recipes/custom-audit/custom-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/docs/recipes/custom-audit/custom-config.js)


fwiw this is another: https://github.com/paulirish/pwmetrics/blob/master/lib/lh-config.ts

but its nearly identical to the plots config.

paulirish · 2017-06-26T19:24:28Z

docs/configuration.md

+
+The groups property controls how to visually group audits within a category. For example, this is what enables the grouped rendering of metrics and accessibility audits in the report.
+
+**Note: logic to display audit groups is required in the report renderer. Adding arbitrary groups without additional rendering logic may not perform as expected.**


The report-renderer has display logic that's hardcoded to specific audit group names. Adding arbitrary groups without the accompanying rendering logic may not perform as expected.

paulirish · 2017-06-26T19:25:00Z

docs/configuration.md

+| recordTrace | `boolean` | Records a [trace](https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#understanding-a-trace) of the pass when enabled. |
+| useThrottling | `boolean` | Enables throttling of the pass when enabled. |
+| pauseAfterLoadMs | `number` | The number of milliseconds to wait after the load event before the pass can continue. Used to ensure the page has had time for post-load JavaScript to execute before ending a trace. |
+| networkQuietThresholdMs | `number` | The number of milliseconds since the last network request to wait before the page should be considered to have reached 'network quiet'. Used to ensure the page has had time for the full waterfall of network requests to complete before ending a trace. |


(Default: 5000)

paulirish · 2017-06-26T19:25:12Z

docs/configuration.md

+| useThrottling | `boolean` | Enables throttling of the pass when enabled. |
+| pauseAfterLoadMs | `number` | The number of milliseconds to wait after the load event before the pass can continue. Used to ensure the page has had time for post-load JavaScript to execute before ending a trace. |
+| networkQuietThresholdMs | `number` | The number of milliseconds since the last network request to wait before the page should be considered to have reached 'network quiet'. Used to ensure the page has had time for the full waterfall of network requests to complete before ending a trace. |
+| pauseAfterNetworkQuietMs | `number` | The number of milliseconds to wait after 'network quiet' before the pass can continue. Used to ensure the page has had time for post-network-quiet JavaScript to execute before ending a trace. |


(Default: 0)

paulirish · 2017-06-26T19:25:24Z

docs/configuration.md

+| passName | `string` | A unique identifier for the pass used in audits and during config extension. |
+| recordTrace | `boolean` | Records a [trace](https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#understanding-a-trace) of the pass when enabled. |
+| useThrottling | `boolean` | Enables throttling of the pass when enabled. |
+| pauseAfterLoadMs | `number` | The number of milliseconds to wait after the load event before the pass can continue. Used to ensure the page has had time for post-load JavaScript to execute before ending a trace. |


(Default: 0)

paulirish · 2017-06-26T19:27:51Z

docs/configuration.md

+
+The passes property controls how to load the requested URL and what information to gather about the page while loading. Each entry in the passes array represents one load of the page (e.g. 4 entries in `passes` will load the page 4 times), so be judicious about adding multiple entries here to avoid extending run times.
+
+Along with the basic settings on how long to wait for the page to load and whether to record a trace file you'll find a list of **gatherers** to use. 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).


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 the gatherers are defined. Gatherers can read information...

Also note: artifacts.devtoolsLogs will be automatically populated for every pass. Gathers also have access to this data within afterPass as traceData.devtoolsLog. (Most will find the higher-level traceData.networkRecords more useful, however.)

paulirish · 2017-06-26T19:36:39Z

docs/configuration.md

+| Name | Type | Description |
+| -- | -- | -- |
+| passName | `string` | A unique identifier for the pass used in audits and during config extension. |
+| recordTrace | `boolean` | Records a [trace](https://github.com/GoogleChrome/lighthouse/blob/master/docs/architecture.md#understanding-a-trace) of the pass when enabled. |


Available to gatherers during afterPass as traceData.trace, and to audits in artifacts.traces.

paulirish

lgtm!

brendankenny

Looks great.

Would it be dumb to also put all the extends: string|boolean|undefined, settings: Object|undefined all in one block so you can see all the options in one screen?

It feels like it would be helpful to have an overview, but it might just end up crowded since every Object would also need to be expanded in place to all the options inside them.

patrickhulce · 2017-06-27T01:34:53Z

Would it be dumb to also put all the extends: string|boolean|undefined, settings: Object|undefined all in one block so you can see all the options in one screen?

I like it I'll add the overview, just not dive into the nested properties

patrickhulce added 2 commits June 23, 2017 16:24

docs(config): add config documentation

afba9d7

fix broken table

2ad70ae

ebidel suggested changes Jun 24, 2017

View reviewed changes

feedback

bb6d509

ebidel approved these changes Jun 26, 2017

View reviewed changes

paulirish requested changes Jun 26, 2017

View reviewed changes

more feedback

08b04ea

paulirish approved these changes Jun 26, 2017

View reviewed changes

brendankenny approved these changes Jun 26, 2017

View reviewed changes

add overview

178c7fa

patrickhulce merged commit 9f8543d into master Jun 27, 2017

patrickhulce deleted the config_documentation branch June 27, 2017 01:45

ryan-ally mentioned this pull request Mar 29, 2024

[Snyk] Security upgrade gulp from 3.9.1 to 5.0.0 ryan-ally/lighthouse#59

Open

MaxMood96 mentioned this pull request Mar 30, 2024

[Snyk] Security upgrade gulp from 3.9.1 to 5.0.0 MaxMood96/lighthouse#118

Open


		## Usage

		You can specify a custom config file when using lighthouse through the CLi or consuming the npm module yourself.

		@@ -0,0 +1,198 @@
		# Lighthouse Configuration

		The Lighthouse config object is the primary method of customizing a Lighthouse run to suit your use case. Using a custom config, you can limit the audits to run, add additional loads of the page under special conditions, add your own custom checks, tweak the scoring, and more.


		The passes property controls how to load the requested URL and what information to gather about the page while loading. Each entry in the passes array represents one load of the page (e.g. 4 entries in `passes` will load the page 4 times), so be judicious about adding multiple entries here to avoid extending run times.

		Along with the basic settings on how long to wait for the page to load and whether to record a trace file you'll find a list of gatherers to use. 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/).


		### `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 groups property controls how to visually group audits within a category. For example, this is what enables the grouped rendering of metrics and accessibility audits in the report.

		Note: logic to display audit groups is required in the report renderer. Adding arbitrary groups without additional rendering logic may not perform as expected.

docs(config): add config documentation #2592

docs(config): add config documentation #2592

Conversation

patrickhulce commented Jun 23, 2017

ebidel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paulirish left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paulirish left a comment

Choose a reason for hiding this comment

brendankenny left a comment

Choose a reason for hiding this comment

patrickhulce commented Jun 27, 2017