diff --git a/docs-src/api-body.md b/docs-src/api-body.md index 90a9ea1a5c01b..0087e2b98a335 100644 --- a/docs-src/api-body.md +++ b/docs-src/api-body.md @@ -16,9 +16,6 @@ const { chromium, firefox, webkit } = require('playwright'); By default, the `playwright` NPM package automatically downloads browser executables during installation. The `playwright-core` NPM package can be used to skip automatic downloads. - - - ## property: Playwright.chromium - type: <[BrowserType]> @@ -104,9 +101,6 @@ See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific BrowserType.connect`] and [`method: BrowserType.launch`] always return a specific browser instance, based on the browser being connected to or launched. - - - ## event: Browser.disconnected Emitted when Browser gets disconnected from the browser application. This might happen because of one of the following: @@ -204,9 +198,6 @@ await page.goto('https://example.com'); await context.close(); ``` - - - ## event: BrowserContext.close Emitted when Browser context gets closed. This might happen because of one of the following: @@ -718,9 +709,6 @@ page.on('request', logRequest); page.removeListener('request', logRequest); ``` - - - ## event: Page.close Emitted when the page closes. @@ -2482,9 +2470,6 @@ const text = await frame.$eval('.selector', element => element.textContent); console.log(text); ``` - - - ## async method: Frame.$ - returns: <[null]|[ElementHandle]> @@ -3337,12 +3322,6 @@ JSHandle.dispose`]. ElementHandles are auto-disposed when their origin frame get ElementHandle instances can be used as an argument in [`method: Page.$eval`] and [`method: Page.evaluate`] methods. - - - - - - ## async method: ElementHandle.$ - returns: <[null]|[ElementHandle]> @@ -3929,9 +3908,6 @@ destroyed. JSHandle instances can be used as an argument in [`method: Page.$eval`], [`method: Page.evaluate`] and [`method: Page.evaluateHandle`] methods. - - - ## method: JSHandle.asElement - returns: <[null]|[ElementHandle]> @@ -4028,9 +4004,6 @@ error if the object has circular references. [ConsoleMessage] objects are dispatched by page via the [`event: Page.console`] event. - - - ## method: ConsoleMessage.args - returns: <[Array]<[JSHandle]>> @@ -4071,9 +4044,6 @@ const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. })(); ``` - - - ## async method: Dialog.accept Returns when the dialog has been accepted. @@ -4125,9 +4095,6 @@ const path = await download.path(); 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. - - - ## async method: Download.createReadStream - returns: <[null]|[Readable]> @@ -4177,9 +4144,6 @@ When browser context is created with the `videosPath` option, each page has a vi console.log(await page.video().path()); ``` - - - ## async method: Video.path - returns: <[string]> @@ -4196,9 +4160,6 @@ page.on('filechooser', async (fileChooser) => { }); ``` - - - ## method: FileChooser.element - returns: <[ElementHandle]> @@ -4265,9 +4226,6 @@ await page.keyboard.press('Control+A'); await page.keyboard.press('Meta+A'); ``` - - - ## async method: Keyboard.down Dispatches a `keydown` event. @@ -4409,9 +4367,6 @@ await page.mouse.move(0, 0); await page.mouse.up(); ``` - - - ## async method: Mouse.click Shortcut for [`method: Mouse.move`], [`method: Mouse.down`], [`method: Mouse.up`]. @@ -4505,9 +4460,6 @@ will complete with `'requestfinished'` event. If request gets a 'redirect' response, the request is successfully finished with the 'requestfinished' event, and a new request is issued to a redirected url. - - - ## method: Request.failure - returns: <[null]|[Object]> - `errorText` <[string]> Human-readable error message, e.g. `'net::ERR_FAILED'`. @@ -4639,9 +4591,6 @@ URL of the request. [Response] class represents responses which are received by page. - - - ## async method: Response.body - returns: <[Buffer]> @@ -4704,9 +4653,6 @@ Contains the URL of the response. Selectors can be used to install custom selector engines. See [Working with selectors](#working-with-selectors) for more information. - - - ## async method: Selectors.register An example of registering selector engine that queries elements based on a tag name: @@ -4771,9 +4717,6 @@ guaranteed when this engine is used together with other registered engines. Whenever a network route is set up with [`method: Page.route`] or [`method: BrowserContext.route`], the `Route` object allows to handle the route. - - - ## async method: Route.abort Aborts the route's request. @@ -4863,9 +4806,6 @@ A request to be routed. The [WebSocket] class represents websocket connections in the page. - - - ## event: WebSocket.close Fired when the websocket closes. @@ -4939,9 +4879,6 @@ Most of the accessibility tree gets filtered out when converting from Blink AX T assistive technologies themselves. By default, Playwright tries to approximate this filtering, exposing only the "interesting" nodes of the tree. - - - ## async method: Accessibility.snapshot - returns: <[null]|[Object]> - `role` <[string]> The [role](https://www.w3.org/TR/wai-aria/#usage_intro). @@ -5030,9 +4967,6 @@ for (const worker of page.workers()) console.log(' ' + worker.url()); ``` - - - ## event: Worker.close - type: <[Worker]> @@ -5086,9 +5020,6 @@ Optional argument to pass to [`param: pageFunction`] # class: BrowserServer - - - ## event: BrowserServer.close Emitted when the browser server closes. @@ -5131,9 +5062,6 @@ const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. })(); ``` - - - ## async method: BrowserType.connect - returns: <[Browser]> @@ -5515,9 +5443,6 @@ const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. })(); ``` - - - ## method: Logger.isEnabled - returns: <[boolean]> @@ -5570,12 +5495,6 @@ await page.goto('https://www.google.com'); await browser.stopTracing(); ``` - - - - - - ## async method: ChromiumBrowser.newBrowserCDPSession - returns: <[CDPSession]> @@ -5619,12 +5538,6 @@ Chromium-specific features including background pages, service worker support, e const backgroundPage = await context.waitForEvent('backgroundpage'); ``` - - - - - - ## event: ChromiumBrowserContext.backgroundpage - type: <[Page]> @@ -5683,9 +5596,6 @@ const v8toIstanbul = require('v8-to-istanbul'); })(); ``` - - - ## async method: ChromiumCoverage.startCSSCoverage Returns coverage is started @@ -5765,9 +5675,6 @@ await client.send('Animation.setPlaybackRate', { }); ``` - - - ## async method: CDPSession.detach Detaches the CDPSession from the target. Once detached, the CDPSession object won't emit any events and can't be used to @@ -5791,13 +5698,7 @@ Optional method parameters Firefox browser instance does not expose Firefox-specific features. - - - # class: WebKitBrowser * extends: [Browser] WebKit browser instance does not expose WebKit-specific features. - - - diff --git a/docs/api.md b/docs/api.md index fc627e86d5580..c5e094ac61c05 100644 --- a/docs/api.md +++ b/docs/api.md @@ -62,14 +62,13 @@ const { chromium, firefox, webkit } = require('playwright'); By default, the `playwright` NPM package automatically downloads browser executables during installation. The `playwright-core` NPM package can be used to skip automatic downloads. - + - [playwright.chromium](#playwrightchromium) - [playwright.devices](#playwrightdevices) - [playwright.errors](#playwrighterrors) - [playwright.firefox](#playwrightfirefox) - [playwright.selectors](#playwrightselectors) - [playwright.webkit](#playwrightwebkit) - #### playwright.chromium - type: <[BrowserType]> @@ -79,7 +78,7 @@ This object can be used to launch or connect to Chromium, returning instances of #### playwright.devices - type: <[Object]> -Returns a list of devices to be used with [`browser.newContext([options])`](#browsernewcontextoptions) or [`browser.newPage([options])`](#browsernewpageoptions). Actual list of devices can be found in [src/server/deviceDescriptors.ts](https://github.com/Microsoft/playwright/blob/master/src/server/deviceDescriptors.ts). +Returns a list of devices to be used with [browser.newContext([options])](#browsernewcontextoptions) or [browser.newPage([options])](#browsernewpageoptions). Actual list of devices can be found in [src/server/deviceDescriptors.ts](https://github.com/Microsoft/playwright/blob/master/src/server/deviceDescriptors.ts). ```js const { webkit, devices } = require('playwright'); @@ -101,7 +100,7 @@ const iPhone = devices['iPhone 6']; - type: <[Object]> - `TimeoutError` <[function]> A class of [TimeoutError]. -Playwright methods might throw errors if they are unable to fulfill a request. For example, [`page.waitForSelector(selector[, options])`](#pagewaitforselectorselector-options) might fail if the selector doesn't match any nodes during the given timeframe. +Playwright methods might throw errors if they are unable to fulfill a request. For example, [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) might fail if the selector doesn't match any nodes during the given timeframe. For certain types of errors Playwright uses specific error classes. These classes are available via [`playwright.errors`](#playwrighterrors). @@ -137,7 +136,7 @@ This object can be used to launch or connect to WebKit, returning instances of [ ### 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([options])`](#browsertypelaunchoptions) or [`browserType.connect(params)`](#browsertypeconnectparams). +A Browser is created when Playwright connects to a browser instance, either through [browserType.launch([options])](#browsertypelaunchoptions) or [browserType.connect(params)](#browsertypeconnectparams). An example of using a [Browser] to create a [Page]: @@ -152,9 +151,9 @@ const { firefox } = require('playwright'); // Or 'chromium' or 'webkit'. })(); ``` -See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific features. Note that [`browserType.connect(params)`](#browsertypeconnectparams) 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(params)](#browsertypeconnectparams) and [browserType.launch([options])](#browsertypelaunchoptions) always return a specific browser instance, based on the browser being connected to or launched. - + - [browser.on('disconnected')](#browserondisconnected) - [browser.close()](#browserclose) - [browser.contexts()](#browsercontexts) @@ -162,20 +161,19 @@ See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific - [browser.newContext([options])](#browsernewcontextoptions) - [browser.newPage([options])](#browsernewpageoptions) - [browser.version()](#browserversion) - #### browser.on('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. +* The [browser.close()](#browserclose) method was called. #### browser.close() - returns: <[Promise]> -In case this browser is obtained using [`browserType.launch([options])`](#browsertypelaunchoptions), closes the browser and all of its pages (if any were opened). +In case this browser is obtained using [browserType.launch([options])](#browsertypelaunchoptions), closes the browser and all of its pages (if any were opened). -In case this browser is obtained using [`browserType.connect(params)`](#browsertypeconnectparams), clears all created contexts belonging to this browser and disconnects from the browser server. +In case this browser is obtained using [browserType.connect(params)](#browsertypeconnectparams), 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. @@ -201,7 +199,7 @@ Indicates that the browser is connected. - `options` <[Object]> - `acceptDownloads` <[boolean]> Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled. - `bypassCSP` <[boolean]> Toggles bypassing page's Content-Security-Policy. - - `colorScheme` <"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [`page.emulateMedia(params)`](#pageemulatemediaparams) for more details. Defaults to '`light`'. + - `colorScheme` <"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [page.emulateMedia(params)](#pageemulatemediaparams) for more details. Defaults to '`light`'. - `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`. - `extraHTTPHeaders` <[Object]<[string], [string]>> An object containing additional HTTP headers to be sent with every request. All header values must be strings. - `geolocation` <[Object]> @@ -218,21 +216,21 @@ Indicates that the browser is connected. - `locale` <[string]> Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, `Accept-Language` request header value as well as number and date formatting rules. - `logger` <[Logger]> Logger sink for Playwright logging. - `offline` <[boolean]> Whether to emulate network being offline. Defaults to `false`. - - `permissions` <[Array]<[string]>> A list of permissions to grant to all pages in this context. See [`browserContext.grantPermissions(permissions[, options])`](#browsercontextgrantpermissionspermissions-options) for more details. + - `permissions` <[Array]<[string]>> A list of permissions to grant to all pages in this context. See [browserContext.grantPermissions(permissions[, options])](#browsercontextgrantpermissionspermissions-options) for more details. - `proxy` <[Object]> Network proxy settings to use with this context. Note that browser needs to be launched with the global proxy for this option to work. If all contexts override the proxy, global proxy will be never used and can be any string, for example `launch({ proxy: { server: 'per-context' } })`. - `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. - `bypass` <[string]> Optional coma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. - `username` <[string]> Optional username to use if HTTP proxy requires authentication. - `password` <[string]> Optional password to use if HTTP proxy requires authentication. - - `recordHar` <[Object]> Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into `recordHar.path` file. If not specified, the HAR is not recorded. Make sure to await [`browserContext.close()`](#browsercontextclose) for the HAR to be saved. + - `recordHar` <[Object]> Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into `recordHar.path` file. If not specified, the HAR is not recorded. Make sure to await [browserContext.close()](#browsercontextclose) for the HAR to be saved. - `omitContent` <[boolean]> Optional setting to control whether to omit request content from the HAR. Defaults to `false`. - `path` <[string]> Path on the filesystem to write the HAR file to. - - `recordVideo` <[Object]> Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded. Make sure to await [`browserContext.close()`](#browsercontextclose) for videos to be saved. + - `recordVideo` <[Object]> Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded. Make sure to await [browserContext.close()](#browsercontextclose) for videos to be saved. - `dir` <[string]> Path to the directory to put videos into. - `size` <[Object]> Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport`. If `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of each page will be scaled down if necessary to fit the specified size. - `width` <[number]> Video frame width. - `height` <[number]> Video frame height. - - `storageState` <[string]|[Object]> Populates context with given storage state. This method can be used to initialize context with logged-in information obtained via [`browserContext.storageState([options])`](#browsercontextstoragestateoptions). Either a path to the file with saved storage, or an object with the following fields: + - `storageState` <[string]|[Object]> Populates context with given storage state. This method can be used to initialize context with logged-in information obtained via [browserContext.storageState([options])](#browsercontextstoragestateoptions). Either a path to the file with saved storage, or an object with the following fields: - `cookies` <[Array]<[Object]>> Optional cookies to set for context - `name` <[string]> **required** - `value` <[string]> **required** @@ -253,7 +251,7 @@ Indicates that the browser is connected. - `videoSize` <[Object]> **NOTE** Use `recordVideo` instead, it takes precedence over `videoSize`. Specifies dimensions of the automatically recorded video. Can only be used if `videosPath` is set. If not specified the size will be equal to `viewport`. If `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of the page will be scaled down if necessary to fit specified size. - `width` <[number]> Video frame width. - `height` <[number]> Video frame height. - - `videosPath` <[string]> **NOTE** Use `recordVideo` instead, it takes precedence over `videosPath`. Enables video recording for all pages to `videosPath` directory. If not specified, videos are not recorded. Make sure to await [`browserContext.close()`](#browsercontextclose) for videos to be saved. + - `videosPath` <[string]> **NOTE** Use `recordVideo` instead, it takes precedence over `videosPath`. Enables video recording for all pages to `videosPath` directory. If not specified, videos are not recorded. Make sure to await [browserContext.close()](#browsercontextclose) for videos to be saved. - `viewport` <[null]|[Object]> Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport. - `width` <[number]> page width in pixels. - `height` <[number]> page height in pixels. @@ -276,7 +274,7 @@ Creates a new browser context. It won't share cookies/cache with other browser c - `options` <[Object]> - `acceptDownloads` <[boolean]> Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled. - `bypassCSP` <[boolean]> Toggles bypassing page's Content-Security-Policy. - - `colorScheme` <"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [`page.emulateMedia(params)`](#pageemulatemediaparams) for more details. Defaults to '`light`'. + - `colorScheme` <"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See [page.emulateMedia(params)](#pageemulatemediaparams) for more details. Defaults to '`light`'. - `deviceScaleFactor` <[number]> Specify device scale factor (can be thought of as dpr). Defaults to `1`. - `extraHTTPHeaders` <[Object]<[string], [string]>> An object containing additional HTTP headers to be sent with every request. All header values must be strings. - `geolocation` <[Object]> @@ -293,21 +291,21 @@ Creates a new browser context. It won't share cookies/cache with other browser c - `locale` <[string]> Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, `Accept-Language` request header value as well as number and date formatting rules. - `logger` <[Logger]> Logger sink for Playwright logging. - `offline` <[boolean]> Whether to emulate network being offline. Defaults to `false`. - - `permissions` <[Array]<[string]>> A list of permissions to grant to all pages in this context. See [`browserContext.grantPermissions(permissions[, options])`](#browsercontextgrantpermissionspermissions-options) for more details. + - `permissions` <[Array]<[string]>> A list of permissions to grant to all pages in this context. See [browserContext.grantPermissions(permissions[, options])](#browsercontextgrantpermissionspermissions-options) for more details. - `proxy` <[Object]> Network proxy settings to use with this context. Note that browser needs to be launched with the global proxy for this option to work. If all contexts override the proxy, global proxy will be never used and can be any string, for example `launch({ proxy: { server: 'per-context' } })`. - `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. - `bypass` <[string]> Optional coma-separated domains to bypass proxy, for example `".com, chromium.org, .domain.com"`. - `username` <[string]> Optional username to use if HTTP proxy requires authentication. - `password` <[string]> Optional password to use if HTTP proxy requires authentication. - - `recordHar` <[Object]> Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into `recordHar.path` file. If not specified, the HAR is not recorded. Make sure to await [`browserContext.close()`](#browsercontextclose) for the HAR to be saved. + - `recordHar` <[Object]> Enables [HAR](http://www.softwareishard.com/blog/har-12-spec) recording for all pages into `recordHar.path` file. If not specified, the HAR is not recorded. Make sure to await [browserContext.close()](#browsercontextclose) for the HAR to be saved. - `omitContent` <[boolean]> Optional setting to control whether to omit request content from the HAR. Defaults to `false`. - `path` <[string]> Path on the filesystem to write the HAR file to. - - `recordVideo` <[Object]> Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded. Make sure to await [`browserContext.close()`](#browsercontextclose) for videos to be saved. + - `recordVideo` <[Object]> Enables video recording for all pages into `recordVideo.dir` directory. If not specified videos are not recorded. Make sure to await [browserContext.close()](#browsercontextclose) for videos to be saved. - `dir` <[string]> Path to the directory to put videos into. - `size` <[Object]> Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport`. If `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of each page will be scaled down if necessary to fit the specified size. - `width` <[number]> Video frame width. - `height` <[number]> Video frame height. - - `storageState` <[string]|[Object]> Populates context with given storage state. This method can be used to initialize context with logged-in information obtained via [`browserContext.storageState([options])`](#browsercontextstoragestateoptions). Either a path to the file with saved storage, or an object with the following fields: + - `storageState` <[string]|[Object]> Populates context with given storage state. This method can be used to initialize context with logged-in information obtained via [browserContext.storageState([options])](#browsercontextstoragestateoptions). Either a path to the file with saved storage, or an object with the following fields: - `cookies` <[Array]<[Object]>> Optional cookies to set for context - `name` <[string]> **required** - `value` <[string]> **required** @@ -328,7 +326,7 @@ Creates a new browser context. It won't share cookies/cache with other browser c - `videoSize` <[Object]> **NOTE** Use `recordVideo` instead, it takes precedence over `videoSize`. Specifies dimensions of the automatically recorded video. Can only be used if `videosPath` is set. If not specified the size will be equal to `viewport`. If `viewport` is not configured explicitly the video size defaults to 1280x720. Actual picture of the page will be scaled down if necessary to fit specified size. - `width` <[number]> Video frame width. - `height` <[number]> Video frame height. - - `videosPath` <[string]> **NOTE** Use `recordVideo` instead, it takes precedence over `videosPath`. Enables video recording for all pages to `videosPath` directory. If not specified, videos are not recorded. Make sure to await [`browserContext.close()`](#browsercontextclose) for videos to be saved. + - `videosPath` <[string]> **NOTE** Use `recordVideo` instead, it takes precedence over `videosPath`. Enables video recording for all pages to `videosPath` directory. If not specified, videos are not recorded. Make sure to await [browserContext.close()](#browsercontextclose) for videos to be saved. - `viewport` <[null]|[Object]> Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport. - `width` <[number]> page width in pixels. - `height` <[number]> page height in pixels. @@ -336,7 +334,7 @@ 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([options])`](#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([options])](#browsernewcontextoptions) followed by the [browserContext.newPage()](#browsercontextnewpage) to control their exact life times. #### browser.version() - returns: <[string]> @@ -364,7 +362,7 @@ await page.goto('https://example.com'); await context.close(); ``` - + - [browserContext.on('close')](#browsercontextonclose) - [browserContext.on('page')](#browsercontextonpage) - [browserContext.addCookies(cookies)](#browsercontextaddcookiescookies) @@ -389,19 +387,18 @@ await context.close(); - [browserContext.storageState([options])](#browsercontextstoragestateoptions) - [browserContext.unroute(url[, handler])](#browsercontextunrouteurl-handler) - [browserContext.waitForEvent(event[, optionsOrPredicate])](#browsercontextwaitforeventevent-optionsorpredicate) - #### browserContext.on('close') Emitted when Browser context gets closed. This might happen because of one of the following: * Browser context is closed. * Browser application is closed or crashed. -* The [`browser.close()`](#browserclose) method was called. +* The [browser.close()](#browserclose) method was called. #### browserContext.on('page') - type: <[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')`](#pageonpopup) 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')](#pageonpopup) 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. @@ -413,7 +410,7 @@ 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]>> @@ -428,7 +425,7 @@ console.log(await page.evaluate('location.href')); - `sameSite` <"Strict"|"Lax"|"None"> Optional. - returns: <[Promise]> -Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies can be obtained via [`browserContext.cookies([urls])`](#browsercontextcookiesurls). +Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies can be obtained via [browserContext.cookies([urls])](#browsercontextcookiesurls). ```js await browserContext.addCookies([cookieObject1, cookieObject2]); @@ -461,7 +458,7 @@ 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]> @@ -517,7 +514,7 @@ The method adds a function called `name` on the `window` object of every frame i The first argument of the `playwrightBinding` function contains information about the caller: `{ browserContext: BrowserContext, page: Page, frame: Frame }`. -See [`page.exposeBinding(name, playwrightBinding[, options])`](#pageexposebindingname-playwrightbinding-options) for page-only version. +See [page.exposeBinding(name, playwrightBinding[, options])](#pageexposebindingname-playwrightbinding-options) for page-only version. An example of exposing page URL to all frames in all pages in the context: @@ -566,7 +563,7 @@ The method adds a function called `name` on the `window` object of every frame i If the `playwrightFunction` returns a [Promise], it will be awaited. -See [`page.exposeFunction(name, playwrightFunction)`](#pageexposefunctionname-playwrightfunction) for page-only version. +See [page.exposeFunction(name, playwrightFunction)](#pageexposefunctionname-playwrightfunction) for page-only version. An example of adding an `md5` function to all pages in the context: @@ -624,7 +621,7 @@ Creates a new page in the browser context. #### browserContext.pages() - returns: <[Array]<[Page]>> -Returns all open pages in the context. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using [`chromiumBrowserContext.backgroundPages()`](#chromiumbrowsercontextbackgroundpages). +Returns all open pages in the context. Non visible pages, such as `"background_page"`, will not be listed here. You can find them using [chromiumBrowserContext.backgroundPages()](#chromiumbrowsercontextbackgroundpages). #### browserContext.route(url, handler) - `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> A glob pattern, regex pattern or predicate receiving [URL] to match while routing. @@ -653,7 +650,7 @@ 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. @@ -661,27 +658,27 @@ Page routes (set up with [`page.route(url, handler)`](#pagerouteurl-handler)) ta - `timeout` <[number]> Maximum navigation time in milliseconds This setting will change the default maximum navigation time for the following methods and related shortcuts: -* [`page.goBack([options])`](#pagegobackoptions) -* [`page.goForward([options])`](#pagegoforwardoptions) -* [`page.goto(url[, options])`](#pagegotourl-options) -* [`page.reload([options])`](#pagereloadoptions) -* [`page.setContent(html[, options])`](#pagesetcontenthtml-options) -* [`page.waitForNavigation([options])`](#pagewaitfornavigationoptions) +* [page.goBack([options])](#pagegobackoptions) +* [page.goForward([options])](#pagegoforwardoptions) +* [page.goto(url[, options])](#pagegotourl-options) +* [page.reload([options])](#pagereloadoptions) +* [page.setContent(html[, options])](#pagesetcontenthtml-options) +* [page.waitForNavigation([options])](#pagewaitfornavigationoptions) -> **NOTE** [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) and [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) take priority over [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout). +> **NOTE** [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout) and [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) take priority over [browserContext.setDefaultNavigationTimeout(timeout)](#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(timeout)`](#pagesetdefaultnavigationtimeouttimeout), [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) and [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout) take priority over [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout). +> **NOTE** [page.setDefaultNavigationTimeout(timeout)](#pagesetdefaultnavigationtimeouttimeout), [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) and [browserContext.setDefaultNavigationTimeout(timeout)](#browsercontextsetdefaultnavigationtimeouttimeout) take priority over [browserContext.setDefaultTimeout(timeout)](#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(headers)`](#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(headers)](#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. @@ -698,7 +695,7 @@ 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(permissions[, options])`](#browsercontextgrantpermissionspermissions-options) to grant permissions for the browser context pages to read its geolocation. +> **NOTE** Consider using [browserContext.grantPermissions(permissions[, options])](#browsercontextgrantpermissionspermissions-options) to grant permissions for the browser context pages to read its geolocation. #### browserContext.setHTTPCredentials(httpCredentials) - `httpCredentials` <[null]|[Object]> @@ -736,17 +733,17 @@ Provide credentials for [HTTP authentication](https://developer.mozilla.org/en-U Returns storage state for this browser context, contains current cookies and local storage snapshot. #### browserContext.unroute(url[, handler]) -- `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> A glob pattern, regex pattern or predicate receiving [URL] used to register a routing with [`browserContext.route(url, handler)`](#browsercontextrouteurl-handler). -- `handler` <[function]\([Route], [Request]\)> Optional handler function used to register a routing with [`browserContext.route(url, handler)`](#browsercontextrouteurl-handler). +- `url` <[string]|[RegExp]|[function]\([URL]\):[boolean]> A glob pattern, regex pattern or predicate receiving [URL] used to register a routing with [browserContext.route(url, handler)](#browsercontextrouteurl-handler). +- `handler` <[function]\([Route], [Request]\)> Optional 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)`. - `optionsOrPredicate` <[Function]|[Object]> Either a predicate that receives an event or an options object. Optional. - `predicate` <[Function]> receives the event data and resolves to truthy value when the waiting should resolve. - - `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout). + - `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout). - returns: <[Promise]<[Object]>> Waits for event to fire and passes its value into the predicate function. Returns when the predicate returns truthy value. Will throw an error if the context closes before the event is fired. Returns the event data value. @@ -797,7 +794,7 @@ page.on('request', logRequest); page.removeListener('request', logRequest); ``` - + - [page.on('close')](#pageonclose) - [page.on('console')](#pageonconsole) - [page.on('crash')](#pageoncrash) @@ -886,7 +883,6 @@ page.removeListener('request', logRequest); - [page.waitForSelector(selector[, options])](#pagewaitforselectorselector-options) - [page.waitForTimeout(timeout)](#pagewaitfortimeouttimeout) - [page.workers()](#pageworkers) - #### page.on('close') @@ -941,7 +937,7 @@ await new Promise((resolve, reject) => { #### page.on('dialog') - type: <[Dialog]> -Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via [`dialog.accept([promptText])`](#dialogacceptprompttext) or [`dialog.dismiss()`](#dialogdismiss) methods. +Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via [dialog.accept([promptText])](#dialogacceptprompttext) or [dialog.dismiss()](#dialogdismiss) methods. #### page.on('domcontentloaded') @@ -957,7 +953,7 @@ Emitted when attachment download started. User can access basic file operations #### page.on('filechooser') - type: <[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(files[, options])`](#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(files[, options])](#filechoosersetfilesfiles-options) that can be uploaded after that. ```js page.on('filechooser', async (fileChooser) => { @@ -992,7 +988,7 @@ Emitted when an uncaught exception happens within the page. #### page.on('popup') - type: <[Page]> -Emitted when the page opens a new tab or window. This event is emitted in addition to the [`browserContext.on('page')`](#browsercontextonpage), 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')](#browsercontextonpage), 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. @@ -1004,19 +1000,19 @@ 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). #### page.on('request') - type: <[Request]> -Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, see [`page.route(url, handler)`](#pagerouteurl-handler) or [`browserContext.route(url, handler)`](#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(url, handler)](#pagerouteurl-handler) or [browserContext.route(url, handler)](#browsercontextrouteurl-handler). #### page.on('requestfailed') - type: <[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 [`page.on('requestfinished')`](#pageonrequestfinished) event and not with [`page.on('requestfailed')`](#pageonrequestfailed). +> **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with [page.on('requestfinished')](#pageonrequestfinished) event and not with [page.on('requestfailed')](#pageonrequestfailed). #### page.on('requestfinished') - type: <[Request]> @@ -1044,7 +1040,7 @@ Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/We 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 main frame's [`frame.$(selector)`](#frameselector). +Shortcut for main frame's [frame.$(selector)](#frameselector). #### page.$$(selector) - `selector` <[string]> A selector to query for. See [working with selectors](#working-with-selectors) for more details. @@ -1052,7 +1048,7 @@ Shortcut for main frame's [`frame.$(selector)`](#frameselector). 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 main frame's [`frame.$$(selector)`](#frameselector). +Shortcut for main frame's [frame.$$(selector)](#frameselector-1). #### page.$eval(selector, pageFunction[, arg]) - `selector` <[string]> A selector to query for. See [working with selectors](#working-with-selectors) for more details. @@ -1062,7 +1058,7 @@ Shortcut for main frame's [`frame.$$(selector)`](#frameselector). 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. Returns the value of `pageFunction`. -If `pageFunction` returns a [Promise], then [`page.$eval(selector, pageFunction[, arg])`](#pageevalselector-pagefunction-arg) would wait for the promise to resolve and return its value. +If `pageFunction` returns a [Promise], then [page.$eval(selector, pageFunction[, arg])](#pageevalselector-pagefunction-arg) would wait for the promise to resolve and return its value. Examples: @@ -1072,7 +1068,7 @@ const preloadHref = await page.$eval('link[rel=preload]', el => el.href); const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello'); ``` -Shortcut for main frame's [`frame.$eval(selector, pageFunction[, arg])`](#frameevalselector-pagefunction-arg). +Shortcut for main frame's [frame.$eval(selector, pageFunction[, arg])](#frameevalselector-pagefunction-arg). #### page.$$eval(selector, pageFunction[, arg]) - `selector` <[string]> A selector to query for. See [working with selectors](#working-with-selectors) for more details. @@ -1082,7 +1078,7 @@ Shortcut for main frame's [`frame.$eval(selector, pageFunction[, arg])`](#framee 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`. Returns the result of `pageFunction` invocation. -If `pageFunction` returns a [Promise], then [`page.$$eval(selector, pageFunction[, arg])`](#pageevalselector-pagefunction-arg) would wait for the promise to resolve and return its value. +If `pageFunction` returns a [Promise], then [page.$$eval(selector, pageFunction[, arg])](#pageevalselector-pagefunction-arg-1) would wait for the promise to resolve and return its value. Examples: @@ -1117,7 +1113,7 @@ 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(params) - `params` <[Object]> @@ -1129,7 +1125,7 @@ await page.addInitScript(preloadFile); Adds a `