fix: update documentation on configuring puppeteer (#9150)

This PR updates the docs regarding configuring puppeteer. In addition, some changes have been made to the documentation generator to show default values on the documentation site. Also fixes: #9144
puppeteer · Oct 24, 2022 · f07ad2c · f07ad2c
1 parent 4bf338b
commit f07ad2c
Show file tree

Hide file tree

Showing 734 changed files with 2,228 additions and 1,629 deletions.
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 
 <img src="https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" height="200" align="right"/>
 
-#### [API](https://pptr.dev/api) | [FAQ](https://pptr.dev/faq) | [Contributing](https://pptr.dev/contributing) | [Troubleshooting](https://pptr.dev/troubleshooting)
+#### [Guides](https://pptr.dev/guides) | [API](https://pptr.dev/api) | [FAQ](https://pptr.dev/faq) | [Contributing](https://pptr.dev/contributing) | [Troubleshooting](https://pptr.dev/troubleshooting)
 
 > Puppeteer is a Node.js library which provides a high-level API to control
 > Chrome/Chromium over the
@@ -49,51 +49,32 @@ Chromium (~170MB macOS, ~282MB Linux, ~280MB Windows) that is
 with Puppeteer. For a version of Puppeteer without installation, see
 [`puppeteer-core`](#puppeteer-core).
 
-#### Environment Variables
-
-Puppeteer looks for certain
-[environment variables](https://en.wikipedia.org/wiki/Environment_variable) for
-customizing behavior. If Puppeteer doesn't find them in the environment during
-the installation step, a lowercased variant of these variables will be used from
-the [npm config](https://docs.npmjs.com/cli/config).
-
-- `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` - defines HTTP proxy settings that are
-  used to download and run the browser.
-- `PUPPETEER_CACHE_DIR` - defines the directory to be used by Puppeteer for
-  caching. Defaults to
-  [`os.homedir()/.cache/puppeteer`](https://nodejs.org/api/os.html#os_os_homedir).
-- `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` - do not download bundled Chromium during
-  installation step.
-- `PUPPETEER_TMP_DIR` - defines the directory to be used by Puppeteer for
-  creating temporary files. Defaults to
-  [`os.tmpdir()`](https://nodejs.org/api/os.html#os_os_tmpdir).
-- `PUPPETEER_DOWNLOAD_HOST` - specifies the URL prefix that is used to download
-  Chromium. Note: this includes protocol and might even include path prefix.
-  Defaults to `https://storage.googleapis.com`.
-- `PUPPETEER_DOWNLOAD_PATH` - specifies the path for the downloads folder.
-  Defaults to `<cache>/chromium`, where `<cache>` is Puppeteer's cache
-  directory.
-- `PUPPETEER_BROWSER_REVISION` - specifies a certain version of the browser
-  you'd like Puppeteer to use. See
-  [`puppeteer.launch`](https://pptr.dev/api/puppeteer.puppeteernode.launch) on
-  how executable path is inferred.
-- `PUPPETEER_EXECUTABLE_PATH` - specifies an executable path to be used in
-  [`puppeteer.launch`](https://pptr.dev/api/puppeteer.puppeteernode.launch).
-- `PUPPETEER_PRODUCT` - specifies which browser you'd like Puppeteer to use.
-  Must be either `chrome` or `firefox`. This can also be used during
-  installation to fetch the recommended browser binary. Setting `product`
-  programmatically in
-  [`puppeteer.launch`](https://pptr.dev/api/puppeteer.puppeteernode.launch)
-  supersedes this environment variable.
-- `PUPPETEER_EXPERIMENTAL_CHROMIUM_MAC_ARM` — specify Puppeteer download
-  Chromium for Apple M1. On Apple M1 devices Puppeteer by default downloads the
-  version for Intel's processor which runs via Rosetta. It works without any
-  problems, however, with this option, you should get more efficient resource
-  usage (CPU and RAM) that could lead to a faster execution time.
-
-Environment variables except for `PUPPETEER_CACHE_DIR` are not used for
-[`puppeteer-core`](#puppeteer-core) since core does not automatically handle
-browser downloading.
+#### Configuring Puppeteer
+
+Puppeteer uses several defaults that can be customized through configuration
+files.
+
+For example, to change the default cache directory Puppeteer uses to install
+browsers, you can add a `.puppeteerrc.cjs` (or `puppeteer.config.cjs`) at the
+root of your application with the contents
+
+```js
+const {join} = require('path');
+
+/**
+ * @type {import("puppeteer").Configuration}
+ */
+module.exports = {
+  // Changes the cache location for Puppeteer.
+  cacheDirectory: join(__dirname, '.cache', 'puppeteer'),
+};
+```
+
+After adding the configuration file, you will need to remove and reinstall
+`puppeteer` for it to take effect.
+
+See [Configuring
+Puppeteer](https://pptr.dev/guides/configuring-puppeteer) for more information.
 
 #### `puppeteer-core`
 
@@ -104,21 +85,21 @@ Every release since v1.7.0 we publish two packages:
 
 `puppeteer` is a _product_ for browser automation. When installed, it downloads
 a version of Chromium, which it then drives using `puppeteer-core`. Being an
-end-user product, `puppeteer` supports a bunch of convenient `PUPPETEER_*` env
-variables to tweak its behavior.
+end-user product, `puppeteer` automates several workflows using reasonable defaults [that can be customized](https://pptr.dev/guides/configuring-puppeteer).
 
 `puppeteer-core` is a _library_ to help drive anything that supports DevTools
-protocol. `puppeteer-core` doesn't download Chromium when installed. Being a
-library, `puppeteer-core` is fully driven through its programmatic interface.
-
-You should only use `puppeteer-core` if you are
-[connecting to a remote browser](https://pptr.dev/api/puppeteer.puppeteer.connect)
-or [managing browsers yourself](https://pptr.dev/api/puppeteer.browserfetcher).
-If you are managing browsers yourself, you will need to call
+protocol. Being a library, `puppeteer-core` is fully driven through its
+programmatic interface implying no defaults are assumed and `puppeteer-core`
+will not download Chromium when installed.
+
+You should use `puppeteer-core` if you are [connecting to a remote
+browser](https://pptr.dev/api/puppeteer.puppeteer.connect) or [managing browsers
+yourself](https://pptr.dev/api/puppeteer.browserfetcher). If you are managing
+browsers yourself, you will need to call
 [`puppeteer.launch`](https://pptr.dev/api/puppeteer.puppeteernode.launch) with
-an explicit
+an an explicit
 [`executablePath`](https://pptr.dev/api/puppeteer.launchoptions.executablepath)
-or [`channel`](https://pptr.dev/api/puppeteer.launchoptions.channel).
+(or [`channel`](https://pptr.dev/api/puppeteer.launchoptions.channel) if it's installed in a standard location).
 
 When using `puppeteer-core`, remember to change the import:
 

diff --git a/docs/api/index.md b/docs/api/index.md
@@ -73,7 +73,7 @@ sidebar_label: API
 | [CDPSessionOnMessageObject](./puppeteer.cdpsessiononmessageobject.md)       |                                                                                                                                                                                                     |
 | [ClickOptions](./puppeteer.clickoptions.md)                                 |                                                                                                                                                                                                     |
 | [CommonEventEmitter](./puppeteer.commoneventemitter.md)                     |                                                                                                                                                                                                     |
-| [Configuration](./puppeteer.configuration.md)                               |                                                                                                                                                                                                     |
+| [Configuration](./puppeteer.configuration.md)                               | <p>Defines options to configure Puppeteer's behavior during installation and runtime.</p><p>See individual properties for more information.</p>                                                     |
 | [ConnectionCallback](./puppeteer.connectioncallback.md)                     |                                                                                                                                                                                                     |
 | [ConnectionTransport](./puppeteer.connectiontransport.md)                   |                                                                                                                                                                                                     |
 | [ConnectOptions](./puppeteer.connectoptions.md)                             |                                                                                                                                                                                                     |
@@ -84,6 +84,7 @@ sidebar_label: API
 | [CSSCoverageOptions](./puppeteer.csscoverageoptions.md)                     | Set of configurable options for CSS coverage.                                                                                                                                                       |
 | [CustomQueryHandler](./puppeteer.customqueryhandler.md)                     |                                                                                                                                                                                                     |
 | [Device](./puppeteer.device.md)                                             |                                                                                                                                                                                                     |
+| [ExperimentsConfiguration](./puppeteer.experimentsconfiguration.md)         | <p>Defines experiment options for Puppeteer.</p><p>See individual properties for more information.</p>                                                                                              |
 | [FrameAddScriptTagOptions](./puppeteer.frameaddscripttagoptions.md)         |                                                                                                                                                                                                     |
 | [FrameAddStyleTagOptions](./puppeteer.frameaddstyletagoptions.md)           |                                                                                                                                                                                                     |
 | [FrameWaitForFunctionOptions](./puppeteer.framewaitforfunctionoptions.md)   |                                                                                                                                                                                                     |

diff --git a/docs/api/puppeteer.accessibility.md b/docs/api/puppeteer.accessibility.md
@@ -6,7 +6,7 @@ sidebar_label: Accessibility
 
 The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access).
 
-**Signature:**
+#### Signature:
 
 ```typescript
 export declare class Accessibility

diff --git a/docs/api/puppeteer.accessibility.snapshot.md b/docs/api/puppeteer.accessibility.snapshot.md
@@ -6,7 +6,7 @@ sidebar_label: Accessibility.snapshot
 
 Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page.
 
-**Signature:**
+#### Signature:
 
 ```typescript
 class Accessibility {

diff --git a/docs/api/puppeteer.actionresult.md b/docs/api/puppeteer.actionresult.md
@@ -4,7 +4,7 @@ sidebar_label: ActionResult
 
 # ActionResult type
 
-**Signature:**
+#### Signature:
 
 ```typescript
 export declare type ActionResult = 'continue' | 'abort' | 'respond';

diff --git a/docs/api/puppeteer.awaitable.md b/docs/api/puppeteer.awaitable.md
@@ -4,7 +4,7 @@ sidebar_label: Awaitable
 
 # Awaitable type
 
-**Signature:**
+#### Signature:
 
 ```typescript
 export declare type Awaitable<T> = T | PromiseLike<T>;

diff --git a/docs/api/puppeteer.boundingbox.height.md b/docs/api/puppeteer.boundingbox.height.md
@@ -6,7 +6,7 @@ sidebar_label: BoundingBox.height
 
 the height of the element in pixels.
 
-**Signature:**
+#### Signature:
 
 ```typescript
 interface BoundingBox {

diff --git a/docs/api/puppeteer.boundingbox.md b/docs/api/puppeteer.boundingbox.md
@@ -4,7 +4,7 @@ sidebar_label: BoundingBox
 
 # BoundingBox interface
 
-**Signature:**
+#### Signature:
 
 ```typescript
 export interface BoundingBox extends Point
@@ -14,7 +14,7 @@ export interface BoundingBox extends Point
 
 ## Properties
 
-| Property                                    | Modifiers | Type   | Description                          |
-| ------------------------------------------- | --------- | ------ | ------------------------------------ |
-| [height](./puppeteer.boundingbox.height.md) |           | number | the height of the element in pixels. |
-| [width](./puppeteer.boundingbox.width.md)   |           | number | the width of the element in pixels.  |
+| Property                                    | Modifiers | Type   | Description                          | Default |
+| ------------------------------------------- | --------- | ------ | ------------------------------------ | ------- |
+| [height](./puppeteer.boundingbox.height.md) |           | number | the height of the element in pixels. |         |
+| [width](./puppeteer.boundingbox.width.md)   |           | number | the width of the element in pixels.  |         |
diff --git a/docs/api/puppeteer.boundingbox.width.md b/docs/api/puppeteer.boundingbox.width.md
@@ -6,7 +6,7 @@ sidebar_label: BoundingBox.width
 
 the width of the element in pixels.
 
-**Signature:**
+#### Signature:
 
 ```typescript
 interface BoundingBox {

diff --git a/docs/api/puppeteer.boxmodel.border.md b/docs/api/puppeteer.boxmodel.border.md
@@ -4,7 +4,7 @@ sidebar_label: BoxModel.border
 
 # BoxModel.border property
 
-**Signature:**
+#### Signature:
 
 ```typescript
 interface BoxModel {

diff --git a/docs/api/puppeteer.boxmodel.content.md b/docs/api/puppeteer.boxmodel.content.md
@@ -4,7 +4,7 @@ sidebar_label: BoxModel.content
 
 # BoxModel.content property
 
-**Signature:**
+#### Signature:
 
 ```typescript
 interface BoxModel {

diff --git a/docs/api/puppeteer.boxmodel.height.md b/docs/api/puppeteer.boxmodel.height.md
@@ -4,7 +4,7 @@ sidebar_label: BoxModel.height
 
 # BoxModel.height property
 
-**Signature:**
+#### Signature:
 
 ```typescript
 interface BoxModel {

diff --git a/docs/api/puppeteer.boxmodel.margin.md b/docs/api/puppeteer.boxmodel.margin.md
@@ -4,7 +4,7 @@ sidebar_label: BoxModel.margin
 
 # BoxModel.margin property
 
-**Signature:**
+#### Signature:
 
 ```typescript
 interface BoxModel {

diff --git a/docs/api/puppeteer.boxmodel.md b/docs/api/puppeteer.boxmodel.md
@@ -4,19 +4,19 @@ sidebar_label: BoxModel
 
 # BoxModel interface
 
-**Signature:**
+#### Signature:
 
 ```typescript
 export interface BoxModel
 ```
 
 ## Properties
 
-| Property                                   | Modifiers | Type                              | Description |
-| ------------------------------------------ | --------- | --------------------------------- | ----------- |
-| [border](./puppeteer.boxmodel.border.md)   |           | [Point](./puppeteer.point.md)\[\] |             |
-| [content](./puppeteer.boxmodel.content.md) |           | [Point](./puppeteer.point.md)\[\] |             |
-| [height](./puppeteer.boxmodel.height.md)   |           | number                            |             |
-| [margin](./puppeteer.boxmodel.margin.md)   |           | [Point](./puppeteer.point.md)\[\] |             |
-| [padding](./puppeteer.boxmodel.padding.md) |           | [Point](./puppeteer.point.md)\[\] |             |
-| [width](./puppeteer.boxmodel.width.md)     |           | number                            |             |
+| Property                                   | Modifiers | Type                              | Description | Default |
+| ------------------------------------------ | --------- | --------------------------------- | ----------- | ------- |
+| [border](./puppeteer.boxmodel.border.md)   |           | [Point](./puppeteer.point.md)\[\] |             |         |
+| [content](./puppeteer.boxmodel.content.md) |           | [Point](./puppeteer.point.md)\[\] |             |         |
+| [height](./puppeteer.boxmodel.height.md)   |           | number                            |             |         |
+| [margin](./puppeteer.boxmodel.margin.md)   |           | [Point](./puppeteer.point.md)\[\] |             |         |
+| [padding](./puppeteer.boxmodel.padding.md) |           | [Point](./puppeteer.point.md)\[\] |             |         |
+| [width](./puppeteer.boxmodel.width.md)     |           | number                            |             |         |
diff --git a/docs/api/puppeteer.boxmodel.padding.md b/docs/api/puppeteer.boxmodel.padding.md
@@ -4,7 +4,7 @@ sidebar_label: BoxModel.padding
 
 # BoxModel.padding property
 
-**Signature:**
+#### Signature:
 
 ```typescript
 interface BoxModel {

diff --git a/docs/api/puppeteer.boxmodel.width.md b/docs/api/puppeteer.boxmodel.width.md
@@ -4,7 +4,7 @@ sidebar_label: BoxModel.width
 
 # BoxModel.width property
 
-**Signature:**
+#### Signature:
 
 ```typescript
 interface BoxModel {

diff --git a/docs/api/puppeteer.browser.browsercontexts.md b/docs/api/puppeteer.browser.browsercontexts.md
@@ -6,7 +6,7 @@ sidebar_label: Browser.browserContexts
 
 Returns an array of all open browser contexts. In a newly created browser, this will return a single instance of [BrowserContext](./puppeteer.browsercontext.md).
 
-**Signature:**
+#### Signature:
 
 ```typescript
 class Browser {

diff --git a/docs/api/puppeteer.browser.close.md b/docs/api/puppeteer.browser.close.md
@@ -6,7 +6,7 @@ sidebar_label: Browser.close
 
 Closes Chromium and all of its pages (if any were opened). The [Browser](./puppeteer.browser.md) object itself is considered to be disposed and cannot be used anymore.
 
-**Signature:**
+#### Signature:
 
 ```typescript
 class Browser {

diff --git a/docs/api/puppeteer.browser.createincognitobrowsercontext.md b/docs/api/puppeteer.browser.createincognitobrowsercontext.md
@@ -6,7 +6,7 @@ sidebar_label: Browser.createIncognitoBrowserContext
 
 Creates a new incognito browser context. This won't share cookies/cache with other browser contexts.
 
-**Signature:**
+#### Signature:
 
 ```typescript
 class Browser {

diff --git a/docs/api/puppeteer.browser.defaultbrowsercontext.md b/docs/api/puppeteer.browser.defaultbrowsercontext.md
@@ -6,7 +6,7 @@ sidebar_label: Browser.defaultBrowserContext
 
 Returns the default browser context. The default browser context cannot be closed.
 
-**Signature:**
+#### Signature:
 
 ```typescript
 class Browser {

diff --git a/docs/api/puppeteer.browser.disconnect.md b/docs/api/puppeteer.browser.disconnect.md
@@ -6,7 +6,7 @@ sidebar_label: Browser.disconnect
 
 Disconnects Puppeteer from the browser, but leaves the Chromium process running. After calling `disconnect`, the [Browser](./puppeteer.browser.md) object is considered disposed and cannot be used anymore.
 
-**Signature:**
+#### Signature:
 
 ```typescript
 class Browser {

diff --git a/docs/api/puppeteer.browser.isconnected.md b/docs/api/puppeteer.browser.isconnected.md
@@ -6,7 +6,7 @@ sidebar_label: Browser.isConnected
 
 Indicates that the browser is connected.
 
-**Signature:**
+#### Signature:
 
 ```typescript
 class Browser {

diff --git a/docs/api/puppeteer.browser.md b/docs/api/puppeteer.browser.md
@@ -6,7 +6,7 @@ sidebar_label: Browser
 
 A Browser is created when Puppeteer connects to a Chromium instance, either through [PuppeteerNode.launch()](./puppeteer.puppeteernode.launch.md) or [Puppeteer.connect()](./puppeteer.puppeteer.connect.md).
 
-**Signature:**
+#### Signature:
 
 ```typescript
 export declare class Browser extends EventEmitter

diff --git a/docs/api/puppeteer.browser.newpage.md b/docs/api/puppeteer.browser.newpage.md
@@ -6,7 +6,7 @@ sidebar_label: Browser.newPage
 
 Promise which resolves to a new [Page](./puppeteer.page.md) object. The Page is created in a default browser context.
 
-**Signature:**
+#### Signature:
 
 ```typescript
 class Browser {

diff --git a/docs/api/puppeteer.browser.pages.md b/docs/api/puppeteer.browser.pages.md
@@ -6,7 +6,7 @@ sidebar_label: Browser.pages
 
 An array of all open pages inside the Browser.
 
-**Signature:**
+#### Signature:
 
 ```typescript
 class Browser {

diff --git a/docs/api/puppeteer.browser.process.md b/docs/api/puppeteer.browser.process.md
@@ -6,7 +6,7 @@ sidebar_label: Browser.process
 
 The spawned browser process. Returns `null` if the browser instance was created with [Puppeteer.connect()](./puppeteer.puppeteer.connect.md).
 
-**Signature:**
+#### Signature:
 
 ```typescript
 class Browser {

diff --git a/docs/api/puppeteer.browser.target.md b/docs/api/puppeteer.browser.target.md
@@ -6,7 +6,7 @@ sidebar_label: Browser.target
 
 The target associated with the browser.
 
-**Signature:**
+#### Signature:
 
 ```typescript
 class Browser {