diff --git a/docs/api/index.md b/docs/api/index.md
index aa62b2a7688..409fecfe82c 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -23,6 +23,16 @@ Description
The Accessibility class provides methods for inspecting the browser'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).
+**Remarks:**
+
+Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might have wildly different output.
+
+Blink - Chrome's rendering engine - has a concept of "accessibility tree", which is then translated into different platform-specific APIs. Accessibility namespace gives users access to the Blink Accessibility Tree.
+
+Most of the accessibility tree gets filtered out when converting from Blink AX Tree to Platform-specific AX-Tree or by assistive technologies themselves. By default, Puppeteer tries to approximate this filtering, exposing only the "interesting" nodes of the tree.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Accessibility` class.
+
@@ -36,6 +46,10 @@ The Accessibility class provides methods for inspecting the browser's accessibil
[Browser](./puppeteer.browser.md) [emits](./puppeteer.eventemitter.emit.md) various events which are documented in the [BrowserEvent](./puppeteer.browserevent.md) enum.
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Browser` class.
+
@@ -51,6 +65,10 @@ When a [browser](./puppeteer.browser.md) is launched, it has a single [browser c
If a [page](./puppeteer.page.md) opens another [page](./puppeteer.page.md), e.g. using `window.open`, the popup will belong to the parent [page's browser context](./puppeteer.page.browsercontext.md).
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `BrowserContext` class.
+
@@ -60,6 +78,14 @@ If a [page](./puppeteer.page.md) opens another [page](./puppeteer.page.md), e.g.
The `CDPSession` instances are used to talk raw Chrome Devtools Protocol.
+**Remarks:**
+
+Protocol methods can be called with [CDPSession.send()](./puppeteer.cdpsession.send.md) method and protocol events can be subscribed to with `CDPSession.on` method.
+
+Useful links: [DevTools Protocol Viewer](https://chromedevtools.github.io/devtools-protocol/) and [Getting Started with DevTools Protocol](https://github.com/aslushnikov/getting-started-with-cdp/blob/HEAD/README.md).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `CDPSession` class.
+
@@ -85,6 +111,10 @@ ConsoleMessage objects are dispatched by page via the 'console' event.
The Coverage class provides methods to gather information about parts of JavaScript and CSS that were used by the page.
+**Remarks:**
+
+To output coverage in a form consumable by [Istanbul](https://github.com/istanbuljs), see [puppeteer-to-istanbul](https://github.com/istanbuljs/puppeteer-to-istanbul).
+
@@ -101,6 +131,12 @@ The Coverage class provides methods to gather information about parts of JavaScr
Device request prompts let you respond to the page requesting for a device through an API like WebBluetooth.
+**Remarks:**
+
+`DeviceRequestPrompt` instances are returned via the [Page.waitForDevicePrompt()](./puppeteer.page.waitfordeviceprompt.md) method.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `DeviceRequestPrompt` class.
+
@@ -110,6 +146,10 @@ Device request prompts let you respond to the page requesting for a device throu
Device in a request prompt.
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `DeviceRequestPromptDevice` class.
+
@@ -119,6 +159,10 @@ Device in a request prompt.
Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the `dialog` event.
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Dialog` class.
+
@@ -128,6 +172,31 @@ Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the `dial
ElementHandle represents an in-page DOM element.
+**Remarks:**
+
+ElementHandles can be created with the [Page.$()](./puppeteer.page._.md) method.
+
+```ts
+import puppeteer from 'puppeteer';
+
+(async () => {
+ const browser = await puppeteer.launch();
+ const page = await browser.newPage();
+ await page.goto('https://example.com');
+ const hrefElement = await page.$('a');
+ await hrefElement.click();
+ // ...
+})();
+```
+
+ElementHandle prevents the DOM element from being garbage-collected unless the handle is [disposed](./puppeteer.jshandle.dispose.md). ElementHandles are auto-disposed when their origin frame gets navigated.
+
+ElementHandle instances can be used as arguments in [Page.$eval()](./puppeteer.page._eval.md) and [Page.evaluate()](./puppeteer.page.evaluate.md) methods.
+
+If you're using TypeScript, ElementHandle takes a generic argument that denotes the type of element the handle is holding within. For example, if you have a handle to a `
@@ -137,6 +206,12 @@ ElementHandle represents an in-page DOM element.
The EventEmitter class that many Puppeteer classes extend.
+**Remarks:**
+
+This allows you to listen to events that Puppeteer classes fire and act accordingly. Therefore you'll mostly use [on](./puppeteer.eventemitter.on.md) and [off](./puppeteer.eventemitter.off.md) to bind and unbind to event listeners.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `EventEmitter` class.
+
@@ -146,6 +221,14 @@ The EventEmitter class that many Puppeteer classes extend.
File choosers let you react to the page requesting for a file.
+**Remarks:**
+
+`FileChooser` instances are returned via the [Page.waitForFileChooser()](./puppeteer.page.waitforfilechooser.md) method.
+
+In browsers, only one file chooser can be opened at a time. All file choosers must be accepted or canceled. Not doing so will prevent subsequent file choosers from appearing.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `FileChooser` class.
+
@@ -157,6 +240,14 @@ Represents a DOM frame.
To understand frames, you can think of frames as `
@@ -166,6 +257,26 @@ To understand frames, you can think of frames as `
@@ -175,6 +286,10 @@ Represents an HTTP request sent by a page.
The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class.
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `HTTPResponse` class.
+
@@ -195,6 +310,10 @@ Handles prevent the referenced JavaScript object from being garbage-collected un
Handles can be used as arguments for any evaluation function such as [Page.$eval()](./puppeteer.page._eval.md), [Page.evaluate()](./puppeteer.page.evaluate.md), and [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md). They are resolved to their referenced object.
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `JSHandle` class.
+
@@ -204,6 +323,14 @@ Handles can be used as arguments for any evaluation function such as [Page.$eval
Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
+**Remarks:**
+
+For finer control, you can use [Keyboard.down()](./puppeteer.keyboard.down.md), [Keyboard.up()](./puppeteer.keyboard.up.md), and [Keyboard.sendCharacter()](./puppeteer.keyboard.sendcharacter.md) to manually fire events as if they were generated from a real keyboard.
+
+On macOS, keyboard shortcuts like `⌘ A` -> Select All do not work. See [\#1313](https://github.com/puppeteer/puppeteer/issues/1313).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Keyboard` class.
+
@@ -222,6 +349,12 @@ Locators describe a strategy of locating objects and performing an action on the
The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.
+**Remarks:**
+
+Every `page` object has its own Mouse, accessible with \[`page.mouse`\](\#pagemouse).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Mouse` class.
+
@@ -237,6 +370,10 @@ One Browser instance might have multiple Page instances.
:::
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Page` class.
+
@@ -246,6 +383,10 @@ One Browser instance might have multiple Page instances.
Describes a launcher - a class that is able to create and launch a browser instance.
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ProductLauncher` class.
+
@@ -266,6 +407,10 @@ The main Puppeteer class.
IMPORTANT: if you are using Puppeteer in a Node environment, you will get an instance of [PuppeteerNode](./puppeteer.puppeteernode.md) when you import or require `puppeteer`. That class extends `Puppeteer`, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Puppeteer` class.
+
@@ -275,6 +420,10 @@ IMPORTANT: if you are using Puppeteer in a Node environment, you will get an ins
The base class for all Puppeteer-specific errors
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `PuppeteerError` class.
+
@@ -286,6 +435,14 @@ Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific
If you're using Puppeteer in a Node environment, this is the class you'll get when you run `require('puppeteer')` (or the equivalent ES `import`).
+**Remarks:**
+
+The most common method to use is [launch](./puppeteer.puppeteernode.launch.md), which is used to launch and connect to a new browser instance.
+
+See [the main Puppeteer class](./puppeteer.puppeteer.md) for methods common to all environments, such as [Puppeteer.connect()](./puppeteer.puppeteer.connect.md).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `PuppeteerNode` class.
+
@@ -293,6 +450,10 @@ If you're using Puppeteer in a Node environment, this is the class you'll get wh
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ScreenRecorder` class.
+
@@ -302,6 +463,10 @@ If you're using Puppeteer in a Node environment, this is the class you'll get wh
The SecurityDetails class represents the security details of a response that was received over a secure connection.
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `SecurityDetails` class.
+
@@ -311,6 +476,10 @@ The SecurityDetails class represents the security details of a response that was
Target represents a [CDP target](https://chromedevtools.github.io/devtools-protocol/tot/Target/). In CDP a target is something that can be debugged such a frame, a page or a worker.
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Target` class.
+
@@ -320,6 +489,10 @@ Target represents a [CDP target](https://chromedevtools.github.io/devtools-proto
TimeoutError is emitted whenever certain operations are terminated due to timeout.
+**Remarks:**
+
+Example operations are [page.waitForSelector](./puppeteer.page.waitforselector.md) or [puppeteer.launch](./puppeteer.puppeteernode.launch.md).
+
@@ -329,6 +502,10 @@ TimeoutError is emitted whenever certain operations are terminated due to timeou
The Touchscreen class exposes touchscreen events.
+**Remarks:**
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Touchscreen` class.
+
@@ -338,6 +515,12 @@ The Touchscreen class exposes touchscreen events.
The Tracing class exposes the tracing audit interface.
+**Remarks:**
+
+You can use `tracing.start` and `tracing.stop` to create a trace file which can be opened in Chrome DevTools or [timeline viewer](https://chromedevtools.github.io/timeline-viewer/).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Tracing` class.
+
@@ -356,6 +539,12 @@ Puppeteer will throw this error if a method is not supported by the currently us
This class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
+**Remarks:**
+
+The events `workercreated` and `workerdestroyed` are emitted on the page object to signal the worker lifecycle.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `WebWorker` class.
+
@@ -713,6 +902,8 @@ Set of configurable options for CSS coverage.
+**_(Experimental)_**
+
@@ -986,6 +1177,8 @@ Required response data to fulfill a request with.
+**_(Experimental)_**
+
@@ -1389,6 +1582,32 @@ All the valid keys that can be passed to functions that take user input, such as
All the valid paper format types when printing a PDF.
+**Remarks:**
+
+The sizes of each format are as follows:
+
+- `Letter`: 8.5in x 11in
+
+- `Legal`: 8.5in x 14in
+
+- `Tabloid`: 11in x 17in
+
+- `Ledger`: 17in x 11in
+
+- `A0`: 33.1in x 46.8in
+
+- `A1`: 23.4in x 33.1in
+
+- `A2`: 16.54in x 23.4in
+
+- `A3`: 11.7in x 16.54in
+
+- `A4`: 8.27in x 11.7in
+
+- `A5`: 5.83in x 8.27in
+
+- `A6`: 4.13in x 5.83in
+
diff --git a/docs/api/puppeteer.accessibility.md b/docs/api/puppeteer.accessibility.md
index 56c90430517..dd4e5fafc86 100644
--- a/docs/api/puppeteer.accessibility.md
+++ b/docs/api/puppeteer.accessibility.md
@@ -47,5 +47,9 @@ Description
Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page.
+**Remarks:**
+
+**NOTE** The Chrome accessibility tree contains nodes that go unused on most platforms and by most screen readers. Puppeteer will discard them as well for an easier to process tree, unless `interestingOnly` is set to `false`.
+
diff --git a/docs/api/puppeteer.browser.md b/docs/api/puppeteer.browser.md
index c1d9297b80e..c36b0c55d0d 100644
--- a/docs/api/puppeteer.browser.md
+++ b/docs/api/puppeteer.browser.md
@@ -104,7 +104,11 @@ Whether Puppeteer is connected to this [browser](./puppeteer.browser.md).
-Get debug information from Puppeteer.
+**_(Experimental)_** Get debug information from Puppeteer.
+
+**Remarks:**
+
+Currently, includes pending protocol calls. In the future, we might add more info.
@@ -171,6 +175,10 @@ This won't share cookies/cache with other [browser contexts](./puppeteer.browser
Gets the default [browser context](./puppeteer.browsercontext.md).
+**Remarks:**
+
+The default [browser context](./puppeteer.browsercontext.md) cannot be closed.
+
@@ -223,6 +231,10 @@ Gets a list of all open [pages](./puppeteer.page.md) inside this [Browser](./pup
If there ar multiple [browser contexts](./puppeteer.browsercontext.md), this returns all [pages](./puppeteer.page.md) in all [browser contexts](./puppeteer.browsercontext.md).
+**Remarks:**
+
+Non-visible [pages](./puppeteer.page.md), such as `"background_page"`, will not be listed here. You can find them using [Target.page()](./puppeteer.target.page.md).
+
@@ -316,5 +328,9 @@ You can find the debugger URL (`webSocketDebuggerUrl`) from `http://HOST:PORT/js
See [browser endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target) for more information.
+**Remarks:**
+
+The format is always `ws://HOST:PORT/devtools/browser/`.
+
diff --git a/docs/api/puppeteer.browsercontext.md b/docs/api/puppeteer.browsercontext.md
index 888b2d4fb0c..536a677a371 100644
--- a/docs/api/puppeteer.browsercontext.md
+++ b/docs/api/puppeteer.browsercontext.md
@@ -141,6 +141,10 @@ Clears all permission overrides for this [browser context](./puppeteer.browserco
Closes this [browser context](./puppeteer.browsercontext.md) and all associated [pages](./puppeteer.page.md).
+**Remarks:**
+
+The [default browser context](./puppeteer.browser.defaultbrowsercontext.md) cannot be closed.
+
@@ -193,6 +197,10 @@ Grants this [browser context](./puppeteer.browsercontext.md) the given `permissi
Gets a list of all open [pages](./puppeteer.page.md) inside this [browser context](./puppeteer.browsercontext.md).
+**Remarks:**
+
+Non-visible [pages](./puppeteer.page.md), such as `"background_page"`, will not be listed here. You can find them using [Target.page()](./puppeteer.target.page.md).
+
diff --git a/docs/api/puppeteer.browserevent.md b/docs/api/puppeteer.browserevent.md
index b47ddad638a..79e7073fbb2 100644
--- a/docs/api/puppeteer.browserevent.md
+++ b/docs/api/puppeteer.browserevent.md
@@ -54,6 +54,10 @@ TargetChanged
Emitted when the URL of a target changes. Contains a [Target](./puppeteer.target.md) instance.
+**Remarks:**
+
+Note that this includes target changes in all browser contexts.
+
@@ -69,6 +73,10 @@ Emitted when a target is created, for example when a new page is opened by [wind
Contains a [Target](./puppeteer.target.md) instance.
+**Remarks:**
+
+Note that this includes target creations in all browser contexts.
+
@@ -82,5 +90,9 @@ TargetDestroyed
Emitted when a target is destroyed, for example when a page is closed. Contains a [Target](./puppeteer.target.md) instance.
+**Remarks:**
+
+Note that this includes target destructions in all browser contexts.
+
diff --git a/docs/api/puppeteer.browserlaunchargumentoptions.md b/docs/api/puppeteer.browserlaunchargumentoptions.md
index a031502ce32..7b05b200657 100644
--- a/docs/api/puppeteer.browserlaunchargumentoptions.md
+++ b/docs/api/puppeteer.browserlaunchargumentoptions.md
@@ -110,6 +110,12 @@ boolean \| 'shell'
Whether to run the browser in headless mode.
+**Remarks:**
+
+- `true` launches the browser in the [new headless](https://developer.chrome.com/articles/new-headless/) mode.
+
+- `'shell'` launches [shell](https://developer.chrome.com/blog/chrome-headless-shell) known as the old headless mode.
+
`true`
diff --git a/docs/api/puppeteer.configuration.md b/docs/api/puppeteer.configuration.md
index 674490e8b93..674b1621936 100644
--- a/docs/api/puppeteer.configuration.md
+++ b/docs/api/puppeteer.configuration.md
@@ -128,6 +128,10 @@ Specifies the URL prefix that is used to download the browser.
Can be overridden by `PUPPETEER_DOWNLOAD_BASE_URL`.
+**Remarks:**
+
+This must include the protocol and may even need a path prefix.
+
Either https://storage.googleapis.com/chrome-for-testing-public or https://archive.mozilla.org/pub/firefox/nightly/latest-mozilla-central, depending on the product.
diff --git a/docs/api/puppeteer.connectoptions.md b/docs/api/puppeteer.connectoptions.md
index 94bf97d92f4..5cea7e290fb 100644
--- a/docs/api/puppeteer.connectoptions.md
+++ b/docs/api/puppeteer.connectoptions.md
@@ -85,6 +85,10 @@ Record<string, string>
Headers to use for the web socket connection.
+**Remarks:**
+
+Only works in the Node.js environment.
+
+**Remarks:**
+
+Anonymous scripts are ones that don't have an associated url. These are scripts that are dynamically created on the page using `eval` or `new Function`. If `reportAnonymousScripts` is set to `true`, anonymous scripts URL will start with `debugger://VM` (unless a magic //\# sourceURL comment is present, in which case that will the be URL).
+
@@ -114,6 +118,10 @@ Description
Promise that resolves to the array of coverage reports for all stylesheets.
+**Remarks:**
+
+CSS Coverage doesn't include dynamically injected style tags without sourceURLs.
+
@@ -125,5 +133,9 @@ Promise that resolves to the array of coverage reports for all stylesheets.
Promise that resolves to the array of coverage reports for all scripts.
+**Remarks:**
+
+JavaScript Coverage doesn't include anonymous scripts by default. However, scripts with sourceURLs are reported.
+
diff --git a/docs/api/puppeteer.elementhandle.md b/docs/api/puppeteer.elementhandle.md
index 6a733a438a6..a3a7f6f5d7a 100644
--- a/docs/api/puppeteer.elementhandle.md
+++ b/docs/api/puppeteer.elementhandle.md
@@ -150,6 +150,25 @@ If the given function returns a promise, then this method will wait till the pro
If the element is a form input, you can use [ElementHandle.autofill()](./puppeteer.elementhandle.autofill.md) to test if the form is compatible with the browser's autofill implementation. Throws an error if the form cannot be autofilled.
+**Remarks:**
+
+Currently, Puppeteer supports auto-filling credit card information only and in Chrome in the new headless and headful modes only.
+
+```ts
+// Select an input on the credit card form.
+const name = await page.waitForSelector('form #name');
+// Trigger autofill with the desired data.
+await name.autofill({
+ creditCard: {
+ number: '4444444444444444',
+ name: 'John Smith',
+ expiryMonth: '01',
+ expiryYear: '2030',
+ cvc: '123',
+ },
+});
+```
+
@@ -172,6 +191,10 @@ This method returns the bounding box of the element (relative to the main frame)
This method returns boxes of the element, or `null` if the element is [not part of the layout](https://drafts.csswg.org/css-display-4/#box-generation) (example: `display: none`).
+**Remarks:**
+
+Boxes are represented as an array of points; Each Point is an object `{x, y}`. Box points are sorted clock-wise.
+
@@ -362,6 +385,12 @@ Checks if an element is visible using the same mechanism as [ElementHandle.waitF
Focuses the element, and then uses [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md).
+**Remarks:**
+
+If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also be generated. The `text` option can be specified to force an input event to be generated.
+
+**NOTE** Modifier keys DO affect `elementHandle.press`. Holding down `Shift` will type the text in upper case.
+
@@ -477,6 +506,10 @@ To press a special key, like `Control` or `ArrowDown`, use [ElementHandle.press(
Sets the value of an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) to the given file paths.
+**Remarks:**
+
+This will not validate whether the file paths exists. Also, if a path is relative, then it is resolved against the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). For locals script connecting to remote chrome environments, paths must be absolute.
+
diff --git a/docs/api/puppeteer.filechooser.md b/docs/api/puppeteer.filechooser.md
index 1646fccb909..4eab715cf03 100644
--- a/docs/api/puppeteer.filechooser.md
+++ b/docs/api/puppeteer.filechooser.md
@@ -55,6 +55,10 @@ Description
Accept the file chooser request with the given file paths.
+**Remarks:**
+
+This will not validate whether the file paths exists. Also, if a path is relative, then it is resolved against the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). For locals script connecting to remote chrome environments, paths must be absolute.
+
diff --git a/docs/api/puppeteer.frame.md b/docs/api/puppeteer.frame.md
index 1e84596aadd..977222d536e 100644
--- a/docs/api/puppeteer.frame.md
+++ b/docs/api/puppeteer.frame.md
@@ -214,6 +214,17 @@ An array of child frames.
Clicks the first element found that matches `selector`.
+**Remarks:**
+
+If `click()` triggers a navigation event and there's a separate `page.waitForNavigation()` promise to be resolved, you may end up with a race condition that yields unexpected results. The correct pattern for click and wait for navigation is the following:
+
+```ts
+const [response] = await Promise.all([
+ page.waitForNavigation(waitOptions),
+ frame.click(selector, clickOptions),
+]);
+```
+
@@ -278,6 +289,16 @@ Focuses the first element that matches the `selector`.
Navigates the frame to the given `url`.
+**Remarks:**
+
+Navigation to `about:blank` or navigation to the same URL with a different hash will succeed and return `null`.
+
+:::warning
+
+Headless mode doesn't support navigation to a PDF document. See the [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
+
+:::
+
@@ -328,6 +349,10 @@ Is `true` if the frame is an out-of-process (OOP) frame. Otherwise, `false`.
Creates a locator for the provided selector. See [Locator](./puppeteer.locator.md) for details and supported actions.
+**Remarks:**
+
+Locators API is experimental and we will not follow semver for breaking change in the Locators API.
+
@@ -339,6 +364,10 @@ Creates a locator for the provided selector. See [Locator](./puppeteer.locator.m
Creates a locator for the provided function. See [Locator](./puppeteer.locator.md) for details and supported actions.
+**Remarks:**
+
+Locators API is experimental and we will not follow semver for breaking change in the Locators API.
+
@@ -361,6 +390,10 @@ const element = await frame.frameElement();
const nameOrId = await element.evaluate(frame => frame.name ?? frame.id);
```
+**Remarks:**
+
+This value is calculated once when the frame is created, and will not update if the attribute is changed later.
+
@@ -438,6 +471,10 @@ The frame's title.
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
+**Remarks:**
+
+To press a special key, like `Control` or `ArrowDown`, use [Keyboard.press()](./puppeteer.keyboard.press.md).
+
diff --git a/docs/api/puppeteer.frameaddscripttagoptions.md b/docs/api/puppeteer.frameaddscripttagoptions.md
index fd39cfbb836..3d566c37080 100644
--- a/docs/api/puppeteer.frameaddscripttagoptions.md
+++ b/docs/api/puppeteer.frameaddscripttagoptions.md
@@ -87,6 +87,10 @@ string
Path to a JavaScript file to be injected into the frame.
+**Remarks:**
+
+If `path` is a relative path, it is resolved relative to the current working directory (`process.cwd()` in Node.js).
+
diff --git a/docs/api/puppeteer.frameaddstyletagoptions.md b/docs/api/puppeteer.frameaddstyletagoptions.md
index 5109c8e3e42..c7db7e0f3f0 100644
--- a/docs/api/puppeteer.frameaddstyletagoptions.md
+++ b/docs/api/puppeteer.frameaddstyletagoptions.md
@@ -68,6 +68,10 @@ string
The path to a CSS file to be injected into the frame.
+**Remarks:**
+
+If `path` is a relative path, it is resolved relative to the current working directory (`process.cwd()` in Node.js).
+
-Warning! Using this client can break Puppeteer. Use with caution.
+**_(Experimental)_** Warning! Using this client can break Puppeteer. Use with caution.
@@ -95,6 +95,10 @@ Description
Aborts a request.
+**Remarks:**
+
+To use this, request interception should be enabled with [Page.setRequestInterception()](./puppeteer.page.setrequestinterception.md). If it is not enabled, this method will throw an exception immediately.
+
@@ -117,6 +121,12 @@ The most recent reason for aborting the request
Continues request with optional request overrides.
+**Remarks:**
+
+To use this, request interception should be enabled with [Page.setRequestInterception()](./puppeteer.page.setrequestinterception.md).
+
+Exception is immediately thrown if the request interception is not enabled.
+
@@ -150,6 +160,8 @@ Adds an async request handler to the processing queue. Deferred handlers are not
Access information about the request's failure.
+**Remarks:**
+
@@ -286,6 +298,27 @@ The request's post body, if any.
A `redirectChain` is a chain of requests initiated to fetch a resource.
+**Remarks:**
+
+`redirectChain` is shared between all the requests of the same chain.
+
+For example, if the website `http://example.com` has a single redirect to `https://example.com`, then the chain will contain one request:
+
+```ts
+const response = await page.goto('http://example.com');
+const chain = response.request().redirectChain();
+console.log(chain.length); // 1
+console.log(chain[0].url()); // 'http://example.com'
+```
+
+If the website `https://google.com` has no redirects, then the chain will be empty:
+
+```ts
+const response = await page.goto('https://google.com');
+const chain = response.request().redirectChain();
+console.log(chain.length); // 0
+```
+
@@ -308,6 +341,12 @@ Contains the request's resource type as it was perceived by the rendering engine
Fulfills a request with the given response.
+**Remarks:**
+
+To use this, request interception should be enabled with [Page.setRequestInterception()](./puppeteer.page.setrequestinterception.md).
+
+Exception is immediately thrown if the request interception is not enabled.
+
diff --git a/docs/api/puppeteer.httpresponse.md b/docs/api/puppeteer.httpresponse.md
index 1dea29aa4d5..16b8bdc280f 100644
--- a/docs/api/puppeteer.httpresponse.md
+++ b/docs/api/puppeteer.httpresponse.md
@@ -41,6 +41,10 @@ Description
Promise which resolves to a buffer with response body.
+**Remarks:**
+
+The buffer might be re-encoded by the browser based on HTTP-headers or other heuristics. If the browser failed to detect the correct encoding, the buffer might be encoded incorrectly. See https://github.com/puppeteer/puppeteer/issues/6478.
+
@@ -96,6 +100,10 @@ An object with HTTP headers associated with the response. All header names are l
Promise which resolves to a JSON representation of response body.
+**Remarks:**
+
+This method will throw if the response body is not parsable via `JSON.parse`.
+
diff --git a/docs/api/puppeteer.jshandle.md b/docs/api/puppeteer.jshandle.md
index 30e4db92754..60efd6e949c 100644
--- a/docs/api/puppeteer.jshandle.md
+++ b/docs/api/puppeteer.jshandle.md
@@ -177,6 +177,10 @@ Fetches a single property from the referenced object.
A vanilla object representing the serializable portions of the referenced object.
+**Remarks:**
+
+If the object has a `toJSON` function, it **will not** be called.
+
@@ -199,5 +203,9 @@ Provides access to the [Protocol.Runtime.RemoteObject](https://chromedevtools.gi
Returns a string representation of the JSHandle.
+**Remarks:**
+
+Useful during debugging.
+
diff --git a/docs/api/puppeteer.keyboard.md b/docs/api/puppeteer.keyboard.md
index 0cc9fdbad90..1f2e3ba08c2 100644
--- a/docs/api/puppeteer.keyboard.md
+++ b/docs/api/puppeteer.keyboard.md
@@ -72,6 +72,14 @@ Description
Dispatches a `keydown` event.
+**Remarks:**
+
+If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also generated. The `text` option can be specified to force an input event to be generated. If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`, subsequent key presses will be sent with that modifier active. To release the modifier key, use [Keyboard.up()](./puppeteer.keyboard.up.md).
+
+After the key is pressed once, subsequent calls to [Keyboard.down()](./puppeteer.keyboard.down.md) will have [repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key, use [Keyboard.up()](./puppeteer.keyboard.up.md).
+
+Modifier keys DO influence [Keyboard.down()](./puppeteer.keyboard.down.md). Holding down `Shift` will type the text in upper case.
+
@@ -83,6 +91,12 @@ Dispatches a `keydown` event.
Shortcut for [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md).
+**Remarks:**
+
+If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also generated. The `text` option can be specified to force an input event to be generated.
+
+Modifier keys DO effect [Keyboard.press()](./puppeteer.keyboard.press.md). Holding down `Shift` will type the text in upper case.
+
@@ -94,6 +108,10 @@ Shortcut for [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()]
Dispatches a `keypress` and `input` event. This does not send a `keydown` or `keyup` event.
+**Remarks:**
+
+Modifier keys DO NOT effect [Keyboard.sendCharacter](./puppeteer.keyboard.sendcharacter.md). Holding down `Shift` will not type the text in upper case.
+
@@ -105,6 +123,12 @@ Dispatches a `keypress` and `input` event. This does not send a `keydown` or `ke
Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
+**Remarks:**
+
+To press a special key, like `Control` or `ArrowDown`, use [Keyboard.press()](./puppeteer.keyboard.press.md).
+
+Modifier keys DO NOT effect `keyboard.type`. Holding down `Shift` will not type the text in upper case.
+
diff --git a/docs/api/puppeteer.page.md b/docs/api/puppeteer.page.md
index e234e2a92f6..bb2df2bafd1 100644
--- a/docs/api/puppeteer.page.md
+++ b/docs/api/puppeteer.page.md
@@ -96,6 +96,16 @@ Description
The Accessibility class provides methods for inspecting the browser'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).
+**Remarks:**
+
+Accessibility is a very platform-specific thing. On different platforms, there are different screen readers that might have wildly different output.
+
+Blink - Chrome's rendering engine - has a concept of "accessibility tree", which is then translated into different platform-specific APIs. Accessibility namespace gives users access to the Blink Accessibility Tree.
+
+Most of the accessibility tree gets filtered out when converting from Blink AX Tree to Platform-specific AX-Tree or by assistive technologies themselves. By default, Puppeteer tries to approximate this filtering, exposing only the "interesting" nodes of the tree.
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Accessibility` class.
+
@@ -113,6 +123,10 @@ The Accessibility class provides methods for inspecting the browser's accessibil
The Coverage class provides methods to gather information about parts of JavaScript and CSS that were used by the page.
+**Remarks:**
+
+To output coverage in a form consumable by [Istanbul](https://github.com/istanbuljs), see [puppeteer-to-istanbul](https://github.com/istanbuljs/puppeteer-to-istanbul).
+
@@ -130,6 +144,14 @@ The Coverage class provides methods to gather information about parts of JavaScr
Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
+**Remarks:**
+
+For finer control, you can use [Keyboard.down()](./puppeteer.keyboard.down.md), [Keyboard.up()](./puppeteer.keyboard.up.md), and [Keyboard.sendCharacter()](./puppeteer.keyboard.sendcharacter.md) to manually fire events as if they were generated from a real keyboard.
+
+On macOS, keyboard shortcuts like `⌘ A` -> Select All do not work. See [\#1313](https://github.com/puppeteer/puppeteer/issues/1313).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Keyboard` class.
+
@@ -147,6 +169,12 @@ Keyboard provides an api for managing a virtual keyboard. The high level api is
The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.
+**Remarks:**
+
+Every `page` object has its own Mouse, accessible with \[`page.mouse`\](\#pagemouse).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Mouse` class.
+
@@ -181,6 +209,12 @@ The Touchscreen class exposes touchscreen events.
The Tracing class exposes the tracing audit interface.
+**Remarks:**
+
+You can use `tracing.start` and `tracing.stop` to create a trace file which can be opened in Chrome DevTools or [timeline viewer](https://chromedevtools.github.io/timeline-viewer/).
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Tracing` class.
+
@@ -220,6 +254,10 @@ Runs `document.querySelector` within the page. If no element matches the selecto
The method runs `document.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`.
+**Remarks:**
+
+Shortcut for [Page.mainFrame().$$(selector)](./puppeteer.frame.__.md).
+
@@ -231,6 +269,10 @@ The method runs `document.querySelectorAll` within the page. If no elements matc
This method runs `Array.from(document.querySelectorAll(selector))` within the page and passes the result as the first argument to the `pageFunction`.
+**Remarks:**
+
+If `pageFunction` returns a promise `$$eval` will wait for the promise to resolve and then return its value.
+
@@ -242,6 +284,12 @@ This method runs `Array.from(document.querySelectorAll(selector))` within the pa
This method runs `document.querySelector` within the page and passes the result as the first argument to the `pageFunction`.
+**Remarks:**
+
+If no element is found matching `selector`, the method will throw an error.
+
+If `pageFunction` returns a promise `$eval` will wait for the promise to resolve and then return its value.
+
@@ -253,6 +301,10 @@ This method runs `document.querySelector` within the page and passes the result
Adds a `