Filip/playwright
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

docs: disambiguate events (#4597)

Browse source
This commit is contained in:
Pavel Feldman 2020-12-04 11:09:20 -08:00 committed by GitHub
parent 8551fff43b
commit 150d778ca7
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
18 changed files with 557 additions and 556 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

751
docs-src/api-body.md
View file

File diff suppressed because it is too large Load diff

160
docs/api.md
View file

@ -158,7 +158,7 @@ See [ChromiumBrowser], [FirefoxBrowser] and [WebKitBrowser] for browser-specific
being connected to or launched. being connected to or launched.
<!-- GEN:toc --> <!-- GEN:toc -->
- [event: 'disconnected'](#event-disconnected) - [browser.on('disconnected')](#browserondisconnected)
- [browser.close()](#browserclose) - [browser.close()](#browserclose)
- [browser.contexts()](#browsercontexts) - [browser.contexts()](#browsercontexts)
- [browser.isConnected()](#browserisconnected) - [browser.isConnected()](#browserisconnected)
@ -167,7 +167,7 @@ being connected to or launched.
- [browser.version()](#browserversion) - [browser.version()](#browserversion)
<!-- GEN:stop --> <!-- GEN:stop -->
#### event: 'disconnected' #### browser.on('disconnected')
Emitted when Browser gets disconnected from the browser application. This might happen because of one of the following: Emitted when Browser gets disconnected from the browser application. This might happen because of one of the following:
* Browser application is closed or crashed. * Browser application is closed or crashed.
@ -372,8 +372,8 @@ await context.close();
``` ```
<!-- GEN:toc --> <!-- GEN:toc -->
- [event: 'close'](#event-close) - [browserContext.on('close')](#browsercontextonclose)
- [event: 'page'](#event-page) - [browserContext.on('page')](#browsercontextonpage)
- [browserContext.addCookies(cookies)](#browsercontextaddcookiescookies) - [browserContext.addCookies(cookies)](#browsercontextaddcookiescookies)
- [browserContext.addInitScript(script[, arg])](#browsercontextaddinitscriptscript-arg) - [browserContext.addInitScript(script[, arg])](#browsercontextaddinitscriptscript-arg)
- [browserContext.browser()](#browsercontextbrowser) - [browserContext.browser()](#browsercontextbrowser)
@ -398,18 +398,18 @@ await context.close();
- [browserContext.waitForEvent(event[, optionsOrPredicate])](#browsercontextwaitforeventevent-optionsorpredicate) - [browserContext.waitForEvent(event[, optionsOrPredicate])](#browsercontextwaitforeventevent-optionsorpredicate)
<!-- GEN:stop --> <!-- GEN:stop -->
#### event: 'close' #### browserContext.on('close')
Emitted when Browser context gets closed. This might happen because of one of the following: Emitted when Browser context gets closed. This might happen because of one of the following:
* Browser context is closed. * Browser context is closed.
* Browser application is closed or crashed. * Browser application is closed or crashed.
* The [browser.close()](#browserclose) method was called. * The [browser.close()](#browserclose) method was called.
#### event: 'page' #### browserContext.on('page')
- <[Page]> - <[Page]>
The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event will The event is emitted when a new Page is created in the BrowserContext. The page may still be loading. The event will
also fire for popup pages. See also [page.on('popup')](#event-popup) to receive events about popups relevant to a specific page. 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 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 popup with `window.open('http://example.com')`, this event will fire when the network request to "http://example.com" is
@ -823,25 +823,25 @@ page.removeListener('request', logRequest);
``` ```
<!-- GEN:toc --> <!-- GEN:toc -->
- [event: 'close'](#event-close-1) - [page.on('close')](#pageonclose)
- [event: 'console'](#event-console) - [page.on('console')](#pageonconsole)
- [event: 'crash'](#event-crash) - [page.on('crash')](#pageoncrash)
- [event: 'dialog'](#event-dialog) - [page.on('dialog')](#pageondialog)
- [event: 'domcontentloaded'](#event-domcontentloaded) - [page.on('domcontentloaded')](#pageondomcontentloaded)
- [event: 'download'](#event-download) - [page.on('download')](#pageondownload)
- [event: 'filechooser'](#event-filechooser) - [page.on('filechooser')](#pageonfilechooser)
- [event: 'frameattached'](#event-frameattached) - [page.on('frameattached')](#pageonframeattached)
- [event: 'framedetached'](#event-framedetached) - [page.on('framedetached')](#pageonframedetached)
- [event: 'framenavigated'](#event-framenavigated) - [page.on('framenavigated')](#pageonframenavigated)
- [event: 'load'](#event-load) - [page.on('load')](#pageonload)
- [event: 'pageerror'](#event-pageerror) - [page.on('pageerror')](#pageonpageerror)
- [event: 'popup'](#event-popup) - [page.on('popup')](#pageonpopup)
- [event: 'request'](#event-request) - [page.on('request')](#pageonrequest)
- [event: 'requestfailed'](#event-requestfailed) - [page.on('requestfailed')](#pageonrequestfailed)
- [event: 'requestfinished'](#event-requestfinished) - [page.on('requestfinished')](#pageonrequestfinished)
- [event: 'response'](#event-response) - [page.on('response')](#pageonresponse)
- [event: 'websocket'](#event-websocket) - [page.on('websocket')](#pageonwebsocket)
- [event: 'worker'](#event-worker) - [page.on('worker')](#pageonworker)
- [page.$(selector)](#pageselector) - [page.$(selector)](#pageselector)
- [page.$$(selector)](#pageselector-1) - [page.$$(selector)](#pageselector-1)
- [page.$eval(selector, pageFunction[, arg])](#pageevalselector-pagefunction-arg) - [page.$eval(selector, pageFunction[, arg])](#pageevalselector-pagefunction-arg)
@ -913,11 +913,11 @@ page.removeListener('request', logRequest);
- [page.workers()](#pageworkers) - [page.workers()](#pageworkers)
<!-- GEN:stop --> <!-- GEN:stop -->
#### event: 'close' #### page.on('close')
Emitted when the page closes. Emitted when the page closes.
#### event: 'console' #### page.on('console')
- <[ConsoleMessage]> - <[ConsoleMessage]>
Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also
@ -935,7 +935,7 @@ page.on('console', msg => {
page.evaluate(() => console.log('hello', 5, {foo: 'bar'})); page.evaluate(() => console.log('hello', 5, {foo: 'bar'}));
``` ```
#### event: 'crash' #### page.on('crash')
Emitted when the page crashes. Browser pages might crash if they try to allocate too much memory. When the page crashes, 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. ongoing and subsequent operations will throw.
@ -966,18 +966,18 @@ await new Promise((resolve, reject) => {
}); });
``` ```
#### event: 'dialog' #### page.on('dialog')
- <[Dialog]> - <[Dialog]>
Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond
to the dialog via [dialog.accept([promptText])](#dialogacceptprompttext) or [dialog.dismiss()](#dialogdismiss) methods. to the dialog via [dialog.accept([promptText])](#dialogacceptprompttext) or [dialog.dismiss()](#dialogdismiss) methods.
#### event: 'domcontentloaded' #### page.on('domcontentloaded')
Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded)
event is dispatched. event is dispatched.
#### event: 'download' #### page.on('download')
- <[Download]> - <[Download]>
Emitted when attachment download started. User can access basic file operations on downloaded content via the passed Emitted when attachment download started. User can access basic file operations on downloaded content via the passed
@ -987,7 +987,7 @@ Emitted when attachment download started. User can access basic file operations
downloaded content. If `acceptDownloads` is not set or set to `false`, download events are emitted, but the actual 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. download is not performed and user has no access to the downloaded files.
#### event: 'filechooser' #### page.on('filechooser')
- <[FileChooser]> - <[FileChooser]>
Emitted when a file chooser is supposed to appear, such as after clicking the `<input type=file>`. Playwright can Emitted when a file chooser is supposed to appear, such as after clicking the `<input type=file>`. Playwright can
@ -999,34 +999,34 @@ page.on('filechooser', async (fileChooser) => {
}); });
``` ```
#### event: 'frameattached' #### page.on('frameattached')
- <[Frame]> - <[Frame]>
Emitted when a frame is attached. Emitted when a frame is attached.
#### event: 'framedetached' #### page.on('framedetached')
- <[Frame]> - <[Frame]>
Emitted when a frame is detached. Emitted when a frame is detached.
#### event: 'framenavigated' #### page.on('framenavigated')
- <[Frame]> - <[Frame]>
Emitted when a frame is navigated to a new url. Emitted when a frame is navigated to a new url.
#### event: 'load' #### page.on('load')
Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched. Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched.
#### event: 'pageerror' #### page.on('pageerror')
- <[Error]> The exception message - <[Error]> The exception message
Emitted when an uncaught exception happens within the page. Emitted when an uncaught exception happens within the page.
#### event: 'popup' #### page.on('popup')
- <[Page]> Page corresponding to "popup" window - <[Page]> Page corresponding to "popup" window
Emitted when the page opens a new tab or window. This event is emitted in addition to the [browserContext.on('page')](#event-page), 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. 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 The earliest moment that page is available is when it has navigated to the initial url. For example, when opening a
@ -1044,38 +1044,38 @@ console.log(await popup.evaluate('location.href'));
> **NOTE** Use [page.waitForLoadState([state, options])](#pagewaitforloadstatestate-options) to wait until the page gets to a particular state (you should not need it in > **NOTE** Use [page.waitForLoadState([state, options])](#pagewaitforloadstatestate-options) to wait until the page gets to a particular state (you should not need it in
most cases). most cases).
#### event: 'request' #### page.on('request')
- <[Request]> - <[Request]>
Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, see Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, see
[page.route(url, handler)](#pagerouteurl-handler) or [browserContext.route(url, handler)](#browsercontextrouteurl-handler). [page.route(url, handler)](#pagerouteurl-handler) or [browserContext.route(url, handler)](#browsercontextrouteurl-handler).
#### event: 'requestfailed' #### page.on('requestfailed')
- <[Request]> - <[Request]>
Emitted when a request fails, for example by timing out. 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 > **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-requestfinished) event and not with [page.on('requestfailed')](#event-requestfailed). will complete with [page.on('requestfinished')](#pageonrequestfinished) event and not with [page.on('requestfailed')](#pageonrequestfailed).
#### event: 'requestfinished' #### page.on('requestfinished')
- <[Request]> - <[Request]>
Emitted when a request finishes successfully after downloading the response body. For a successful response, the Emitted when a request finishes successfully after downloading the response body. For a successful response, the
sequence of events is `request`, `response` and `requestfinished`. sequence of events is `request`, `response` and `requestfinished`.
#### event: 'response' #### page.on('response')
- <[Response]> - <[Response]>
Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events
is `request`, `response` and `requestfinished`. is `request`, `response` and `requestfinished`.
#### event: 'websocket' #### page.on('websocket')
- <[WebSocket]> websocket - <[WebSocket]> websocket
Emitted when <[WebSocket]> request is sent. Emitted when <[WebSocket]> request is sent.
#### event: 'worker' #### page.on('worker')
- <[Worker]> - <[Worker]>
Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the
@ -1256,7 +1256,7 @@ If `runBeforeUnload` is `false` the result will resolve only after the page has
handlers. handlers.
> **NOTE** if `runBeforeUnload` is passed as true, a `beforeunload` dialog might be summoned > **NOTE** if `runBeforeUnload` is passed as true, a `beforeunload` dialog might be summoned
> and should be handled manually via [page.on('dialog')](#event-dialog) event. > and should be handled manually via [page.on('dialog')](#pageondialog) event.
#### page.content() #### page.content()
- returns: <[Promise]<[string]>> - returns: <[Promise]<[string]>>
@ -2296,9 +2296,9 @@ At every point of time, page exposes its current frame tree via the [page.mainFr
methods. methods.
[Frame] object's lifecycle is controlled by three events, dispatched on the page object: [Frame] object's lifecycle is controlled by three events, dispatched on the page object:
- [frame.on('frameattached')](#event-frameattached) - fired when the frame gets attached to the page. A Frame can be attached to 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.
- [frame.on('framenavigated')](#event-framenavigated) - fired when the frame commits navigation to a different URL. - [page.on('framenavigated')](#pageonframenavigated) - fired when the frame commits navigation to a different URL.
- [frame.on('framedetached')](#event-framedetached) - fired when the frame gets detached from the page. A Frame can be detached from the page only once. - [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: An example of dumping frame tree:
@ -3659,7 +3659,7 @@ error if the object has circular references.
### class: ConsoleMessage ### class: ConsoleMessage
[ConsoleMessage] objects are dispatched by page via the [page.on('console')](#event-console) event. [ConsoleMessage] objects are dispatched by page via the [page.on('console')](#pageonconsole) event.
<!-- GEN:toc --> <!-- GEN:toc -->
- [consoleMessage.args()](#consolemessageargs) - [consoleMessage.args()](#consolemessageargs)
@ -3689,7 +3689,7 @@ One of the following values: `'log'`, `'debug'`, `'info'`, `'error'`, `'warning'
### class: Dialog ### class: Dialog
[Dialog] objects are dispatched by page via the [page.on('dialog')](#event-dialog) event. [Dialog] objects are dispatched by page via the [page.on('dialog')](#pageondialog) event.
An example of using `Dialog` class: An example of using `Dialog` class:
@ -3734,7 +3734,7 @@ const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
### class: Download ### class: Download
[Download] objects are dispatched by page via the [page.on('download')](#event-download) 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 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. files are deleted when the browser closes.
@ -3824,7 +3824,7 @@ upon closing the browser context.
### class: FileChooser ### class: FileChooser
[FileChooser] objects are dispatched by the page in the [page.on('filechooser')](#event-filechooser) event. [FileChooser] objects are dispatched by the page in the [page.on('filechooser')](#pageonfilechooser) event.
```js ```js
page.on('filechooser', async (fileChooser) => { page.on('filechooser', async (fileChooser) => {
@ -4103,12 +4103,12 @@ Dispatches a `touchstart` and `touchend` event with a single touch at the positi
### class: Request ### class: Request
Whenever the page sends a request for a network resource the following sequence of events are emitted by [Page]: Whenever the page sends a request for a network resource the following sequence of events are emitted by [Page]:
- [page.on('request')](#event-request) emitted when the request is issued by the page. - [page.on('request')](#pageonrequest) emitted when the request is issued by the page.
- [page.on('response')](#event-response) emitted when/if the response status and headers are received for the request. - [page.on('response')](#pageonresponse) emitted when/if the response status and headers are received for the request.
- [page.on('requestfinished')](#event-requestfinished) emitted when the response body is downloaded and the request is complete. - [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), If request fails at some point, then instead of `'requestfinished'` event (and possibly instead of 'response' event),
the [page.on('requestfailed')](#event-requestfailed) event is emitted. 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 > **NOTE** HTTP Error responses, such as 404 or 503, are still successful responses from HTTP standpoint, so request
will complete with `'requestfinished'` event. will complete with `'requestfinished'` event.
@ -4453,32 +4453,32 @@ await page.route('**/xhr_endpoint', route => route.fulfill({ path: 'mock_data.js
The [WebSocket] class represents websocket connections in the page. The [WebSocket] class represents websocket connections in the page.
<!-- GEN:toc --> <!-- GEN:toc -->
- [event: 'close'](#event-close-2) - [webSocket.on('close')](#websocketonclose)
- [event: 'framereceived'](#event-framereceived) - [webSocket.on('framereceived')](#websocketonframereceived)
- [event: 'framesent'](#event-framesent) - [webSocket.on('framesent')](#websocketonframesent)
- [event: 'socketerror'](#event-socketerror) - [webSocket.on('socketerror')](#websocketonsocketerror)
- [webSocket.isClosed()](#websocketisclosed) - [webSocket.isClosed()](#websocketisclosed)
- [webSocket.url()](#websocketurl) - [webSocket.url()](#websocketurl)
- [webSocket.waitForEvent(event[, optionsOrPredicate])](#websocketwaitforeventevent-optionsorpredicate) - [webSocket.waitForEvent(event[, optionsOrPredicate])](#websocketwaitforeventevent-optionsorpredicate)
<!-- GEN:stop --> <!-- GEN:stop -->
#### event: 'close' #### webSocket.on('close')
Fired when the websocket closes. Fired when the websocket closes.
#### event: 'framereceived' #### webSocket.on('framereceived')
- <[Object]> web socket frame data - <[Object]> web socket frame data
- `payload` <[string]|[Buffer]> frame payload - `payload` <[string]|[Buffer]> frame payload
Fired when the websocket recieves a frame. Fired when the websocket recieves a frame.
#### event: 'framesent' #### webSocket.on('framesent')
- <[Object]> web socket frame data - <[Object]> web socket frame data
- `payload` <[string]|[Buffer]> frame payload - `payload` <[string]|[Buffer]> frame payload
Fired when the websocket sends a frame. Fired when the websocket sends a frame.
#### event: 'socketerror' #### webSocket.on('socketerror')
- <[String]> the error message - <[String]> the error message
Fired when the websocket has an error. Fired when the websocket has an error.
@ -4610,13 +4610,13 @@ for (const worker of page.workers())
``` ```
<!-- GEN:toc --> <!-- GEN:toc -->
- [event: 'close'](#event-close-3) - [worker.on('close')](#workeronclose)
- [worker.evaluate(pageFunction[, arg])](#workerevaluatepagefunction-arg) - [worker.evaluate(pageFunction[, arg])](#workerevaluatepagefunction-arg)
- [worker.evaluateHandle(pageFunction[, arg])](#workerevaluatehandlepagefunction-arg) - [worker.evaluateHandle(pageFunction[, arg])](#workerevaluatehandlepagefunction-arg)
- [worker.url()](#workerurl) - [worker.url()](#workerurl)
<!-- GEN:stop --> <!-- GEN:stop -->
#### event: 'close' #### worker.on('close')
- <[Worker]> - <[Worker]>
Emitted when this dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is terminated. Emitted when this dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is terminated.
@ -4650,14 +4650,14 @@ the promise to resolve and return its value.
### class: BrowserServer ### class: BrowserServer
<!-- GEN:toc --> <!-- GEN:toc -->
- [event: 'close'](#event-close-4) - [browserServer.on('close')](#browserserveronclose)
- [browserServer.close()](#browserserverclose) - [browserServer.close()](#browserserverclose)
- [browserServer.kill()](#browserserverkill) - [browserServer.kill()](#browserserverkill)
- [browserServer.process()](#browserserverprocess) - [browserServer.process()](#browserserverprocess)
- [browserServer.wsEndpoint()](#browserserverwsendpoint) - [browserServer.wsEndpoint()](#browserserverwsendpoint)
<!-- GEN:stop --> <!-- GEN:stop -->
#### event: 'close' #### browserServer.on('close')
Emitted when the browser server closes. Emitted when the browser server closes.
@ -4932,7 +4932,7 @@ await browser.stopTracing();
<!-- GEN:stop --> <!-- GEN:stop -->
<!-- GEN:toc-extends-Browser --> <!-- GEN:toc-extends-Browser -->
- [event: 'disconnected'](#event-disconnected) - [browser.on('disconnected')](#browserondisconnected)
- [browser.close()](#browserclose) - [browser.close()](#browserclose)
- [browser.contexts()](#browsercontexts) - [browser.contexts()](#browsercontexts)
- [browser.isConnected()](#browserisconnected) - [browser.isConnected()](#browserisconnected)
@ -4967,16 +4967,16 @@ const backgroundPage = await context.waitForEvent('backgroundpage');
``` ```
<!-- GEN:toc --> <!-- GEN:toc -->
- [event: 'backgroundpage'](#event-backgroundpage) - [chromiumBrowserContext.on('backgroundpage')](#chromiumbrowsercontextonbackgroundpage)
- [event: 'serviceworker'](#event-serviceworker) - [chromiumBrowserContext.on('serviceworker')](#chromiumbrowsercontextonserviceworker)
- [chromiumBrowserContext.backgroundPages()](#chromiumbrowsercontextbackgroundpages) - [chromiumBrowserContext.backgroundPages()](#chromiumbrowsercontextbackgroundpages)
- [chromiumBrowserContext.newCDPSession(page)](#chromiumbrowsercontextnewcdpsessionpage) - [chromiumBrowserContext.newCDPSession(page)](#chromiumbrowsercontextnewcdpsessionpage)
- [chromiumBrowserContext.serviceWorkers()](#chromiumbrowsercontextserviceworkers) - [chromiumBrowserContext.serviceWorkers()](#chromiumbrowsercontextserviceworkers)
<!-- GEN:stop --> <!-- GEN:stop -->
<!-- GEN:toc-extends-BrowserContext --> <!-- GEN:toc-extends-BrowserContext -->
- [event: 'close'](#event-close) - [browserContext.on('close')](#browsercontextonclose)
- [event: 'page'](#event-page) - [browserContext.on('page')](#browsercontextonpage)
- [browserContext.addCookies(cookies)](#browsercontextaddcookiescookies) - [browserContext.addCookies(cookies)](#browsercontextaddcookiescookies)
- [browserContext.addInitScript(script[, arg])](#browsercontextaddinitscriptscript-arg) - [browserContext.addInitScript(script[, arg])](#browsercontextaddinitscriptscript-arg)
- [browserContext.browser()](#browsercontextbrowser) - [browserContext.browser()](#browsercontextbrowser)
@ -5001,14 +5001,14 @@ const backgroundPage = await context.waitForEvent('backgroundpage');
- [browserContext.waitForEvent(event[, optionsOrPredicate])](#browsercontextwaitforeventevent-optionsorpredicate) - [browserContext.waitForEvent(event[, optionsOrPredicate])](#browsercontextwaitforeventevent-optionsorpredicate)
<!-- GEN:stop --> <!-- GEN:stop -->
#### event: 'backgroundpage' #### chromiumBrowserContext.on('backgroundpage')
- <[Page]> - <[Page]>
Emitted when new background page is created in the context. Emitted when new background page is created in the context.
> **NOTE** Only works with persistent context. > **NOTE** Only works with persistent context.
#### event: 'serviceworker' #### chromiumBrowserContext.on('serviceworker')
- <[Worker]> - <[Worker]>
Emitted when new service worker is created in the context. Emitted when new service worker is created in the context.
@ -5141,7 +5141,7 @@ send messages.
Firefox browser instance does not expose Firefox-specific features. Firefox browser instance does not expose Firefox-specific features.
<!-- GEN:toc-extends-Browser --> <!-- GEN:toc-extends-Browser -->
- [event: 'disconnected'](#event-disconnected) - [browser.on('disconnected')](#browserondisconnected)
- [browser.close()](#browserclose) - [browser.close()](#browserclose)
- [browser.contexts()](#browsercontexts) - [browser.contexts()](#browsercontexts)
- [browser.isConnected()](#browserisconnected) - [browser.isConnected()](#browserisconnected)
@ -5156,7 +5156,7 @@ Firefox browser instance does not expose Firefox-specific features.
WebKit browser instance does not expose WebKit-specific features. WebKit browser instance does not expose WebKit-specific features.
<!-- GEN:toc-extends-Browser --> <!-- GEN:toc-extends-Browser -->
- [event: 'disconnected'](#event-disconnected) - [browser.on('disconnected')](#browserondisconnected)
- [browser.close()](#browserclose) - [browser.close()](#browserclose)
- [browser.contexts()](#browsercontexts) - [browser.contexts()](#browsercontexts)
- [browser.isConnected()](#browserisconnected) - [browser.isConnected()](#browserisconnected)

4
docs/multi-pages.md
View file

@ -90,7 +90,7 @@ context.on('page', async page => {
#### API reference #### API reference
- [event: 'page'](./api.md#event-page) - [browserContext.on('page')](./api.md#browsercontextonpage)
## Handling popups ## Handling popups
@ -122,4 +122,4 @@ page.on('popup', async popup => {
#### API reference #### API reference
- [event: 'popup'](./api.md#event-popup) - [page.on('popup')](./api.md#pageonpopup)

4
docs/navigations.md
View file

@ -18,9 +18,9 @@ Playwright splits the process of showing a new document in a page into **navigat
- [`page.url()`](api.md#pageurl) is set to the new url - [`page.url()`](api.md#pageurl) is set to the new url
- document content is loaded over network and parsed - document content is loaded over network and parsed
- [`domcontentloaded`](api.md#event-domcontentloaded) event is fired - [`domcontentloaded`](api.md#pageondomcontentloaded) event is fired
- page executes some scripts and loads resources like stylesheets and images - page executes some scripts and loads resources like stylesheets and images
- [`load`](api.md#event-load) event is fired - [`load`](api.md#pageonload) event is fired
- page executes dynamically loaded scripts - page executes dynamically loaded scripts
- `networkidle` is fired when no new network requests are made for 500 ms - `networkidle` is fired when no new network requests are made for 500 ms

32
docs/network.md
View file

@ -30,7 +30,7 @@ await page.goto('https://example.com');
#### API reference #### API reference
- [`browser.newContext([options])`](./api.md#browsernewcontextoptions) - [browser.newContext([options])](./api.md#browsernewcontextoptions)
<br/> <br/>
@ -58,9 +58,9 @@ Note that handling the event forks the control flow and makes script harder to f
#### API reference #### API reference
- [`Download`](https://github.com/microsoft/playwright/blob/master/docs/api.md#class-download) - [Download](https://github.com/microsoft/playwright/blob/master/docs/api.md#class-download)
- [`page.on('download')`](https://github.com/microsoft/playwright/blob/master/docs/api.md#event-download) - [page.on('download')](https://github.com/microsoft/playwright/blob/master/docs/api.md#event-download)
- [`page.waitForEvent(event)`](https://github.com/microsoft/playwright/blob/master/docs/api.md##pagewaitforeventevent-optionsorpredicate) - [page.waitForEvent(event)](https://github.com/microsoft/playwright/blob/master/docs/api.md##pagewaitforeventevent-optionsorpredicate)
<br/> <br/>
@ -116,10 +116,10 @@ const [response] = await Promise.all([
- [class `Request`](./api.md#class-request) - [class `Request`](./api.md#class-request)
- [class `Response`](./api.md#class-response) - [class `Response`](./api.md#class-response)
- [event `'request'`](./api.md#event-request) - [page.on('request')](./api.md#pageonrequest)
- [event `'response'`](./api.md#event-response) - [page.on('response')](./api.md#pageonresponse)
- [`page.waitForRequest(urlOrPredicate[, options])`](./api.md#pagewaitforrequesturlorpredicate-options) - [page.waitForRequest(urlOrPredicate[, options])](./api.md#pagewaitforrequesturlorpredicate-options)
- [`page.waitForResponse(urlOrPredicate[, options])`](./api.md#pagewaitforresponseurlorpredicate-options) - [page.waitForResponse(urlOrPredicate[, options])](./api.md#pagewaitforresponseurlorpredicate-options)
<br/> <br/>
@ -150,11 +150,11 @@ await page.goto('https://example.com');
#### API reference #### API reference
- [`browserContext.route(url, handler)`](./api.md#browsercontextrouteurl-handler) - [browserContext.route(url, handler)](./api.md#browsercontextrouteurl-handler)
- [`browserContext.unroute(url[, handler])`](./api.md#browsercontextunrouteurl-handler) - [browserContext.unroute(url[, handler])](./api.md#browsercontextunrouteurl-handler)
- [`page.route(url, handler)`](./api.md#pagerouteurl-handler) - [page.route(url, handler)](./api.md#pagerouteurl-handler)
- [`page.unroute(url[, handler])`](./api.md#pageunrouteurl-handler) - [page.unroute(url[, handler])](./api.md#pageunrouteurl-handler)
- [`Route`](./api.md#class-route) - [Route](./api.md#class-route)
<br/> <br/>
@ -188,8 +188,8 @@ await page.route('**/*', route => {
#### API reference #### API reference
- [`page.route(url, handler)`](./api.md#pagerouteurl-handler) - [page.route(url, handler)](./api.md#pagerouteurl-handler)
- [`browserContext.route(url, handler)`](./api.md#browsercontextrouteurl-handler) - [browserContext.route(url, handler)](./api.md#browsercontextrouteurl-handler)
- [`route.abort([errorCode])`](./api.md#routeaborterrorcode) - [route.abort([errorCode])](./api.md#routeaborterrorcode)
<br/> <br/>

10
docs/verification.md
View file

@ -98,7 +98,7 @@ await msg.args[1].jsonValue() // 42
- [class: ConsoleMessage](./api.md#class-consolemessage) - [class: ConsoleMessage](./api.md#class-consolemessage)
- [class: Page](./api.md#class-page) - [class: Page](./api.md#class-page)
- [event: 'console'](./api.md#event-console) - [page.on('console')](./api.md#pageonconsole)
<br/> <br/>
@ -119,7 +119,7 @@ await page.goto('data:text/html,<script>throw new Error("Test")</script>');
#### API reference #### API reference
- [class: Page](./api.md#class-page) - [class: Page](./api.md#class-page)
- [event: 'pageerror'](./api.md#event-pageerror) - [page.on('pageerror')](./api.md#pageonpageerror)
<br/> <br/>
@ -153,6 +153,6 @@ const [popup] = await Promise.all([
#### API reference #### API reference
- [class: Page](./api.md#class-page) - [class: Page](./api.md#class-page)
- [event: 'requestfailed'](./api.md#event-requestfailed) - [page.on('requestfailed')](./api.md#pageonrequestfailed)
- [event: 'dialog'](./api.md#event-dialog) - [page.on('dialog')](./api.md#pageondialog)
- [event: 'popup'](./api.md#event-popup) - [page.on('popup')](./api.md#pageonpopup)

4
utils/doclint/check_public_api/MDBuilder.js
View file

@ -233,9 +233,9 @@ class MDOutline {
this.errors = errors; this.errors = errors;
const classHeading = /^class: (\w+)$/; const classHeading = /^class: (\w+)$/;
const constructorRegex = /^new (\w+)\((.*)\)$/; const constructorRegex = /^new (\w+)\((.*)\)$/;
const methodRegex = /^(\w+)\.([\w$]+)\((.*)\)$/; const methodRegex = /^(\w+)\.([\w$]+)\(([^']*)\)$/;
const propertyRegex = /^(\w+)\.(\w+)$/; const propertyRegex = /^(\w+)\.(\w+)$/;
const eventRegex = /^event: '(\w+)'$/; const eventRegex = /^.*\.on\('(\w+)'\)$/;
let currentClassName = null; let currentClassName = null;
let currentClassMembers = []; let currentClassMembers = [];
let currentClassComment = ''; let currentClassComment = '';

20
utils/doclint/check_public_api/index.js
View file

@ -102,9 +102,9 @@ function compareDocumentations(actual, expected) {
const expectedClasses = Array.from(expected.classes.keys()).sort(); const expectedClasses = Array.from(expected.classes.keys()).sort();
const classesDiff = diff(actualClasses, expectedClasses); const classesDiff = diff(actualClasses, expectedClasses);
for (const className of classesDiff.extra) for (const className of classesDiff.extra)
errors.push(`Non-existing class found: ${className}`); errors.push(`Documented but not implemented class: ${className}`);
for (const className of classesDiff.missing) for (const className of classesDiff.missing)
errors.push(`Class not found: ${className}`); errors.push(`Implemented but not documented class: ${className}`);
for (const className of classesDiff.equal) { for (const className of classesDiff.equal) {
const actualClass = actual.classes.get(className); const actualClass = actual.classes.get(className);
@ -113,9 +113,9 @@ function compareDocumentations(actual, expected) {
const expectedMethods = Array.from(expectedClass.methods.keys()).sort(); const expectedMethods = Array.from(expectedClass.methods.keys()).sort();
const methodDiff = diff(actualMethods, expectedMethods); const methodDiff = diff(actualMethods, expectedMethods);
for (const methodName of methodDiff.extra) for (const methodName of methodDiff.extra)
errors.push(`Non-existing method found: ${className}.${methodName}()`); errors.push(`Documented but not implemented method: ${className}.${methodName}()`);
for (const methodName of methodDiff.missing) for (const methodName of methodDiff.missing)
errors.push(`Method not found: ${className}.${methodName}()`); errors.push(`Implemented but not documented method: ${className}.${methodName}()`);
for (const methodName of methodDiff.equal) { for (const methodName of methodDiff.equal) {
const actualMethod = actualClass.methods.get(methodName); const actualMethod = actualClass.methods.get(methodName);
@ -134,9 +134,9 @@ function compareDocumentations(actual, expected) {
if (argsDiff.extra.length || argsDiff.missing.length) { if (argsDiff.extra.length || argsDiff.missing.length) {
const text = [`Method ${className}.${methodName}() fails to describe its parameters:`]; const text = [`Method ${className}.${methodName}() fails to describe its parameters:`];
for (const arg of argsDiff.missing) for (const arg of argsDiff.missing)
text.push(`- Argument not found: ${arg}`); text.push(`- Implemented but not documented argument: ${arg}`);
for (const arg of argsDiff.extra) for (const arg of argsDiff.extra)
text.push(`- Non-existing argument found: ${arg}`); text.push(`- Documented but not implemented argument: ${arg}`);
errors.push(text.join('\n')); errors.push(text.join('\n'));
} }
@ -147,20 +147,20 @@ function compareDocumentations(actual, expected) {
const expectedProperties = Array.from(expectedClass.properties.keys()).sort(); const expectedProperties = Array.from(expectedClass.properties.keys()).sort();
const propertyDiff = diff(actualProperties, expectedProperties); const propertyDiff = diff(actualProperties, expectedProperties);
for (const propertyName of propertyDiff.extra) for (const propertyName of propertyDiff.extra)
errors.push(`Non-existing property found: ${className}.${propertyName}`); errors.push(`Documented but not implemented property: ${className}.${propertyName}`);
for (const propertyName of propertyDiff.missing) { for (const propertyName of propertyDiff.missing) {
if (propertyName === 'T') if (propertyName === 'T')
continue; continue;
errors.push(`Property not found: ${className}.${propertyName}`); errors.push(`Implemented but not documented property: ${className}.${propertyName}`);
} }
const actualEvents = Array.from(actualClass.events.keys()).sort(); const actualEvents = Array.from(actualClass.events.keys()).sort();
const expectedEvents = Array.from(expectedClass.events.keys()).sort(); const expectedEvents = Array.from(expectedClass.events.keys()).sort();
const eventsDiff = diff(actualEvents, expectedEvents); const eventsDiff = diff(actualEvents, expectedEvents);
for (const eventName of eventsDiff.extra) for (const eventName of eventsDiff.extra)
errors.push(`Non-existing event found in class ${className}: '${eventName}'`); errors.push(`Documented but not implemented event ${className}: '${eventName}'`);
for (const eventName of eventsDiff.missing) for (const eventName of eventsDiff.missing)
errors.push(`Event not found in class ${className}: '${eventName}'`); errors.push(`Implemented but not documented event ${className}: '${eventName}'`);
} }

6
utils/doclint/check_public_api/test/check-sorting/doc.md
View file

@ -1,12 +1,12 @@
### class: Foo ### class: Foo
#### event: 'c' #### foo.on('c')
#### event: 'a' #### foo.on('a')
#### foo.aaa() #### foo.aaa()
#### event: 'b' #### foo.on('b')
#### foo.ddd #### foo.ddd

4
utils/doclint/check_public_api/test/diff-arguments/result.txt
View file

@ -1,4 +1,4 @@
[MarkDown] Heading arguments for "foo.test(...files)" do not match described ones, i.e. "...files" != "...filePaths" [MarkDown] Heading arguments for "foo.test(...files)" do not match described ones, i.e. "...files" != "...filePaths"
[MarkDown] Method Foo.foo() fails to describe its parameters: [MarkDown] Method Foo.foo() fails to describe its parameters:
- Argument not found: arg3 - Implemented but not documented argument: arg3
- Non-existing argument found: arg2 - Documented but not implemented argument: arg2

6
utils/doclint/check_public_api/test/diff-classes/result.txt
View file

@ -1,3 +1,3 @@
[MarkDown] Non-existing class found: Bar [MarkDown] Documented but not implemented class: Bar
[MarkDown] Non-existing class found: Baz [MarkDown] Documented but not implemented class: Baz
[MarkDown] Class not found: Other [MarkDown] Implemented but not documented class: Other

4
utils/doclint/check_public_api/test/diff-events/doc.md
View file

@ -1,5 +1,5 @@
### class: Foo ### class: Foo
#### event: 'start' #### foo.on('start')
#### event: 'stop' #### foo.on('stop')

4
utils/doclint/check_public_api/test/diff-events/result.txt
View file

@ -1,2 +1,2 @@
[MarkDown] Non-existing event found in class Foo: 'stop' [MarkDown] Implemented but not documented event Foo: 'finish'
[MarkDown] Event not found in class Foo: 'finish' [MarkDown] Implemented but not documented event Foo: 'start'

6
utils/doclint/check_public_api/test/diff-methods/result.txt
View file

@ -1,3 +1,3 @@
[MarkDown] Non-existing method found: Foo.proceed() [MarkDown] Documented but not implemented method: Foo.proceed()
[MarkDown] Method not found: Foo.stop() [MarkDown] Implemented but not documented method: Foo.stop()
[MarkDown] Property not found: Foo.zzz [MarkDown] Implemented but not documented property: Foo.zzz

4
utils/doclint/check_public_api/test/diff-properties/result.txt
View file

@ -1,2 +1,2 @@
[MarkDown] Non-existing property found: Foo.c [MarkDown] Documented but not implemented property: Foo.c
[MarkDown] Property not found: Foo.b [MarkDown] Implemented but not documented property: Foo.b

2
utils/doclint/check_public_api/test/md-builder-common/doc.md
View file

@ -2,7 +2,7 @@
This is a class. This is a class.
#### event: 'frame' #### foo.on('frame')
- <[Frame]> - <[Frame]>
This event is dispatched. This event is dispatched.

83
utils/doclint/cli.js
View file

@ -59,47 +59,67 @@ async function run() {
{ {
const nodes = parseMd(renderMdTemplate(body, params)); const nodes = parseMd(renderMdTemplate(body, params));
const signatures = new Map(); const signatures = new Map();
let h4; let lastMethod;
let args; let args;
const flush = () => { const flushMethodSignature = () => {
if (h4 && !['page.accessibility', 'page.mouse', 'page.keyboard', 'page.coverage', 'page.touchscreen'].includes(h4.h4)) { if (!lastMethod)
const tokens = []; return;
let hasOptional = false; const tokens = [];
for (const arg of args) { let hasOptional = false;
const optional = arg.name === 'options' || arg.text.includes('Optional'); for (const arg of args) {
if (tokens.length) { const optional = arg.name === 'options' || arg.text.includes('Optional');
if (optional && !hasOptional) if (tokens.length) {
tokens.push(`[, ${arg.name}`); if (optional && !hasOptional)
else tokens.push(`[, ${arg.name}`);
tokens.push(`, ${arg.name}`); else
} else { tokens.push(`, ${arg.name}`);
if (optional && !hasOptional) } else {
tokens.push(`[${arg.name}`); if (optional && !hasOptional)
else tokens.push(`[${arg.name}`);
tokens.push(`${arg.name}`); else
} tokens.push(`${arg.name}`);
hasOptional = hasOptional || optional;
} }
if (hasOptional) hasOptional = hasOptional || optional;
tokens.push(']');
const signature = tokens.join('');
signatures.set(h4.h4, signature);
h4.h4 = `${h4.h4}(${signature})`;
} }
h4 = null; if (hasOptional)
tokens.push(']');
const signature = tokens.join('');
signatures.set(lastMethod.h4, signature);
lastMethod.h4 = `${lastMethod.h4}(${signature})`;
lastMethod = null;
args = null; args = null;
}; };
for (const node of nodes) { for (const node of nodes) {
if (node.h1 || node.h2 || node.h3 || node.h4) if (node.h1 || node.h2 || node.h3 || node.h4)
flush(); flushMethodSignature();
if (node.h4) { if (node.h4) {
h4 = node.h4.startsWith('event:') ? null : node; lastMethod = null;
args = node.h4.startsWith('event:') ? null : []; args = null;
let match = node.h4.match(/(event|method|namespace) (JS|CDP|[A-Z])([^.]+)\.(.*)/);
if (!match)
continue;
if (match[1] === 'event') {
node.h4 = `${match[2].toLowerCase() + match[3]}.on('${match[4]}')`;
continue;
}
if (match[1] === 'method') {
node.h4 = `${match[2].toLowerCase() + match[3]}.${match[4]}`;
lastMethod = node;
args = [];
continue;
}
if (match[1] === 'namespace') {
node.h4 = `${match[2].toLowerCase() + match[3]}.${match[4]}`;
continue;
}
continue; continue;
} }
if (args && node.li && node.liType === 'default' && !node.li.startsWith('returns')) { if (args && node.li && node.liType === 'default' && !node.li.startsWith('returns'))
args.push(parseArgument(node.li)); args.push(parseArgument(node.li));
}
} }
api.setText([comment, header, renderMd(nodes), footer].join('\n')); api.setText([comment, header, renderMd(nodes), footer].join('\n'));
@ -202,7 +222,8 @@ async function getChromeVersion() {
function getRepositoryFiles() { function getRepositoryFiles() {
const out = spawnSync('git', ['ls-files'], {cwd: PROJECT_DIR}); const out = spawnSync('git', ['ls-files'], {cwd: PROJECT_DIR});
return out.stdout.toString().trim().split('\n').map(file => path.join(PROJECT_DIR, file)); const files = out.stdout.toString().trim().split('\n').filter(f => !f.startsWith('docs-src'));
return files.map(file => path.join(PROJECT_DIR, file));
} }
async function getFirefoxVersion() { async function getFirefoxVersion() {

9
utils/doclint/preprocessor/index.js
View file

@ -126,7 +126,6 @@ function autocorrectInvalidLinks(projectRoot, sources, allowedFilePaths) {
} }
const sourceEdits = new SourceEdits(source); const sourceEdits = new SourceEdits(source);
let offset = 0; let offset = 0;
const edits = [];
const lines = source.text().split('\n'); const lines = source.text().split('\n');
lines.forEach((line, lineNumber) => { lines.forEach((line, lineNumber) => {
@ -192,10 +191,10 @@ function generateLinks(source, signatures, messages) {
while (match = linkRegex.exec(line)) { while (match = linkRegex.exec(line)) {
const [, name] = match; const [, name] = match;
const hrefOffset = offset + lineNumber + match.index + 3 + name.length; const hrefOffset = offset + lineNumber + match.index + 3 + name.length;
const eventMatch = name.match(/.*on\('(.*)'\)/); const eventMatch = name.match(/.*on\('.*'\)/);
let replacement; let replacement;
if (eventMatch) { if (eventMatch) {
replacement = `#event-${eventMatch[1]}`; replacement = eventMatch[0];
} else { } else {
const method = name.substring(0, name.length - 2); const method = name.substring(0, name.length - 2);
let signature = signatures.get(method); let signature = signatures.get(method);
@ -204,9 +203,9 @@ function generateLinks(source, signatures, messages) {
signature = '\u2026'; signature = '\u2026';
} }
sourceEdits.edit(hrefOffset - 3, hrefOffset - 3, signature); sourceEdits.edit(hrefOffset - 3, hrefOffset - 3, signature);
replacement = `#${(name + signature).toLowerCase().replace(/[^a-z]/gm, '')}`; replacement = name + signature;
} }
sourceEdits.edit(hrefOffset, hrefOffset, replacement); sourceEdits.edit(hrefOffset, hrefOffset, '#' + replacement.toLowerCase().replace(/[^a-z]/gm, ''));
} }
offset += line.length; offset += line.length;
}); });