diff --git a/docs/api.md b/docs/api.md index 119d790b74..b950218f5f 100644 --- a/docs/api.md +++ b/docs/api.md @@ -650,6 +650,7 @@ page.removeListener('request', logRequest); - [page.mouse](#pagemouse) - [page.opener()](#pageopener) - [page.pdf([options])](#pagepdfoptions) +- [page.press(selector, key[, options])](#pagepressselector-key-options) - [page.reload([options])](#pagereloadoptions) - [page.route(url, handler)](#pagerouteurl-handler) - [page.screenshot([options])](#pagescreenshotoptions) @@ -1193,11 +1194,19 @@ If there's no element matching `selector`, the method throws an error. Shortcut for [page.mainFrame().focus(selector)](#framefocusselector). #### page.frame(options) -- `options` <[Object]> +- `options` <[string]|[Object]> Frame name or other frame lookup options. - `name` <[string]> frame name specified in the `iframe`'s `name` attribute - `url` <[string]|[RegExp]|[Function]> A glob pattern, regex pattern or predicate receiving frame's `url` as a [URL] object. - returns: <[Frame]> frame matching the criteria. +```js +const frame = page.frame('frame-name'); +``` + +```js +const frame = page.frame({ url: /.*domain.*/ }); +``` + Returns frame matching the specified criteria. Either `name` or `url` must be specified. #### page.frames() @@ -1366,6 +1375,28 @@ The `format` options are: > 1. Script tags inside templates are not evaluated. > 2. Page styles are not visible inside templates. +#### page.press(selector, key[, options]) +- `selector` <[string]> A selector of an element to type into. If there are multiple elements satisfying the selector, the first will be used. +- `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names. +- `options` <[Object]> + - `text` <[string]> If specified, generates an input event with this text. + - `delay` <[number]> Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0. + - `waitFor` <[boolean]> Whether to wait for the element to be present in the dom. Defaults to `true`. + - `waitUntil` <"commit"|"load"|"domcontentloaded"|"networkidle0"|"networkidle2"> When to consider navigation succeeded, defaults to `commit`. Events can be either: + - `'commit'` - navigation is committed, new url is displayed in the browser address bar. + - `'load'` - consider navigation to be finished when the `load` event is fired. + - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. + - `'networkidle0'` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms. + - `'networkidle2'` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms. + - `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]> + +Focuses the element, and then uses [`keyboard.down`](#keyboarddownkey-options) and [`keyboard.up`](#keyboardupkey). + +If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also be generated. The `text` option can be specified to force an input event to be generated. + +> **NOTE** Modifier keys DO affect `page.press`. Holding down `Shift` will type the text in upper case. + #### page.reload([options]) - `options` <[Object]> Navigation parameters which might have the following properties: - `timeout` <[number]> Maximum navigation 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. @@ -1860,6 +1891,7 @@ An example of getting text from an iframe element: - [frame.isDetached()](#frameisdetached) - [frame.name()](#framename) - [frame.parentFrame()](#frameparentframe) +- [frame.press(selector, key[, options])](#framepressselector-key-options) - [frame.select(selector, values[, options])](#frameselectselector-values-options) - [frame.setContent(html[, options])](#framesetcontenthtml-options) - [frame.title()](#frametitle) @@ -2165,6 +2197,28 @@ If the name is empty, returns the id attribute instead. #### frame.parentFrame() - returns: Parent frame, if any. Detached frames and main frames return `null`. +#### frame.press(selector, key[, options]) +- `selector` <[string]> A selector of an element to type into. If there are multiple elements satisfying the selector, the first will be used. +- `key` <[string]> Name of key to press, such as `ArrowLeft`. See [USKeyboardLayout] for a list of all key names. +- `options` <[Object]> + - `text` <[string]> If specified, generates an input event with this text. + - `delay` <[number]> Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0. + - `waitFor` <[boolean]> Whether to wait for the element to be present in the dom. Defaults to `true`. + - `waitUntil` <"commit"|"load"|"domcontentloaded"|"networkidle0"|"networkidle2"> When to consider navigation succeeded, defaults to `commit`. Events can be either: + - `'commit'` - navigation is committed, new url is displayed in the browser address bar. + - `'load'` - consider navigation to be finished when the `load` event is fired. + - `'domcontentloaded'` - consider navigation to be finished when the `DOMContentLoaded` event is fired. + - `'networkidle0'` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms. + - `'networkidle2'` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms. + - `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]> + +Focuses the element, and then uses [`keyboard.down`](#keyboarddownkey-options) and [`keyboard.up`](#keyboardupkey). + +If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also be generated. The `text` option can be specified to force an input event to be generated. + +> **NOTE** Modifier keys DO affect `frame.press`. Holding down `Shift` will type the text in upper case. + #### frame.select(selector, values[, options]) - `selector` <[string]> A selector to query frame for. - `values` <[string]|[ElementHandle]|[Object]|[Array]<[string]>|[Array]<[ElementHandle]>|[Array]<[Object]>> Options to select. If the `