From a446792c18292dae6e0bef1a6178be6d4e1091d3 Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Mon, 28 Dec 2020 07:03:09 -0800 Subject: [PATCH] docs: generate api.md off documentation model (#4832) --- docs-src/api-body.md | 52 +- docs-src/api-footer.md | 60 - docs-src/api-links.md | 25 + docs-src/api-params.md | 2 +- docs/api.md | 242 ++- types/types.d.ts | 2033 ++++++++++++------- utils/doclint/check_public_api/MDBuilder.js | 134 +- utils/doclint/check_public_api/index.js | 2 +- utils/doclint/cli.js | 194 +- utils/doclint/preprocessor/index.js | 45 +- utils/parse_md.js | 5 +- 11 files changed, 1657 insertions(+), 1137 deletions(-) create mode 100644 docs-src/api-links.md diff --git a/docs-src/api-body.md b/docs-src/api-body.md index 7b0740af19..eae73d15ee 100644 --- a/docs-src/api-body.md +++ b/docs-src/api-body.md @@ -827,12 +827,12 @@ Emitted when a frame is navigated to a new url. Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. ## event: Page.pageerror -- type: <[Error]> The exception message +- type: <[Error]> Emitted when an uncaught exception happens within the page. ## event: Page.popup -- type: <[Page]> Page corresponding to "popup" window +- type: <[Page]> Emitted when the page opens a new tab or window. This event is emitted in addition to the [`event: BrowserContext.page`](), but only for popups relevant to this page. @@ -879,7 +879,7 @@ Emitted when [response] status and headers are received for a request. For a suc is `request`, `response` and `requestfinished`. ## event: Page.websocket -- type: <[WebSocket]> websocket +- type: <[WebSocket]> Emitted when <[WebSocket]> request is sent. @@ -1046,7 +1046,7 @@ This method checks an element matching [`param: selector`]() by performing the f 1. Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless [`option: force`]() option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element. +1. Use [`property: Page.mouse`]() to click in the center of the element. 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. 1. Ensure that the element is now checked. If not, this method rejects. @@ -1069,7 +1069,7 @@ This method clicks an element matching [`param: selector`]() by performing the f 1. Find an element match matching [`param: selector`](). If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless [`option: force`]() option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element, or the specified [`option: position`](). +1. Use [`property: Page.mouse`]() to click in the center of the element, or the specified [`option: position`](). 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. When all steps combined have not finished during the specified [`option: timeout`](), this method rejects with a @@ -1134,7 +1134,7 @@ This method double clicks an element matching [`param: selector`]() by performin 1. Find an element match matching [`param: selector`](). If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless [`option: force`]() option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to double click in the center of the element, or the specified [`option: position`](). +1. Use [`property: Page.mouse`]() to double click in the center of the element, or the specified [`option: position`](). 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject. When all steps combined have not finished during the specified [`option: timeout`](), this method rejects with a @@ -1608,7 +1608,7 @@ This method hovers over an element matching [`param: selector`]() by performing 1. Find an element match matching [`param: selector`](). If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless [`option: force`]() option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to hover over the center of the element, or the specified [`option: position`](). +1. Use [`property: Page.mouse`]() to hover over the center of the element, or the specified [`option: position`](). 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. When all steps combined have not finished during the specified [`option: timeout`](), this method rejects with a @@ -2075,7 +2075,7 @@ This method taps an element matching [`param: selector`]() by performing the fol 1. Find an element match matching [`param: selector`](). If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless [`option: force`]() option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.touchscreen](#pagetouchscreen#pagetouchscreen) to tap the center of the element, or the specified [`option: position`](). +1. Use [`property: Page.touchscreen`]() to tap the center of the element, or the specified [`option: position`](). 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. When all steps combined have not finished during the specified [`option: timeout`](), this method rejects with a @@ -2151,7 +2151,7 @@ This method unchecks an element matching [`param: selector`]() by performing the 1. Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless [`option: force`]() option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element. +1. Use [`property: Page.mouse`]() to click in the center of the element. 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. 1. Ensure that the element is now unchecked. If not, this method rejects. @@ -2602,7 +2602,7 @@ This method checks an element matching [`param: selector`]() by performing the f 1. Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless [`option: force`]() option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element. +1. Use [`property: Page.mouse`]() to click in the center of the element. 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. 1. Ensure that the element is now checked. If not, this method rejects. @@ -2626,7 +2626,7 @@ This method clicks an element matching [`param: selector`]() by performing the f 1. Find an element match matching [`param: selector`](). If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless [`option: force`]() option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element, or the specified [`option: position`](). +1. Use [`property: Page.mouse`]() to click in the center of the element, or the specified [`option: position`](). 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. When all steps combined have not finished during the specified [`option: timeout`](), this method rejects with a @@ -2661,7 +2661,7 @@ This method double clicks an element matching [`param: selector`]() by performin 1. Find an element match matching [`param: selector`](). If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless [`option: force`]() option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to double click in the center of the element, or the specified [`option: position`](). +1. Use [`property: Page.mouse`]() to double click in the center of the element, or the specified [`option: position`](). 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject. When all steps combined have not finished during the specified [`option: timeout`](), this method rejects with a @@ -2916,7 +2916,7 @@ This method hovers over an element matching [`param: selector`]() by performing 1. Find an element match matching [`param: selector`](). If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless [`option: force`]() option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to hover over the center of the element, or the specified [`option: position`](). +1. Use [`property: Page.mouse`]() to hover over the center of the element, or the specified [`option: position`](). 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. When all steps combined have not finished during the specified [`option: timeout`](), this method rejects with a @@ -3079,7 +3079,7 @@ This method taps an element matching [`param: selector`]() by performing the fol 1. Find an element match matching [`param: selector`](). If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless [`option: force`]() option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.touchscreen](#pagetouchscreen#pagetouchscreen) to tap the center of the element, or the specified [`option: position`](). +1. Use [`property: Page.touchscreen`]() to tap the center of the element, or the specified [`option: position`](). 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. When all steps combined have not finished during the specified [`option: timeout`](), this method rejects with a @@ -3148,7 +3148,7 @@ This method checks an element matching [`param: selector`]() by performing the f 1. Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless [`option: force`]() option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element. +1. Use [`property: Page.mouse`]() to click in the center of the element. 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. 1. Ensure that the element is now unchecked. If not, this method rejects. @@ -3460,7 +3460,7 @@ This method checks the element by performing the following steps: 1. Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. 1. Wait for [actionability](./actionability.md) checks on the element, unless [`option: force`]() option is set. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element. +1. Use [`property: Page.mouse`]() to click in the center of the element. 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. 1. Ensure that the element is now checked. If not, this method rejects. @@ -3480,7 +3480,7 @@ When all steps combined have not finished during the specified [`option: timeout This method clicks the element by performing the following steps: 1. Wait for [actionability](./actionability.md) checks on the element, unless [`option: force`]() option is set. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element, or the specified [`option: position`](). +1. Use [`property: Page.mouse`]() to click in the center of the element, or the specified [`option: position`](). 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. If the element is detached from the DOM at any moment during the action, this method rejects. @@ -3514,7 +3514,7 @@ Returns the content frame for element handles referencing iframe nodes, or `null This method double clicks the element by performing the following steps: 1. Wait for [actionability](./actionability.md) checks on the element, unless [`option: force`]() option is set. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to double click in the center of the element, or the specified [`option: position`](). +1. Use [`property: Page.mouse`]() to double click in the center of the element, or the specified [`option: position`](). 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject. If the element is detached from the DOM at any moment during the action, this method rejects. @@ -3613,7 +3613,7 @@ Attribute name to get the value for. This method hovers over the element by performing the following steps: 1. Wait for [actionability](./actionability.md) checks on the element, unless [`option: force`]() option is set. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to hover over the center of the element, or the specified [`option: position`](). +1. Use [`property: Page.mouse`]() to hover over the center of the element, or the specified [`option: position`](). 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. If the element is detached from the DOM at any moment during the action, this method rejects. @@ -3786,7 +3786,7 @@ are resolved relative to the the current working directory. For empty array, cle This method taps the element by performing the following steps: 1. Wait for [actionability](./actionability.md) checks on the element, unless [`option: force`]() option is set. 1. Scroll the element into view if needed. -1. Use [page.touchscreen](#pagetouchscreen) to tap in the center of the element, or the specified [`option: position`](). +1. Use [`property: Page.touchscreen`]() to tap the center of the element, or the specified [`option: position`](). 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. If the element is detached from the DOM at any moment during the action, this method rejects. @@ -3853,7 +3853,7 @@ This method checks the element by performing the following steps: 1. Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately. 1. Wait for [actionability](./actionability.md) checks on the element, unless [`option: force`]() option is set. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element. +1. Use [`property: Page.mouse`]() to click in the center of the element. 1. Wait for initiated navigations to either succeed or fail, unless [`option: noWaitAfter`]() option is set. 1. Ensure that the element is now unchecked. If not, this method rejects. @@ -4399,7 +4399,7 @@ Name of the key to press or a character to generate, such as `ArrowLeft` or `a`. The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. -Every `page` object has its own Mouse, accessible with [page.mouse](#pagemouse). +Every `page` object has its own Mouse, accessible with [`property: Page.mouse`](). ```js // Using ‘page.mouse’ to trace a 100x100 square. @@ -4874,19 +4874,19 @@ The [WebSocket] class represents websocket connections in the page. Fired when the websocket closes. ## event: WebSocket.framereceived -- type: <[Object]> web socket frame data +- type: <[Object]> - `payload` <[string]|[Buffer]> frame payload Fired when the websocket recieves a frame. ## event: WebSocket.framesent -- type: <[Object]> web socket frame data +- type: <[Object]> - `payload` <[string]|[Buffer]> frame payload Fired when the websocket sends a frame. ## event: WebSocket.socketerror -- type: <[String]> the error message +- type: <[String]> Fired when the websocket has an error. @@ -4972,7 +4972,7 @@ assistive technologies themselves. By default, Playwright tries to approximate t - `haspopup` <[string]> What kind of popup is currently being shown for a node, if applicable. - `invalid` <[string]> Whether and in what way this node's value is invalid, if applicable. - `orientation` <[string]> Whether the node is oriented horizontally or vertically, if applicable. - - `children` <[Array]<[Object]>> Child [AXNode]s of this node, if any, if applicable. + - `children` <[Array]<[Object]>> Child nodes, if any, if applicable. Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page. diff --git a/docs-src/api-footer.md b/docs-src/api-footer.md index 287c9e9e28..cccd1dab1b 100644 --- a/docs-src/api-footer.md +++ b/docs-src/api-footer.md @@ -155,63 +155,3 @@ const { chromium } = require('playwright'); > **NOTE** It is not yet possible to test extension popups or content scripts. -[AXNode]: #accessibilitysnapshotoptions "AXNode" -[Accessibility]: #class-accessibility "Accessibility" -[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array" -[Body]: #class-body "Body" -[BrowserServer]: #class-browserserver "BrowserServer" -[BrowserContext]: #class-browsercontext "BrowserContext" -[BrowserType]: #class-browsertype "BrowserType" -[Browser]: #class-browser "Browser" -[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer" -[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess" -[ChromiumBrowser]: #class-chromiumbrowser "ChromiumBrowser" -[ChromiumBrowserContext]: #class-chromiumbrowsercontext "ChromiumBrowserContext" -[ChromiumCoverage]: #class-chromiumcoverage "ChromiumCoverage" -[CDPSession]: #class-cdpsession "CDPSession" -[ConsoleMessage]: #class-consolemessage "ConsoleMessage" -[Dialog]: #class-dialog "Dialog" -[Download]: #class-download "Download" -[ElementHandle]: #class-elementhandle "ElementHandle" -[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" -[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error" -[EvaluationArgument]: #evaluationargument "Evaluation Argument" -[File]: #class-file "https://developer.mozilla.org/en-US/docs/Web/API/File" -[FileChooser]: #class-filechooser "FileChooser" -[FirefoxBrowser]: #class-firefoxbrowser "FirefoxBrowser" -[Frame]: #class-frame "Frame" -[JSHandle]: #class-jshandle "JSHandle" -[Keyboard]: #class-keyboard "Keyboard" -[Logger]: #class-logger "Logger" -[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map" -[Mouse]: #class-mouse "Mouse" -[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object" -[Page]: #class-page "Page" -[Playwright]: #class-playwright "Playwright" -[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise" -[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp -[Request]: #class-request "Request" -[Response]: #class-response "Response" -[Route]: #class-route "Route" -[Selectors]: #class-selectors "Selectors" -[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable" -[TimeoutError]: #class-timeouterror "TimeoutError" -[Touchscreen]: #class-touchscreen "Touchscreen" -[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail" -[URL]: https://nodejs.org/api/url.html -[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout" -[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time" -[Video]: #class-video "Video" -[WebKitBrowser]: #class-webkitbrowser "WebKitBrowser" -[WebSocket]: #class-websocket "WebSocket" -[Worker]: #class-worker "Worker" -[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean" -[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function "Function" -[iterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols "Iterator" -[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null -[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number" -[origin]: https://developer.mozilla.org/en-US/docs/Glossary/Origin "Origin" -[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector" -[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable" -[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String" -[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath" diff --git a/docs-src/api-links.md b/docs-src/api-links.md new file mode 100644 index 0000000000..3a3cd3cf4b --- /dev/null +++ b/docs-src/api-links.md @@ -0,0 +1,25 @@ +[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array" +[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer" +[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess" +[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" +[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error" +[EvaluationArgument]: #evaluationargument "Evaluation Argument" +[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map" +[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object" +[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise" +[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp" +[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable" +[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail" +[URL]: https://nodejs.org/api/url.html "URL" +[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout" +[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time" +[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean" +[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function "Function" +[iterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols "Iterator" +[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null" +[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number" +[origin]: https://developer.mozilla.org/en-US/docs/Glossary/Origin "Origin" +[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector" +[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable" +[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string" +[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath" diff --git a/docs-src/api-params.md b/docs-src/api-params.md index f980fb84ae..2085f50f40 100644 --- a/docs-src/api-params.md +++ b/docs-src/api-params.md @@ -170,7 +170,7 @@ Whether or not to enable JavaScript in the context. Defaults to `true`. ## context-option-timezoneid - `timezoneId` <[string]> -Changes the timezone of the context. See [ICU’s `metaZones.txt`](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) +Changes the timezone of the context. See [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. ## context-option-geolocation diff --git a/docs/api.md b/docs/api.md index ccfeef1312..48c435e875 100644 --- a/docs/api.md +++ b/docs/api.md @@ -132,6 +132,8 @@ Selectors can be used to install custom selector engines. See [Working with sele This object can be used to launch or connect to WebKit, returning instances of [WebKitBrowser]. +[Playwright]: #class-playwright "Playwright" + ### class: Browser * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) @@ -246,7 +248,7 @@ Indicates that the browser is connected. - `localStorage` <[Array]<[Object]>> - `name` <[string]> - `value` <[string]> - - `timezoneId` <[string]> Changes the timezone of the context. See [ICU’s `metaZones.txt`](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. + - `timezoneId` <[string]> Changes the timezone of the context. See [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. - `userAgent` <[string]> Specific user agent to use in this context. - `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. @@ -321,7 +323,7 @@ Creates a new browser context. It won't share cookies/cache with other browser c - `localStorage` <[Array]<[Object]>> - `name` <[string]> - `value` <[string]> - - `timezoneId` <[string]> Changes the timezone of the context. See [ICU’s `metaZones.txt`](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. + - `timezoneId` <[string]> Changes the timezone of the context. See [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. - `userAgent` <[string]> Specific user agent to use in this context. - `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. @@ -341,6 +343,8 @@ This is a convenience API that should only be used for the single-page scenarios Returns the browser version. +[Browser]: #class-browser "Browser" + ### class: BrowserContext * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) @@ -397,7 +401,7 @@ Emitted when Browser context gets closed. This might happen because of one of th #### 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. @@ -752,6 +756,8 @@ const context = await browser.newContext(); await context.grantPermissions(['geolocation']); ``` +[BrowserContext]: #class-browsercontext "BrowserContext" + ### class: Page * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) @@ -979,14 +985,14 @@ Emitted when a frame is navigated to a new url. Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. #### page.on('pageerror') -- type: <[Error]> The exception message +- type: <[Error]> Emitted when an uncaught exception happens within the page. #### page.on('popup') -- type: <[Page]> Page corresponding to "popup" window +- 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. @@ -1010,7 +1016,7 @@ Emitted when a page issues a request. The [request] object is read-only. In orde 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]> @@ -1023,7 +1029,7 @@ Emitted when a request finishes successfully after downloading the response body Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events is `request`, `response` and `requestfinished`. #### page.on('websocket') -- type: <[WebSocket]> websocket +- type: <[WebSocket]> Emitted when <[WebSocket]> request is sent. @@ -1154,7 +1160,7 @@ This method checks an element matching `selector` by performing the following st 1. Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element. +1. Use [`page.mouse`](#pagemouse) to click in the center of the element. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. 1. Ensure that the element is now checked. If not, this method rejects. @@ -1181,7 +1187,7 @@ This method clicks an element matching `selector` by performing the following st 1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element, or the specified `position`. +1. Use [`page.mouse`](#pagemouse) to click in the center of the element, or the specified `position`. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this. @@ -1198,7 +1204,7 @@ If `runBeforeUnload` is `false`, does not run any unload handlers and waits for By default, `page.close()` **does not** run `beforeunload` handlers. > **NOTE** if `runBeforeUnload` is passed as true, a `beforeunload` dialog might be summoned -> and should be handled manually via [page.on('dialog')](#pageondialog) event. +> and should be handled manually via [`page.on('dialog')`](#pageondialog) event. #### page.content() - returns: <[Promise]<[string]>> @@ -1233,7 +1239,7 @@ This method double clicks an element matching `selector` by performing the follo 1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to double click in the center of the element, or the specified `position`. +1. Use [`page.mouse`](#pagemouse) to double click in the center of the element, or the specified `position`. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject. When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this. @@ -1614,7 +1620,7 @@ This method hovers over an element matching `selector` by performing the followi 1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to hover over the center of the element, or the specified `position`. +1. Use [`page.mouse`](#pagemouse) to hover over the center of the element, or the specified `position`. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this. @@ -1943,7 +1949,7 @@ This method taps an element matching `selector` by performing the following step 1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.touchscreen](#pagetouchscreen#pagetouchscreen) to tap the center of the element, or the specified `position`. +1. Use [`page.touchscreen`](#pagetouchscreen) to tap the center of the element, or the specified `position`. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this. @@ -2001,7 +2007,7 @@ This method unchecks an element matching `selector` by performing the following 1. Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element. +1. Use [`page.mouse`](#pagemouse) to click in the center of the element. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. 1. Ensure that the element is now unchecked. If not, this method rejects. @@ -2218,14 +2224,16 @@ This method returns all of the dedicated [WebWorkers](https://developer.mozilla. > **NOTE** This does not contain ServiceWorkers +[Page]: #class-page "Page" + ### class: Frame At every point of time, page exposes its current frame tree via the [`page.mainFrame()`](#pagemainframe) and [`frame.childFrames()`](#framechildframes) methods. [Frame] object's lifecycle is controlled by three events, dispatched on the page object: -* [page.on('frameattached')](#pageonframeattached) - fired when the frame gets attached to the page. A Frame can be attached to the page only once. -* [page.on('framenavigated')](#pageonframenavigated) - fired when the frame commits navigation to a different URL. -* [page.on('framedetached')](#pageonframedetached) - fired when the frame gets detached from the page. A Frame can be detached from the page only once. +* [`page.on('frameattached')`](#pageonframeattached) - fired when the frame gets attached to the page. A Frame can be attached to the page only once. +* [`page.on('framenavigated')`](#pageonframenavigated) - fired when the frame commits navigation to a different URL. +* [`page.on('framedetached')`](#pageonframedetached) - fired when the frame gets detached from the page. A Frame can be detached from the page only once. An example of dumping frame tree: @@ -2390,7 +2398,7 @@ This method checks an element matching `selector` by performing the following st 1. Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element. +1. Use [`page.mouse`](#pagemouse) to click in the center of the element. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. 1. Ensure that the element is now checked. If not, this method rejects. @@ -2418,7 +2426,7 @@ This method clicks an element matching `selector` by performing the following st 1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element, or the specified `position`. +1. Use [`page.mouse`](#pagemouse) to click in the center of the element, or the specified `position`. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this. @@ -2446,7 +2454,7 @@ This method double clicks an element matching `selector` by performing the follo 1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to double click in the center of the element, or the specified `position`. +1. Use [`page.mouse`](#pagemouse) to double click in the center of the element, or the specified `position`. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject. When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this. @@ -2633,7 +2641,7 @@ This method hovers over an element matching `selector` by performing the followi 1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to hover over the center of the element, or the specified `position`. +1. Use [`page.mouse`](#pagemouse) to hover over the center of the element, or the specified `position`. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this. @@ -2766,7 +2774,7 @@ This method taps an element matching `selector` by performing the following step 1. Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.touchscreen](#pagetouchscreen#pagetouchscreen) to tap the center of the element, or the specified `position`. +1. Use [`page.touchscreen`](#pagetouchscreen) to tap the center of the element, or the specified `position`. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. When all steps combined have not finished during the specified `timeout`, this method rejects with a [TimeoutError]. Passing zero timeout disables this. @@ -2817,7 +2825,7 @@ This method checks an element matching `selector` by performing the following st 1. Ensure that matched element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately. 1. Wait for [actionability](./actionability.md) checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element. +1. Use [`page.mouse`](#pagemouse) to click in the center of the element. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. 1. Ensure that the element is now unchecked. If not, this method rejects. @@ -2943,6 +2951,8 @@ Waits for the given `timeout` in milliseconds. Note that `frame.waitForTimeout()` should only be used for debugging. Tests using the timer in production are going to be flaky. Use signals such as network events, selectors becoming visible and others instead. +[Frame]: #class-frame "Frame" + ### class: ElementHandle * extends: [JSHandle] @@ -3097,7 +3107,7 @@ This method checks the element by performing the following steps: 1. Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already checked, this method returns immediately. 1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element. +1. Use [`page.mouse`](#pagemouse) to click in the center of the element. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. 1. Ensure that the element is now checked. If not, this method rejects. @@ -3122,7 +3132,7 @@ When all steps combined have not finished during the specified `timeout`, this m This method clicks the element by performing the following steps: 1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element, or the specified `position`. +1. Use [`page.mouse`](#pagemouse) to click in the center of the element, or the specified `position`. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. If the element is detached from the DOM at any moment during the action, this method rejects. @@ -3150,7 +3160,7 @@ Returns the content frame for element handles referencing iframe nodes, or `null This method double clicks the element by performing the following steps: 1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to double click in the center of the element, or the specified `position`. +1. Use [`page.mouse`](#pagemouse) to double click in the center of the element, or the specified `position`. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. Note that if the first click of the `dblclick()` triggers a navigation event, this method will reject. If the element is detached from the DOM at any moment during the action, this method rejects. @@ -3222,7 +3232,7 @@ Returns element attribute value. This method hovers over the element by performing the following steps: 1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to hover over the center of the element, or the specified `position`. +1. Use [`page.mouse`](#pagemouse) to hover over the center of the element, or the specified `position`. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. If the element is detached from the DOM at any moment during the action, this method rejects. @@ -3351,7 +3361,7 @@ Sets the value of the file input to these file paths or files. If some of the `f This method taps the element by performing the following steps: 1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set. 1. Scroll the element into view if needed. -1. Use [page.touchscreen](#pagetouchscreen) to tap in the center of the element, or the specified `position`. +1. Use [`page.touchscreen`](#pagetouchscreen) to tap the center of the element, or the specified `position`. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. If the element is detached from the DOM at any moment during the action, this method rejects. @@ -3404,7 +3414,7 @@ This method checks the element by performing the following steps: 1. Ensure that element is a checkbox or a radio input. If not, this method rejects. If the element is already unchecked, this method returns immediately. 1. Wait for [actionability](./actionability.md) checks on the element, unless `force` option is set. 1. Scroll the element into view if needed. -1. Use [page.mouse](#pagemouse) to click in the center of the element. +1. Use [`page.mouse`](#pagemouse) to click in the center of the element. 1. Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set. 1. Ensure that the element is now unchecked. If not, this method rejects. @@ -3453,6 +3463,8 @@ const span = await div.waitForSelector('span', { state: 'attached' }); > **NOTE** This method does not work across navigations, use [`page.waitForSelector(selector[, options])`](#pagewaitforselectorselector-options) instead. +[ElementHandle]: #class-elementhandle "ElementHandle" + ### class: JSHandle JSHandle represents an in-page JavaScript object. JSHandles can be created with the [`page.evaluateHandle(pageFunction[, arg])`](#pageevaluatehandlepagefunction-arg) method. @@ -3545,9 +3557,11 @@ Returns a JSON representation of the object. If the object has a `toJSON` functi > **NOTE** The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an error if the object has circular references. +[JSHandle]: #class-jshandle "JSHandle" + ### class: ConsoleMessage -[ConsoleMessage] objects are dispatched by page via the [page.on('console')](#pageonconsole) event. +[ConsoleMessage] objects are dispatched by page via the [`page.on('console')`](#pageonconsole) event. - [consoleMessage.args()](#consolemessageargs) @@ -3573,9 +3587,11 @@ Returns a JSON representation of the object. If the object has a `toJSON` functi One of the following values: `'log'`, `'debug'`, `'info'`, `'error'`, `'warning'`, `'dir'`, `'dirxml'`, `'table'`, `'trace'`, `'clear'`, `'startGroup'`, `'startGroupCollapsed'`, `'endGroup'`, `'assert'`, `'profile'`, `'profileEnd'`, `'count'`, `'timeEnd'`. +[ConsoleMessage]: #class-consolemessage "ConsoleMessage" + ### class: Dialog -[Dialog] objects are dispatched by page via the [page.on('dialog')](#pageondialog) event. +[Dialog] objects are dispatched by page via the [`page.on('dialog')`](#pageondialog) event. An example of using `Dialog` class: @@ -3628,9 +3644,11 @@ A message displayed in the dialog. Returns dialog's type, can be one of `alert`, `beforeunload`, `confirm` or `prompt`. +[Dialog]: #class-dialog "Dialog" + ### class: Download -[Download] objects are dispatched by page via the [page.on('download')](#pageondownload) event. +[Download] objects are dispatched by page via the [`page.on('download')`](#pageondownload) event. All the downloaded files belonging to the browser context are deleted when the browser context is closed. All downloaded files are deleted when the browser closes. @@ -3694,6 +3712,8 @@ Returns suggested filename for this download. It is typically computed by the br Returns downloaded url. +[Download]: #class-download "Download" + ### class: Video When browser context is created with the `videosPath` option, each page has a video object associated with it. @@ -3711,9 +3731,11 @@ console.log(await page.video().path()); Returns the file system path this video will be recorded to. The video is guaranteed to be written to the filesystem upon closing the browser context. +[Video]: #class-video "Video" + ### class: FileChooser -[FileChooser] objects are dispatched by the page in the [page.on('filechooser')](#pageonfilechooser) event. +[FileChooser] objects are dispatched by the page in the [`page.on('filechooser')`](#pageonfilechooser) event. ```js page.on('filechooser', async (fileChooser) => { @@ -3755,6 +3777,8 @@ Returns page this file chooser belongs to. Sets the value of the file input this chooser is associated with. If some of the `filePaths` are relative paths, then they are resolved relative to the the current working directory. For empty array, clears the selected files. +[FileChooser]: #class-filechooser "FileChooser" + ### class: Keyboard Keyboard provides an api for managing a virtual keyboard. The high level api is [`keyboard.type(text[, options])`](#keyboardtypetext-options), which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. @@ -3890,11 +3914,13 @@ await page.keyboard.type('World', {delay: 100}); // Types slower, like a user Dispatches a `keyup` event. +[Keyboard]: #class-keyboard "Keyboard" + ### class: Mouse The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. -Every `page` object has its own Mouse, accessible with [page.mouse](#pagemouse). +Every `page` object has its own Mouse, accessible with [`page.mouse`](#pagemouse). ```js // Using ‘page.mouse’ to trace a 100x100 square. @@ -3961,6 +3987,8 @@ Dispatches a `mousemove` event. Dispatches a `mouseup` event. +[Mouse]: #class-mouse "Mouse" + ### class: Touchscreen The Touchscreen class operates in main-frame CSS pixels relative to the top-left corner of the viewport. Methods on the touchscreen can only be used in browser contexts that have been intialized with `hasTouch` set to true. @@ -3972,14 +4000,16 @@ The Touchscreen class operates in main-frame CSS pixels relative to the top-left Dispatches a `touchstart` and `touchend` event with a single touch at the position (`x`,`y`). +[Touchscreen]: #class-touchscreen "Touchscreen" + ### class: Request Whenever the page sends a request for a network resource the following sequence of events are emitted by [Page]: -* [page.on('request')](#pageonrequest) emitted when the request is issued by the page. -* [page.on('response')](#pageonresponse) emitted when/if the response status and headers are received for the request. -* [page.on('requestfinished')](#pageonrequestfinished) emitted when the response body is downloaded and the request is complete. +* [`page.on('request')`](#pageonrequest) emitted when the request is issued by the page. +* [`page.on('response')`](#pageonresponse) emitted when/if the response status and headers are received for the request. +* [`page.on('requestfinished')`](#pageonrequestfinished) emitted when the response body is downloaded and the request is complete. -If request fails at some point, then instead of `'requestfinished'` event (and possibly instead of 'response' event), the [page.on('requestfailed')](#pageonrequestfailed) event is emitted. +If request fails at some point, then instead of `'requestfinished'` event (and possibly instead of 'response' event), the [`page.on('requestfailed')`](#pageonrequestfailed) event is emitted. > **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with `'requestfinished'` event. @@ -4122,6 +4152,8 @@ console.log(request.timing()); URL of the request. +[Request]: #class-request "Request" + ### class: Response [Response] class represents responses which are received by page. @@ -4197,6 +4229,8 @@ Returns the text representation of response body. Contains the URL of the response. +[Response]: #class-response "Response" + ### class: Selectors Selectors can be used to install custom selector engines. See [Working with selectors](#working-with-selectors) for more information. @@ -4251,6 +4285,8 @@ const { selectors, firefox } = require('playwright'); // Or 'chromium' or 'webk })(); ``` +[Selectors]: #class-selectors "Selectors" + ### class: Route Whenever a network route is set up with [`page.route(url, handler)`](#pagerouteurl-handler) or [`browserContext.route(url, handler)`](#browsercontextrouteurl-handler), the `Route` object allows to handle the route. @@ -4338,6 +4374,8 @@ await page.route('**/xhr_endpoint', route => route.fulfill({ path: 'mock_data.js A request to be routed. +[Route]: #class-route "Route" + ### class: WebSocket The [WebSocket] class represents websocket connections in the page. @@ -4357,19 +4395,19 @@ The [WebSocket] class represents websocket connections in the page. Fired when the websocket closes. #### webSocket.on('framereceived') -- type: <[Object]> web socket frame data +- type: <[Object]> - `payload` <[string]|[Buffer]> frame payload Fired when the websocket recieves a frame. #### webSocket.on('framesent') -- type: <[Object]> web socket frame data +- type: <[Object]> - `payload` <[string]|[Buffer]> frame payload Fired when the websocket sends a frame. #### webSocket.on('socketerror') -- type: <[String]> the error message +- type: <[String]> Fired when the websocket has an error. @@ -4394,11 +4432,15 @@ Returns the event data value. 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 webSocket is closed before the event is fired. +[WebSocket]: #class-websocket "WebSocket" + ### class: TimeoutError * extends: [Error] TimeoutError is emitted whenever certain operations are terminated due to timeout, e.g. [`page.waitForSelector(selector[, options])`](#pagewaitforselectorselector-options) or [`browserType.launch([options])`](#browsertypelaunchoptions). +[TimeoutError]: #class-timeouterror "TimeoutError" + ### class: Accessibility The Accessibility class provides methods for inspecting Chromium's accessibility tree. The accessibility tree is used by assistive technology such as [screen readers](https://en.wikipedia.org/wiki/Screen_reader) or [switches](https://en.wikipedia.org/wiki/Switch_access). @@ -4434,8 +4476,8 @@ Most of the accessibility tree gets filtered out when converting from Blink AX T - `readonly` <[boolean]> Whether the node is read only, if applicable. - `required` <[boolean]> Whether the node is required, if applicable. - `selected` <[boolean]> Whether the node is selected in its parent node, if applicable. - - `checked` <[boolean]|"mixed"> Whether the checkbox is checked, or "mixed", if applicable. - - `pressed` <[boolean]|"mixed"> Whether the toggle button is checked, or "mixed", if applicable. + - `checked` Whether the checkbox is checked, or "mixed", if applicable. + - `pressed` Whether the toggle button is checked, or "mixed", if applicable. - `level` <[number]> The level of a heading, if applicable. - `valuemin` <[number]> The minimum value in a node, if applicable. - `valuemax` <[number]> The maximum value in a node, if applicable. @@ -4443,7 +4485,7 @@ Most of the accessibility tree gets filtered out when converting from Blink AX T - `haspopup` <[string]> What kind of popup is currently being shown for a node, if applicable. - `invalid` <[string]> Whether and in what way this node's value is invalid, if applicable. - `orientation` <[string]> Whether the node is oriented horizontally or vertically, if applicable. - - `children` <[Array]<[Object]>> Child [AXNode]s of this node, if any, if applicable. + - `children` <[Array]<[Object]>> Child nodes, if any, if applicable. Captures the current state of the accessibility tree. The returned object represents the root accessible node of the page. @@ -4474,6 +4516,8 @@ function findFocusedNode(node) { } ``` +[Accessibility]: #class-accessibility "Accessibility" + ### class: Worker The Worker class represents a [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). `worker` event is emitted on the page object to signal a worker creation. `close` event is emitted on the worker object when the worker is gone. @@ -4526,6 +4570,8 @@ If the function passed to the `worker.evaluateHandle` returns a [Promise], then #### worker.url() - returns: <[string]> +[Worker]: #class-worker "Worker" + ### class: BrowserServer @@ -4562,6 +4608,8 @@ Browser websocket url. Browser websocket endpoint which can be used as an argument to [`browserType.connect(params)`](#browsertypeconnectparams) to establish connection to the browser. +[BrowserServer]: #class-browserserver "BrowserServer" + ### class: BrowserType BrowserType provides methods to launch a specific browser instance or connect to an existing one. The following is a typical example of using Playwright to drive automation: @@ -4693,7 +4741,7 @@ const browser = await chromium.launch({ // Or 'firefox' or 'webkit'. - `height` <[number]> Video frame height. - `slowMo` <[number]> Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on. Defaults to 0. - `timeout` <[number]> Maximum time in milliseconds to wait for the browser instance to start. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - - `timezoneId` <[string]> Changes the timezone of the context. See [ICU’s `metaZones.txt`](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. + - `timezoneId` <[string]> Changes the timezone of the context. See [ICU's metaZones.txt](https://cs.chromium.org/chromium/src/third_party/icu/source/data/misc/metaZones.txt?rcl=faee8bc70570192d82d2978a71e2a615788597d1) for a list of supported timezone IDs. - `userAgent` <[string]> Specific user agent to use in this context. - `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. @@ -4754,6 +4802,8 @@ const { chromium } = require('playwright'); // Or 'webkit' or 'firefox'. Returns browser name. For example: `'chromium'`, `'webkit'` or `'firefox'`. +[BrowserType]: #class-browsertype "BrowserType" + ### class: Logger Playwright generates a lot of logs and they are accessible via the pluggable logger sink. @@ -4792,6 +4842,8 @@ Determines whether sink is interested in the logger with the given name and seve - `hints` <[Object]> optional formatting hints - `color` <[string]> Optional preferred logger color. +[Logger]: #class-logger "Logger" + ### class: ChromiumBrowser * extends: [Browser] @@ -4839,6 +4891,8 @@ Only one trace can be active at a time per browser. Returns the buffer with trace data. +[ChromiumBrowser]: #class-chromiumbrowser "ChromiumBrowser" + ### class: ChromiumBrowserContext * extends: [BrowserContext] @@ -4911,6 +4965,8 @@ Returns the newly created session. All existing service workers in the context. +[ChromiumBrowserContext]: #class-chromiumbrowsercontext "ChromiumBrowserContext" + ### class: ChromiumCoverage Coverage gathers information about parts of JavaScript and CSS that were used by the page. @@ -4990,6 +5046,8 @@ Returns the array of coverage reports for all scripts > **NOTE** JavaScript Coverage doesn't include anonymous scripts by default. However, scripts with sourceURLs are reported. +[ChromiumCoverage]: #class-chromiumcoverage "ChromiumCoverage" + ### class: CDPSession * extends: [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) @@ -5027,6 +5085,8 @@ Detaches the CDPSession from the target. Once detached, the CDPSession object wo - `params` <[Object]> Optional method parameters - returns: <[Promise]<[Object]>> +[CDPSession]: #class-cdpsession "CDPSession" + ### class: FirefoxBrowser * extends: [Browser] @@ -5042,6 +5102,8 @@ Firefox browser instance does not expose Firefox-specific features. - [browser.version()](#browserversion) +[FirefoxBrowser]: #class-firefoxbrowser "FirefoxBrowser" + ### class: WebKitBrowser * extends: [Browser] @@ -5057,6 +5119,34 @@ WebKit browser instance does not expose WebKit-specific features. - [browser.version()](#browserversion) +[WebKitBrowser]: #class-webkitbrowser "WebKitBrowser" + +[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array" +[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer" +[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess" +[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" +[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error" +[EvaluationArgument]: #evaluationargument "Evaluation Argument" +[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map" +[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object" +[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise" +[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp "RegExp" +[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable" +[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail" +[URL]: https://nodejs.org/api/url.html "URL" +[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout" +[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time" +[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean" +[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function "Function" +[iterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols "Iterator" +[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null "null" +[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number" +[origin]: https://developer.mozilla.org/en-US/docs/Glossary/Origin "Origin" +[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector" +[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable" +[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "string" +[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath" + ### EvaluationArgument Playwright evaluation methods like [page.evaluate(pageFunction[, arg])](#pageevaluatepagefunction-arg) take a single optional argument. This argument can be a mix of [Serializable] values and [JSHandle] or [ElementHandle] instances. Handles are automatically converted to the value they represent. @@ -5214,63 +5304,3 @@ const { chromium } = require('playwright'); > **NOTE** It is not yet possible to test extension popups or content scripts. -[AXNode]: #accessibilitysnapshotoptions "AXNode" -[Accessibility]: #class-accessibility "Accessibility" -[Array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array" -[Body]: #class-body "Body" -[BrowserServer]: #class-browserserver "BrowserServer" -[BrowserContext]: #class-browsercontext "BrowserContext" -[BrowserType]: #class-browsertype "BrowserType" -[Browser]: #class-browser "Browser" -[Buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer "Buffer" -[ChildProcess]: https://nodejs.org/api/child_process.html "ChildProcess" -[ChromiumBrowser]: #class-chromiumbrowser "ChromiumBrowser" -[ChromiumBrowserContext]: #class-chromiumbrowsercontext "ChromiumBrowserContext" -[ChromiumCoverage]: #class-chromiumcoverage "ChromiumCoverage" -[CDPSession]: #class-cdpsession "CDPSession" -[ConsoleMessage]: #class-consolemessage "ConsoleMessage" -[Dialog]: #class-dialog "Dialog" -[Download]: #class-download "Download" -[ElementHandle]: #class-elementhandle "ElementHandle" -[Element]: https://developer.mozilla.org/en-US/docs/Web/API/element "Element" -[Error]: https://nodejs.org/api/errors.html#errors_class_error "Error" -[EvaluationArgument]: #evaluationargument "Evaluation Argument" -[File]: #class-file "https://developer.mozilla.org/en-US/docs/Web/API/File" -[FileChooser]: #class-filechooser "FileChooser" -[FirefoxBrowser]: #class-firefoxbrowser "FirefoxBrowser" -[Frame]: #class-frame "Frame" -[JSHandle]: #class-jshandle "JSHandle" -[Keyboard]: #class-keyboard "Keyboard" -[Logger]: #class-logger "Logger" -[Map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map "Map" -[Mouse]: #class-mouse "Mouse" -[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object" -[Page]: #class-page "Page" -[Playwright]: #class-playwright "Playwright" -[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise" -[RegExp]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp -[Request]: #class-request "Request" -[Response]: #class-response "Response" -[Route]: #class-route "Route" -[Selectors]: #class-selectors "Selectors" -[Serializable]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable" -[TimeoutError]: #class-timeouterror "TimeoutError" -[Touchscreen]: #class-touchscreen "Touchscreen" -[UIEvent.detail]: https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail" -[URL]: https://nodejs.org/api/url.html -[USKeyboardLayout]: ../src/usKeyboardLayout.ts "USKeyboardLayout" -[UnixTime]: https://en.wikipedia.org/wiki/Unix_time "Unix Time" -[Video]: #class-video "Video" -[WebKitBrowser]: #class-webkitbrowser "WebKitBrowser" -[WebSocket]: #class-websocket "WebSocket" -[Worker]: #class-worker "Worker" -[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean" -[function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function "Function" -[iterator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols "Iterator" -[null]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/null -[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number" -[origin]: https://developer.mozilla.org/en-US/docs/Glossary/Origin "Origin" -[selector]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector" -[Readable]: https://nodejs.org/api/stream.html#stream_class_stream_readable "Readable" -[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String" -[xpath]: https://developer.mozilla.org/en-US/docs/Web/XPath "xpath" diff --git a/types/types.d.ts b/types/types.d.ts index 5efd82e60e..290aa7bea1 100644 --- a/types/types.d.ts +++ b/types/types.d.ts @@ -28,8 +28,12 @@ type ElementHandleWaitForSelectorOptionsNotHidden = ElementHandleWaitForSelector }; /** - * Page provides methods to interact with a single tab in a Browser, or an extension background page in Chromium. One Browser instance might have multiple Page instances. + * - 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. + * * This example creates a page, navigates it to a URL, and then saves a screenshot: + * * ```js * const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. * @@ -42,12 +46,17 @@ type ElementHandleWaitForSelectorOptionsNotHidden = ElementHandleWaitForSelector * await browser.close(); * })(); * ``` - * The Page class emits various events (described below) which can be handled using any of Node's native `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!')); * ``` + * * To unsubscribe from events use the `removeListener` method: + * * ```js * function logRequest(interceptedRequest) { * console.log('A request was made:', interceptedRequest.url()); @@ -56,32 +65,42 @@ type ElementHandleWaitForSelectorOptionsNotHidden = ElementHandleWaitForSelector * // Sometime later... * page.removeListener('request', logRequest); * ``` + * */ export interface Page { /** * Returns the value of the `pageFunction` invocation. - * If the function passed to the `page.evaluate` returns a Promise, then `page.evaluate` would wait for the promise to resolve and return its value. - * If the function passed to the `page.evaluate` returns a non-Serializable value, then `page.evaluate` resolves to `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals. + * + * If the function passed to the `page.evaluate` returns a [Promise], then `page.evaluate` would wait for the promise to resolve and return its value. + * + * If the function passed to the `page.evaluate` returns a non-[Serializable] value, then `page.evaluate` resolves to `undefined`. DevTools Protocol also supports transferring some additional values that are not serializable by `JSON`: `-0`, `NaN`, `Infinity`, `-Infinity`, and bigint literals. + * * Passing argument to `pageFunction`: + * * ```js * const result = await page.evaluate(([x, y]) => { * return Promise.resolve(x * y); * }, [7, 8]); * console.log(result); // prints "56" * ``` + * * A string can also be passed in instead of a function: + * * ```js * console.log(await page.evaluate('1 + 2')); // prints "3" * const x = 10; * console.log(await page.evaluate(`1 + ${x}`)); // prints "11" * ``` - * ElementHandle instances can be passed as an argument to the `page.evaluate`: + * + * [ElementHandle] instances can be passed as an argument to the `page.evaluate`: + * * ```js * const bodyHandle = await page.$('body'); * const html = await page.evaluate(([body, suffix]) => body.innerHTML + suffix, [bodyHandle, 'hello']); * await bodyHandle.dispose(); * ``` - * Shortcut for main frame's `frame.evaluate(pageFunction[, arg])`. + * + * Shortcut for main frame's [`frame.evaluate(pageFunction[, arg])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#frameevaluatepagefunction-arg). * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` */ @@ -90,19 +109,26 @@ export interface Page { /** * Returns the value of the `pageFunction` invocation as in-page object (JSHandle). + * * The only difference between `page.evaluate` and `page.evaluateHandle` is that `page.evaluateHandle` returns in-page object (JSHandle). - * If the function passed to the `page.evaluateHandle` returns a Promise, then `page.evaluateHandle` would wait for the promise to resolve and return its value. + * + * If the function passed to the `page.evaluateHandle` returns a [Promise], then `page.evaluateHandle` would wait for the promise to resolve and return its value. + * * A string can also be passed in instead of a function: + * * ```js * const aHandle = await page.evaluateHandle('document'); // Handle for the 'document' * ``` - * JSHandle instances can be passed as an argument to the `page.evaluateHandle`: + * + * [JSHandle] instances can be passed as an argument to the `page.evaluateHandle`: + * * ```js * const aHandle = await page.evaluateHandle(() => document.body); * const resultHandle = await page.evaluateHandle(body => body.innerHTML, aHandle); * console.log(await resultHandle.jsonValue()); * await resultHandle.dispose(); * ``` + * * @param pageFunction Function to be evaluated in the page context * @param arg Optional argument to pass to `pageFunction` */ @@ -111,31 +137,37 @@ export interface Page { /** * 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)`. - * @param selector A selector to query for. See working with selectors for more details. + * + * Shortcut for main frame's [`frame.$(selector)`](https://github.com/microsoft/playwright/blob/master/docs/api.md#frameselector). + * @param selector A selector to query for. See [working with selectors](https://github.com/microsoft/playwright/blob/master/docs/api.md#working-with-selectors) for more details. */ $(selector: K): Promise | null>; $(selector: string): Promise | null>; /** * 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)`. - * @param selector A selector to query for. See working with selectors for more details. + * + * Shortcut for main frame's [`frame.$$(selector)`](https://github.com/microsoft/playwright/blob/master/docs/api.md#frameselector). + * @param selector A selector to query for. See [working with selectors](https://github.com/microsoft/playwright/blob/master/docs/api.md#working-with-selectors) for more details. */ $$(selector: K): Promise[]>; $$(selector: string): Promise[]>; /** * 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])` would wait for the promise to resolve and return its value. + * + * If `pageFunction` returns a [Promise], then [`page.$eval(selector, pageFunction[, arg])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageevalselector-pagefunction-arg) 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); * const html = await page.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello'); * ``` - * Shortcut for main frame's `frame.$eval(selector, pageFunction[, arg])`. - * @param selector A selector to query for. See working with selectors for more details. + * + * Shortcut for main frame's [`frame.$eval(selector, pageFunction[, arg])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#frameevalselector-pagefunction-arg). + * @param selector A selector to query for. See [working with selectors](https://github.com/microsoft/playwright/blob/master/docs/api.md#working-with-selectors) for more details. * @param pageFunction Function to be evaluated in browser context * @param arg Optional argument to pass to `pageFunction` */ @@ -146,12 +178,16 @@ export interface Page { /** * 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])` would wait for the promise to resolve and return its value. + * + * If `pageFunction` returns a [Promise], then [`page.$$eval(selector, pageFunction[, arg])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageevalselector-pagefunction-arg) 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); * ``` - * @param selector A selector to query for. See working with selectors for more details. + * + * @param selector A selector to query for. See [working with selectors](https://github.com/microsoft/playwright/blob/master/docs/api.md#working-with-selectors) for more details. * @param pageFunction Function to be evaluated in browser context * @param arg Optional argument to pass to `pageFunction` */ @@ -162,7 +198,9 @@ export interface Page { /** * Returns when the `pageFunction` returns a truthy value. It resolves to a JSHandle of the truthy value. + * * The `waitForFunction` can be used to observe viewport size change: + * * ```js * const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. * @@ -175,12 +213,15 @@ export interface Page { * await browser.close(); * })(); * ``` + * * To pass an argument to the predicate of `page.waitForFunction` function: + * * ```js * const selector = '.foo'; * await page.waitForFunction(selector => !!document.querySelector(selector), selector); * ``` - * Shortcut for main frame's `frame.waitForFunction(pageFunction[, arg, options])`. + * + * Shortcut for main frame's [`frame.waitForFunction(pageFunction[, arg, options])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#framewaitforfunctionpagefunction-arg-options). * @param pageFunction Function to be evaluated in browser context * @param arg Optional argument to pass to `pageFunction` * @param options @@ -190,8 +231,11 @@ export interface Page { /** * Returns when element specified by selector satisfies `state` option. Returns `null` if waiting for `hidden` or `detached`. + * * Wait for the `selector` to satisfy `state` option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method `selector` already satisfies the condition, the method will return immediately. If the selector doesn't satisfy the condition for the `timeout` milliseconds, the function will throw. + * * This method works across navigations: + * * ```js * const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'. * @@ -208,7 +252,8 @@ export interface Page { * await browser.close(); * })(); * ``` - * @param selector A selector to query for. See working with selectors for more details. + * + * @param selector A selector to query for. See [working with selectors](https://github.com/microsoft/playwright/blob/master/docs/api.md#working-with-selectors) for more details. * @param options */ waitForSelector(selector: K, options?: PageWaitForSelectorOptionsNotHidden): Promise>; @@ -217,12 +262,16 @@ export interface Page { waitForSelector(selector: string, options: PageWaitForSelectorOptions): Promise>; /** - * The method adds a function called `name` on the `window` object of every frame in this page. When called, the function executes `playwrightBinding` 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 this page. When called, the function executes `playwrightBinding` 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 }`. - * See `browserContext.exposeBinding(name, playwrightBinding[, options])` for the context-wide version. + * + * See [`browserContext.exposeBinding(name, playwrightBinding[, options])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsercontextexposebindingname-playwrightbinding-options) for the context-wide version. * * > **NOTE** Functions installed via `page.exposeBinding` survive navigations. + * * An example of exposing page URL to all frames in a page: + * * ```js * const { webkit } = require('playwright'); // Or 'chromium' or 'firefox'. * @@ -243,7 +292,9 @@ export interface Page { * await page.click('button'); * })(); * ``` + * * An example of passing an element handle: + * * ```js * await page.exposeBinding('clicked', async (source, element) => { * console.log(await element.textContent()); @@ -256,6 +307,7 @@ export interface Page { *
Or click me
* `); * ``` + * * @param name Name of the function on the window object. * @param playwrightBinding Callback function that will be called in the Playwright's context. * @param options @@ -269,8 +321,11 @@ export interface Page { /** * 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) @@ -278,12 +333,15 @@ export interface Page { * }); * page.evaluate(() => console.log('hello', 5, {foo: 'bar'})); * ``` + * */ on(event: 'console', listener: (consoleMessage: ConsoleMessage) => void): this; /** * 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. @@ -294,7 +352,9 @@ export interface Page { * // When the page crashes, exception message contains 'crash'. * } * ``` + * * 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) => { * page.on('requestfinished', async request => { @@ -304,33 +364,36 @@ export interface Page { * page.on('crash', error => reject(error)); * }); * ``` + * */ on(event: 'crash', listener: () => void): this; /** - * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via `dialog.accept([promptText])` or `dialog.dismiss()` methods. + * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via [`dialog.accept([promptText])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#dialogacceptprompttext) or [`dialog.dismiss()`](https://github.com/microsoft/playwright/blob/master/docs/api.md#dialogdismiss) methods. */ on(event: 'dialog', listener: (dialog: Dialog) => void): this; /** - * Emitted when the JavaScript `DOMContentLoaded` event is dispatched. + * Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched. */ on(event: 'domcontentloaded', listener: () => void): this; /** - * 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. */ on(event: 'download', listener: (download: Download) => void): this; /** - * 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])` 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])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#filechoosersetfilesfiles-options) that can be uploaded after that. + * * ```js * page.on('filechooser', async (fileChooser) => { * await fileChooser.setFiles('/tmp/myfile.pdf'); * }); * ``` + * */ on(event: 'filechooser', listener: (fileChooser: FileChooser) => void): this; @@ -350,7 +413,7 @@ export interface Page { on(event: 'framenavigated', listener: (frame: Frame) => void): this; /** - * Emitted when the JavaScript `load` event is dispatched. + * Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. */ on(event: 'load', listener: () => void): this; @@ -360,8 +423,10 @@ export interface Page { on(event: 'pageerror', listener: (error: Error) => void): this; /** - * Emitted when the page opens a new tab or window. This event is emitted in addition to the `browserContext.on('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')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#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. + * * ```js * const [popup] = await Promise.all([ * page.waitForEvent('popup'), @@ -370,19 +435,19 @@ export interface Page { * console.log(await popup.evaluate('location.href')); * ``` * - * > **NOTE** Use `page.waitForLoadState([state, 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])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagewaitforloadstatestate-options) to wait until the page gets to a particular state (you should not need it in most cases). */ on(event: 'popup', listener: (page: Page) => void): this; /** - * 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)` or `browserContext.route(url, 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)`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagerouteurl-handler) or [`browserContext.route(url, handler)`](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsercontextrouteurl-handler). */ on(event: 'request', listener: (request: Request) => void): this; /** * 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')` event and not with `page.on('requestfailed')`. + * > **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with [`page.on('requestfinished')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageonrequestfinished) event and not with [`page.on('requestfailed')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageonrequestfailed). */ on(event: 'requestfailed', listener: (request: Request) => void): this; @@ -397,12 +462,12 @@ export interface Page { on(event: 'response', listener: (response: Response) => void): this; /** - * Emitted when request is sent. + * Emitted when <[WebSocket]> request is sent. */ on(event: 'websocket', listener: (webSocket: WebSocket) => void): this; /** - * Emitted when a dedicated WebWorker 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. */ on(event: 'worker', listener: (worker: Worker) => void): this; @@ -413,8 +478,11 @@ export interface Page { /** * 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) @@ -422,12 +490,15 @@ export interface Page { * }); * page.evaluate(() => console.log('hello', 5, {foo: 'bar'})); * ``` + * */ once(event: 'console', listener: (consoleMessage: ConsoleMessage) => void): this; /** * 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. @@ -438,7 +509,9 @@ export interface Page { * // When the page crashes, exception message contains 'crash'. * } * ``` + * * 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) => { * page.on('requestfinished', async request => { @@ -448,33 +521,36 @@ export interface Page { * page.on('crash', error => reject(error)); * }); * ``` + * */ once(event: 'crash', listener: () => void): this; /** - * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via `dialog.accept([promptText])` or `dialog.dismiss()` methods. + * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via [`dialog.accept([promptText])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#dialogacceptprompttext) or [`dialog.dismiss()`](https://github.com/microsoft/playwright/blob/master/docs/api.md#dialogdismiss) methods. */ once(event: 'dialog', listener: (dialog: Dialog) => void): this; /** - * Emitted when the JavaScript `DOMContentLoaded` event is dispatched. + * Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched. */ once(event: 'domcontentloaded', listener: () => void): this; /** - * 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. */ once(event: 'download', listener: (download: Download) => void): this; /** - * 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])` 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])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#filechoosersetfilesfiles-options) that can be uploaded after that. + * * ```js * page.on('filechooser', async (fileChooser) => { * await fileChooser.setFiles('/tmp/myfile.pdf'); * }); * ``` + * */ once(event: 'filechooser', listener: (fileChooser: FileChooser) => void): this; @@ -494,7 +570,7 @@ export interface Page { once(event: 'framenavigated', listener: (frame: Frame) => void): this; /** - * Emitted when the JavaScript `load` event is dispatched. + * Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. */ once(event: 'load', listener: () => void): this; @@ -504,8 +580,10 @@ export interface Page { once(event: 'pageerror', listener: (error: Error) => void): this; /** - * Emitted when the page opens a new tab or window. This event is emitted in addition to the `browserContext.on('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')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#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. + * * ```js * const [popup] = await Promise.all([ * page.waitForEvent('popup'), @@ -514,19 +592,19 @@ export interface Page { * console.log(await popup.evaluate('location.href')); * ``` * - * > **NOTE** Use `page.waitForLoadState([state, 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])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagewaitforloadstatestate-options) to wait until the page gets to a particular state (you should not need it in most cases). */ once(event: 'popup', listener: (page: Page) => void): this; /** - * 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)` or `browserContext.route(url, 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)`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagerouteurl-handler) or [`browserContext.route(url, handler)`](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsercontextrouteurl-handler). */ once(event: 'request', listener: (request: Request) => void): this; /** * 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')` event and not with `page.on('requestfailed')`. + * > **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with [`page.on('requestfinished')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageonrequestfinished) event and not with [`page.on('requestfailed')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageonrequestfailed). */ once(event: 'requestfailed', listener: (request: Request) => void): this; @@ -541,12 +619,12 @@ export interface Page { once(event: 'response', listener: (response: Response) => void): this; /** - * Emitted when request is sent. + * Emitted when <[WebSocket]> request is sent. */ once(event: 'websocket', listener: (webSocket: WebSocket) => void): this; /** - * Emitted when a dedicated WebWorker 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. */ once(event: 'worker', listener: (worker: Worker) => void): this; @@ -557,8 +635,11 @@ export interface Page { /** * 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) @@ -566,12 +647,15 @@ export interface Page { * }); * page.evaluate(() => console.log('hello', 5, {foo: 'bar'})); * ``` + * */ addListener(event: 'console', listener: (consoleMessage: ConsoleMessage) => void): this; /** * 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. @@ -582,7 +666,9 @@ export interface Page { * // When the page crashes, exception message contains 'crash'. * } * ``` + * * 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) => { * page.on('requestfinished', async request => { @@ -592,33 +678,36 @@ export interface Page { * page.on('crash', error => reject(error)); * }); * ``` + * */ addListener(event: 'crash', listener: () => void): this; /** - * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via `dialog.accept([promptText])` or `dialog.dismiss()` methods. + * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via [`dialog.accept([promptText])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#dialogacceptprompttext) or [`dialog.dismiss()`](https://github.com/microsoft/playwright/blob/master/docs/api.md#dialogdismiss) methods. */ addListener(event: 'dialog', listener: (dialog: Dialog) => void): this; /** - * Emitted when the JavaScript `DOMContentLoaded` event is dispatched. + * Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched. */ addListener(event: 'domcontentloaded', listener: () => void): this; /** - * 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. */ addListener(event: 'download', listener: (download: Download) => void): this; /** - * 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])` 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])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#filechoosersetfilesfiles-options) that can be uploaded after that. + * * ```js * page.on('filechooser', async (fileChooser) => { * await fileChooser.setFiles('/tmp/myfile.pdf'); * }); * ``` + * */ addListener(event: 'filechooser', listener: (fileChooser: FileChooser) => void): this; @@ -638,7 +727,7 @@ export interface Page { addListener(event: 'framenavigated', listener: (frame: Frame) => void): this; /** - * Emitted when the JavaScript `load` event is dispatched. + * Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. */ addListener(event: 'load', listener: () => void): this; @@ -648,8 +737,10 @@ export interface Page { addListener(event: 'pageerror', listener: (error: Error) => void): this; /** - * Emitted when the page opens a new tab or window. This event is emitted in addition to the `browserContext.on('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')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#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. + * * ```js * const [popup] = await Promise.all([ * page.waitForEvent('popup'), @@ -658,19 +749,19 @@ export interface Page { * console.log(await popup.evaluate('location.href')); * ``` * - * > **NOTE** Use `page.waitForLoadState([state, 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])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagewaitforloadstatestate-options) to wait until the page gets to a particular state (you should not need it in most cases). */ addListener(event: 'popup', listener: (page: Page) => void): this; /** - * 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)` or `browserContext.route(url, 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)`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagerouteurl-handler) or [`browserContext.route(url, handler)`](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsercontextrouteurl-handler). */ addListener(event: 'request', listener: (request: Request) => void): this; /** * 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')` event and not with `page.on('requestfailed')`. + * > **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with [`page.on('requestfinished')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageonrequestfinished) event and not with [`page.on('requestfailed')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageonrequestfailed). */ addListener(event: 'requestfailed', listener: (request: Request) => void): this; @@ -685,12 +776,12 @@ export interface Page { addListener(event: 'response', listener: (response: Response) => void): this; /** - * Emitted when request is sent. + * Emitted when <[WebSocket]> request is sent. */ addListener(event: 'websocket', listener: (webSocket: WebSocket) => void): this; /** - * Emitted when a dedicated WebWorker 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. */ addListener(event: 'worker', listener: (worker: Worker) => void): this; @@ -701,8 +792,11 @@ export interface Page { /** * 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) @@ -710,12 +804,15 @@ export interface Page { * }); * page.evaluate(() => console.log('hello', 5, {foo: 'bar'})); * ``` + * */ removeListener(event: 'console', listener: (consoleMessage: ConsoleMessage) => void): this; /** * 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. @@ -726,7 +823,9 @@ export interface Page { * // When the page crashes, exception message contains 'crash'. * } * ``` + * * 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) => { * page.on('requestfinished', async request => { @@ -736,33 +835,36 @@ export interface Page { * page.on('crash', error => reject(error)); * }); * ``` + * */ removeListener(event: 'crash', listener: () => void): this; /** - * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via `dialog.accept([promptText])` or `dialog.dismiss()` methods. + * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via [`dialog.accept([promptText])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#dialogacceptprompttext) or [`dialog.dismiss()`](https://github.com/microsoft/playwright/blob/master/docs/api.md#dialogdismiss) methods. */ removeListener(event: 'dialog', listener: (dialog: Dialog) => void): this; /** - * Emitted when the JavaScript `DOMContentLoaded` event is dispatched. + * Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched. */ removeListener(event: 'domcontentloaded', listener: () => void): this; /** - * 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. */ removeListener(event: 'download', listener: (download: Download) => void): this; /** - * 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])` 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])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#filechoosersetfilesfiles-options) that can be uploaded after that. + * * ```js * page.on('filechooser', async (fileChooser) => { * await fileChooser.setFiles('/tmp/myfile.pdf'); * }); * ``` + * */ removeListener(event: 'filechooser', listener: (fileChooser: FileChooser) => void): this; @@ -782,7 +884,7 @@ export interface Page { removeListener(event: 'framenavigated', listener: (frame: Frame) => void): this; /** - * Emitted when the JavaScript `load` event is dispatched. + * Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. */ removeListener(event: 'load', listener: () => void): this; @@ -792,8 +894,10 @@ export interface Page { removeListener(event: 'pageerror', listener: (error: Error) => void): this; /** - * Emitted when the page opens a new tab or window. This event is emitted in addition to the `browserContext.on('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')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#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. + * * ```js * const [popup] = await Promise.all([ * page.waitForEvent('popup'), @@ -802,19 +906,19 @@ export interface Page { * console.log(await popup.evaluate('location.href')); * ``` * - * > **NOTE** Use `page.waitForLoadState([state, 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])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagewaitforloadstatestate-options) to wait until the page gets to a particular state (you should not need it in most cases). */ removeListener(event: 'popup', listener: (page: Page) => void): this; /** - * 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)` or `browserContext.route(url, 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)`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagerouteurl-handler) or [`browserContext.route(url, handler)`](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsercontextrouteurl-handler). */ removeListener(event: 'request', listener: (request: Request) => void): this; /** * 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')` event and not with `page.on('requestfailed')`. + * > **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with [`page.on('requestfinished')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageonrequestfinished) event and not with [`page.on('requestfailed')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageonrequestfailed). */ removeListener(event: 'requestfailed', listener: (request: Request) => void): this; @@ -829,12 +933,12 @@ export interface Page { removeListener(event: 'response', listener: (response: Response) => void): this; /** - * Emitted when request is sent. + * Emitted when <[WebSocket]> request is sent. */ removeListener(event: 'websocket', listener: (webSocket: WebSocket) => void): this; /** - * Emitted when a dedicated WebWorker 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. */ removeListener(event: 'worker', listener: (worker: Worker) => void): this; @@ -845,8 +949,11 @@ export interface Page { /** * 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) @@ -854,12 +961,15 @@ export interface Page { * }); * page.evaluate(() => console.log('hello', 5, {foo: 'bar'})); * ``` + * */ off(event: 'console', listener: (consoleMessage: ConsoleMessage) => void): this; /** * 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. @@ -870,7 +980,9 @@ export interface Page { * // When the page crashes, exception message contains 'crash'. * } * ``` + * * 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) => { * page.on('requestfinished', async request => { @@ -880,33 +992,36 @@ export interface Page { * page.on('crash', error => reject(error)); * }); * ``` + * */ off(event: 'crash', listener: () => void): this; /** - * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via `dialog.accept([promptText])` or `dialog.dismiss()` methods. + * Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via [`dialog.accept([promptText])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#dialogacceptprompttext) or [`dialog.dismiss()`](https://github.com/microsoft/playwright/blob/master/docs/api.md#dialogdismiss) methods. */ off(event: 'dialog', listener: (dialog: Dialog) => void): this; /** - * Emitted when the JavaScript `DOMContentLoaded` event is dispatched. + * Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched. */ off(event: 'domcontentloaded', listener: () => void): this; /** - * 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. */ off(event: 'download', listener: (download: Download) => void): this; /** - * 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])` 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])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#filechoosersetfilesfiles-options) that can be uploaded after that. + * * ```js * page.on('filechooser', async (fileChooser) => { * await fileChooser.setFiles('/tmp/myfile.pdf'); * }); * ``` + * */ off(event: 'filechooser', listener: (fileChooser: FileChooser) => void): this; @@ -926,7 +1041,7 @@ export interface Page { off(event: 'framenavigated', listener: (frame: Frame) => void): this; /** - * Emitted when the JavaScript `load` event is dispatched. + * Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. */ off(event: 'load', listener: () => void): this; @@ -936,8 +1051,10 @@ export interface Page { off(event: 'pageerror', listener: (error: Error) => void): this; /** - * Emitted when the page opens a new tab or window. This event is emitted in addition to the `browserContext.on('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')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#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. + * * ```js * const [popup] = await Promise.all([ * page.waitForEvent('popup'), @@ -946,19 +1063,19 @@ export interface Page { * console.log(await popup.evaluate('location.href')); * ``` * - * > **NOTE** Use `page.waitForLoadState([state, 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])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagewaitforloadstatestate-options) to wait until the page gets to a particular state (you should not need it in most cases). */ off(event: 'popup', listener: (page: Page) => void): this; /** - * 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)` or `browserContext.route(url, 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)`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagerouteurl-handler) or [`browserContext.route(url, handler)`](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsercontextrouteurl-handler). */ off(event: 'request', listener: (request: Request) => void): this; /** * 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')` event and not with `page.on('requestfailed')`. + * > **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request will complete with [`page.on('requestfinished')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageonrequestfinished) event and not with [`page.on('requestfailed')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageonrequestfailed). */ off(event: 'requestfailed', listener: (request: Request) => void): this; @@ -973,12 +1090,12 @@ export interface Page { off(event: 'response', listener: (response: Response) => void): this; /** - * Emitted when request is sent. + * Emitted when <[WebSocket]> request is sent. */ off(event: 'websocket', listener: (webSocket: WebSocket) => void): this; /** - * Emitted when a dedicated WebWorker 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. */ off(event: 'worker', listener: (worker: Worker) => void): this; @@ -988,8 +1105,11 @@ export interface Page { * 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`. + * * An example of overriding `Math.random` before the page loads: + * * ```js * // preload.js * Math.random = () => 42; @@ -999,67 +1119,69 @@ export interface Page { * await page.addInitScript(preloadFile); * ``` * - * > **NOTE** The order of evaluation of multiple scripts installed via `browserContext.addInitScript(script[, arg])` and `page.addInitScript(script[, arg])` is not defined. + * > **NOTE** The order of evaluation of multiple scripts installed via [`browserContext.addInitScript(script[, arg])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#browsercontextaddinitscriptscript-arg) and [`page.addInitScript(script[, arg])`](https://github.com/microsoft/playwright/blob/master/docs/api.md#pageaddinitscriptscript-arg) is not defined. * @param script Script to be evaluated in the page. * @param arg Optional argument to pass to `script` (only supported when passing a function). */ addInitScript(script: Function|string|{ /** - * Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. + * Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional. */ path?: string; /** - * Raw script content. + * Raw script content. Optional. */ content?: string; }, arg?: Serializable): Promise; /** * Adds a `