diff --git a/docs-src/api-body.md b/docs-src/api-body.md
index 25c2343790..8b8f8c95af 100644
--- a/docs-src/api-body.md
+++ b/docs-src/api-body.md
@@ -1,10 +1,11 @@
### class: Browser
-
* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
-A Browser is created when Playwright connects to a browser instance, either through [`browserType.launch`](#browsertypelaunchoptions) or [`browserType.connect`](#browsertypeconnectoptions).
+A Browser is created when Playwright connects to a browser instance, either through
+[`browserType.launch`](#browsertypelaunchoptions) or [`browserType.connect`](#browsertypeconnectoptions).
An example of using a [Browser] to create a [Page]:
+
```js
const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'.
@@ -16,7 +17,10 @@ const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'.
})();
```
-See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that [browserType.connect(options)](#browsertypeconnectoptions) and [browserType.launch([options])](#browsertypelaunchoptions) always return a specific browser instance, based on the browser being connected to or launched.
+See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that
+[browserType.connect(options)](#browsertypeconnectoptions) and
+[browserType.launch([options])](#browsertypelaunchoptions) always return a specific browser instance, based on the
+browser being connected to or launched.
- [event: 'disconnected'](#event-disconnected)
@@ -29,6 +33,7 @@ See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific
#### event: 'disconnected'
+
Emitted when Browser gets disconnected from the browser application. This might happen because of one of the following:
- Browser application is closed or crashed.
- The [`browser.close`](#browserclose) method was called.
@@ -36,17 +41,18 @@ Emitted when Browser gets disconnected from the browser application. This might
#### browser.close()
- returns: <[Promise]>
-In case this browser is obtained using [browserType.launch](#browsertypelaunchoptions), closes the browser and all of its pages (if any were opened).
+In case this browser is obtained using [browserType.launch](#browsertypelaunchoptions), closes the browser and all of
+its pages (if any were opened).
-In case this browser is obtained using [browserType.connect](#browsertypeconnectoptions), clears all created contexts belonging to this browser and disconnects from the browser server.
+In case this browser is obtained using [browserType.connect](#browsertypeconnectoptions), clears all created contexts
+belonging to this browser and disconnects from the browser server.
The [Browser] object itself is considered to be disposed and cannot be used anymore.
#### browser.contexts()
- returns: <[Array]<[BrowserContext]>>
-Returns an array of all open browser contexts. In a newly created browser, this will return zero
-browser contexts.
+Returns an array of all open browser contexts. In a newly created browser, this will return zero browser contexts.
```js
const browser = await pw.webkit.launch();
@@ -90,16 +96,16 @@ Creates a new browser context. It won't share cookies/cache with other browser c
Creates a new page in a new browser context. Closing this page will close the context as well.
-This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and testing frameworks should explicitly create [browser.newContext](#browsernewcontextoptions) followed by the [browserContext.newPage](#browsercontextnewpage) to control their exact life times.
+This is a convenience API that should only be used for the single-page scenarios and short snippets. Production code and
+testing frameworks should explicitly create [browser.newContext](#browsernewcontextoptions) followed by the
+[browserContext.newPage](#browsercontextnewpage) to control their exact life times.
#### browser.version()
-
- returns: <[string]>
Returns the browser version.
### class: BrowserContext
-
* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
BrowserContexts provide a way to operate multiple independent browser sessions.
@@ -107,8 +113,8 @@ BrowserContexts provide a way to operate multiple independent browser sessions.
If a page opens another page, e.g. with a `window.open` call, the popup will belong to the parent page's browser
context.
-Playwright allows creation of "incognito" browser contexts with `browser.newContext()` method.
-"Incognito" browser contexts don't write any browsing data to disk.
+Playwright allows creation of "incognito" browser contexts with `browser.newContext()` method. "Incognito" browser
+contexts don't write any browsing data to disk.
```js
// Create a new incognito browser context
@@ -157,9 +163,13 @@ Emitted when Browser context gets closed. This might happen because of one of th
#### event: 'page'
- <[Page]>
-The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event will also fire for popup pages. See also [`Page.on('popup')`](#event-popup) to receive events about popups relevant to a specific page.
+The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event will
+also fire for popup pages. See also [`Page.on('popup')`](#event-popup) to receive events about popups relevant to a
+specific page.
-The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is done and its response has started loading in the popup.
+The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a
+popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is
+done and its response has started loading in the popup.
```js
const [page] = await Promise.all([
@@ -169,7 +179,8 @@ const [page] = await Promise.all([
console.log(await page.evaluate('location.href'));
```
-> **NOTE** Use [`page.waitForLoadState([state[, options]])`](#pagewaitforloadstatestate-options) to wait until the page gets to a particular state (you should not need it in most cases).
+> **NOTE** Use [`page.waitForLoadState([state[, options]])`](#pagewaitforloadstatestate-options) to wait until the page
+gets to a particular state (you should not need it in most cases).
#### browserContext.addCookies(cookies)
- `cookies` <[Array]<[Object]>>
@@ -199,7 +210,8 @@ Adds a script which would be evaluated in one of the following scenarios:
- Whenever a page is created in the browser context or is navigated.
- Whenever a child frame is attached or navigated in any page in the browser context. In this case, the script is evaluated in the context of the newly attached frame.
-The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed `Math.random`.
+The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend
+the JavaScript environment, e.g. to seed `Math.random`.
An example of overriding `Math.random` before the page loads:
@@ -215,7 +227,9 @@ await browserContext.addInitScript({
});
```
-> **NOTE** The order of evaluation of multiple scripts installed via [browserContext.addInitScript(script[, arg])](#browsercontextaddinitscriptscript-arg) and [page.addInitScript(script[, arg])](#pageaddinitscriptscript-arg) is not defined.
+> **NOTE** The order of evaluation of multiple scripts installed via [browserContext.addInitScript(script[,
+arg])](#browsercontextaddinitscriptscript-arg) and [page.addInitScript(script[, arg])](#pageaddinitscriptscript-arg) is
+not defined.
#### browserContext.browser()
- returns: <[null]|[Browser]> Returns the browser instance of the context. If it was launched as a persistent context null gets returned.
@@ -240,8 +254,7 @@ context.clearPermissions();
#### browserContext.close()
- returns: <[Promise]>
-Closes the browser context. All the pages that belong to the browser context
-will be closed.
+Closes the browser context. All the pages that belong to the browser context will be closed.
> **NOTE** the default browser context cannot be closed.
@@ -257,8 +270,8 @@ will be closed.
- `secure` <[boolean]>
- `sameSite` <"Strict"|"Lax"|"None">
-If no URLs are specified, this method returns all cookies.
-If URLs are specified, only cookies that affect those URLs are returned.
+If no URLs are specified, this method returns all cookies. If URLs are specified, only cookies that affect those URLs
+are returned.
#### browserContext.exposeBinding(name, playwrightBinding[, options])
- `name` <[string]> Name of the function on the window object.
@@ -267,16 +280,18 @@ If URLs are specified, only cookies that affect those URLs are returned.
- `handle` <[boolean]> Whether to pass the argument as a handle, instead of passing by value. When passing a handle, only one argument is supported. When passing by value, multiple arguments are supported.
- returns: <[Promise]>
-The method adds a function called `name` on the `window` object of every frame in every page in the context.
-When called, the function executes `playwrightBinding` in Node.js and returns a [Promise] which resolves to the return value of `playwrightBinding`.
-If the `playwrightBinding` returns a [Promise], it will be awaited.
+The method adds a function called `name` on the `window` object of every frame in every page in the context. When
+called, the function executes `playwrightBinding` in Node.js and returns a [Promise] which resolves to the return value
+of `playwrightBinding`. If the `playwrightBinding` returns a [Promise], it will be awaited.
-The first argument of the `playwrightBinding` function contains information about the caller:
-`{ browserContext: BrowserContext, page: Page, frame: Frame }`.
+The first argument of the `playwrightBinding` function contains information about the caller: `{ browserContext:
+BrowserContext, page: Page, frame: Frame }`.
-See [page.exposeBinding(name, playwrightBinding)](#pageexposebindingname-playwrightbinding-options) for page-only version.
+See [page.exposeBinding(name, playwrightBinding)](#pageexposebindingname-playwrightbinding-options) for page-only
+version.
An example of exposing page URL to all frames in all pages in the context:
+
```js
const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
@@ -299,6 +314,7 @@ const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
```
An example of passing an element handle:
+
```js
await context.exposeBinding('clicked', async (source, element) => {
console.log(await element.textContent());
@@ -317,14 +333,16 @@ await page.setContent(`
- `playwrightFunction` <[function]> Callback function that will be called in the Playwright's context.
- returns: <[Promise]>
-The method adds a function called `name` on the `window` object of every frame in every page in the context.
-When called, the function executes `playwrightFunction` in Node.js and returns a [Promise] which resolves to the return value of `playwrightFunction`.
+The method adds a function called `name` on the `window` object of every frame in every page in the context. When
+called, the function executes `playwrightFunction` in Node.js and returns a [Promise] which resolves to the return value
+of `playwrightFunction`.
If the `playwrightFunction` returns a [Promise], it will be awaited.
See [page.exposeFunction(name, playwrightFunction)](#pageexposefunctionname-playwrightfunction) for page-only version.
An example of adding an `md5` function to all pages in the context:
+
```js
const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
const crypto = require('crypto');
@@ -349,27 +367,28 @@ const crypto = require('crypto');
#### browserContext.grantPermissions(permissions[][, options])
- `permissions` <[Array]<[string]>> A permission or an array of permissions to grant. Permissions can be one of the following values:
- - `'geolocation'`
- - `'midi'`
- - `'midi-sysex'` (system-exclusive midi)
- - `'notifications'`
- - `'push'`
- - `'camera'`
- - `'microphone'`
- - `'background-sync'`
- - `'ambient-light-sensor'`
- - `'accelerometer'`
- - `'gyroscope'`
- - `'magnetometer'`
- - `'accessibility-events'`
- - `'clipboard-read'`
- - `'clipboard-write'`
- - `'payment-handler'`
+ - `'geolocation'`
+ - `'midi'`
+ - `'midi-sysex'` (system-exclusive midi)
+ - `'notifications'`
+ - `'push'`
+ - `'camera'`
+ - `'microphone'`
+ - `'background-sync'`
+ - `'ambient-light-sensor'`
+ - `'accelerometer'`
+ - `'gyroscope'`
+ - `'magnetometer'`
+ - `'accessibility-events'`
+ - `'clipboard-read'`
+ - `'clipboard-write'`
+ - `'payment-handler'`
- `options` <[Object]>
- `origin` <[string]> The [origin] to grant permissions to, e.g. "https://example.com".
- returns: <[Promise]>
-Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if specified.
+Grants specified permissions to the browser context. Only grants corresponding permissions to the given origin if
+specified.
#### browserContext.newPage()
- returns: <[Promise]<[Page]>>
@@ -384,8 +403,8 @@ Creates a new page in the browser context.
- `handler` <[function]\([Route], [Request]\)> handler function to route the request.
- returns: <[Promise]>
-Routing provides the capability to modify network requests that are made by any page in the browser context.
-Once route is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.
+Routing provides the capability to modify network requests that are made by any page in the browser context. Once route
+is enabled, every request matching the url pattern will stall unless it's continued, fulfilled or aborted.
An example of a naïve handler that aborts all image requests:
@@ -407,7 +426,8 @@ await page.goto('https://example.com');
await browser.close();
```
-Page routes (set up with [page.route(url, handler)](#pagerouteurl-handler)) take precedence over browser context routes when request matches both handlers.
+Page routes (set up with [page.route(url, handler)](#pagerouteurl-handler)) take precedence over browser context routes
+when request matches both handlers.
> **NOTE** Enabling routing disables http cache.
@@ -422,20 +442,27 @@ This setting will change the default maximum navigation time for the following m
- [page.setContent(html[, options])](#pagesetcontenthtml-options)
- [page.waitForNavigation([options])](#pagewaitfornavigationoptions)
-> **NOTE** [`page.setDefaultNavigationTimeout`](#pagesetdefaultnavigationtimeouttimeout) and [`page.setDefaultTimeout`](#pagesetdefaulttimeouttimeout) take priority over [`browserContext.setDefaultNavigationTimeout`](#browsercontextsetdefaultnavigationtimeouttimeout).
+> **NOTE** [`page.setDefaultNavigationTimeout`](#pagesetdefaultnavigationtimeouttimeout) and
+[`page.setDefaultTimeout`](#pagesetdefaulttimeouttimeout) take priority over
+[`browserContext.setDefaultNavigationTimeout`](#browsercontextsetdefaultnavigationtimeouttimeout).
#### browserContext.setDefaultTimeout(timeout)
- `timeout` <[number]> Maximum time in milliseconds
This setting will change the default maximum time for all the methods accepting `timeout` option.
-> **NOTE** [`page.setDefaultNavigationTimeout`](#pagesetdefaultnavigationtimeouttimeout), [`page.setDefaultTimeout`](#pagesetdefaulttimeouttimeout) and [`browserContext.setDefaultNavigationTimeout`](#browsercontextsetdefaultnavigationtimeouttimeout) take priority over [`browserContext.setDefaultTimeout`](#browsercontextsetdefaulttimeouttimeout).
+> **NOTE** [`page.setDefaultNavigationTimeout`](#pagesetdefaultnavigationtimeouttimeout),
+[`page.setDefaultTimeout`](#pagesetdefaulttimeouttimeout) and
+[`browserContext.setDefaultNavigationTimeout`](#browsercontextsetdefaultnavigationtimeouttimeout) take priority over
+[`browserContext.setDefaultTimeout`](#browsercontextsetdefaulttimeouttimeout).
#### browserContext.setExtraHTTPHeaders(headers)
- `headers` <[Object]<[string], [string]>> An object containing additional HTTP headers to be sent with every request. All header values must be strings.
- returns: <[Promise]>
-The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are merged with page-specific extra HTTP headers set with [page.setExtraHTTPHeaders()](#pagesetextrahttpheadersheaders). If page overrides a particular header, page-specific header value will be used instead of the browser context header value.
+The extra HTTP headers will be sent with every request initiated by any page in the context. These headers are merged
+with page-specific extra HTTP headers set with [page.setExtraHTTPHeaders()](#pagesetextrahttpheadersheaders). If page
+overrides a particular header, page-specific header value will be used instead of the browser context header value.
> **NOTE** `browserContext.setExtraHTTPHeaders` does not guarantee the order of headers in the outgoing requests.
@@ -452,7 +479,8 @@ Sets the context's geolocation. Passing `null` or `undefined` emulates position
await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667});
```
-> **NOTE** Consider using [browserContext.grantPermissions](#browsercontextgrantpermissionspermissions-options) to grant permissions for the browser context pages to read its geolocation.
+> **NOTE** Consider using [browserContext.grantPermissions](#browsercontextgrantpermissionspermissions-options) to grant
+permissions for the browser context pages to read its geolocation.
#### browserContext.setHTTPCredentials(httpCredentials)
- `httpCredentials` <[null]|[Object]>
@@ -462,7 +490,9 @@ await browserContext.setGeolocation({latitude: 59.95, longitude: 30.31667});
Provide credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
-> **NOTE** Browsers may cache credentials after successful authentication. Passing different credentials or passing `null` to disable authentication will be unreliable. To remove or replace credentials, create a new browser context instead.
+> **NOTE** Browsers may cache credentials after successful authentication. Passing different credentials or passing
+`null` to disable authentication will be unreliable. To remove or replace credentials, create a new browser context
+instead.
#### browserContext.setOffline(offline)
- `offline` <[boolean]> Whether to emulate network being offline for the browser context.
@@ -492,7 +522,8 @@ Returns storage state for this browser context, contains current cookies and loc
- `handler` <[function]\([Route], [Request]\)> Handler function used to register a routing with [browserContext.route(url, handler)](#browsercontextrouteurl-handler).
- returns: <[Promise]>
-Removes a route created with [browserContext.route(url, handler)](#browsercontextrouteurl-handler). When `handler` is not specified, removes all routes for the `url`.
+Removes a route created with [browserContext.route(url, handler)](#browsercontextrouteurl-handler). When `handler` is
+not specified, removes all routes for the `url`.
#### browserContext.waitForEvent(event[, optionsOrPredicate])
- `event` <[string]> Event name, same one would pass into `browserContext.on(event)`.
@@ -501,8 +532,8 @@ Removes a route created with [browserContext.route(url, handler)](#browsercontex
- %%-wait-for-timeout-%%
- returns: <[Promise]<[Object]>> Promise which resolves to the event data value.
-Waits for event to fire and passes its value into the predicate function. Resolves when the predicate returns truthy value. Will throw an error if the context closes before the event
-is fired.
+Waits for event to fire and passes its value into the predicate function. Resolves when the predicate returns truthy
+value. Will throw an error if the context closes before the event is fired.
```js
const context = await browser.newContext();
@@ -510,12 +541,14 @@ await context.grantPermissions(['geolocation']);
```
### class: Page
-
* extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
-Page provides methods to interact with a single tab in a [Browser], or an [extension background page](https://developer.chrome.com/extensions/background_pages) in Chromium. One [Browser] instance might have multiple [Page] instances.
+Page provides methods to interact with a single tab in a [Browser], or an [extension background
+page](https://developer.chrome.com/extensions/background_pages) in Chromium. One [Browser] instance might have multiple
+[Page] instances.
This example creates a page, navigates it to a URL, and then saves a screenshot:
+
```js
const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
@@ -529,9 +562,12 @@ const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'.
})();
```
-The Page class emits various events (described below) which can be handled using any of Node's native [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) methods, such as `on`, `once` or `removeListener`.
+The Page class emits various events (described below) which can be handled using any of Node's native
+[`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) methods, such as `on`, `once` or
+`removeListener`.
This example logs a message for a single page `load` event:
+
```js
page.once('load', () => console.log('Page loaded!'));
```
@@ -645,11 +681,13 @@ Emitted when the page closes.
#### event: 'console'
- <[ConsoleMessage]>
-Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also emitted if the page throws an error or a warning.
+Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also
+emitted if the page throws an error or a warning.
The arguments passed into `console.log` appear as arguments on the event handler.
An example of handling `console` event:
+
```js
page.on('console', msg => {
for (let i = 0; i < msg.args().length; ++i)
@@ -660,9 +698,11 @@ page.evaluate(() => console.log('hello', 5, {foo: 'bar'}));
#### event: 'crash'
-Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page crashes, ongoing and subsequent operations will throw.
+Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page crashes,
+ongoing and subsequent operations will throw.
The most common way to deal with crashes is to catch an exception:
+
```js
try {
// Crash might happen during a click.
@@ -674,7 +714,8 @@ try {
}
```
-However, when manually listening to events, it might be useful to avoid stalling when the page crashes. In this case, handling `crash` event helps:
+However, when manually listening to events, it might be useful to avoid stalling when the page crashes. In this case,
+handling `crash` event helps:
```js
await new Promise((resolve, reject) => {
@@ -689,23 +730,30 @@ await new Promise((resolve, reject) => {
#### event: 'dialog'
- <[Dialog]>
-Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via [Dialog]'s [accept](#dialogacceptprompttext) or [dismiss](#dialogdismiss) methods.
+Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond
+to the dialog via [Dialog]'s [accept](#dialogacceptprompttext) or [dismiss](#dialogdismiss) methods.
#### event: 'domcontentloaded'
-Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched.
+Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded)
+event is dispatched.
#### event: 'download'
- <[Download]>
-Emitted when attachment download started. User can access basic file operations on downloaded content via the passed [Download] instance.
+Emitted when attachment download started. User can access basic file operations on downloaded content via the passed
+[Download] instance.
-> **NOTE** Browser context **must** be created with the `acceptDownloads` set to `true` when user needs access to the downloaded content. If `acceptDownloads` is not set or set to `false`, download events are emitted, but the actual download is not performed and user has no access to the downloaded files.
+> **NOTE** Browser context **must** be created with the `acceptDownloads` set to `true` when user needs access to the
+downloaded content. If `acceptDownloads` is not set or set to `false`, download events are emitted, but the actual
+download is not performed and user has no access to the downloaded files.
#### event: 'filechooser'
- <[FileChooser]>
-Emitted when a file chooser is supposed to appear, such as after clicking the ``. Playwright can respond to it via setting the input files using [`fileChooser.setFiles`](#filechoosersetfilesfiles-options) that can be uploaded after that.
+Emitted when a file chooser is supposed to appear, such as after clicking the ``. Playwright can
+respond to it via setting the input files using [`fileChooser.setFiles`](#filechoosersetfilesfiles-options) that can be
+uploaded after that.
```js
page.on('filechooser', async (fileChooser) => {
@@ -740,9 +788,12 @@ Emitted when an uncaught exception happens within the page.
#### event: 'popup'
- <[Page]> Page corresponding to "popup" window
-Emitted when the page opens a new tab or window. This event is emitted in addition to the [`browserContext.on('page')`](#event-page), but only for popups relevant to this page.
+Emitted when the page opens a new tab or window. This event is emitted in addition to the
+[`browserContext.on('page')`](#event-page), but only for popups relevant to this page.
-The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is done and its response has started loading in the popup.
+The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a
+popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is
+done and its response has started loading in the popup.
```js
const [popup] = await Promise.all([
@@ -752,30 +803,35 @@ const [popup] = await Promise.all([
console.log(await popup.evaluate('location.href'));
```
-> **NOTE** Use [`page.waitForLoadState([state[, options]])`](#pagewaitforloadstatestate-options) to wait until the page gets to a particular state (you should not need it in most cases).
+> **NOTE** Use [`page.waitForLoadState([state[, options]])`](#pagewaitforloadstatestate-options) to wait until the page
+gets to a particular state (you should not need it in most cases).
#### event: 'request'
- <[Request]>
-Emitted when a page issues a request. The [request] object is read-only.
-In order to intercept and mutate requests, see [`page.route()`](#pagerouteurl-handler) or [`browserContext.route()`](#browsercontextrouteurl-handler).
+Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, see
+[`page.route()`](#pagerouteurl-handler) or [`browserContext.route()`](#browsercontextrouteurl-handler).
#### event: 'requestfailed'
- <[Request]>
Emitted when a request fails, for example by timing out.
-> **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with [`'requestfinished'`](#event-requestfinished) event and not with [`'requestfailed'`](#event-requestfailed).
+> **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request
+will complete with [`'requestfinished'`](#event-requestfinished) event and not with
+[`'requestfailed'`](#event-requestfailed).
#### event: 'requestfinished'
- <[Request]>
-Emitted when a request finishes successfully after downloading the response body. For a successful response, the sequence of events is `request`, `response` and `requestfinished`.
+Emitted when a request finishes successfully after downloading the response body. For a successful response, the
+sequence of events is `request`, `response` and `requestfinished`.
#### event: 'response'
- <[Response]>
-Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events is `request`, `response` and `requestfinished`.
+Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events
+is `request`, `response` and `requestfinished`.
#### event: 'websocket'
- <[WebSocket]> websocket
@@ -785,13 +841,15 @@ Emitted when <[WebSocket]> request is sent.
#### event: 'worker'
- <[Worker]>
-Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the page.
+Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the
+page.
#### page.$(selector)
- %%-query-selector-%%
- returns: <[Promise]<[null]|[ElementHandle]>>
-The method finds an element matching the specified selector within the page. If no elements match the selector, the return value resolves to `null`.
+The method finds an element matching the specified selector within the page. If no elements match the selector, the
+return value resolves to `null`.
Shortcut for [page.mainFrame().$(selector)](#frameselector).
@@ -799,7 +857,8 @@ Shortcut for [page.mainFrame().$(selector)](#frameselector).
- %%-query-selector-%%
- returns: <[Promise]<[Array]<[ElementHandle]>>>
-The method finds all elements matching the specified selector within the page. If no elements match the selector, the return value resolves to `[]`.
+The method finds all elements matching the specified selector within the page. If no elements match the selector, the
+return value resolves to `[]`.
Shortcut for [page.mainFrame().$$(selector)](#frameselector-1).
@@ -809,11 +868,13 @@ Shortcut for [page.mainFrame().$$(selector)](#frameselector-1).
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
-The method finds an element matching the specified selector within the page and passes it as a first argument to `pageFunction`. If no elements match the selector, the method throws an error.
+The method finds an element matching the specified selector within the page and passes it as a first argument to
+`pageFunction`. If no elements match the selector, the method throws an error.
If `pageFunction` returns a [Promise], then `page.$eval` would wait for the promise to resolve and return its value.
Examples:
+
```js
const searchValue = await page.$eval('#search', el => el.value);
const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
@@ -828,11 +889,13 @@ Shortcut for [page.mainFrame().$eval(selector, pageFunction)](#frameevalselector
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
-The method finds all elements matching the specified selector within the page and passes an array of matched elements as a first argument to `pageFunction`.
+The method finds all elements matching the specified selector within the page and passes an array of matched elements as
+a first argument to `pageFunction`.
If `pageFunction` returns a [Promise], then `page.$$eval` would wait for the promise to resolve and return its value.
Examples:
+
```js
const divsCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 10);
```
@@ -851,7 +914,8 @@ Adds a script which would be evaluated in one of the following scenarios:
- Whenever the page is navigated.
- Whenever the child frame is attached or navigated. In this case, the script is evaluated in the context of the newly attached frame.
-The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend the JavaScript environment, e.g. to seed `Math.random`.
+The script is evaluated after the document was created but before any of its scripts were run. This is useful to amend
+the JavaScript environment, e.g. to seed `Math.random`.
An example of overriding `Math.random` before the page loads:
@@ -864,7 +928,9 @@ const preloadFile = fs.readFileSync('./preload.js', 'utf8');
await page.addInitScript(preloadFile);
```
-> **NOTE** The order of evaluation of multiple scripts installed via [browserContext.addInitScript(script[, arg])](#browsercontextaddinitscriptscript-arg) and [page.addInitScript(script[, arg])](#pageaddinitscriptscript-arg) is not defined.
+> **NOTE** The order of evaluation of multiple scripts installed via [browserContext.addInitScript(script[,
+arg])](#browsercontextaddinitscriptscript-arg) and [page.addInitScript(script[, arg])](#pageaddinitscriptscript-arg) is
+not defined.
#### page.addScriptTag(options)
- `options` <[Object]>
@@ -885,18 +951,16 @@ Shortcut for [page.mainFrame().addScriptTag(options)](#frameaddscripttagoptions)
- `content` <[string]> Raw CSS content to be injected into frame.
- returns: <[Promise]<[ElementHandle]>> which resolves to the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
-Adds a `` tag into the page with the desired url or a `