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

chore: generate types, api.json off md rather than html (#4825)

Browse source
This commit is contained in:
Pavel Feldman 2020-12-26 14:31:41 -08:00 committed by GitHub
parent 9dd982c508
commit 15cdfd1cc1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
31 changed files with 1302 additions and 1330 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -132,7 +132,7 @@ Emitted when Browser context gets closed. This might happen because of one of th
* The [`method: Browser.close`]() method was called. * The [`method: Browser.close`]() method was called.
## event: BrowserContext.page ## event: BrowserContext.page
- <[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 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 [`event: Page.popup`]() to receive events about popups relevant to a specific page. also fire for popup pages. See also [`event: Page.popup`]() to receive events about popups relevant to a specific page.
@ -165,13 +165,13 @@ await browserContext.addCookies([cookieObject1, cookieObject2]);
- `cookies` <[Array]<[Object]>> - `cookies` <[Array]<[Object]>>
- `name` <[string]> **required** - `name` <[string]> **required**
- `value` <[string]> **required** - `value` <[string]> **required**
- `url` <[string]> either url or domain / path are required - `url` <[string]> either url or domain / path are required. Optional.
- `domain` <[string]> either url or domain / path are required - `domain` <[string]> either url or domain / path are required Optional.
- `path` <[string]> either url or domain / path are required - `path` <[string]> either url or domain / path are required Optional.
- `expires` <[number]> Unix time in seconds. - `expires` <[number]> Unix time in seconds. Optional.
- `httpOnly` <[boolean]> - `httpOnly` <[boolean]> Optional.
- `secure` <[boolean]> - `secure` <[boolean]> Optional.
- `sameSite` <"Strict"|"Lax"|"None"> - `sameSite` <"Strict"|"Lax"|"None"> Optional.
## async method: BrowserContext.addInitScript ## async method: BrowserContext.addInitScript
@ -201,8 +201,8 @@ await browserContext.addInitScript({
### param: BrowserContext.addInitScript.script ### param: BrowserContext.addInitScript.script
- `script` <[function]|[string]|[Object]> - `script` <[function]|[string]|[Object]>
- `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw script content. - `content` <[string]> Raw script content. Optional.
Script to be evaluated in all pages in the browser context. Script to be evaluated in all pages in the browser context.
@ -372,24 +372,24 @@ specified.
### param: BrowserContext.grantPermissions.permissions ### param: BrowserContext.grantPermissions.permissions
- `permissions` <[Array]<[string]>> - `permissions` <[Array]<[string]>>
- `'geolocation'`
- `'midi'`
- `'midi-sysex'` (system-exclusive midi)
- `'notifications'`
- `'push'`
- `'camera'`
- `'microphone'`
- `'background-sync'`
- `'ambient-light-sensor'`
- `'accelerometer'`
- `'gyroscope'`
- `'magnetometer'`
- `'accessibility-events'`
- `'clipboard-read'`
- `'clipboard-write'`
- `'payment-handler'`
A permission or an array of permissions to grant. Permissions can be one of the following values: A permission or an array of permissions to grant. Permissions can be one of the following values:
* `'geolocation'`
* `'midi'`
* `'midi-sysex'` (system-exclusive midi)
* `'notifications'`
* `'push'`
* `'camera'`
* `'microphone'`
* `'background-sync'`
* `'ambient-light-sensor'`
* `'accelerometer'`
* `'gyroscope'`
* `'magnetometer'`
* `'accessibility-events'`
* `'clipboard-read'`
* `'clipboard-write'`
* `'payment-handler'`
### option: BrowserContext.grantPermissions.origin ### option: BrowserContext.grantPermissions.origin
- `origin` <[string]> - `origin` <[string]>
@ -643,7 +643,7 @@ page.removeListener('request', logRequest);
Emitted when the page closes. Emitted when the page closes.
## event: Page.console ## event: Page.console
- <[ConsoleMessage]> - type: <[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
emitted if the page throws an error or a warning. emitted if the page throws an error or a warning.
@ -692,7 +692,7 @@ await new Promise((resolve, reject) => {
``` ```
## event: Page.dialog ## event: Page.dialog
- <[Dialog]> - type: <[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 [`method: Dialog.accept`]() or [`method: Dialog.dismiss`]() methods. to the dialog via [`method: Dialog.accept`]() or [`method: Dialog.dismiss`]() methods.
@ -703,7 +703,7 @@ Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/e
event is dispatched. event is dispatched.
## event: Page.download ## event: Page.download
- <[Download]> - type: <[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
[Download] instance. [Download] instance.
@ -713,7 +713,7 @@ downloaded content. If `acceptDownloads` is not set or set to `false`, download
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: Page.filechooser ## event: Page.filechooser
- <[FileChooser]> - type: <[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
respond to it via setting the input files using [`method: FileChooser.setFiles`]() that can be uploaded after that. respond to it via setting the input files using [`method: FileChooser.setFiles`]() that can be uploaded after that.
@ -725,17 +725,17 @@ page.on('filechooser', async (fileChooser) => {
``` ```
## event: Page.frameattached ## event: Page.frameattached
- <[Frame]> - type: <[Frame]>
Emitted when a frame is attached. Emitted when a frame is attached.
## event: Page.framedetached ## event: Page.framedetached
- <[Frame]> - type: <[Frame]>
Emitted when a frame is detached. Emitted when a frame is detached.
## event: Page.framenavigated ## event: Page.framenavigated
- <[Frame]> - type: <[Frame]>
Emitted when a frame is navigated to a new url. Emitted when a frame is navigated to a new url.
@ -744,12 +744,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. Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched.
## event: Page.pageerror ## event: Page.pageerror
- <[Error]> The exception message - type: <[Error]> The exception message
Emitted when an uncaught exception happens within the page. Emitted when an uncaught exception happens within the page.
## event: Page.popup ## event: Page.popup
- <[Page]> Page corresponding to "popup" window - type: <[Page]> Page corresponding to "popup" window
Emitted when the page opens a new tab or window. This event is emitted in addition to the [`event: 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. BrowserContext.page`](), but only for popups relevant to this page.
@ -770,13 +770,13 @@ console.log(await popup.evaluate('location.href'));
need it in most cases). need it in most cases).
## event: Page.request ## event: Page.request
- <[Request]> - type: <[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
[`method: Page.route`]() or [`method: BrowserContext.route`](). [`method: Page.route`]() or [`method: BrowserContext.route`]().
## event: Page.requestfailed ## event: Page.requestfailed
- <[Request]> - type: <[Request]>
Emitted when a request fails, for example by timing out. Emitted when a request fails, for example by timing out.
@ -784,24 +784,24 @@ Emitted when a request fails, for example by timing out.
will complete with [`event: Page.requestfinished`]() event and not with [`event: Page.requestfailed`](). will complete with [`event: Page.requestfinished`]() event and not with [`event: Page.requestfailed`]().
## event: Page.requestfinished ## event: Page.requestfinished
- <[Request]> - type: <[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: Page.response ## event: Page.response
- <[Response]> - type: <[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: Page.websocket ## event: Page.websocket
- <[WebSocket]> websocket - type: <[WebSocket]> websocket
Emitted when <[WebSocket]> request is sent. Emitted when <[WebSocket]> request is sent.
## event: Page.worker ## event: Page.worker
- <[Worker]> - type: <[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
page. page.
@ -885,8 +885,8 @@ Function to be evaluated in browser context
Optional argument to pass to [`param: pageFunction`]() Optional argument to pass to [`param: pageFunction`]()
## namespace: Page.accessibility ## property: Page.accessibility
- returns: <[Accessibility]> - type: <[Accessibility]>
## async method: Page.addInitScript ## async method: Page.addInitScript
@ -913,8 +913,8 @@ await page.addInitScript(preloadFile);
### param: Page.addInitScript.script ### param: Page.addInitScript.script
- `script` <[function]|[string]|[Object]> - `script` <[function]|[string]|[Object]>
- `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw script content. - `content` <[string]> Raw script content. Optional.
Script to be evaluated in the page. Script to be evaluated in the page.
@ -933,10 +933,10 @@ Shortcut for main frame's [`method: Frame.addScriptTag`]().
### param: Page.addScriptTag.params ### param: Page.addScriptTag.params
- `params` <[Object]> - `params` <[Object]>
- `url` <[string]> URL of a script to be added. - `url` <[string]> URL of a script to be added. Optional.
- `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw JavaScript content to be injected into frame. - `content` <[string]> Raw JavaScript content to be injected into frame. Optional.
- `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details. - `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details. Optional.
## async method: Page.addStyleTag ## async method: Page.addStyleTag
- returns: <[ElementHandle]> - returns: <[ElementHandle]>
@ -948,9 +948,9 @@ Shortcut for main frame's [`method: Frame.addStyleTag`]().
### param: Page.addStyleTag.params ### param: Page.addStyleTag.params
- `params` <[Object]> - `params` <[Object]>
- `url` <[string]> URL of the `<link>` tag. - `url` <[string]> URL of the `<link>` tag. Optional.
- `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw CSS content to be injected into frame. - `content` <[string]> Raw CSS content to be injected into frame. Optional.
## async method: Page.bringToFront ## async method: Page.bringToFront
@ -1039,8 +1039,8 @@ Gets the full HTML contents of the page, including the doctype.
Get the browser context that the page belongs to. Get the browser context that the page belongs to.
## namespace: Page.coverage ## property: Page.coverage
- returns: <[null]|[ChromiumCoverage]> - type: <[null]|[ChromiumCoverage]>
Browser-specific Coverage implementation, only available for Chromium atm. See Browser-specific Coverage implementation, only available for Chromium atm. See
[ChromiumCoverage](#class-chromiumcoverage) for more details. [ChromiumCoverage](#class-chromiumcoverage) for more details.
@ -1155,13 +1155,13 @@ await page.evaluate(() => matchMedia('(prefers-color-scheme: no-preference)').ma
### param: Page.emulateMedia.params ### param: Page.emulateMedia.params
- `params` <[Object]> - `params` <[Object]>
- `media` <[null]|"screen"|"print"> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation. Omitting `media` or passing `undefined` does not change the emulated value. - `media` <[null]|"screen"|"print"> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation. Omitting `media` or passing `undefined` does not change the emulated value. Optional.
- `colorScheme` <[null]|"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing `null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated value. - `colorScheme` <[null]|"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing `null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated value. Optional.
## async method: Page.evaluate ## async method: Page.evaluate
- returns: <[Serializable]> - returns: <[Serializable]>
Returns the value of the [`param: pageFunction`]() invacation. Returns the value of the [`param: pageFunction`]() invocation.
If the function passed to the `page.evaluate` returns a [Promise], then `page.evaluate` would wait for the promise to 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. resolve and return its value.
@ -1210,7 +1210,7 @@ Optional argument to pass to [`param: pageFunction`]()
## async method: Page.evaluateHandle ## async method: Page.evaluateHandle
- returns: <[JSHandle]> - returns: <[JSHandle]>
Returns the value of the [`param: pageFunction`]() invacation as in-page object (JSHandle). Returns the value of the [`param: pageFunction`]() invocation as in-page object (JSHandle).
The only difference between `page.evaluate` and `page.evaluateHandle` is that `page.evaluateHandle` returns in-page The only difference between `page.evaluate` and `page.evaluateHandle` is that `page.evaluateHandle` returns in-page
object (JSHandle). object (JSHandle).
@ -1432,8 +1432,8 @@ const frame = page.frame({ url: /.*domain.*/ });
### param: Page.frame.frameSelector ### param: Page.frame.frameSelector
- `frameSelector` <[string]|[Object]> - `frameSelector` <[string]|[Object]>
- `name` <[string]> frame name specified in the `iframe`'s `name` attribute - `name` <[string]> Frame name specified in the `iframe`'s `name` attribute. Optional.
- `url` <[string]|[RegExp]|[Function]> A glob pattern, regex pattern or predicate receiving frame's `url` as a [URL] object. - `url` <[string]|[RegExp]|[Function]> A glob pattern, regex pattern or predicate receiving frame's `url` as a [URL] object. Optional.
Frame name or other frame lookup options. Frame name or other frame lookup options.
@ -1566,16 +1566,16 @@ Returns `element.innerText`.
Indicates that the page has been closed. Indicates that the page has been closed.
## namespace: Page.keyboard ## property: Page.keyboard
- returns: <[Keyboard]> - type: <[Keyboard]>
## method: Page.mainFrame ## method: Page.mainFrame
- returns: <[Frame]> - returns: <[Frame]>
The page's main frame. Page is guaranteed to have a main frame which persists during navigations. The page's main frame. Page is guaranteed to have a main frame which persists during navigations.
## namespace: Page.mouse ## property: Page.mouse
- returns: <[Mouse]> - type: <[Mouse]>
## async method: Page.opener ## async method: Page.opener
- returns: <[null]|[Page]> - returns: <[null]|[Page]>
@ -1651,14 +1651,14 @@ Display header and footer. Defaults to `false`.
### option: Page.pdf.headerTemplate ### option: Page.pdf.headerTemplate
- `headerTemplate` <[string]> - `headerTemplate` <[string]>
- `'date'` formatted print date
- `'title'` document title
- `'url'` document location
- `'pageNumber'` current page number
- `'totalPages'` total pages in the document
HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values
into them: into them:
* `'date'` formatted print date
* `'title'` document title
* `'url'` document location
* `'pageNumber'` current page number
* `'totalPages'` total pages in the document
### option: Page.pdf.footerTemplate ### option: Page.pdf.footerTemplate
- `footerTemplate` <[string]> - `footerTemplate` <[string]>
@ -1722,7 +1722,7 @@ generate the text for. A superset of the [`param: key`]() values can be found
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
`Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc. `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
Following modification shortcuts are also suported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`. Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
Holding down `Shift` will type the text that corresponds to the [`param: key`]() in the upper case. Holding down `Shift` will type the text that corresponds to the [`param: key`]() in the upper case.
@ -1885,9 +1885,9 @@ Shortcut for main frame's [`method: Frame.selectOption`]()
### param: Page.selectOption.values ### param: Page.selectOption.values
- `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> - `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>>
- `value` <[string]> Matches by `option.value`. - `value` <[string]> Matches by `option.value`. Optional.
- `label` <[string]> Matches by `option.label`. - `label` <[string]> Matches by `option.label`. Optional.
- `index` <[number]> Matches by the index. - `index` <[number]> Matches by the index. Optional.
Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option
@ -2028,8 +2028,8 @@ Returns `element.textContent`.
Returns the page's title. Shortcut for main frame's [`method: Frame.title`](). Returns the page's title. Shortcut for main frame's [`method: Frame.title`]().
## namespace: Page.touchscreen ## property: Page.touchscreen
- returns: <[Touchscreen]> - type: <[Touchscreen]>
## async method: Page.type ## async method: Page.type
@ -2208,12 +2208,12 @@ Shortcut for main frame's [`method: Frame.waitForLoadState`]().
### param: Page.waitForLoadState.state ### param: Page.waitForLoadState.state
- `state` <"load"|"domcontentloaded"|"networkidle"> - `state` <"load"|"domcontentloaded"|"networkidle">
- `'load'` - wait for the `load` event to be fired.
- `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
- `'networkidle'` - wait until there are no network connections for at least `500` ms.
Load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the
method resolves immediately. Optional. method resolves immediately. Can be one of:
* `'load'` - wait for the `load` event to be fired.
* `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
* `'networkidle'` - wait until there are no network connections for at least `500` ms.
### option: Page.waitForLoadState.timeout = %%-navigation-timeout-%% ### option: Page.waitForLoadState.timeout = %%-navigation-timeout-%%
@ -2366,9 +2366,9 @@ At every point of time, page exposes its current frame tree via the [`method: Pa
Frame.childFrames`]() methods. Frame.childFrames`]() 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:
- [`event: Page.frameattached`]() - fired when the frame gets attached to the page. A Frame can be attached to the page only once. * [`event: Page.frameattached`]() - fired when the frame gets attached to the page. A Frame can be attached to the page only once.
- [`event: Page.framenavigated`]() - fired when the frame commits navigation to a different URL. * [`event: Page.framenavigated`]() - fired when the frame commits navigation to a different URL.
- [`event: Page.framedetached`]() - fired when the frame gets detached from the page. A Frame can be detached from the page only once. * [`event: Page.framedetached`]() - 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:
@ -2493,10 +2493,10 @@ Adds a `<script>` tag into the page with the desired url or content.
### param: Frame.addScriptTag.params ### param: Frame.addScriptTag.params
- `params` <[Object]> - `params` <[Object]>
- `url` <[string]> URL of a script to be added. - `url` <[string]> URL of a script to be added. Optional.
- `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw JavaScript content to be injected into frame. - `content` <[string]> Raw JavaScript content to be injected into frame. Optional.
- `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details. - `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details. Optional.
## async method: Frame.addStyleTag ## async method: Frame.addStyleTag
- returns: <[ElementHandle]> - returns: <[ElementHandle]>
@ -2508,9 +2508,9 @@ content.
### param: Frame.addStyleTag.params ### param: Frame.addStyleTag.params
- `params` <[Object]> - `params` <[Object]>
- `url` <[string]> URL of the `<link>` tag. - `url` <[string]> URL of the `<link>` tag. Optional.
- `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw CSS content to be injected into frame. - `content` <[string]> Raw CSS content to be injected into frame. Optional.
## async method: Frame.check ## async method: Frame.check
@ -2902,7 +2902,7 @@ generate the text for. A superset of the [`param: key`]() values can be found
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
`Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc. `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
Following modification shortcuts are also suported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`. Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
Holding down `Shift` will type the text that corresponds to the [`param: key`]() in the upper case. Holding down `Shift` will type the text that corresponds to the [`param: key`]() in the upper case.
@ -2951,9 +2951,9 @@ frame.selectOption('select#colors', 'red', 'green', 'blue');
### param: Frame.selectOption.values ### param: Frame.selectOption.values
- `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> - `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>>
- `value` <[string]> Matches by `option.value`. - `value` <[string]> Matches by `option.value`. Optional.
- `label` <[string]> Matches by `option.label`. - `label` <[string]> Matches by `option.label`. Optional.
- `index` <[number]> Matches by the index. - `index` <[number]> Matches by the index. Optional.
Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option
@ -3145,12 +3145,12 @@ await frame.waitForLoadState(); // Waits for 'load' state by default.
### param: Frame.waitForLoadState.state ### param: Frame.waitForLoadState.state
- `state` <"load"|"domcontentloaded"|"networkidle"> - `state` <"load"|"domcontentloaded"|"networkidle">
- `'load'` - wait for the `load` event to be fired.
- `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
- `'networkidle'` - wait until there are no network connections for at least `500` ms.
Load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the
method returns immediately. Optional. method returns immediately. Can be one of:
* `'load'` - wait for the `load` event to be fired.
* `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
* `'networkidle'` - wait until there are no network connections for at least `500` ms.
### option: Frame.waitForLoadState.timeout = %%-navigation-timeout-%% ### option: Frame.waitForLoadState.timeout = %%-navigation-timeout-%%
@ -3350,8 +3350,8 @@ Optional argument to pass to [`param: pageFunction`]()
- returns: <[null]|[Object]> - returns: <[null]|[Object]>
- `x` <[number]> the x coordinate of the element in pixels. - `x` <[number]> the x coordinate of the element in pixels.
- `y` <[number]> the y coordinate of the element in pixels. - `y` <[number]> the y coordinate of the element in pixels.
- width <[number]> the width of the element in pixels. - `width` <[number]> the width of the element in pixels.
- height <[number]> the height of the element in pixels. - `height` <[number]> the height of the element in pixels.
This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is
calculated relative to the main frame viewport - which is usually the same as the browser window. calculated relative to the main frame viewport - which is usually the same as the browser window.
@ -3573,7 +3573,7 @@ generate the text for. A superset of the [`param: key`]() values can be found
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
`Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc. `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
Following modification shortcuts are also suported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`. Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
Holding down `Shift` will type the text that corresponds to the [`param: key`]() in the upper case. Holding down `Shift` will type the text that corresponds to the [`param: key`]() in the upper case.
@ -3636,7 +3636,7 @@ This method waits for [actionability](./actionability.md) checks, then tries to
completely visible as defined by completely visible as defined by
[IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)'s ```ratio```. [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)'s ```ratio```.
Throws when ```elementHandle``` does not point to an element Throws when `elementHandle` does not point to an element
[connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) to a Document or a ShadowRoot. [connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) to a Document or a ShadowRoot.
### option: ElementHandle.scrollIntoViewIfNeeded.timeout = %%-input-timeout-%% ### option: ElementHandle.scrollIntoViewIfNeeded.timeout = %%-input-timeout-%%
@ -3665,9 +3665,9 @@ handle.selectOption({ value: 'blue' }, { index: 2 }, 'red');
### param: ElementHandle.selectOption.values ### param: ElementHandle.selectOption.values
- `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> - `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>>
- `value` <[string]> Matches by `option.value`. - `value` <[string]> Matches by `option.value`. Optional.
- `label` <[string]> Matches by `option.label`. - `label` <[string]> Matches by `option.label`. Optional.
- `index` <[number]> Matches by the index. - `index` <[number]> Matches by the index. Optional.
Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option
@ -3939,9 +3939,7 @@ property to get
## async method: JSHandle.jsonValue ## async method: JSHandle.jsonValue
- returns: <[Serializable]> - returns: <[Serializable]>
Returns a JSON representation of the object. If the object has a Returns a JSON representation of the object. If the object has a `toJSON` function, it **will not be called**.
[`toJSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON()_behavior)
function, it **will not be called**.
> **NOTE** The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an > **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. error if the object has circular references.
@ -3958,7 +3956,7 @@ error if the object has circular references.
## method: ConsoleMessage.location ## method: ConsoleMessage.location
- returns: <[Object]> - returns: <[Object]>
- `url` <[string]> URL of the resource if available, otherwise empty string. - `url` <[string]> URL of the resource.
- `lineNumber` <[number]> 0-based line number in the resource. - `lineNumber` <[number]> 0-based line number in the resource.
- `columnNumber` <[number]> 0-based column number in the resource. - `columnNumber` <[number]> 0-based column number in the resource.
@ -4202,7 +4200,7 @@ generate the text for. A superset of the [`param: key`]() values can be found
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
`Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc. `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
Following modification shortcuts are also suported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`. Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
Holding down `Shift` will type the text that corresponds to the [`param: key`]() in the upper case. Holding down `Shift` will type the text that corresponds to the [`param: key`]() in the upper case.
@ -4248,7 +4246,7 @@ generate the text for. A superset of the [`param: key`]() values can be found
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`,
`Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc. `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
Following modification shortcuts are also suported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`. Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
Holding down `Shift` will type the text that corresponds to the [`param: key`]() in the upper case. Holding down `Shift` will type the text that corresponds to the [`param: key`]() in the upper case.
@ -4414,9 +4412,9 @@ 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]:
- [`event: Page.request`]() emitted when the request is issued by the page. * [`event: Page.request`]() emitted when the request is issued by the page.
- [`event: Page.response`]() emitted when/if the response status and headers are received for the request. * [`event: Page.response`]() emitted when/if the response status and headers are received for the request.
- [`event: Page.requestfinished`]() emitted when the response body is downloaded and the request is complete. * [`event: Page.requestfinished`]() 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 [`event: Page.requestfailed`]() event is emitted. the [`event: Page.requestfailed`]() event is emitted.
@ -4676,8 +4674,8 @@ contain `[a-zA-Z0-9_]` characters.
### param: Selectors.register.script ### param: Selectors.register.script
- `script` <[function]|[string]|[Object]> - `script` <[function]|[string]|[Object]>
- `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw script content. - `content` <[string]> Raw script content. Optional.
Script that evaluates to a selector engine instance. Script that evaluates to a selector engine instance.
@ -4702,22 +4700,22 @@ Aborts the route's request.
### param: Route.abort.errorCode ### param: Route.abort.errorCode
- `errorCode` <[string]> - `errorCode` <[string]>
- `'aborted'` - An operation was aborted (due to user action)
- `'accessdenied'` - Permission to access a resource, other than the network, was denied
- `'addressunreachable'` - The IP address is unreachable. This usually means that there is no route to the specified host or network.
- `'blockedbyclient'` - The client chose to block the request.
- `'blockedbyresponse'` - The request failed because the response was delivered along with requirements which are not met ('X-Frame-Options' and 'Content-Security-Policy' ancestor checks, for instance).
- `'connectionaborted'` - A connection timed out as a result of not receiving an ACK for data sent.
- `'connectionclosed'` - A connection was closed (corresponding to a TCP FIN).
- `'connectionfailed'` - A connection attempt failed.
- `'connectionrefused'` - A connection attempt was refused.
- `'connectionreset'` - A connection was reset (corresponding to a TCP RST).
- `'internetdisconnected'` - The Internet connection has been lost.
- `'namenotresolved'` - The host name could not be resolved.
- `'timedout'` - An operation timed out.
- `'failed'` - A generic failure occurred.
Optional error code. Defaults to `failed`, could be one of the following: Optional error code. Defaults to `failed`, could be one of the following:
* `'aborted'` - An operation was aborted (due to user action)
* `'accessdenied'` - Permission to access a resource, other than the network, was denied
* `'addressunreachable'` - The IP address is unreachable. This usually means that there is no route to the specified host or network.
* `'blockedbyclient'` - The client chose to block the request.
* `'blockedbyresponse'` - The request failed because the response was delivered along with requirements which are not met ('X-Frame-Options' and 'Content-Security-Policy' ancestor checks, for instance).
* `'connectionaborted'` - A connection timed out as a result of not receiving an ACK for data sent.
* `'connectionclosed'` - A connection was closed (corresponding to a TCP FIN).
* `'connectionfailed'` - A connection attempt failed.
* `'connectionrefused'` - A connection attempt was refused.
* `'connectionreset'` - A connection was reset (corresponding to a TCP RST).
* `'internetdisconnected'` - The Internet connection has been lost.
* `'namenotresolved'` - The host name could not be resolved.
* `'timedout'` - An operation timed out.
* `'failed'` - A generic failure occurred.
## async method: Route.continue ## async method: Route.continue
@ -4793,19 +4791,19 @@ The [WebSocket] class represents websocket connections in the page.
Fired when the websocket closes. Fired when the websocket closes.
## event: WebSocket.framereceived ## event: WebSocket.framereceived
- <[Object]> web socket frame data - type: <[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: WebSocket.framesent ## event: WebSocket.framesent
- <[Object]> web socket frame data - type: <[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: WebSocket.socketerror ## event: WebSocket.socketerror
- <[String]> the error message - type: <[String]> the error message
Fired when the websocket has an error. Fired when the websocket has an error.
@ -4956,7 +4954,7 @@ for (const worker of page.workers())
<!-- GEN:stop --> <!-- GEN:stop -->
## event: Worker.close ## event: Worker.close
- <[Worker]> - type: <[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.
@ -5065,7 +5063,7 @@ This methods attaches Playwright to an existing browser instance.
- `params` <[Object]> - `params` <[Object]>
- `wsEndpoint` <[string]> A browser websocket endpoint to connect to. **required** - `wsEndpoint` <[string]> A browser websocket endpoint to connect to. **required**
- `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. - `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.
- `logger` <[Logger]> Logger sink for Playwright logging. - `logger` <[Logger]> Logger sink for Playwright logging. Optional.
- `timeout` <[number]> Maximum time in milliseconds to wait for the connection to be established. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - `timeout` <[number]> Maximum time in milliseconds to wait for the connection to be established. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
## method: BrowserType.executablePath ## method: BrowserType.executablePath
@ -5475,7 +5473,7 @@ message arguments
### param: Logger.log.hints ### param: Logger.log.hints
- `hints` <[Object]> - `hints` <[Object]>
- `color` <[string]> preferred logger color - `color` <[string]> Optional preferred logger color.
optional formatting hints optional formatting hints
@ -5548,14 +5546,14 @@ const backgroundPage = await context.waitForEvent('backgroundpage');
<!-- GEN:stop --> <!-- GEN:stop -->
## event: ChromiumBrowserContext.backgroundpage ## event: ChromiumBrowserContext.backgroundpage
- <[Page]> - type: <[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: ChromiumBrowserContext.serviceworker ## event: ChromiumBrowserContext.serviceworker
- <[Worker]> - type: <[Worker]>
Emitted when new service worker is created in the context. Emitted when new service worker is created in the context.

57
docs-src/api-params.md
View file

@ -1,14 +1,12 @@
## navigation-wait-until ## navigation-wait-until
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> - `waitUntil` <"load"|"domcontentloaded"|"networkidle">
- `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
- `'load'` - consider operation to be finished when the `load` event is fired.
- `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
When to consider operation succeeded, defaults to `load`. Events can be either: When to consider operation succeeded, defaults to `load`. Events can be either:
* `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
* `'load'` - consider operation to be finished when the `load` event is fired.
* `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
## navigation-timeout ## navigation-timeout
- `timeout` <[number]> - `timeout` <[number]>
Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout.
@ -19,14 +17,12 @@ The default value can be changed by using the
[`method: Page.setDefaultTimeout`]() methods. [`method: Page.setDefaultTimeout`]() methods.
## wait-for-timeout ## wait-for-timeout
- `timeout` <[number]> - `timeout` <[number]>
maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default
value can be changed by using the [`method: BrowserContext.setDefaultTimeout`](). value can be changed by using the [`method: BrowserContext.setDefaultTimeout`]().
## input-timeout ## input-timeout
- `timeout` <[number]> - `timeout` <[number]>
Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by
@ -34,7 +30,6 @@ using the [`method: BrowserContext.setDefaultTimeout`]() or
[`method: Page.setDefaultTimeout`]() methods. [`method: Page.setDefaultTimeout`]() methods.
## input-no-wait-after ## input-no-wait-after
- `noWaitAfter` <[boolean]> - `noWaitAfter` <[boolean]>
Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can
@ -42,20 +37,17 @@ opt out of waiting via setting this flag. You would only need this option in the
to inaccessible pages. Defaults to `false`. to inaccessible pages. Defaults to `false`.
## input-force ## input-force
- `force` <[boolean]> - `force` <[boolean]>
Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`. Whether to bypass the [actionability](./actionability.md) checks. Defaults to `false`.
## input-selector ## input-selector
- `selector` <[string]> - `selector` <[string]>
A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See
[working with selectors](#working-with-selectors) for more details. [working with selectors](#working-with-selectors) for more details.
## input-position ## input-position
- `position` <[Object]> - `position` <[Object]>
- `x` <[number]> - `x` <[number]>
- `y` <[number]> - `y` <[number]>
@ -64,57 +56,49 @@ A point to use relative to the top-left corner of element padding box. If not sp
element. element.
## input-modifiers ## input-modifiers
- `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">> - `modifiers` <[Array]<"Alt"|"Control"|"Meta"|"Shift">>
Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current
modifiers back. If not specified, currently pressed modifiers are used. modifiers back. If not specified, currently pressed modifiers are used.
## input-button ## input-button
- `button` <"left"|"right"|"middle"> - `button` <"left"|"right"|"middle">
Defaults to `left`. Defaults to `left`.
## input-files ## input-files
- `files` <[string]|[Array]<[string]>|[Object]|[Array]<[Object]>> - `files` <[string]|[Array]<[string]>|[Object]|[Array]<[Object]>>
- `name` <[string]> [File] name **required** - `name` <[string]> [File] name **required**
- `mimeType` <[string]> [File] type **required** - `mimeType` <[string]> [File] type **required**
- `buffer` <[Buffer]> File content **required** - `buffer` <[Buffer]> File content **required**
## input-down-up-delay ## input-down-up-delay
- `delay` <[number]> - `delay` <[number]>
Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0. Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
## input-click-count ## input-click-count
- `clickCount` <[number]> - `clickCount` <[number]>
defaults to 1. See [UIEvent.detail]. defaults to 1. See [UIEvent.detail].
## query-selector ## query-selector
- `selector` <[string]> - `selector` <[string]>
A selector to query for. See [working with selectors](#working-with-selectors) for more details. A selector to query for. See [working with selectors](#working-with-selectors) for more details.
## wait-for-selector-state ## wait-for-selector-state
- `state` <"attached"|"detached"|"visible"|"hidden"> - `state` <"attached"|"detached"|"visible"|"hidden">
- `'attached'` - wait for element to be present in DOM.
- `'detached'` - wait for element to not be present in DOM.
- `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without
any content or with `display:none` has an empty bounding box and is not considered visible.
- `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`.
This is opposite to the `'visible'` option.
Defaults to `'visible'`. Can be either: Defaults to `'visible'`. Can be either:
* `'attached'` - wait for element to be present in DOM.
* `'detached'` - wait for element to not be present in DOM.
* `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without
any content or with `display:none` has an empty bounding box and is not considered visible.
* `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`.
This is opposite to the `'visible'` option.
## context-option-storage-state ## context-option-storage-state
- `storageState` <[string]|[Object]> - `storageState` <[string]|[Object]>
- `cookies` <[Array]<[Object]>> Optional cookies to set for context - `cookies` <[Array]<[Object]>> Optional cookies to set for context
- `name` <[string]> **required** - `name` <[string]> **required**
@ -136,25 +120,21 @@ Populates context with given storage state. This method can be used to initializ
obtained via [`method: BrowserContext.storageState`](). Either a path to the file with saved storage, or an object with the following fields: obtained via [`method: BrowserContext.storageState`](). Either a path to the file with saved storage, or an object with the following fields:
## context-option-acceptdownloads ## context-option-acceptdownloads
- `acceptDownloads` <[boolean]> - `acceptDownloads` <[boolean]>
Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled. Whether to automatically download all the attachments. Defaults to `false` where all the downloads are canceled.
## context-option-ignorehttpserrors ## context-option-ignorehttpserrors
- `ignoreHTTPSErrors` <[boolean]> - `ignoreHTTPSErrors` <[boolean]>
Whether to ignore HTTPS errors during navigation. Defaults to `false`. Whether to ignore HTTPS errors during navigation. Defaults to `false`.
## context-option-bypasscsp ## context-option-bypasscsp
- `bypassCSP` <[boolean]> - `bypassCSP` <[boolean]>
Toggles bypassing page's Content-Security-Policy. Toggles bypassing page's Content-Security-Policy.
## context-option-viewport ## context-option-viewport
- `viewport` <[null]|[Object]> - `viewport` <[null]|[Object]>
- `width` <[number]> page width in pixels. - `width` <[number]> page width in pixels.
- `height` <[number]> page height in pixels. - `height` <[number]> page height in pixels.
@ -162,78 +142,66 @@ Toggles bypassing page's Content-Security-Policy.
Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport. Sets a consistent viewport for each page. Defaults to an 1280x720 viewport. `null` disables the default viewport.
## context-option-useragent ## context-option-useragent
- `userAgent` <[string]> - `userAgent` <[string]>
Specific user agent to use in this context. Specific user agent to use in this context.
## context-option-devicescalefactor ## context-option-devicescalefactor
- `deviceScaleFactor` <[number]> - `deviceScaleFactor` <[number]>
Specify device scale factor (can be thought of as dpr). Defaults to `1`. Specify device scale factor (can be thought of as dpr). Defaults to `1`.
## context-option-ismobile ## context-option-ismobile
- `isMobile` <[boolean]> - `isMobile` <[boolean]>
Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported Whether the `meta viewport` tag is taken into account and touch events are enabled. Defaults to `false`. Not supported
in Firefox. in Firefox.
## context-option-hastouch ## context-option-hastouch
- `hasTouch` <[boolean]> - `hasTouch` <[boolean]>
Specifies if viewport supports touch events. Defaults to false. Specifies if viewport supports touch events. Defaults to false.
## context-option-javascriptenabled ## context-option-javascriptenabled
- `javaScriptEnabled` <[boolean]> - `javaScriptEnabled` <[boolean]>
Whether or not to enable JavaScript in the context. Defaults to `true`. Whether or not to enable JavaScript in the context. Defaults to `true`.
## context-option-timezoneid ## context-option-timezoneid
- `timezoneId` <[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) 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. for a list of supported timezone IDs.
## context-option-geolocation ## context-option-geolocation
- `geolocation` <[Object]> - `geolocation` <[Object]>
- `latitude` <[number]> Latitude between -90 and 90. - `latitude` <[number]> Latitude between -90 and 90.
- `longitude` <[number]> Longitude between -180 and 180. - `longitude` <[number]> Longitude between -180 and 180.
- `accuracy` <[number]> Non-negative accuracy value. Defaults to `0`. - `accuracy` <[number]> Non-negative accuracy value. Defaults to `0`.
## context-option-locale ## context-option-locale
- `locale` <[string]> - `locale` <[string]>
Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, `Accept-Language` Specify user locale, for example `en-GB`, `de-DE`, etc. Locale will affect `navigator.language` value, `Accept-Language`
request header value as well as number and date formatting rules. request header value as well as number and date formatting rules.
## context-option-permissions ## context-option-permissions
- `permissions` <[Array]<[string]>> - `permissions` <[Array]<[string]>>
A list of permissions to grant to all pages in this context. See A list of permissions to grant to all pages in this context. See
[`method: BrowserContext.grantPermissions`]() for more details. [`method: BrowserContext.grantPermissions`]() for more details.
## context-option-extrahttpheaders ## context-option-extrahttpheaders
- `extraHTTPHeaders` <[Object]<[string], [string]>> - `extraHTTPHeaders` <[Object]<[string], [string]>>
An object containing additional HTTP headers to be sent with every request. All header values must be strings. An object containing additional HTTP headers to be sent with every request. All header values must be strings.
## context-option-offline ## context-option-offline
- `offline` <[boolean]> - `offline` <[boolean]>
Whether to emulate network being offline. Defaults to `false`. Whether to emulate network being offline. Defaults to `false`.
## context-option-httpcredentials ## context-option-httpcredentials
- `httpCredentials` <[Object]> - `httpCredentials` <[Object]>
- `username` <[string]> - `username` <[string]>
- `password` <[string]> - `password` <[string]>
@ -241,20 +209,17 @@ Whether to emulate network being offline. Defaults to `false`.
Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication). Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).
## context-option-colorscheme ## context-option-colorscheme
- `colorScheme` <"light"|"dark"|"no-preference"> - `colorScheme` <"light"|"dark"|"no-preference">
Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. See
[`method: Page.emulateMedia`]() for more details. Defaults to '`light`'. [`method: Page.emulateMedia`]() for more details. Defaults to '`light`'.
## context-option-logger ## context-option-logger
- `logger` <[Logger]> - `logger` <[Logger]>
Logger sink for Playwright logging. Logger sink for Playwright logging.
## context-option-videospath ## context-option-videospath
- `videosPath` <[string]> - `videosPath` <[string]>
**NOTE** Use [`param: recordVideo`]() instead, it takes precedence over `videosPath`. Enables video recording for all pages to **NOTE** Use [`param: recordVideo`]() instead, it takes precedence over `videosPath`. Enables video recording for all pages to
@ -262,7 +227,6 @@ Logger sink for Playwright logging.
[`method: BrowserContext.close`]() for videos to be saved. [`method: BrowserContext.close`]() for videos to be saved.
## context-option-videosize ## context-option-videosize
- `videoSize` <[Object]> - `videoSize` <[Object]>
- `width` <[number]> Video frame width. - `width` <[number]> Video frame width.
- `height` <[number]> Video frame height. - `height` <[number]> Video frame height.
@ -273,7 +237,6 @@ recorded video. Can only be used if `videosPath` is set. If not specified the si
down if necessary to fit specified size. down if necessary to fit specified size.
## context-option-recordhar ## context-option-recordhar
- `recordHar` <[Object]> - `recordHar` <[Object]>
- `omitContent` <[boolean]> Optional setting to control whether to omit request content from the HAR. Defaults to - `omitContent` <[boolean]> Optional setting to control whether to omit request content from the HAR. Defaults to
`false`. `false`.
@ -284,7 +247,6 @@ specified, the HAR is not recorded. Make sure to await [`method: BrowserContext.
saved. saved.
## context-option-recordvideo ## context-option-recordvideo
- `recordVideo` <[Object]> - `recordVideo` <[Object]>
- `dir` <[string]> Path to the directory to put videos into. - `dir` <[string]> Path to the directory to put videos into.
- `size` <[Object]> Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport`. - `size` <[Object]> Optional dimensions of the recorded videos. If not specified the size will be equal to `viewport`.
@ -297,7 +259,6 @@ Enables video recording for all pages into `recordVideo.dir` directory. If not s
sure to await [`method: BrowserContext.close`]() for videos to be saved. sure to await [`method: BrowserContext.close`]() for videos to be saved.
## context-option-proxy ## context-option-proxy
- `proxy` <[Object]> - `proxy` <[Object]>
- `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example - `server` <[string]> Proxy to be used for all requests. HTTP and SOCKS proxies are supported, for example
`http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy. `http://myproxy.com:3128` or `socks5://myproxy.com:3128`. Short form `myproxy.com:3128` is considered an HTTP proxy.

338
docs/api.md
View file

@ -397,7 +397,7 @@ Emitted when Browser context gets closed. This might happen because of one of th
* The [`browser.close()`](#browserclose) method was called. * The [`browser.close()`](#browserclose) method was called.
#### browserContext.on('page') #### browserContext.on('page')
- <[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.
@ -417,13 +417,13 @@ console.log(await page.evaluate('location.href'));
- `cookies` <[Array]<[Object]>> - `cookies` <[Array]<[Object]>>
- `name` <[string]> **required** - `name` <[string]> **required**
- `value` <[string]> **required** - `value` <[string]> **required**
- `url` <[string]> either url or domain / path are required - `url` <[string]> either url or domain / path are required. Optional.
- `domain` <[string]> either url or domain / path are required - `domain` <[string]> either url or domain / path are required Optional.
- `path` <[string]> either url or domain / path are required - `path` <[string]> either url or domain / path are required Optional.
- `expires` <[number]> Unix time in seconds. - `expires` <[number]> Unix time in seconds. Optional.
- `httpOnly` <[boolean]> - `httpOnly` <[boolean]> Optional.
- `secure` <[boolean]> - `secure` <[boolean]> Optional.
- `sameSite` <"Strict"|"Lax"|"None"> - `sameSite` <"Strict"|"Lax"|"None"> Optional.
- returns: <[Promise]> - returns: <[Promise]>
Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies can be obtained via [`browserContext.cookies([urls])`](#browsercontextcookiesurls). Adds cookies into this browser context. All pages within this context will have these cookies installed. Cookies can be obtained via [`browserContext.cookies([urls])`](#browsercontextcookiesurls).
@ -434,8 +434,8 @@ await browserContext.addCookies([cookieObject1, cookieObject2]);
#### browserContext.addInitScript(script[, arg]) #### browserContext.addInitScript(script[, arg])
- `script` <[function]|[string]|[Object]> Script to be evaluated in all pages in the browser context. - `script` <[function]|[string]|[Object]> Script to be evaluated in all pages in the browser context.
- `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw script content. - `content` <[string]> Raw script content. Optional.
- `arg` <[Serializable]> Optional argument to pass to `script` (only supported when passing a function). - `arg` <[Serializable]> Optional argument to pass to `script` (only supported when passing a function).
- returns: <[Promise]> - returns: <[Promise]>
@ -592,22 +592,22 @@ const crypto = require('crypto');
#### browserContext.grantPermissions(permissions[, options]) #### browserContext.grantPermissions(permissions[, options])
- `permissions` <[Array]<[string]>> A permission or an array of permissions to grant. Permissions can be one of the following values: - `permissions` <[Array]<[string]>> A permission or an array of permissions to grant. Permissions can be one of the following values:
- `'geolocation'` * `'geolocation'`
- `'midi'` * `'midi'`
- `'midi-sysex'` (system-exclusive midi) * `'midi-sysex'` (system-exclusive midi)
- `'notifications'` * `'notifications'`
- `'push'` * `'push'`
- `'camera'` * `'camera'`
- `'microphone'` * `'microphone'`
- `'background-sync'` * `'background-sync'`
- `'ambient-light-sensor'` * `'ambient-light-sensor'`
- `'accelerometer'` * `'accelerometer'`
- `'gyroscope'` * `'gyroscope'`
- `'magnetometer'` * `'magnetometer'`
- `'accessibility-events'` * `'accessibility-events'`
- `'clipboard-read'` * `'clipboard-read'`
- `'clipboard-write'` * `'clipboard-write'`
- `'payment-handler'` * `'payment-handler'`
- `options` <[Object]> - `options` <[Object]>
- `origin` <[string]> The [origin] to grant permissions to, e.g. "https://example.com". - `origin` <[string]> The [origin] to grant permissions to, e.g. "https://example.com".
- returns: <[Promise]> - returns: <[Promise]>
@ -889,7 +889,7 @@ page.removeListener('request', logRequest);
Emitted when the page closes. Emitted when the page closes.
#### page.on('console') #### page.on('console')
- <[ConsoleMessage]> - type: <[ConsoleMessage]>
Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also emitted if the page throws an error or a warning. Emitted when JavaScript within the page calls one of console API methods, e.g. `console.log` or `console.dir`. Also emitted if the page throws an error or a warning.
@ -935,7 +935,7 @@ await new Promise((resolve, reject) => {
``` ```
#### page.on('dialog') #### page.on('dialog')
- <[Dialog]> - type: <[Dialog]>
Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via [`dialog.accept([promptText])`](#dialogacceptprompttext) or [`dialog.dismiss()`](#dialogdismiss) methods. Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` or `beforeunload`. Playwright can respond to the dialog via [`dialog.accept([promptText])`](#dialogacceptprompttext) or [`dialog.dismiss()`](#dialogdismiss) methods.
@ -944,14 +944,14 @@ Emitted when a JavaScript dialog appears, such as `alert`, `prompt`, `confirm` o
Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched. Emitted when the JavaScript [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event is dispatched.
#### page.on('download') #### page.on('download')
- <[Download]> - type: <[Download]>
Emitted when attachment download started. User can access basic file operations on downloaded content via the passed [Download] instance. Emitted when attachment download started. User can access basic file operations on downloaded content via the passed [Download] instance.
> **NOTE** Browser context **must** be created with the `acceptDownloads` set to `true` when user needs access to the downloaded content. If `acceptDownloads` is not set or set to `false`, download events are emitted, but the actual download is not performed and user has no access to the downloaded files. > **NOTE** Browser context **must** be created with the `acceptDownloads` set to `true` when user needs access to the downloaded content. If `acceptDownloads` is not set or set to `false`, download events are emitted, but the actual download is not performed and user has no access to the downloaded files.
#### page.on('filechooser') #### page.on('filechooser')
- <[FileChooser]> - type: <[FileChooser]>
Emitted when a file chooser is supposed to appear, such as after clicking the `<input type=file>`. Playwright can respond to it via setting the input files using [`fileChooser.setFiles(files[, options])`](#filechoosersetfilesfiles-options) that can be uploaded after that. Emitted when a file chooser is supposed to appear, such as after clicking the `<input type=file>`. Playwright can respond to it via setting the input files using [`fileChooser.setFiles(files[, options])`](#filechoosersetfilesfiles-options) that can be uploaded after that.
@ -962,17 +962,17 @@ page.on('filechooser', async (fileChooser) => {
``` ```
#### page.on('frameattached') #### page.on('frameattached')
- <[Frame]> - type: <[Frame]>
Emitted when a frame is attached. Emitted when a frame is attached.
#### page.on('framedetached') #### page.on('framedetached')
- <[Frame]> - type: <[Frame]>
Emitted when a frame is detached. Emitted when a frame is detached.
#### page.on('framenavigated') #### page.on('framenavigated')
- <[Frame]> - type: <[Frame]>
Emitted when a frame is navigated to a new url. Emitted when a frame is navigated to a new url.
@ -981,12 +981,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. Emitted when the JavaScript [`load`](https://developer.mozilla.org/en-US/docs/Web/Events/load) event is dispatched.
#### page.on('pageerror') #### page.on('pageerror')
- <[Error]> The exception message - type: <[Error]> The exception message
Emitted when an uncaught exception happens within the page. Emitted when an uncaught exception happens within the page.
#### page.on('popup') #### page.on('popup')
- <[Page]> Page corresponding to "popup" window - type: <[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')](#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.
@ -1003,34 +1003,34 @@ console.log(await popup.evaluate('location.href'));
> **NOTE** Use [`page.waitForLoadState([state, options])`](#pagewaitforloadstatestate-options) to wait until the page gets to a particular state (you should not need it in most cases). > **NOTE** Use [`page.waitForLoadState([state, options])`](#pagewaitforloadstatestate-options) to wait until the page gets to a particular state (you should not need it in most cases).
#### page.on('request') #### page.on('request')
- <[Request]> - type: <[Request]>
Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, see [`page.route(url, handler)`](#pagerouteurl-handler) or [`browserContext.route(url, handler)`](#browsercontextrouteurl-handler). Emitted when a page issues a request. The [request] object is read-only. In order to intercept and mutate requests, see [`page.route(url, handler)`](#pagerouteurl-handler) or [`browserContext.route(url, handler)`](#browsercontextrouteurl-handler).
#### page.on('requestfailed') #### page.on('requestfailed')
- <[Request]> - type: <[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 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') #### page.on('requestfinished')
- <[Request]> - type: <[Request]>
Emitted when a request finishes successfully after downloading the response body. For a successful response, the sequence of events is `request`, `response` and `requestfinished`. Emitted when a request finishes successfully after downloading the response body. For a successful response, the sequence of events is `request`, `response` and `requestfinished`.
#### page.on('response') #### page.on('response')
- <[Response]> - type: <[Response]>
Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events is `request`, `response` and `requestfinished`. Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events is `request`, `response` and `requestfinished`.
#### page.on('websocket') #### page.on('websocket')
- <[WebSocket]> websocket - type: <[WebSocket]> websocket
Emitted when <[WebSocket]> request is sent. Emitted when <[WebSocket]> request is sent.
#### page.on('worker') #### page.on('worker')
- <[Worker]> - type: <[Worker]>
Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the page. Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the page.
@ -1087,12 +1087,12 @@ const divsCounts = await page.$$eval('div', (divs, min) => divs.length >= min, 1
``` ```
#### page.accessibility #### page.accessibility
- returns: <[Accessibility]> - type: <[Accessibility]>
#### page.addInitScript(script[, arg]) #### page.addInitScript(script[, arg])
- `script` <[function]|[string]|[Object]> Script to be evaluated in the page. - `script` <[function]|[string]|[Object]> Script to be evaluated in the page.
- `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw script content. - `content` <[string]> Raw script content. Optional.
- `arg` <[Serializable]> Optional argument to pass to `script` (only supported when passing a function). - `arg` <[Serializable]> Optional argument to pass to `script` (only supported when passing a function).
- returns: <[Promise]> - returns: <[Promise]>
@ -1117,10 +1117,10 @@ await page.addInitScript(preloadFile);
#### page.addScriptTag(params) #### page.addScriptTag(params)
- `params` <[Object]> - `params` <[Object]>
- `url` <[string]> URL of a script to be added. - `url` <[string]> URL of a script to be added. Optional.
- `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw JavaScript content to be injected into frame. - `content` <[string]> Raw JavaScript content to be injected into frame. Optional.
- `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details. - `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details. Optional.
- returns: <[Promise]<[ElementHandle]>> - returns: <[Promise]<[ElementHandle]>>
Adds a `<script>` tag into the page with the desired url or content. Returns the added tag when the script's onload fires or when the script content was injected into frame. Adds a `<script>` tag into the page with the desired url or content. Returns the added tag when the script's onload fires or when the script content was injected into frame.
@ -1129,9 +1129,9 @@ Shortcut for main frame's [`frame.addScriptTag(params)`](#frameaddscripttagparam
#### page.addStyleTag(params) #### page.addStyleTag(params)
- `params` <[Object]> - `params` <[Object]>
- `url` <[string]> URL of the `<link>` tag. - `url` <[string]> URL of the `<link>` tag. Optional.
- `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw CSS content to be injected into frame. - `content` <[string]> Raw CSS content to be injected into frame. Optional.
- returns: <[Promise]<[ElementHandle]>> - returns: <[Promise]<[ElementHandle]>>
Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the content. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame. Adds a `<link rel="stylesheet">` tag into the page with the desired url or a `<style type="text/css">` tag with the content. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
@ -1213,7 +1213,7 @@ Gets the full HTML contents of the page, including the doctype.
Get the browser context that the page belongs to. Get the browser context that the page belongs to.
#### page.coverage #### page.coverage
- returns: <[null]|[ChromiumCoverage]> - type: <[null]|[ChromiumCoverage]>
Browser-specific Coverage implementation, only available for Chromium atm. See [ChromiumCoverage](#class-chromiumcoverage) for more details. Browser-specific Coverage implementation, only available for Chromium atm. See [ChromiumCoverage](#class-chromiumcoverage) for more details.
@ -1279,8 +1279,8 @@ await page.dispatchEvent('#source', 'dragstart', { dataTransfer });
#### page.emulateMedia(params) #### page.emulateMedia(params)
- `params` <[Object]> - `params` <[Object]>
- `media` <[null]|"screen"|"print"> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation. Omitting `media` or passing `undefined` does not change the emulated value. - `media` <[null]|"screen"|"print"> Changes the CSS media type of the page. The only allowed values are `'screen'`, `'print'` and `null`. Passing `null` disables CSS media emulation. Omitting `media` or passing `undefined` does not change the emulated value. Optional.
- `colorScheme` <[null]|"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing `null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated value. - `colorScheme` <[null]|"light"|"dark"|"no-preference"> Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, `'no-preference'`. Passing `null` disables color scheme emulation. Omitting `colorScheme` or passing `undefined` does not change the emulated value. Optional.
- returns: <[Promise]> - returns: <[Promise]>
```js ```js
@ -1317,7 +1317,7 @@ await page.evaluate(() => matchMedia('(prefers-color-scheme: no-preference)').ma
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction` - `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> - returns: <[Promise]<[Serializable]>>
Returns the value of the `pageFunction` invacation. 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 [Promise], then `page.evaluate` would wait for the promise to resolve and return its value.
@ -1355,7 +1355,7 @@ Shortcut for main frame's [`frame.evaluate(pageFunction[, arg])`](#frameevaluate
- `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction` - `arg` <[EvaluationArgument]> Optional argument to pass to `pageFunction`
- returns: <[Promise]<[JSHandle]>> - returns: <[Promise]<[JSHandle]>>
Returns the value of the `pageFunction` invacation as in-page object (JSHandle). 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). The only difference between `page.evaluate` and `page.evaluateHandle` is that `page.evaluateHandle` returns in-page object (JSHandle).
@ -1520,8 +1520,8 @@ Shortcut for main frame's [`frame.focus(selector[, options])`](#framefocusselect
#### page.frame(frameSelector) #### page.frame(frameSelector)
- `frameSelector` <[string]|[Object]> Frame name or other frame lookup options. - `frameSelector` <[string]|[Object]> Frame name or other frame lookup options.
- `name` <[string]> frame name specified in the `iframe`'s `name` attribute - `name` <[string]> Frame name specified in the `iframe`'s `name` attribute. Optional.
- `url` <[string]|[RegExp]|[Function]> A glob pattern, regex pattern or predicate receiving frame's `url` as a [URL] object. - `url` <[string]|[RegExp]|[Function]> A glob pattern, regex pattern or predicate receiving frame's `url` as a [URL] object. Optional.
- returns: <[null]|[Frame]> - returns: <[null]|[Frame]>
Returns frame matching the specified criteria. Either `name` or `url` must be specified. Returns frame matching the specified criteria. Either `name` or `url` must be specified.
@ -1552,9 +1552,9 @@ Returns element attribute value.
- `options` <[Object]> - `options` <[Object]>
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either: - `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either:
- `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired. * `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
- `'load'` - consider operation to be finished when the `load` event is fired. * `'load'` - consider operation to be finished when the `load` event is fired.
- `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms. * `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
- returns: <[Promise]<[null]|[Response]>> - returns: <[Promise]<[null]|[Response]>>
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If can not go back, returns `null`. Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If can not go back, returns `null`.
@ -1565,9 +1565,9 @@ Navigate to the previous page in history.
- `options` <[Object]> - `options` <[Object]>
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either: - `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either:
- `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired. * `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
- `'load'` - consider operation to be finished when the `load` event is fired. * `'load'` - consider operation to be finished when the `load` event is fired.
- `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms. * `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
- returns: <[Promise]<[null]|[Response]>> - returns: <[Promise]<[null]|[Response]>>
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If can not go forward, returns `null`. Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If can not go forward, returns `null`.
@ -1580,9 +1580,9 @@ Navigate to the next page in history.
- `referer` <[string]> Referer header value. If provided it will take preference over the referer header value set by [`page.setExtraHTTPHeaders(headers)`](#pagesetextrahttpheadersheaders). - `referer` <[string]> Referer header value. If provided it will take preference over the referer header value set by [`page.setExtraHTTPHeaders(headers)`](#pagesetextrahttpheadersheaders).
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either: - `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either:
- `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired. * `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
- `'load'` - consider operation to be finished when the `load` event is fired. * `'load'` - consider operation to be finished when the `load` event is fired.
- `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms. * `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
- returns: <[Promise]<[null]|[Response]>> - returns: <[Promise]<[null]|[Response]>>
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
@ -1645,7 +1645,7 @@ Returns `element.innerText`.
Indicates that the page has been closed. Indicates that the page has been closed.
#### page.keyboard #### page.keyboard
- returns: <[Keyboard]> - type: <[Keyboard]>
#### page.mainFrame() #### page.mainFrame()
- returns: <[Frame]> - returns: <[Frame]>
@ -1653,7 +1653,7 @@ Indicates that the page has been closed.
The page's main frame. Page is guaranteed to have a main frame which persists during navigations. The page's main frame. Page is guaranteed to have a main frame which persists during navigations.
#### page.mouse #### page.mouse
- returns: <[Mouse]> - type: <[Mouse]>
#### page.opener() #### page.opener()
- returns: <[Promise]<[null]|[Page]>> - returns: <[Promise]<[null]|[Page]>>
@ -1666,11 +1666,11 @@ Returns the opener for popup pages and `null` for others. If the opener has been
- `footerTemplate` <[string]> HTML template for the print footer. Should use the same format as the `headerTemplate`. - `footerTemplate` <[string]> HTML template for the print footer. Should use the same format as the `headerTemplate`.
- `format` <[string]> Paper format. If set, takes priority over `width` or `height` options. Defaults to 'Letter'. - `format` <[string]> Paper format. If set, takes priority over `width` or `height` options. Defaults to 'Letter'.
- `headerTemplate` <[string]> HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them: - `headerTemplate` <[string]> HTML template for the print header. Should be valid HTML markup with following classes used to inject printing values into them:
- `'date'` formatted print date * `'date'` formatted print date
- `'title'` document title * `'title'` document title
- `'url'` document location * `'url'` document location
- `'pageNumber'` current page number * `'pageNumber'` current page number
- `'totalPages'` total pages in the document * `'totalPages'` total pages in the document
- `height` <[string]|[number]> Paper height, accepts values labeled with units. - `height` <[string]|[number]> Paper height, accepts values labeled with units.
- `landscape` <[boolean]> Paper orientation. Defaults to `false`. - `landscape` <[boolean]> Paper orientation. Defaults to `false`.
- `margin` <[Object]> Paper margins, defaults to none. - `margin` <[Object]> Paper margins, defaults to none.
@ -1745,7 +1745,7 @@ Focuses the element, and then uses [`keyboard.down(key)`](#keyboarddownkey) and
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc. `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
Following modification shortcuts are also suported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`. Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
Holding down `Shift` will type the text that corresponds to the `key` in the upper case. Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
@ -1769,9 +1769,9 @@ await browser.close();
- `options` <[Object]> - `options` <[Object]>
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either: - `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either:
- `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired. * `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
- `'load'` - consider operation to be finished when the `load` event is fired. * `'load'` - consider operation to be finished when the `load` event is fired.
- `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms. * `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
- returns: <[Promise]<[null]|[Response]>> - returns: <[Promise]<[null]|[Response]>>
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
@ -1831,9 +1831,9 @@ Returns the buffer with the captured screenshot.
#### page.selectOption(selector, values[, options]) #### page.selectOption(selector, values[, options])
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](#working-with-selectors) for more details. - `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](#working-with-selectors) for more details.
- `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option is considered matching if all specified properties match. - `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option is considered matching if all specified properties match.
- `value` <[string]> Matches by `option.value`. - `value` <[string]> Matches by `option.value`. Optional.
- `label` <[string]> Matches by `option.label`. - `label` <[string]> Matches by `option.label`. Optional.
- `index` <[number]> Matches by the index. - `index` <[number]> Matches by the index. Optional.
- `options` <[Object]> - `options` <[Object]>
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`. - `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
@ -1862,9 +1862,9 @@ Shortcut for main frame's [`frame.selectOption(selector, values[, options])`](#f
- `options` <[Object]> - `options` <[Object]>
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either: - `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either:
- `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired. * `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
- `'load'` - consider operation to be finished when the `load` event is fired. * `'load'` - consider operation to be finished when the `load` event is fired.
- `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms. * `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
- returns: <[Promise]> - returns: <[Promise]>
#### page.setDefaultNavigationTimeout(timeout) #### page.setDefaultNavigationTimeout(timeout)
@ -1968,7 +1968,7 @@ Returns `element.textContent`.
Returns the page's title. Shortcut for main frame's [`frame.title()`](#frametitle). Returns the page's title. Shortcut for main frame's [`frame.title()`](#frametitle).
#### page.touchscreen #### page.touchscreen
- returns: <[Touchscreen]> - type: <[Touchscreen]>
#### page.type(selector, text[, options]) #### page.type(selector, text[, options])
- `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](#working-with-selectors) for more details. - `selector` <[string]> A selector to search for element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](#working-with-selectors) for more details.
@ -2079,10 +2079,10 @@ await page.waitForFunction(selector => !!document.querySelector(selector), selec
Shortcut for main frame's [`frame.waitForFunction(pageFunction[, arg, options])`](#framewaitforfunctionpagefunction-arg-options). Shortcut for main frame's [`frame.waitForFunction(pageFunction[, arg, options])`](#framewaitforfunctionpagefunction-arg-options).
#### page.waitForLoadState([state, options]) #### page.waitForLoadState([state, options])
- `state` <"load"|"domcontentloaded"|"networkidle"> Load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method resolves immediately. Optional. - `state` <"load"|"domcontentloaded"|"networkidle"> Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method resolves immediately. Can be one of:
- `'load'` - wait for the `load` event to be fired. * `'load'` - wait for the `load` event to be fired.
- `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired. * `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
- `'networkidle'` - wait until there are no network connections for at least `500` ms. * `'networkidle'` - wait until there are no network connections for at least `500` ms.
- `options` <[Object]> - `options` <[Object]>
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- returns: <[Promise]> - returns: <[Promise]>
@ -2112,9 +2112,9 @@ Shortcut for main frame's [`frame.waitForLoadState([state, options])`](#framewai
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- `url` <[string]|[RegExp]|[Function]> A glob pattern, regex pattern or predicate receiving [URL] to match while waiting for the navigation. - `url` <[string]|[RegExp]|[Function]> A glob pattern, regex pattern or predicate receiving [URL] to match while waiting for the navigation.
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either: - `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either:
- `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired. * `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
- `'load'` - consider operation to be finished when the `load` event is fired. * `'load'` - consider operation to be finished when the `load` event is fired.
- `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms. * `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
- returns: <[Promise]<[null]|[Response]>> - returns: <[Promise]<[null]|[Response]>>
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`. Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`.
@ -2168,10 +2168,10 @@ return finalResponse.ok();
- `selector` <[string]> A selector to query for. See [working with selectors](#working-with-selectors) for more details. - `selector` <[string]> A selector to query for. See [working with selectors](#working-with-selectors) for more details.
- `options` <[Object]> - `options` <[Object]>
- `state` <"attached"|"detached"|"visible"|"hidden"> Defaults to `'visible'`. Can be either: - `state` <"attached"|"detached"|"visible"|"hidden"> Defaults to `'visible'`. Can be either:
- `'attached'` - wait for element to be present in DOM. * `'attached'` - wait for element to be present in DOM.
- `'detached'` - wait for element to not be present in DOM. * `'detached'` - wait for element to not be present in DOM.
- `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible. * `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible.
- `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option. * `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option.
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- returns: <[Promise]<[null]|[ElementHandle]>> - returns: <[Promise]<[null]|[ElementHandle]>>
@ -2225,9 +2225,9 @@ This method returns all of the dedicated [WebWorkers](https://developer.mozilla.
At every point of time, page exposes its current frame tree via the [`page.mainFrame()`](#pagemainframe) and [`frame.childFrames()`](#framechildframes) methods. 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: [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('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('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('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:
@ -2358,10 +2358,10 @@ const divsCounts = await frame.$$eval('div', (divs, min) => divs.length >= min,
#### frame.addScriptTag(params) #### frame.addScriptTag(params)
- `params` <[Object]> - `params` <[Object]>
- `url` <[string]> URL of a script to be added. - `url` <[string]> URL of a script to be added. Optional.
- `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw JavaScript content to be injected into frame. - `content` <[string]> Raw JavaScript content to be injected into frame. Optional.
- `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details. - `type` <[string]> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details. Optional.
- returns: <[Promise]<[ElementHandle]>> - returns: <[Promise]<[ElementHandle]>>
Returns the added tag when the script's onload fires or when the script content was injected into frame. Returns the added tag when the script's onload fires or when the script content was injected into frame.
@ -2370,9 +2370,9 @@ Adds a `<script>` tag into the page with the desired url or content.
#### frame.addStyleTag(params) #### frame.addStyleTag(params)
- `params` <[Object]> - `params` <[Object]>
- `url` <[string]> URL of the `<link>` tag. - `url` <[string]> URL of the `<link>` tag. Optional.
- `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw CSS content to be injected into frame. - `content` <[string]> Raw CSS content to be injected into frame. Optional.
- returns: <[Promise]<[ElementHandle]>> - returns: <[Promise]<[ElementHandle]>>
Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame. Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
@ -2601,9 +2601,9 @@ Returns element attribute value.
- `referer` <[string]> Referer header value. If provided it will take preference over the referer header value set by [`page.setExtraHTTPHeaders(headers)`](#pagesetextrahttpheadersheaders). - `referer` <[string]> Referer header value. If provided it will take preference over the referer header value set by [`page.setExtraHTTPHeaders(headers)`](#pagesetextrahttpheadersheaders).
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either: - `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either:
- `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired. * `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
- `'load'` - consider operation to be finished when the `load` event is fired. * `'load'` - consider operation to be finished when the `load` event is fired.
- `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms. * `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
- returns: <[Promise]<[null]|[Response]>> - returns: <[Promise]<[null]|[Response]>>
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
@ -2693,7 +2693,7 @@ Parent frame, if any. Detached frames and main frames return `null`.
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc. `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
Following modification shortcuts are also suported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`. Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
Holding down `Shift` will type the text that corresponds to the `key` in the upper case. Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
@ -2704,9 +2704,9 @@ Shortcuts such as `key: "Control+o"` or `key: "Control+Shift+T"` are supported a
#### frame.selectOption(selector, values[, options]) #### frame.selectOption(selector, values[, options])
- `selector` <[string]> A selector to query for. See [working with selectors](#working-with-selectors) for more details. - `selector` <[string]> A selector to query for. See [working with selectors](#working-with-selectors) for more details.
- `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option is considered matching if all specified properties match. - `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option is considered matching if all specified properties match.
- `value` <[string]> Matches by `option.value`. - `value` <[string]> Matches by `option.value`. Optional.
- `label` <[string]> Matches by `option.label`. - `label` <[string]> Matches by `option.label`. Optional.
- `index` <[number]> Matches by the index. - `index` <[number]> Matches by the index. Optional.
- `options` <[Object]> - `options` <[Object]>
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`. - `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
@ -2732,9 +2732,9 @@ frame.selectOption('select#colors', 'red', 'green', 'blue');
- `options` <[Object]> - `options` <[Object]>
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either: - `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either:
- `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired. * `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
- `'load'` - consider operation to be finished when the `load` event is fired. * `'load'` - consider operation to be finished when the `load` event is fired.
- `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms. * `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
- returns: <[Promise]> - returns: <[Promise]>
#### frame.setInputFiles(selector, files[, options]) #### frame.setInputFiles(selector, files[, options])
@ -2863,10 +2863,10 @@ await frame.waitForFunction(selector => !!document.querySelector(selector), sele
``` ```
#### frame.waitForLoadState([state, options]) #### frame.waitForLoadState([state, options])
- `state` <"load"|"domcontentloaded"|"networkidle"> Load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method returns immediately. Optional. - `state` <"load"|"domcontentloaded"|"networkidle"> Optional load state to wait for, defaults to `load`. If the state has been already reached while loading current document, the method returns immediately. Can be one of:
- `'load'` - wait for the `load` event to be fired. * `'load'` - wait for the `load` event to be fired.
- `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired. * `'domcontentloaded'` - wait for the `DOMContentLoaded` event to be fired.
- `'networkidle'` - wait until there are no network connections for at least `500` ms. * `'networkidle'` - wait until there are no network connections for at least `500` ms.
- `options` <[Object]> - `options` <[Object]>
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- returns: <[Promise]> - returns: <[Promise]>
@ -2885,9 +2885,9 @@ await frame.waitForLoadState(); // Waits for 'load' state by default.
- `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultNavigationTimeout(timeout)`](#browsercontextsetdefaultnavigationtimeouttimeout), [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout), [`page.setDefaultNavigationTimeout(timeout)`](#pagesetdefaultnavigationtimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- `url` <[string]|[RegExp]|[Function]> URL string, URL regex pattern or predicate receiving [URL] to match while waiting for the navigation. - `url` <[string]|[RegExp]|[Function]> URL string, URL regex pattern or predicate receiving [URL] to match while waiting for the navigation.
- `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either: - `waitUntil` <"load"|"domcontentloaded"|"networkidle"> When to consider operation succeeded, defaults to `load`. Events can be either:
- `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired. * `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
- `'load'` - consider operation to be finished when the `load` event is fired. * `'load'` - consider operation to be finished when the `load` event is fired.
- `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms. * `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
- returns: <[Promise]<[null]|[Response]>> - returns: <[Promise]<[null]|[Response]>>
Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`. Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`.
@ -2907,10 +2907,10 @@ const [response] = await Promise.all([
- `selector` <[string]> A selector to query for. See [working with selectors](#working-with-selectors) for more details. - `selector` <[string]> A selector to query for. See [working with selectors](#working-with-selectors) for more details.
- `options` <[Object]> - `options` <[Object]>
- `state` <"attached"|"detached"|"visible"|"hidden"> Defaults to `'visible'`. Can be either: - `state` <"attached"|"detached"|"visible"|"hidden"> Defaults to `'visible'`. Can be either:
- `'attached'` - wait for element to be present in DOM. * `'attached'` - wait for element to be present in DOM.
- `'detached'` - wait for element to not be present in DOM. * `'detached'` - wait for element to not be present in DOM.
- `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible. * `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible.
- `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option. * `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option.
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- returns: <[Promise]<[null]|[ElementHandle]>> - returns: <[Promise]<[null]|[ElementHandle]>>
@ -3072,8 +3072,8 @@ expect(await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText))).
- returns: <[Promise]<[null]|[Object]>> - returns: <[Promise]<[null]|[Object]>>
- `x` <[number]> the x coordinate of the element in pixels. - `x` <[number]> the x coordinate of the element in pixels.
- `y` <[number]> the y coordinate of the element in pixels. - `y` <[number]> the y coordinate of the element in pixels.
- width <[number]> the width of the element in pixels. - `width` <[number]> the width of the element in pixels.
- height <[number]> the height of the element in pixels. - `height` <[number]> the height of the element in pixels.
This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is calculated relative to the main frame viewport - which is usually the same as the browser window. This method returns the bounding box of the element, or `null` if the element is not visible. The bounding box is calculated relative to the main frame viewport - which is usually the same as the browser window.
@ -3260,7 +3260,7 @@ Focuses the element, and then uses [`keyboard.down(key)`](#keyboarddownkey) and
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc. `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
Following modification shortcuts are also suported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`. Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
Holding down `Shift` will type the text that corresponds to the `key` in the upper case. Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
@ -3288,13 +3288,13 @@ This method waits for the [actionability](./actionability.md) checks, then scrol
This method waits for [actionability](./actionability.md) checks, then tries to scroll element into view, unless it is completely visible as defined by [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)'s ```ratio```. This method waits for [actionability](./actionability.md) checks, then tries to scroll element into view, unless it is completely visible as defined by [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)'s ```ratio```.
Throws when ```elementHandle``` does not point to an element [connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) to a Document or a ShadowRoot. Throws when `elementHandle` does not point to an element [connected](https://developer.mozilla.org/en-US/docs/Web/API/Node/isConnected) to a Document or a ShadowRoot.
#### elementHandle.selectOption(values[, options]) #### elementHandle.selectOption(values[, options])
- `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option is considered matching if all specified properties match. - `values` <[null]|[string]|[ElementHandle]|[Array]<[string]>|[Object]|[Array]<[ElementHandle]>|[Array]<[Object]>> Options to select. If the `<select>` has the `multiple` attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are equivalent to `{value:'string'}`. Option is considered matching if all specified properties match.
- `value` <[string]> Matches by `option.value`. - `value` <[string]> Matches by `option.value`. Optional.
- `label` <[string]> Matches by `option.label`. - `label` <[string]> Matches by `option.label`. Optional.
- `index` <[number]> Matches by the index. - `index` <[number]> Matches by the index. Optional.
- `options` <[Object]> - `options` <[Object]>
- `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`. - `noWaitAfter` <[boolean]> Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
@ -3435,10 +3435,10 @@ If the element does not satisfy the condition for the `timeout` milliseconds, th
- `selector` <[string]> A selector to query for. See [working with selectors](#working-with-selectors) for more details. - `selector` <[string]> A selector to query for. See [working with selectors](#working-with-selectors) for more details.
- `options` <[Object]> - `options` <[Object]>
- `state` <"attached"|"detached"|"visible"|"hidden"> Defaults to `'visible'`. Can be either: - `state` <"attached"|"detached"|"visible"|"hidden"> Defaults to `'visible'`. Can be either:
- `'attached'` - wait for element to be present in DOM. * `'attached'` - wait for element to be present in DOM.
- `'detached'` - wait for element to not be present in DOM. * `'detached'` - wait for element to not be present in DOM.
- `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible. * `'visible'` - wait for element to have non-empty bounding box and no `visibility:hidden`. Note that element without any content or with `display:none` has an empty bounding box and is not considered visible.
- `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option. * `'hidden'` - wait for element to be either detached from DOM, or have an empty bounding box or `visibility:hidden`. This is opposite to the `'visible'` option.
- `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods. - `timeout` <[number]> Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [`browserContext.setDefaultTimeout(timeout)`](#browsercontextsetdefaulttimeouttimeout) or [`page.setDefaultTimeout(timeout)`](#pagesetdefaulttimeouttimeout) methods.
- returns: <[Promise]<[null]|[ElementHandle]>> - returns: <[Promise]<[null]|[ElementHandle]>>
@ -3543,7 +3543,7 @@ Fetches a single property from the referenced object.
#### jsHandle.jsonValue() #### jsHandle.jsonValue()
- returns: <[Promise]<[Serializable]>> - returns: <[Promise]<[Serializable]>>
Returns a JSON representation of the object. If the object has a [`toJSON`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON()_behavior) function, it **will not be called**. Returns a JSON representation of the object. If the object has a `toJSON` function, it **will not be called**.
> **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. > **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.
@ -3563,7 +3563,7 @@ Returns a JSON representation of the object. If the object has a [`toJSON`](http
#### consoleMessage.location() #### consoleMessage.location()
- returns: <[Object]> - returns: <[Object]>
- `url` <[string]> URL of the resource if available, otherwise empty string. - `url` <[string]> URL of the resource.
- `lineNumber` <[number]> 0-based line number in the resource. - `lineNumber` <[number]> 0-based line number in the resource.
- `columnNumber` <[number]> 0-based column number in the resource. - `columnNumber` <[number]> 0-based column number in the resource.
@ -3813,7 +3813,7 @@ Dispatches a `keydown` event.
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc. `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
Following modification shortcuts are also suported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`. Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
Holding down `Shift` will type the text that corresponds to the `key` in the upper case. Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
@ -3847,7 +3847,7 @@ page.keyboard.insertText('嗨');
`F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc. `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
Following modification shortcuts are also suported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`. Following modification shortcuts are also supported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
Holding down `Shift` will type the text that corresponds to the `key` in the upper case. Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
@ -3977,9 +3977,9 @@ 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')](#pageonrequest) 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')](#pageonresponse) 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')](#pageonrequestfinished) 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), 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.
@ -4210,8 +4210,8 @@ Selectors can be used to install custom selector engines. See [Working with sele
#### selectors.register(name, script[, options]) #### selectors.register(name, script[, options])
- `name` <[string]> Name that is used in selectors as a prefix, e.g. `{name: 'foo'}` enables `foo=myselectorbody` selectors. May only contain `[a-zA-Z0-9_]` characters. - `name` <[string]> Name that is used in selectors as a prefix, e.g. `{name: 'foo'}` enables `foo=myselectorbody` selectors. May only contain `[a-zA-Z0-9_]` characters.
- `script` <[function]|[string]|[Object]> Script that evaluates to a selector engine instance. - `script` <[function]|[string]|[Object]> Script that evaluates to a selector engine instance.
- `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. - `path` <[string]> Path to the JavaScript file. If `path` is a relative path, then it is resolved relative to the current working directory. Optional.
- `content` <[string]> Raw script content. - `content` <[string]> Raw script content. Optional.
- `options` <[Object]> - `options` <[Object]>
- `contentScript` <[boolean]> Whether to run this selector engine in isolated JavaScript environment. This environment has access to the same DOM, but not any JavaScript objects from the frame's scripts. Defaults to `false`. Note that running as a content script is not guaranteed when this engine is used together with other registered engines. - `contentScript` <[boolean]> Whether to run this selector engine in isolated JavaScript environment. This environment has access to the same DOM, but not any JavaScript objects from the frame's scripts. Defaults to `false`. Note that running as a content script is not guaranteed when this engine is used together with other registered engines.
- returns: <[Promise]> - returns: <[Promise]>
@ -4266,20 +4266,20 @@ Whenever a network route is set up with [`page.route(url, handler)`](#pagerouteu
#### route.abort([errorCode]) #### route.abort([errorCode])
- `errorCode` <[string]> Optional error code. Defaults to `failed`, could be one of the following: - `errorCode` <[string]> Optional error code. Defaults to `failed`, could be one of the following:
- `'aborted'` - An operation was aborted (due to user action) * `'aborted'` - An operation was aborted (due to user action)
- `'accessdenied'` - Permission to access a resource, other than the network, was denied * `'accessdenied'` - Permission to access a resource, other than the network, was denied
- `'addressunreachable'` - The IP address is unreachable. This usually means that there is no route to the specified host or network. * `'addressunreachable'` - The IP address is unreachable. This usually means that there is no route to the specified host or network.
- `'blockedbyclient'` - The client chose to block the request. * `'blockedbyclient'` - The client chose to block the request.
- `'blockedbyresponse'` - The request failed because the response was delivered along with requirements which are not met ('X-Frame-Options' and 'Content-Security-Policy' ancestor checks, for instance). * `'blockedbyresponse'` - The request failed because the response was delivered along with requirements which are not met ('X-Frame-Options' and 'Content-Security-Policy' ancestor checks, for instance).
- `'connectionaborted'` - A connection timed out as a result of not receiving an ACK for data sent. * `'connectionaborted'` - A connection timed out as a result of not receiving an ACK for data sent.
- `'connectionclosed'` - A connection was closed (corresponding to a TCP FIN). * `'connectionclosed'` - A connection was closed (corresponding to a TCP FIN).
- `'connectionfailed'` - A connection attempt failed. * `'connectionfailed'` - A connection attempt failed.
- `'connectionrefused'` - A connection attempt was refused. * `'connectionrefused'` - A connection attempt was refused.
- `'connectionreset'` - A connection was reset (corresponding to a TCP RST). * `'connectionreset'` - A connection was reset (corresponding to a TCP RST).
- `'internetdisconnected'` - The Internet connection has been lost. * `'internetdisconnected'` - The Internet connection has been lost.
- `'namenotresolved'` - The host name could not be resolved. * `'namenotresolved'` - The host name could not be resolved.
- `'timedout'` - An operation timed out. * `'timedout'` - An operation timed out.
- `'failed'` - A generic failure occurred. * `'failed'` - A generic failure occurred.
- returns: <[Promise]> - returns: <[Promise]>
Aborts the route's request. Aborts the route's request.
@ -4359,19 +4359,19 @@ The [WebSocket] class represents websocket connections in the page.
Fired when the websocket closes. Fired when the websocket closes.
#### webSocket.on('framereceived') #### webSocket.on('framereceived')
- <[Object]> web socket frame data - type: <[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.
#### webSocket.on('framesent') #### webSocket.on('framesent')
- <[Object]> web socket frame data - type: <[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.
#### webSocket.on('socketerror') #### webSocket.on('socketerror')
- <[String]> the error message - type: <[String]> the error message
Fired when the websocket has an error. Fired when the websocket has an error.
@ -4499,7 +4499,7 @@ for (const worker of page.workers())
<!-- GEN:stop --> <!-- GEN:stop -->
#### worker.on('close') #### worker.on('close')
- <[Worker]> - type: <[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.
@ -4593,7 +4593,7 @@ const { chromium } = require('playwright'); // Or 'firefox' or 'webkit'.
- `params` <[Object]> - `params` <[Object]>
- `wsEndpoint` <[string]> A browser websocket endpoint to connect to. **required** - `wsEndpoint` <[string]> A browser websocket endpoint to connect to. **required**
- `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. - `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.
- `logger` <[Logger]> Logger sink for Playwright logging. - `logger` <[Logger]> Logger sink for Playwright logging. Optional.
- `timeout` <[number]> Maximum time in milliseconds to wait for the connection to be established. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. - `timeout` <[number]> Maximum time in milliseconds to wait for the connection to be established. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
- returns: <[Promise]<[Browser]>> - returns: <[Promise]<[Browser]>>
@ -4792,7 +4792,7 @@ Determines whether sink is interested in the logger with the given name and seve
- `message` <[string]|[Error]> log message format - `message` <[string]|[Error]> log message format
- `args` <[Array]<[Object]>> message arguments - `args` <[Array]<[Object]>> message arguments
- `hints` <[Object]> optional formatting hints - `hints` <[Object]> optional formatting hints
- `color` <[string]> preferred logger color - `color` <[string]> Optional preferred logger color.
### class: ChromiumBrowser ### class: ChromiumBrowser
* extends: [Browser] * extends: [Browser]
@ -4886,14 +4886,14 @@ const backgroundPage = await context.waitForEvent('backgroundpage');
<!-- GEN:stop --> <!-- GEN:stop -->
#### chromiumBrowserContext.on('backgroundpage') #### chromiumBrowserContext.on('backgroundpage')
- <[Page]> - type: <[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.
#### chromiumBrowserContext.on('serviceworker') #### chromiumBrowserContext.on('serviceworker')
- <[Worker]> - type: <[Worker]>
Emitted when new service worker is created in the context. Emitted when new service worker is created in the context.

968
types/types.d.ts vendored
View file

File diff suppressed because it is too large Load diff

74
utils/doclint/check_public_api/Documentation.js
View file

@ -14,6 +14,17 @@
* limitations under the License. * limitations under the License.
*/ */
// @ts-check
/** @typedef {{
* type: 'text' | 'li' | 'code' | 'gen' | 'h1' | 'h2' | 'h3' | 'h4',
* text?: string,
* codeLang?: string,
* lines?: string[],
* liType?: 'default' | 'bullet' | 'ordinal',
* children?: MarkdownNode[]
* }} MarkdownNode */
class Documentation { class Documentation {
/** /**
* @param {!Array<!Documentation.Class>} classesArray * @param {!Array<!Documentation.Class>} classesArray
@ -32,15 +43,16 @@ Documentation.Class = class {
* @param {string} name * @param {string} name
* @param {!Array<!Documentation.Member>} membersArray * @param {!Array<!Documentation.Member>} membersArray
* @param {?string=} extendsName * @param {?string=} extendsName
* @param {string=} comment * @param {MarkdownNode[]=} spec
* @param {string[]=} templates * @param {string[]=} templates
*/ */
constructor(name, membersArray, extendsName = null, comment = '', templates = []) { constructor(name, membersArray, extendsName = null, spec = undefined, templates = []) {
this.name = name; this.name = name;
this.membersArray = membersArray; this.membersArray = membersArray;
this.comment = comment; this.spec = spec;
this.extends = extendsName; this.extends = extendsName;
this.templates = templates; this.templates = templates;
this.comment = '';
this.index(); this.index();
} }
@ -52,6 +64,10 @@ Documentation.Class = class {
/** @type {!Array<!Documentation.Member>} */ /** @type {!Array<!Documentation.Member>} */
this.propertiesArray = []; this.propertiesArray = [];
/** @type {!Map<string, !Documentation.Member>} */ /** @type {!Map<string, !Documentation.Member>} */
this.options = new Map();
/** @type {!Array<!Documentation.Member>} */
this.optionsArray = [];
/** @type {!Map<string, !Documentation.Member>} */
this.methods = new Map(); this.methods = new Map();
/** @type {!Array<!Documentation.Member>} */ /** @type {!Array<!Documentation.Member>} */
this.methodsArray = []; this.methodsArray = [];
@ -118,6 +134,16 @@ Documentation.Class = class {
} }
} }
} }
visit(visitor) {
visitor(this);
for (const p of this.propertiesArray)
p.visit(visitor);
for (const m of this.methodsArray)
m.visit(visitor);
for (const e of this.eventsArray)
e.visit(visitor);
}
}; };
Documentation.Member = class { Documentation.Member = class {
@ -126,20 +152,19 @@ Documentation.Member = class {
* @param {string} name * @param {string} name
* @param {?Documentation.Type} type * @param {?Documentation.Type} type
* @param {!Array<!Documentation.Member>} argsArray * @param {!Array<!Documentation.Member>} argsArray
* @param {string=} comment * @param {MarkdownNode[]=} spec
* @param {string=} returnComment
* @param {boolean=} required * @param {boolean=} required
* @param {string[]=} templates * @param {string[]=} templates
*/ */
constructor(kind, name, type, argsArray, comment = '', returnComment = '', required = true, templates = []) { constructor(kind, name, type, argsArray, spec = undefined, required = true, templates = []) {
this.kind = kind; this.kind = kind;
this.name = name; this.name = name;
this.type = type; this.type = type;
this.comment = comment; this.spec = spec;
this.returnComment = returnComment;
this.argsArray = argsArray; this.argsArray = argsArray;
this.required = required; this.required = required;
this.templates = templates; this.templates = templates;
this.comment = '';
/** @type {!Map<string, !Documentation.Member>} */ /** @type {!Map<string, !Documentation.Member>} */
this.args = new Map(); this.args = new Map();
for (const arg of argsArray) for (const arg of argsArray)
@ -150,34 +175,41 @@ Documentation.Member = class {
* @param {string} name * @param {string} name
* @param {!Array<!Documentation.Member>} argsArray * @param {!Array<!Documentation.Member>} argsArray
* @param {?Documentation.Type} returnType * @param {?Documentation.Type} returnType
* @param {string=} returnComment * @param {MarkdownNode[]=} spec
* @param {string=} comment
* @param {string[]=} templates * @param {string[]=} templates
* @return {!Documentation.Member} * @return {!Documentation.Member}
*/ */
static createMethod(name, argsArray, returnType, returnComment, comment, templates) { static createMethod(name, argsArray, returnType, spec, templates) {
return new Documentation.Member('method', name, returnType, argsArray, comment, returnComment, undefined, templates); return new Documentation.Member('method', name, returnType, argsArray, spec, undefined, templates);
} }
/** /**
* @param {string} name * @param {string} name
* @param {!Documentation.Type} type * @param {!Documentation.Type} type
* @param {string=} comment * @param {MarkdownNode[]=} spec
* @param {boolean=} required * @param {boolean=} required
* @return {!Documentation.Member} * @return {!Documentation.Member}
*/ */
static createProperty(name, type, comment, required) { static createProperty(name, type, spec, required) {
return new Documentation.Member('property', name, type, [], comment, undefined, required); return new Documentation.Member('property', name, type, [], spec, required);
} }
/** /**
* @param {string} name * @param {string} name
* @param {?Documentation.Type=} type * @param {?Documentation.Type=} type
* @param {string=} comment * @param {MarkdownNode[]=} spec
* @return {!Documentation.Member} * @return {!Documentation.Member}
*/ */
static createEvent(name, type = null, comment) { static createEvent(name, type = null, spec) {
return new Documentation.Member('event', name, type, [], comment); return new Documentation.Member('event', name, type, [], spec);
}
visit(visitor) {
visitor(this);
if (this.type)
this.type.visit(visitor);
for (const arg of this.argsArray)
arg.visit(visitor);
} }
}; };
@ -190,7 +222,11 @@ Documentation.Type = class {
this.name = name; this.name = name;
this.properties = properties; this.properties = properties;
} }
visit(visitor) {
for (const p of this.properties || [])
p.visit(visitor);
}
}; };
module.exports = Documentation; module.exports = Documentation;

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

@ -80,7 +80,7 @@ function checkSources(sources) {
visit(classesByName.get(parent)); visit(classesByName.get(parent));
}; };
visit(cls); visit(cls);
return new Documentation.Class(cls.name, Array.from(membersMap.values()), undefined, cls.comment, cls.templates); return new Documentation.Class(cls.name, Array.from(membersMap.values()), undefined, undefined, cls.templates);
}); });
} }
@ -280,7 +280,7 @@ function checkSources(sources) {
const parameters = signature.parameters.map((s, index) => serializeSymbol(s, [], index < minArgumentCount)); const parameters = signature.parameters.map((s, index) => serializeSymbol(s, [], index < minArgumentCount));
const templates = signature.typeParameters ? signature.typeParameters.map(t => t.symbol.name) : []; const templates = signature.typeParameters ? signature.typeParameters.map(t => t.symbol.name) : [];
const returnType = serializeType(signature.getReturnType()); const returnType = serializeType(signature.getReturnType());
return Documentation.Member.createMethod(name, parameters, returnType.name !== 'void' ? returnType : null, undefined, undefined, templates); return Documentation.Member.createMethod(name, parameters, returnType.name !== 'void' ? returnType : null, undefined, templates);
} }
/** /**

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

@ -14,326 +14,276 @@
* limitations under the License. * limitations under the License.
*/ */
// @ts-check
const { parseArgument } = require('../../parse_md');
const Documentation = require('./Documentation'); const Documentation = require('./Documentation');
const commonmark = require('commonmark');
/** @typedef {import('./Documentation').MarkdownNode} MarkdownNode */
class MDOutline { class MDOutline {
/** /**
* @param {!Page} page * @param {MarkdownNode[]} api
* @param {string} text
* @return {!MDOutline}
*/ */
static async create(page, text) { constructor(api) {
// Render markdown as HTML. this.classesArray = /** @type {Documentation.Class[]} */ [];
const reader = new commonmark.Parser(); this.classes = /** @type {Map<string, Documentation.Class>} */ new Map();
const parsed = reader.parse(text); for (const clazz of api) {
const writer = new commonmark.HtmlRenderer(); const c = parseClass(clazz);
const html = writer.render(parsed); this.classesArray.push(c);
this.classes.set(c.name, c);
const logConsole = msg => console.log(msg.text()); }
page.on('console', logConsole); this.signatures = this._generateComments();
// Extract headings.
await page.setContent(html);
const {classes, errors} = await page.evaluate(() => {
const classes = [];
const errors = [];
const headers = document.body.querySelectorAll('h3');
for (let i = 0; i < headers.length; i++) {
const fragment = extractSiblingsIntoFragment(headers[i], headers[i + 1]);
classes.push(parseClass(fragment));
}
return {classes, errors};
/**
* @param {HTMLLIElement} element
* @param {boolean} defaultRequired
*/
function parseProperty(element, defaultRequired) {
const clone = element.cloneNode(true);
const ul = clone.querySelector(':scope > ul');
const str = parseComment(extractSiblingsIntoFragment(clone.firstChild, ul));
const name = str.substring(0, str.indexOf('<')).replace(/\`/g, '').trim();
let type = findType(str);
const literals = type.match(/("[^"]+"(\|"[^"]+")*)/);
if (literals) {
const sorted = literals[1].split('|').sort((a, b) => a.localeCompare(b)).join('|');
type = type.substring(0, literals.index) + sorted + type.substring(literals.index + literals[0].length);
}
const properties = [];
let comment = str.substring(str.indexOf('<') + type.length + 2).trim();
const hasNonEnumProperties = type.split('|').some(part => {
const basicTypes = new Set(['string', 'number', 'boolean']);
const arrayTypes = new Set([...basicTypes].map(type => `Array<${type}>`));
return !basicTypes.has(part) && !arrayTypes.has(part) && !(part.startsWith('"') && part.endsWith('"'));
});
if (hasNonEnumProperties) {
for (const childElement of element.querySelectorAll(':scope > ul > li')) {
const text = childElement.textContent;
if (text.startsWith(`"`) || text.startsWith(`'`))
continue;
const property = parseProperty(childElement, true);
property.required = defaultRequired;
if (property.comment.toLowerCase().includes('defaults to '))
property.required = false;
if (property.comment.startsWith('Optional '))
property.required = false;
if (property.comment.toLowerCase().includes('if applicable.'))
property.required = false;
if (property.comment.toLowerCase().includes('if available.'))
property.required = false;
if (property.comment.includes('**required**'))
property.required = true;
properties.push(property);
}
} else if (ul) {
comment += '\n' + parseComment(ul).split('\n').map(l => ` - ${l}`).join('\n');
}
return {
name,
type,
comment,
properties
};
}
/**
* @param {string} str
* @return {string}
*/
function findType(str) {
const start = str.indexOf('<') + 1;
let count = 1;
for (let i = start; i < str.length; i++) {
if (str[i] === '<') count++;
if (str[i] === '>') count--;
if (!count)
return str.substring(start, i);
}
return 'unknown';
}
/**
* @param {DocumentFragment} content
*/
function parseClass(content) {
const members = [];
const commentWalker = document.createTreeWalker(content, NodeFilter.SHOW_COMMENT | NodeFilter.SHOW_ELEMENT, {
acceptNode(node) {
if (node instanceof HTMLElement && node.tagName === 'H4')
return NodeFilter.FILTER_ACCEPT;
if (!(node instanceof Comment))
return NodeFilter.FILTER_REJECT;
if (node.data.trim().startsWith('GEN:toc'))
return NodeFilter.FILTER_ACCEPT;
return NodeFilter.FILTER_REJECT;
}
});
const commentEnd = commentWalker.nextNode();
const headers = content.querySelectorAll('h4');
const name = content.firstChild.textContent;
let extendsName = null;
let commentStart = content.firstChild.nextSibling;
const extendsElement = content.querySelector('ul');
if (extendsElement && extendsElement.textContent.trim().startsWith('extends:')) {
commentStart = extendsElement.nextSibling;
extendsName = extendsElement.querySelector('a').textContent;
}
const comment = parseComment(extractSiblingsIntoFragment(commentStart, commentEnd));
for (let i = 0; i < headers.length; i++) {
const fragment = extractSiblingsIntoFragment(headers[i], headers[i + 1]);
members.push(parseMember(fragment));
}
return {
name,
comment,
extendsName,
members
};
}
/**
* @param {Node} content
*/
function parseComment(content) {
for (const code of content.querySelectorAll('pre > code'))
code.replaceWith('```' + code.className.substring('language-'.length) + '\n' + code.textContent + '```');
for (const code of content.querySelectorAll('code'))
code.replaceWith('`' + code.textContent + '`');
for (const strong of content.querySelectorAll('strong'))
strong.replaceWith('**' + parseComment(strong) + '**');
return content.textContent.trim();
}
/**
* @param {DocumentFragment} content
*/
function parseMember(content) {
const name = content.firstChild.textContent;
const args = [];
let returnType = null;
const paramRegex = /^\w+\.[\w$]+\((.*)\)$/;
const matches = paramRegex.exec(name) || ['', ''];
const parameters = matches[1];
const optionalStartIndex = parameters.indexOf('[');
const optinalParamsStr = optionalStartIndex !== -1 ? parameters.substring(optionalStartIndex).replace(/[\[\]]/g, '') : '';
const optionalparams = new Set(optinalParamsStr.split(',').filter(x => x).map(x => x.trim()));
const ul = content.querySelector('ul');
for (const element of content.querySelectorAll('h4 + ul > li')) {
if (element.matches('li') && element.textContent.trim().startsWith('<')) {
returnType = parseProperty(element, element.textContent.trim().includes('data'));
} else if (element.matches('li') && element.firstChild.matches && element.firstChild.matches('code')) {
const property = parseProperty(element, false);
property.required = !optionalparams.has(property.name) && !property.name.startsWith('...');
args.push(property);
} else if (element.matches('li') && element.firstChild.nodeType === Element.TEXT_NODE && element.firstChild.textContent.toLowerCase().startsWith('return')) {
returnType = parseProperty(element, true);
const expectedText = 'returns: ';
let actualText = element.firstChild.textContent;
let angleIndex = actualText.indexOf('<');
let spaceIndex = actualText.indexOf(' ');
angleIndex = angleIndex === -1 ? actualText.length : angleIndex;
spaceIndex = spaceIndex === -1 ? actualText.length : spaceIndex + 1;
actualText = actualText.substring(0, Math.min(angleIndex, spaceIndex));
if (actualText !== expectedText)
errors.push(`${name} has mistyped 'return' type declaration: expected exactly '${expectedText}', found '${actualText}'.`);
}
}
const comment = parseComment(extractSiblingsIntoFragment(ul ? ul.nextSibling : content.querySelector('h4').nextSibling));
return {
name,
args,
returnType,
comment
};
}
/**
* @param {!Node} fromInclusive
* @param {!Node} toExclusive
* @return {!DocumentFragment}
*/
function extractSiblingsIntoFragment(fromInclusive, toExclusive) {
const fragment = document.createDocumentFragment();
let node = fromInclusive;
while (node && node !== toExclusive) {
const next = node.nextSibling;
fragment.appendChild(node);
node = next;
}
return fragment;
}
});
page.off('console', logConsole);
return new MDOutline(classes, errors);
} }
constructor(classes, errors) { _generateComments() {
this.classes = []; /**
this.errors = errors; * @type {Map<string, string>}
const classHeading = /^class: (\w+)$/; */
const constructorRegex = /^new (\w+)\((.*)\)$/; const signatures = new Map();
const methodRegex = /^(\w+)\.([\w$]+)\(([^']*)\)$/;
const propertyRegex = /^(\w+)\.(\w+)$/; for (const clazz of this.classesArray) {
const eventRegex = /^.*\.on\('(\w+)'\)$/; for (const method of clazz.methodsArray) {
let currentClassName = null; const tokens = [];
let currentClassMembers = []; let hasOptional = false;
let currentClassComment = ''; for (const arg of method.argsArray) {
let currentClassExtends = null; const optional = !arg.required;
for (const cls of classes) { if (tokens.length) {
const match = cls.name.match(classHeading); if (optional && !hasOptional)
if (!match) tokens.push(`[, ${arg.name}`);
continue; else
currentClassName = match[1]; tokens.push(`, ${arg.name}`);
currentClassComment = cls.comment; } else {
currentClassExtends = cls.extendsName; if (optional && !hasOptional)
for (const member of cls.members) { tokens.push(`[${arg.name}`);
if (constructorRegex.test(member.name)) { else
const match = member.name.match(constructorRegex); tokens.push(`${arg.name}`);
handleMethod.call(this, member, match[1], 'constructor', match[2]); }
} else if (methodRegex.test(member.name)) { hasOptional = hasOptional || optional;
const match = member.name.match(methodRegex);
handleMethod.call(this, member, match[1], match[2], match[3]);
} else if (propertyRegex.test(member.name)) {
const match = member.name.match(propertyRegex);
handleProperty.call(this, member, match[1], match[2]);
} else if (eventRegex.test(member.name)) {
const match = member.name.match(eventRegex);
handleEvent.call(this, member, match[1]);
} }
if (hasOptional)
tokens.push(']');
const signature = tokens.join('');
const methodName = `${clazz.name}.${method.name}`;
signatures.set(methodName, signature);
} }
flushClassIfNeeded.call(this);
} }
function handleMethod(member, className, methodName, parameters) { for (const clazz of this.classesArray)
if (!currentClassName || !className || !methodName || className.toLowerCase() !== currentClassName.toLowerCase()) { clazz.visit(item => item.comment = renderComments(item.spec, signatures));
this.errors.push(`Failed to process header as method: ${member.name}`); return signatures;
return;
}
parameters = parameters.trim().replace(/[\[\]]/g, '');
if (parameters !== member.args.map(arg => arg.name).join(', '))
this.errors.push(`Heading arguments for "${member.name}" do not match described ones, i.e. "${parameters}" != "${member.args.map(a => a.name).join(', ')}"`);
const args = member.args.map(createPropertyFromJSON);
let returnType = null;
let returnComment = '';
if (member.returnType) {
const returnProperty = createPropertyFromJSON(member.returnType);
returnType = returnProperty.type;
returnComment = returnProperty.comment;
}
const method = Documentation.Member.createMethod(methodName, args, returnType, returnComment, member.comment);
currentClassMembers.push(method);
}
function createPropertyFromJSON(payload) {
const type = new Documentation.Type(payload.type, payload.properties.map(createPropertyFromJSON));
const required = payload.required;
return Documentation.Member.createProperty(payload.name, type, payload.comment, required);
}
function handleProperty(member, className, propertyName) {
if (!currentClassName || !className || !propertyName || className.toLowerCase() !== currentClassName.toLowerCase()) {
this.errors.push(`Failed to process header as property: ${member.name}`);
return;
}
const type = member.returnType ? member.returnType.type : null;
const properties = member.returnType ? member.returnType.properties : [];
currentClassMembers.push(createPropertyFromJSON({type, name: propertyName, properties, comment: member.comment}));
}
function handleEvent(member, eventName) {
if (!currentClassName || !eventName) {
this.errors.push(`Failed to process header as event: ${member.name}`);
return;
}
currentClassMembers.push(Documentation.Member.createEvent(eventName, member.returnType && createPropertyFromJSON(member.returnType).type, member.comment));
}
function flushClassIfNeeded() {
if (currentClassName === null)
return;
this.classes.push(new Documentation.Class(currentClassName, currentClassMembers, currentClassExtends, currentClassComment));
currentClassName = null;
currentClassMembers = [];
}
} }
} }
/** /**
* @param {!Page} page * @param {MarkdownNode} node
* @param {!Array<!Source>} sources * @returns {Documentation.Class}
* @param {!boolean} copyDocsFromSuperClasses
* @return {!Promise<{documentation: !Documentation, errors: !Array<string>}>}
*/ */
module.exports = async function(page, sources, copyDocsFromSuperClasses) { function parseClass(node) {
const classes = []; const members = [];
const errors = []; let extendsName = null;
for (const source of sources) { const name = node.text.substring('class: '.length);
const outline = await MDOutline.create(page, source.text()); for (const member of node.children) {
classes.push(...outline.classes); if (member.type === 'li' && member.text.startsWith('extends: [')) {
errors.push(...outline.errors); extendsName = member.text.substring('extends: ['.length, member.text.indexOf(']'));
continue;
}
if (member.type === 'h2')
members.push(parseMember(member));
} }
const documentation = new Documentation(classes); return new Documentation.Class(name, members, extendsName, extractComments(node));
}
/**
* @param {MarkdownNode} item
* @returns {MarkdownNode[]}
*/
function extractComments(item) {
return (item.children || []).filter(c => c.type !== 'gen' && !c.type.startsWith('h'));
}
/**
* @param {MarkdownNode[]} spec
* @param {Map<string, string>} [signatures]
*/
function renderComments(spec, signatures) {
const result = [];
for (const node of spec || []) {
if (node.type === 'text') {
const text = patchSignatures(node.text, signatures);
// Render comments as text.
if (text.startsWith('> ')) {
result.push('');
result.push(text);
} else {
result.push(text);
}
}
if (node.type === 'code') {
result.push('```' + node.codeLang);
for (const line of node.lines)
result.push(line);
result.push('```');
}
if (node.type === 'gen') {
// Skip
}
if (node.type === 'li' && node.liType !== 'default') {
if (node.text.startsWith('extends:'))
continue;
const visit = (node, indent) => {
result.push(`${indent}- ${patchSignatures(node.text, signatures)}`);
for (const child of node.children || [])
visit(child, indent + ' ');
};
visit(node, '');
}
}
return result.join('\n');
}
/**
* @param {string} comment
* @param {Map<string, string>} signatures
*/
function patchSignatures(comment, signatures) {
if (!signatures)
return comment;
comment = comment.replace(/\[`(event|method|property):\s(JS|CDP|[A-Z])([^.]+)\.([^`]+)`\]\(\)/g, (match, type, clazzPrefix, clazz, name) => {
const className = `${clazzPrefix.toLowerCase()}${clazz}`;
if (type === 'event')
return `\`${className}.on('${name}')\``;
if (type === 'method') {
const signature = signatures.get(`${clazzPrefix}${clazz}.${name}`) || '';
return `\`${className}.${name}(${signature})\``;
}
return `\`${className}.${name}\``;
});
comment = comment.replace(/\[`(?:param|option):\s([^`]+)`\]\(\)/g, '`$1`');
comment = comment.replace(/\[([^\]]+)\]\([^\)]*\)/g, '$1');
for (const link of outgoingLinks)
comment = comment.replace(new RegExp('\\[' + link + '\\]', 'g'), link);
return comment;
}
/**
* @param {MarkdownNode} member
* @returns {Documentation.Member}
*/
function parseMember(member) {
const args = [];
const match = member.text.match(/(event|method|property|async method|): (JS|CDP|[A-Z])([^.]+)\.(.*)/);
const name = match[4];
let returnType = null;
const options = [];
for (const item of member.children || []) {
if (item.type === 'li' && item.liType === 'default')
returnType = parseType(item);
}
if (!returnType)
returnType = new Documentation.Type('void');
if (match[1] === 'async method')
returnType.name = `Promise<${returnType.name}>`;
if (match[1] === 'event')
return Documentation.Member.createEvent(name, returnType, extractComments(member));
if (match[1] === 'property')
return Documentation.Member.createProperty(name, returnType, extractComments(member), true);
for (const item of member.children || []) {
if (item.type === 'h3' && item.text.startsWith('param:'))
args.push(parseProperty(item));
if (item.type === 'h3' && item.text.startsWith('option:'))
options.push(parseProperty(item));
}
if (options.length) {
options.sort((o1, o2) => o1.name.localeCompare(o2.name));
for (const option of options)
option.required = false;
const type = new Documentation.Type('Object', options);
args.push(Documentation.Member.createProperty('options', type, undefined, false));
}
return Documentation.Member.createMethod(name, args, returnType, extractComments(member));
}
/**
* @param {MarkdownNode} spec
* @return {Documentation.Member}
*/
function parseProperty(spec) {
const param = spec.children[0];
const text = param.text;
const name = text.substring(0, text.indexOf('<')).replace(/\`/g, '').trim();
const comments = extractComments(spec);
return Documentation.Member.createProperty(name, parseType(param), comments, guessRequired(renderComments(comments)));
}
/**
* @param {MarkdownNode=} spec
* @return {Documentation.Type}
*/
function parseType(spec) {
const { type } = parseArgument(spec.text);
let typeName = type.replace(/[\[\]\\]/g, '');
const literals = typeName.match(/("[^"]+"(\|"[^"]+")*)/);
if (literals) {
const sorted = literals[1].split('|').sort((a, b) => a.localeCompare(b)).join('|');
typeName = typeName.substring(0, literals.index) + sorted + typeName.substring(literals.index + literals[0].length);
}
const properties = [];
const hasNonEnumProperties = typeName.split('|').some(part => {
const basicTypes = new Set(['string', 'number', 'boolean']);
const arrayTypes = new Set([...basicTypes].map(type => `Array<${type}>`));
return !basicTypes.has(part) && !arrayTypes.has(part) && !(part.startsWith('"') && part.endsWith('"'));
});
if (hasNonEnumProperties && spec) {
for (const child of spec.children || []) {
const { name, text } = parseArgument(child.text);
const patchedText = text.replace(/\. Optional\.$/, '.');
const comments = /** @type {MarkdownNode[]} */ ([{ type: 'text', text: patchedText }]);
properties.push(Documentation.Member.createProperty(name, parseType(child), comments, guessRequired(text)));
}
}
return new Documentation.Type(typeName, properties);
}
/**
* @param {string} comment
*/
function guessRequired(comment) {
let required = true;
if (comment.toLowerCase().includes('defaults to '))
required = false;
if (comment.startsWith('Optional'))
required = false;
if (comment.endsWith('Optional.'))
required = false;
if (comment.toLowerCase().includes('if set'))
required = false;
if (comment.toLowerCase().includes('if applicable'))
required = false;
if (comment.toLowerCase().includes('if available'))
required = false;
if (comment.includes('**required**'))
required = true;
return required;
}
module.exports =
/**
* @param {any} api
* @param {boolean} copyDocsFromSuperClasses
*/
function(api, copyDocsFromSuperClasses) {
const errors = [];
const outline = new MDOutline(api);
const documentation = new Documentation(outline.classesArray);
if (copyDocsFromSuperClasses) { if (copyDocsFromSuperClasses) {
// Push base class documentation to derived classes. // Push base class documentation to derived classes.
@ -356,5 +306,7 @@ module.exports = async function(page, sources, copyDocsFromSuperClasses) {
clazz.index(); clazz.index();
} }
} }
return { documentation, errors }; return { documentation, errors, outline };
}; };
const outgoingLinks = ['AXNode', 'Accessibility', 'Array', 'Body', 'BrowserServer', 'BrowserContext', 'BrowserType', 'Browser', 'Buffer', 'ChildProcess', 'ChromiumBrowser', 'ChromiumBrowserContext', 'ChromiumCoverage', 'CDPSession', 'ConsoleMessage', 'Dialog', 'Download', 'ElementHandle', 'Element', 'Error', 'EvaluationArgument', 'File', 'FileChooser', 'FirefoxBrowser', 'Frame', 'JSHandle', 'Keyboard', 'Logger', 'Map', 'Mouse', 'Object', 'Page', 'Playwright', 'Promise', 'RegExp', 'Request', 'Response', 'Route', 'Selectors', 'Serializable', 'TimeoutError', 'Touchscreen', 'UIEvent.detail', 'URL', 'USKeyboardLayout', 'UnixTime', 'Video', 'WebKitBrowser', 'WebSocket', 'Worker', 'boolean', 'function', 'iterator', 'null', 'number', 'origin', 'selector', 'Readable', 'string', 'xpath'];

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

@ -24,12 +24,10 @@ const EXCLUDE_PROPERTIES = new Set([
]); ]);
/** /**
* @param {!Page} page
* @param {!Array<!Source>} mdSources
* @return {!Promise<!Array<!Message>>} * @return {!Promise<!Array<!Message>>}
*/ */
module.exports = async function lint(page, mdSources, jsSources) { module.exports = function lint(api, jsSources) {
const mdResult = await mdBuilder(page, mdSources, true); const mdResult = mdBuilder(api, true);
const jsResult = jsBuilder.checkSources(jsSources); const jsResult = jsBuilder.checkSources(jsSources);
const jsDocumentation = filterJSDocumentation(jsSources, jsResult.documentation); const jsDocumentation = filterJSDocumentation(jsSources, jsResult.documentation);
const mdDocumentation = mdResult.documentation; const mdDocumentation = mdResult.documentation;
@ -120,12 +118,14 @@ function compareDocumentations(actual, expected) {
for (const methodName of methodDiff.equal) { for (const methodName of methodDiff.equal) {
const actualMethod = actualClass.methods.get(methodName); const actualMethod = actualClass.methods.get(methodName);
const expectedMethod = expectedClass.methods.get(methodName); const expectedMethod = expectedClass.methods.get(methodName);
if (!actualMethod.type !== !expectedMethod.type) { const hasActualType = actualMethod.type && actualMethod.type.name !== 'void';
if (actualMethod.type) const hasExpectedType = expectedMethod.type && expectedMethod.type.name !== 'void';
errors.push(`Method ${className}.${methodName} has unneeded description of return type`); if (hasActualType !== hasExpectedType) {
else if (hasActualType)
errors.push(`Method ${className}.${methodName} is missing return type description`); errors.push(`Method ${className}.${methodName} has unneeded description of return type: `+ actualMethod.type.name);
} else if (actualMethod.type) { else if (hasExpectedType)
errors.push(`Method ${className}.${methodName} is missing return type description: ` + expectedMethod.type.name);
} else if (hasActualType) {
checkType(`Method ${className}.${methodName} has the wrong return type: `, actualMethod.type, expectedMethod.type); checkType(`Method ${className}.${methodName} has the wrong return type: `, actualMethod.type, expectedMethod.type);
} }
const actualArgs = Array.from(actualMethod.args.keys()); const actualArgs = Array.from(actualMethod.args.keys());

18
utils/doclint/check_public_api/test/check-duplicates/doc.md
View file

@ -1,15 +1,17 @@
### class: Bar # class: Bar
### class: Foo # class: Foo
#### foo.test() ## method: Foo.test
#### foo.test() ## method: Foo.test
#### foo.title(arg, arg) ## method: Foo.title
- `arg` <[number]>
### param: Foo.title.arg
- `arg` <[number]> - `arg` <[number]>
### class: Bar ### param: Foo.title.arg
- `arg` <[number]>
[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number" # class: Bar

2
utils/doclint/check_public_api/test/check-nullish/api.ts
View file

@ -1,5 +1,5 @@
class Foo { class Foo {
bar(options: {x: number, y: number, maybe?: number, nullable: string|null, object?: {one: number, two?: number}}) { bar(options?: {x?: number, y?: number, maybe?: number, nullable?: string|null, object?: {one: number, two?: number}}) {
} }

43
utils/doclint/check_public_api/test/check-nullish/doc.md
View file

@ -1,32 +1,33 @@
### class: Foo # class: Foo
#### foo.bar(options) ## method: Foo.bar
- `options` <[Object]>
- `x` <[number]> **required**
- `y` <[number]> **required**
- `nullable` <?[string]> **required**
- `maybe` <[number]>
- `object` <[Object]>
- `one` <[number]>
- `two` <[number]> defaults to `2`.
#### foo.baz() ### option: Foo.bar.x
- `x` <[number]>
### option: Foo.bar.y
- `y` <[number]>
### option: Foo.bar.nullable
- `nullable` <?[string]>
### option: Foo.bar.maybe
- `maybe` <[number]>
### option: Foo.bar.object
- `object` <[Object]>
- `one` <[number]>
- `two` <[number]> defaults to `2`.
## method: Foo.baz
- returns: <?[Object]> - returns: <?[Object]>
- `abc` <[number]> - `abc` <[number]>
- `def` <[number]> if applicable. - `def` <[number]> if applicable.
- `ghi` <[string]> - `ghi` <[string]>
## method: Foo.goBack
#### foo.goBack()
- returns: <[Promise]<?[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If - returns: <[Promise]<?[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. If
can not go back, resolves to `null`. can not go back, resolves to `null`.
#### foo.response() ## method: Foo.response
- returns: <?[Response]> A matching [Response] object, or `null` if the response has not been received yet. - returns: <?[Response]> A matching [Response] object, or `null` if the response has not been received yet.
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String"
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Object_type "Object"
[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#number_type "number"
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Promise_type "Promise"
[Response]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Response_type "Response"

15
utils/doclint/check_public_api/test/check-returns/doc.md
View file

@ -1,14 +1,11 @@
### class: Foo # class: Foo
#### foo.asyncFunction() ## async method: Foo.asyncFunction
#### foo.return42() ## method: Foo.return42
#### foo.returnNothing() ## method: Foo.returnNothing
- returns: <[number]> - returns: <[number]>
#### foo.www() ## method: Foo.www
- returns <[string]> - returns: <[string]>
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String"
[number]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number"

6
utils/doclint/check_public_api/test/check-returns/result.txt
View file

@ -1,4 +1,2 @@
[MarkDown] foo.www() has mistyped 'return' type declaration: expected exactly 'returns: ', found 'returns '. [MarkDown] Method Foo.return42 is missing return type description: number
[MarkDown] Method Foo.asyncFunction is missing return type description [MarkDown] Method Foo.returnNothing has unneeded description of return type: number
[MarkDown] Method Foo.return42 is missing return type description
[MarkDown] Method Foo.returnNothing has unneeded description of return type

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

@ -1,15 +1,15 @@
### class: Foo # class: Foo
#### foo.on('c') ## event: Foo.c
#### foo.on('a') ## event: Foo.a
#### foo.aaa() ## method: Foo.aaa
#### foo.on('b') ## event: Foo.b
#### foo.ddd ## property: Foo.ddd
#### foo.ccc() ## method: Foo.ccc
#### foo.bbb() ## method: Foo.bbb

4
utils/doclint/check_public_api/test/diff-arguments/api.ts
View file

@ -2,10 +2,10 @@ class Foo {
foo(arg1: string, arg3 = {}) { foo(arg1: string, arg3 = {}) {
} }
test(...filePaths : string[]) { test(filePaths : string[]) {
} }
bar(options: {visibility?: boolean}) { bar(options?: {visibility?: boolean}) {
} }
} }
export {Foo}; export {Foo};

25
utils/doclint/check_public_api/test/diff-arguments/doc.md
View file

@ -1,14 +1,19 @@
### class: Foo # class: Foo
#### foo.bar(options)
- `options` <[Object]> ## method: Foo.bar
- `visibility` <[boolean]>
#### foo.foo(arg1, arg2) ### option: Foo.bar.visibility
- `visibility` <[boolean]>
## method: Foo.foo
### param: Foo.foo.arg1
- `arg1` <[string]> - `arg1` <[string]>
### param: Foo.foo.arg2
- `arg2` <[string]> - `arg2` <[string]>
#### foo.test(...files) ## method: Foo.test
- `...filePaths` <...[string]>
[Object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object" ### param: Foo.test.filePaths
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String" - `filePaths` <[Array]<[string]>>
[boolean]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean"

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

@ -1,4 +1,3 @@
[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:
- Implemented but not documented argument: arg3 - Implemented but not documented argument: arg3
- Documented but not implemented argument: arg2 - Documented but not implemented argument: arg2

6
utils/doclint/check_public_api/test/diff-classes/doc.md
View file

@ -1,5 +1,5 @@
### class: Foo # class: Foo
### class: Bar # class: Bar
### class: Baz # class: Baz

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

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

10
utils/doclint/check_public_api/test/diff-methods/doc.md
View file

@ -1,10 +1,10 @@
### class: Foo # class: Foo
#### foo.$() ## method: Foo.$
#### foo.money$$money() ## method: Foo.money$$money
#### foo.proceed() ## method: Foo.proceed
#### foo.start() ## method: Foo.start

6
utils/doclint/check_public_api/test/diff-properties/doc.md
View file

@ -1,5 +1,5 @@
### class: Foo # class: Foo
#### foo.a ## property: Foo.a
#### foo.c ## property: Foo.c

23
utils/doclint/check_public_api/test/md-builder-comments/doc.md
View file

@ -1,15 +1,18 @@
### class: Foo # class: Foo
#### foo.method(arg1, arg2) ## method: Foo.method
- `arg1` <[string]> A single line argument comment
- `arg2` <[string]> A multiline argument comment:
- it could be this
- or it could be that
- returns: <[Promise]<[ElementHandle]>> - returns: <[Promise]<[ElementHandle]>>
The method does something. The method does something.
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String" ### param: Foo.method.arg1
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise" - `arg1` <[string]>
[ElementHandle]: # "ElementHandle"
[ElementHandle]: # "Frame" A single line argument comment
### param: Foo.method.arg2
- `arg2` <[string]>
A multiline argument comment:
* it could be this
* or it could be that

2
utils/doclint/check_public_api/test/md-builder-comments/result.txt
View file

@ -25,7 +25,7 @@
"name": "string" "name": "string"
}, },
"kind": "property", "kind": "property",
"comment": "A multiline argument comment:\n - it could be this\n - or it could be that" "comment": "A multiline argument comment:\n- it could be this\n- or it could be that"
} }
] ]
} }

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

@ -1,24 +1,23 @@
### class: Foo # class: Foo
This is a class. This is a class.
#### foo.on('frame') ## event: Foo.frame
- <[Frame]> - type: <[Frame]>
This event is dispatched. This event is dispatched.
#### foo.$(selector) ## method: Foo.$
- `selector` <[string]> A selector to query page for
- returns: <[Promise]<[ElementHandle]>> - returns: <[Promise]<[ElementHandle]>>
The method runs document.querySelector. The method runs document.querySelector.
#### foo.url ### param: Foo.$.selector
- <[string]> - `selector` <[string]>
A selector to query page for
## property: Foo.url
- type: <[string]>
Contains the URL of the request. Contains the URL of the request.
[string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String"
[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"
[ElementHandle]: # "ElementHandle"
[ElementHandle]: # "Frame"

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

@ -7,7 +7,7 @@
{ {
"name": "frame", "name": "frame",
"type": { "type": {
"name": "[Frame]" "name": "Frame"
}, },
"kind": "event", "kind": "event",
"comment": "This event is dispatched." "comment": "This event is dispatched."

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

@ -16,20 +16,14 @@
const fs = require('fs'); const fs = require('fs');
const path = require('path'); const path = require('path');
const playwright = require('../../../../');
const checkPublicAPI = require('..'); const checkPublicAPI = require('..');
const Source = require('../../Source'); const Source = require('../../Source');
const mdBuilder = require('../MDBuilder'); const mdBuilder = require('../MDBuilder');
const jsBuilder = require('../JSBuilder'); const jsBuilder = require('../JSBuilder');
const { folio } = require('folio'); const { folio } = require('folio');
const { parseMd } = require('../../../parse_md');
const fixtures = folio.extend(); const fixtures = folio.extend();
fixtures.page.init(async({}, test) => {
const browser = await playwright.chromium.launch();
const page = await browser.newPage();
await test(page);
await browser.close();
}, { scope: 'worker' });
const { describe, it, expect } = fixtures.build(); const { describe, it, expect } = fixtures.build();
describe('checkPublicAPI', function() { describe('checkPublicAPI', function() {
@ -49,22 +43,22 @@ describe('checkPublicAPI', function() {
}); });
async function testLint(name) { async function testLint(name) {
it(name, async({page}) => { it(name, async({}) => {
const dirPath = path.join(__dirname, name); const dirPath = path.join(__dirname, name);
const mdSources = await Source.readdir(dirPath, '.md'); const api = parseMd(fs.readFileSync(path.join(dirPath, 'doc.md')).toString());
const tsSources = await Source.readdir(dirPath, '.ts'); const tsSources = await Source.readdir(dirPath, '.ts');
const jsSources = await Source.readdir(dirPath, '.js'); const jsSources = await Source.readdir(dirPath, '.js');
const messages = await checkPublicAPI(page, mdSources, jsSources.concat(tsSources)); const messages = await checkPublicAPI(api, jsSources.concat(tsSources));
const errors = messages.map(message => message.text); const errors = messages.map(message => message.text);
expect(errors.join('\n')).toBe(fs.readFileSync(path.join(dirPath, 'result.txt')).toString()); expect(errors.join('\n')).toBe(fs.readFileSync(path.join(dirPath, 'result.txt')).toString());
}); });
} }
async function testMDBuilder(name) { async function testMDBuilder(name) {
it(name, async({page}) => { it(name, ({}) => {
const dirPath = path.join(__dirname, name); const dirPath = path.join(__dirname, name);
const sources = await Source.readdir(dirPath, '.md'); const api = parseMd(fs.readFileSync(path.join(dirPath, 'doc.md')).toString());
const {documentation} = await mdBuilder(page, sources, true); const {documentation} = mdBuilder(api, true);
expect(serialize(documentation)).toBe(fs.readFileSync(path.join(dirPath, 'result.txt')).toString()); expect(serialize(documentation)).toBe(fs.readFileSync(path.join(dirPath, 'result.txt')).toString());
}); });
} }

52
utils/doclint/cli.js
View file

@ -18,12 +18,12 @@
const playwright = require('../../'); const playwright = require('../../');
const fs = require('fs'); const fs = require('fs');
const path = require('path'); const path = require('path');
const os = require('os');
const Source = require('./Source'); const Source = require('./Source');
const Message = require('./Message'); const Message = require('./Message');
const { parseMd, renderMd, parseArgument, applyTemplates } = require('./../parse_md'); const { parseMd, renderMd, parseArgument, applyTemplates } = require('./../parse_md');
const { spawnSync } = require('child_process'); const { spawnSync } = require('child_process');
const preprocessor = require('./preprocessor'); const preprocessor = require('./preprocessor');
const mdBuilder = require('./check_public_api/MDBuilder');
const PROJECT_DIR = path.join(__dirname, '..', '..'); const PROJECT_DIR = path.join(__dirname, '..', '..');
const VERSION = require(path.join(PROJECT_DIR, 'package.json')).version; const VERSION = require(path.join(PROJECT_DIR, 'package.json')).version;
@ -62,7 +62,8 @@ async function run() {
// Generate signatures // Generate signatures
{ {
const nodes = applyTemplates(parseMd(body), parseMd(params)); const nodes = applyTemplates(parseMd(body), parseMd(params));
const signatures = new Map(); const { outline } = mdBuilder(nodes);
const signatures = outline.signatures;
for (const clazz of nodes) { for (const clazz of nodes) {
clazz.type = 'h3'; clazz.type = 'h3';
for (const member of clazz.children) { for (const member of clazz.children) {
@ -70,7 +71,7 @@ async function run() {
continue; continue;
member.type = 'h4'; member.type = 'h4';
let match = member.text.match(/(event|method|namespace|async method|): (JS|CDP|[A-Z])([^.]+)\.(.*)/); let match = member.text.match(/(event|method|property|async method|): (JS|CDP|[A-Z])([^.]+)\.(.*)/);
if (!match) if (!match)
continue; continue;
@ -89,9 +90,9 @@ async function run() {
if (item.type === 'li' && item.liType === 'default') { if (item.type === 'li' && item.liType === 'default') {
const { type } = parseArgument(item.text); const { type } = parseArgument(item.text);
if (match[1] === 'method') if (match[1] === 'method')
item.text = `returns: ${type}`; item.text = `returns: <${type}>`;
else else
item.text = `returns: <[Promise]${type}>`; item.text = `returns: <[Promise]<${type}>>`;
returnContainer.push(item); returnContainer.push(item);
continue; continue;
} }
@ -103,6 +104,8 @@ async function run() {
const param = item.children[0]; const param = item.children[0];
if (item.children[1]) if (item.children[1])
param.text += ' ' + item.children[1].text; param.text += ' ' + item.children[1].text;
if (item.children.length > 2)
param.children = item.children.slice(2);
args.push(parseArgument(param.text)); args.push(parseArgument(param.text));
argChildren.push(param); argChildren.push(param);
} }
@ -121,6 +124,8 @@ async function run() {
const param = item.children[0]; const param = item.children[0];
if (item.children[1]) if (item.children[1])
param.text += ' ' + item.children[1].text; param.text += ' ' + item.children[1].text;
if (item.children.length > 2)
param.children = item.children.slice(2);
optionsNode.children.push(param); optionsNode.children.push(param);
} }
} }
@ -134,33 +139,13 @@ async function run() {
if (optionsContainer[0]) if (optionsContainer[0])
optionsContainer[0].children.sort((o1, o2) => o1.text.localeCompare(o2.text)); optionsContainer[0].children.sort((o1, o2) => o1.text.localeCompare(o2.text));
member.children = [...argChildren, ...optionsContainer, ...returnContainer, ...nonArgChildren]; member.children = [...argChildren, ...optionsContainer, ...returnContainer, ...nonArgChildren];
const signatureKey = match[2] + match[3] + '.' + match[4];
const tokens = []; const methodName = match[2].toLowerCase() + match[3] + '.' + match[4];
let hasOptional = false; const signature = signatures.get(signatureKey);
for (const arg of args) {
const optional = arg.name === 'options' || arg.text.includes('Optional');
if (tokens.length) {
if (optional && !hasOptional)
tokens.push(`[, ${arg.name}`);
else
tokens.push(`, ${arg.name}`);
} else {
if (optional && !hasOptional)
tokens.push(`[${arg.name}`);
else
tokens.push(`${arg.name}`);
}
hasOptional = hasOptional || optional;
}
if (hasOptional)
tokens.push(']');
const signature = tokens.join('');
const methodName = `${match[2].toLowerCase() + match[3]}.${match[4]}`;
signatures.set(methodName, signature);
member.text = `${methodName}(${signature})`; member.text = `${methodName}(${signature})`;
} }
if (match[1] === 'namespace') { if (match[1] === 'property') {
member.text = `${match[2].toLowerCase() + match[3]}.${match[4]}`; member.text = `${match[2].toLowerCase() + match[3]}.${match[4]}`;
continue; continue;
} }
@ -187,12 +172,13 @@ async function run() {
for (const source of mdSources.filter(source => source.hasUpdatedText())) for (const source of mdSources.filter(source => source.hasUpdatedText()))
messages.push(Message.warning(`WARN: updated ${source.projectPath()}`)); messages.push(Message.warning(`WARN: updated ${source.projectPath()}`));
const browser = await playwright.chromium.launch(); const body = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-body.md')).toString();
const page = await browser.newPage(); const params = fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-params.md')).toString();
const api = applyTemplates(parseMd(body), parseMd(params));
const checkPublicAPI = require('./check_public_api'); const checkPublicAPI = require('./check_public_api');
const jsSources = await Source.readdir(path.join(PROJECT_DIR, 'src', 'client'), '', []); const jsSources = await Source.readdir(path.join(PROJECT_DIR, 'src', 'client'), '', []);
messages.push(...await checkPublicAPI(page, [api], jsSources)); messages.push(...checkPublicAPI(api, jsSources));
await browser.close();
for (const source of mdSources) { for (const source of mdSources) {
if (!source.hasUpdatedText()) if (!source.hasUpdatedText())

17
utils/doclint/generateApiJson.js
View file

@ -14,21 +14,20 @@
* limitations under the License. * limitations under the License.
*/ */
const playwright = require('../..'); const fs = require('fs');
const path = require('path'); const path = require('path');
const Source = require('./Source'); const { parseMd, applyTemplates } = require('../parse_md');
const mdBuilder = require('./check_public_api/MDBuilder'); const mdBuilder = require('./check_public_api/MDBuilder');
const PROJECT_DIR = path.join(__dirname, '..', '..'); const PROJECT_DIR = path.join(__dirname, '..', '..');
(async () => { {
const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md')); const apiBody = parseMd(fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-body.md')).toString());
const browser = await playwright.chromium.launch(); const apiParams = parseMd(fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-params.md')).toString());
const page = await browser.newPage(); const api = applyTemplates(apiBody, apiParams);
const { documentation } = await mdBuilder(page, [api], false); const { documentation } = mdBuilder(api, false);
const result = serialize(documentation); const result = serialize(documentation);
console.log(JSON.stringify(result)); console.log(JSON.stringify(result));
await browser.close(); }
})()
function serialize(documentation) { function serialize(documentation) {
const result = {}; const result = {};

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

@ -193,7 +193,7 @@ function generateLinks(source, signatures, messages) {
const linkOffset = offset + lineNumber + match.index; const linkOffset = offset + lineNumber + match.index;
const hrefOffset = offset + lineNumber + match.index + 3 + name.length; const hrefOffset = offset + lineNumber + match.index + 3 + name.length;
let replacement; let replacement;
const memberMatch = name.match(/`(event|method|namespace):\s(JS|CDP|[A-Z])([^.]+)\.(.*)`/m); const memberMatch = name.match(/`(event|method|property):\s(JS|CDP|[A-Z])([^.]+)\.(.*)`/m);
const paramMatch = name.match(/`(?:param|option):\s(.*)`/m); const paramMatch = name.match(/`(?:param|option):\s(.*)`/m);
if (!memberMatch && !paramMatch) { if (!memberMatch && !paramMatch) {
messages.push(Message.error(`Bad link: ${source.filePath()}:${lineNumber + 1}: ${name}`)); messages.push(Message.error(`Bad link: ${source.filePath()}:${lineNumber + 1}: ${name}`));
@ -203,10 +203,11 @@ function generateLinks(source, signatures, messages) {
replacement = `${memberMatch[2].toLowerCase() + memberMatch[3]}.on('${memberMatch[4]}')`; replacement = `${memberMatch[2].toLowerCase() + memberMatch[3]}.on('${memberMatch[4]}')`;
sourceEdits.edit(linkOffset + 1, hrefOffset - 2, replacement); sourceEdits.edit(linkOffset + 1, hrefOffset - 2, replacement);
} else if (memberMatch && memberMatch[1] === 'method') { } else if (memberMatch && memberMatch[1] === 'method') {
const key = memberMatch[2] + memberMatch[3] + '.' + memberMatch[4];
const method = memberMatch[2].toLowerCase() + memberMatch[3] + '.' + memberMatch[4]; const method = memberMatch[2].toLowerCase() + memberMatch[3] + '.' + memberMatch[4];
let signature = signatures.get(method); let signature = signatures.get(key);
if (signature === undefined) { if (signature === undefined) {
messages.push(Message.error(`Bad method link: ${source.filePath()}:${lineNumber + 1}: ${method}`)); messages.push(Message.error(`Bad method link: ${source.filePath()}:${lineNumber + 1}: ${key}`));
signature = '(\u2026)'; signature = '(\u2026)';
} }
replacement = method + '(' + signature + ')'; replacement = method + '(' + signature + ')';

15
utils/generate_types/index.js
View file

@ -17,12 +17,14 @@
//@ts-check //@ts-check
const path = require('path'); const path = require('path');
const Source = require('../doclint/Source'); const Source = require('../doclint/Source');
const {chromium, devices} = require('../..'); const {devices} = require('../..');
const Documentation = require('../doclint/check_public_api/Documentation'); const Documentation = require('../doclint/check_public_api/Documentation');
const PROJECT_DIR = path.join(__dirname, '..', '..'); const PROJECT_DIR = path.join(__dirname, '..', '..');
const fs = require('fs'); const fs = require('fs');
const {parseOverrides} = require('./parseOverrides'); const {parseOverrides} = require('./parseOverrides');
const exported = require('./exported.json'); const exported = require('./exported.json');
const { parseMd, applyTemplates } = require('../parse_md');
const objectDefinitions = []; const objectDefinitions = [];
const handledMethods = new Set(); const handledMethods = new Set();
/** @type {Documentation} */ /** @type {Documentation} */
@ -35,11 +37,10 @@ let hadChanges = false;
fs.mkdirSync(typesDir) fs.mkdirSync(typesDir)
writeFile(path.join(typesDir, 'protocol.d.ts'), fs.readFileSync(path.join(PROJECT_DIR, 'src', 'server', 'chromium', 'protocol.ts'), 'utf8')); writeFile(path.join(typesDir, 'protocol.d.ts'), fs.readFileSync(path.join(PROJECT_DIR, 'src', 'server', 'chromium', 'protocol.ts'), 'utf8'));
writeFile(path.join(typesDir, 'trace.d.ts'), fs.readFileSync(path.join(PROJECT_DIR, 'src', 'trace', 'traceTypes.ts'), 'utf8')); writeFile(path.join(typesDir, 'trace.d.ts'), fs.readFileSync(path.join(PROJECT_DIR, 'src', 'trace', 'traceTypes.ts'), 'utf8'));
const browser = await chromium.launch(); const apiBody = parseMd(fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-body.md')).toString());
const page = await browser.newPage(); const apiParams = parseMd(fs.readFileSync(path.join(PROJECT_DIR, 'docs-src', 'api-params.md')).toString());
const api = await Source.readFile(path.join(PROJECT_DIR, 'docs', 'api.md')); const api = applyTemplates(apiBody, apiParams);
const {documentation: mdDocumentation} = await require('../doclint/check_public_api/MDBuilder')(page, [api], true); const {documentation: mdDocumentation} = require('../doclint/check_public_api/MDBuilder')(api, true);
await browser.close();
const sources = await Source.readdir(path.join(PROJECT_DIR, 'src', 'client'), '', []); const sources = await Source.readdir(path.join(PROJECT_DIR, 'src', 'client'), '', []);
const {documentation: jsDocumentation} = await require('../doclint/check_public_api/JSBuilder').checkSources(sources); const {documentation: jsDocumentation} = await require('../doclint/check_public_api/JSBuilder').checkSources(sources);
documentation = mergeDocumentation(mdDocumentation, jsDocumentation); documentation = mergeDocumentation(mdDocumentation, jsDocumentation);
@ -408,8 +409,6 @@ function memberJSDOC(member, indent) {
if (member.comment) if (member.comment)
lines.push(...member.comment.split('\n')); lines.push(...member.comment.split('\n'));
lines.push(...member.argsArray.map(arg => `@param ${arg.name.replace(/\./g, '')} ${arg.comment.replace('\n', ' ')}`)); lines.push(...member.argsArray.map(arg => `@param ${arg.name.replace(/\./g, '')} ${arg.comment.replace('\n', ' ')}`));
if (member.returnComment)
lines.push(`@returns ${member.returnComment}`);
if (!lines.length) if (!lines.length)
return indent; return indent;
return writeComment(lines.join('\n'), indent) + '\n' + indent; return writeComment(lines.join('\n'), indent) + '\n' + indent;

16
utils/parse_md.js
View file

@ -268,16 +268,22 @@ function applyTemplates(body, params) {
return body; return body;
} }
/**
* @param {string} line
* @returns {{ name: string, type: string, text: string }}
*/
function parseArgument(line) { function parseArgument(line) {
let match = line.match(/`([^`]+)` (.*)/); let match = line.match(/^`([^`]+)` (.*)/);
if (!match) if (!match)
match = line.match(/(returns): (.*)/); match = line.match(/^(returns): (.*)/);
if (!match)
match = line.match(/^(type): (.*)/);
if (!match) if (!match)
throw new Error('Invalid argument: ' + line); throw new Error('Invalid argument: ' + line);
const name = match[1]; const name = match[1];
const remainder = match[2]; const remainder = match[2];
if (!remainder.startsWith('<')) if (!remainder.startsWith('<'))
console.error('Bad argument:', remainder); throw new Error('Bad argument: ' + remainder);
let depth = 0; let depth = 0;
for (let i = 0; i < remainder.length; ++i) { for (let i = 0; i < remainder.length; ++i) {
const c = remainder.charAt(i); const c = remainder.charAt(i);
@ -286,9 +292,9 @@ function parseArgument(line) {
if (c === '>') if (c === '>')
--depth; --depth;
if (depth === 0) if (depth === 0)
return { name, type: remainder.substring(0, i + 1), text: remainder.substring(i + 2) }; return { name, type: remainder.substring(1, i), text: remainder.substring(i + 2) };
} }
throw new Error('Should not be reached'); throw new Error('Should not be reached');
} }
module.exports = { parseMd, renderMd, parseArgument, applyTemplates }; module.exports = { parseMd, renderMd, parseArgument, applyTemplates, clone };