2020-04-20 04:47:36 +03:00
# Input
2020-05-11 19:54:03 +03:00
<!-- GEN:toc - top - level -->
2020-04-20 04:47:36 +03:00
- [Text input ](#text-input )
- [Checkboxes ](#checkboxes )
- [Select options ](#select-options )
- [Mouse click ](#mouse-click )
- [Type characters ](#type-characters )
- [Keys and shortcuts ](#keys-and-shortcuts )
- [Upload files ](#upload-files )
- [Focus element ](#focus-element )
2020-05-11 19:54:03 +03:00
<!-- GEN:stop -->
2020-04-20 04:47:36 +03:00
< br / >
## Text input
2020-04-15 20:53:47 +03:00
2020-04-15 21:01:27 +03:00
This is the easiest way to fill out the form fields. It focuses the element and triggers an `input` event with the entered text. It works for `<input>` , `<textarea>` and `[contenteditable]` elements.
2020-04-15 20:53:47 +03:00
```js
2020-05-03 03:21:46 +03:00
// Text input
await page.fill('#name', 'Peter');
// Date input
2020-04-15 20:53:47 +03:00
await page.fill('#date', '2020-02-02');
2020-05-03 03:21:46 +03:00
// Time input
2020-04-15 20:53:47 +03:00
await page.fill('#time', '13-15');
2020-05-03 03:21:46 +03:00
// Local datetime input
2020-04-15 20:53:47 +03:00
await page.fill('#local', '2020-03-02T05:15');
```
2020-04-20 05:42:40 +03:00
#### API reference
2020-04-15 20:53:47 +03:00
2020-04-20 04:47:36 +03:00
- [page.fill(selector, value[, options])](./api.md#pagefillselector-value-options) — main frame
- [frame.fill(selector, value[, options])](./api.md#framefillselector-value-options) — given frame
- [elementHandle.fill(value[, options])](./api.md#elementhandlefillvalue-options) — given element
2020-04-15 20:53:47 +03:00
2020-04-15 21:05:24 +03:00
< br / >
2020-04-15 20:53:47 +03:00
2020-04-20 04:47:36 +03:00
## Checkboxes
2020-04-15 20:53:47 +03:00
2020-05-03 03:21:46 +03:00
This is the easiest way to check and uncheck a checkbox. This method can be used on the `input[type=checkbox]` and on the `label` associated with that input.
2020-04-15 20:53:47 +03:00
```js
2020-05-03 03:21:46 +03:00
// Check the checkbox
2020-04-15 20:53:47 +03:00
await page.check('#agree');
2020-05-03 03:21:46 +03:00
// Uncheck by input < label > .
2020-04-15 21:01:27 +03:00
await page.uncheck('#subscribe-label');
2020-04-15 20:53:47 +03:00
```
2020-04-20 05:42:40 +03:00
#### API reference
2020-04-15 20:53:47 +03:00
2020-04-20 04:47:36 +03:00
- [page.check(selector[, options])](./api.md#pagecheckselector-options) — main frame
- [page.uncheck(selector[, options])](./api.md#pageuncheckselector-options) — main frame
- [frame.check(selector[, options])](./api.md#framecheckselector-options) — given frame
- [frame.uncheck(selector[, options])](./api.md#frameuncheckselector-options) — given frame
- [elementHandle.check(value[, options])](./api.md#elementhandleuncheckoptions) — given element
- [elementHandle.uncheck(value[, options])](./api.md#elementhandleuncheckoptions) — given element
2020-04-15 20:53:47 +03:00
2020-04-15 21:05:24 +03:00
< br / >
2020-04-15 20:53:47 +03:00
2020-04-20 04:47:36 +03:00
## Select options
2020-04-15 20:53:47 +03:00
2020-04-15 21:01:27 +03:00
Selects one or multiple options in the `<select>` element.
You can specify option `value` , `label` or `elementHandle` to select. Multiple options can be selected.
2020-04-15 20:53:47 +03:00
```js
// Single selection matching the value
2020-04-20 04:47:36 +03:00
await page.selectOption('select#colors', 'blue');
2020-04-15 20:53:47 +03:00
// Single selection matching the label
2020-04-20 04:47:36 +03:00
await page.selectOption('select#colors', { label: 'Blue' });
2020-04-15 20:53:47 +03:00
// Multiple selected items
2020-04-20 04:47:36 +03:00
await page.selectOption('select#colors', ['red', 'green', 'blue']);
2020-04-15 20:53:47 +03:00
2020-05-03 03:21:46 +03:00
// Select the option via element handle
2020-04-20 04:47:36 +03:00
const option = await page.$('#best-option');
await page.selectOption('select#colors', option);
2020-04-15 20:53:47 +03:00
```
2020-04-20 05:42:40 +03:00
#### API reference
2020-04-15 20:53:47 +03:00
2020-04-20 04:47:36 +03:00
- [page.selectOption(selector, values[, options])](./api.md#pageselectoptionselector-values-options) — main frame
- [frame.selectOption(selector, values[, options])](./api.md#frameselectoptionselector-values-options) — given frame
- [elementHandle.selectOption(values[, options])](./api.md#elementhandleselectoptionvalues-options) — given element
2020-04-15 20:53:47 +03:00
2020-04-15 21:05:24 +03:00
< br / >
2020-04-15 20:53:47 +03:00
2020-04-20 04:47:36 +03:00
## Mouse click
2020-05-07 22:33:35 +03:00
Performs a simple human click.
2020-04-20 04:47:36 +03:00
2020-05-03 03:21:46 +03:00
```js
// Generic click
2020-04-20 04:47:36 +03:00
await page.click('button#submit');
2020-05-03 03:21:46 +03:00
// Double click
2020-04-20 04:47:36 +03:00
await page.dblclick('#item');
2020-05-03 03:21:46 +03:00
// Right click
2020-04-20 04:47:36 +03:00
await page.click('#item', { button: 'right' });
2020-05-03 03:21:46 +03:00
// Shift + click
2020-04-21 00:04:49 +03:00
await page.click('#item', { modifiers: ['Shift'] });
2020-04-20 04:47:36 +03:00
2020-05-03 03:21:46 +03:00
// Hover over element
2020-04-20 04:47:36 +03:00
await page.hover('#item');
2020-05-03 03:21:46 +03:00
// Click the top left corner
2020-04-20 04:47:36 +03:00
await page.click('#item', { position: { x: 0, y: 0} });
```
2020-05-03 03:21:46 +03:00
Under the hood, this and other pointer-related methods:
- wait for element with given selector to be in DOM
- wait for it to become displayed, i.e. not empty, no `display:none` , no `visibility:hidden`
- wait for it to stop moving, for example, until css transition finishes
- scroll the element into view
- wait for it to receive pointer events at the action point, for example, waits until element becomes non-obscured by other elements
- retry if the element is detached during any of the above checks
2020-05-07 22:29:59 +03:00
#### Forcing the click
2020-06-15 23:40:55 +03:00
Sometimes, apps use non-trivial logic where hovering the element overlays it with another element that intercepts the click. This behavior is indistinguishable from a bug where element gets covered and the click is dispatched elsewhere. If you know this is taking place, you can bypass the [actionability ](./actionability.md ) checks and force the click:
2020-05-07 22:29:59 +03:00
```js
await page.click('button#submit', { force: true });
```
#### Programmatic click
If you are not interested in testing your app under the real conditions and want to simulate the click by any means possible, you can trigger the [`HTMLElement.click()` ](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click ) behavior via simply dispatching a click event on the element:
```js
await page.dispatchEvent('button#submit', 'click');
```
2020-04-20 05:42:40 +03:00
#### API reference
2020-04-20 04:47:36 +03:00
- [page.click(selector[, options])](./api.md#pageclickselector-options) — main frame
- [frame.click(selector[, options])](./api.md#frameclickselector-options) — given frame
- [elementHandle.click([options])](./api.md#elementhandleclickoptions) — given element
- [page.dblclick(selector[, options])](./api.md#pagedblclickselector-options) — main frame
- [frame.dblclick(selector[, options])](./api.md#framedblclickselector-options) — given frame
- [elementHandle.dblclick([options])](./api.md#elementhandledblclickoptions) — given element
- [page.hover(selector[, options])](./api.md#pagehoverselector-options) — main frame
- [frame.hover(selector[, options])](./api.md#framehoverselector-options) — given frame
- [elementHandle.hover([options])](./api.md#elementhandlehoveroptions) — given element
2020-05-07 22:29:59 +03:00
- [page.dispatchEvent(selector, type) ](./api.md#pagedispatcheventselector-type-eventinit-options ) — main frame
- [frame.dispatchEvent(selector, type) ](./api.md#framedispatcheventselector-type-eventinit-options ) — given frame
- [elementHandle.dispatchEvent(type) ](./api.md#elementhandledispatcheventtype-eventinit ) — given element
2020-04-20 04:47:36 +03:00
< br / >
## Type characters
2020-04-15 20:53:47 +03:00
2020-05-07 22:33:35 +03:00
Type into the field character by character, as if it was a user with a real keyboard.
2020-04-20 04:47:36 +03:00
2020-05-03 03:21:46 +03:00
```js
2020-06-19 01:04:21 +03:00
// Type character by character
2020-04-15 20:53:47 +03:00
await page.type('#area', 'Hello World!');
```
2020-05-03 03:21:46 +03:00
This method will emit all the necessary keyboard events, with all the `keydown` , `keyup` , `keypress` events in place. You can even specify the optional `delay` between the key presses to simulate real user behavior.
2020-04-20 04:47:36 +03:00
2020-05-03 03:21:46 +03:00
> **NOTE** that most of the time, [`page.fill`](#text-input) will just work. You only need to type characters if there is special keyboard handling on the page.
2020-04-15 20:53:47 +03:00
2020-04-20 05:42:40 +03:00
#### API reference
2020-04-15 20:53:47 +03:00
2020-04-20 04:47:36 +03:00
- [page.type(selector, text[, options])](./api.md#pagetypeselector-text-options) — main frame
- [frame.type(selector, text[, options])](./api.md#frametypeselector-text-options) — given frame
- [elementHandle.type(text[, options])](./api.md#elementhandletypetext-options) — given element
- [keyboard.type(text[, options])](./api.md#keyboardtypetext-options) — focused element
2020-04-15 20:53:47 +03:00
2020-04-15 21:05:24 +03:00
< br / >
2020-04-15 20:53:47 +03:00
2020-04-20 04:47:36 +03:00
## Keys and shortcuts
2020-04-15 20:53:47 +03:00
```js
2020-05-03 03:21:46 +03:00
// Hit Enter
2020-04-15 20:53:47 +03:00
await page.press('#submit', 'Enter');
2020-05-03 03:21:46 +03:00
// Dispatch Control+Right
2020-04-15 20:53:47 +03:00
await page.press('#name', 'Control+ArrowRight');
2020-05-03 03:21:46 +03:00
// Press $ sign on keyboard
2020-04-15 20:53:47 +03:00
await page.press('#value', '$');
```
This method focuses the selected element and produces a single keystroke. It accepts the logical key names that are emitted in the [keyboardEvent.key ](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key ) property of the keyboard events:
```
2020-04-15 21:01:27 +03:00
Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape,
ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrayRight,
ArrowUp, F1 - F12, Digit0 - Digit9, KeyA - KeyZ, etc.
2020-04-15 20:53:47 +03:00
```
- You can alternatively specify a single character you'd like to produce such as `"a"` or `"#"` .
2020-04-23 23:40:34 +03:00
- Following modification shortcuts are also supported: `Shift, Control, Alt, Meta` .
2020-04-15 20:53:47 +03:00
Simple version produces a single character. This character is case-sensitive, so `"a"` and `"A"` will produce different results.
```js
2020-05-07 22:33:35 +03:00
// < input id = name >
2020-04-15 20:53:47 +03:00
await page.press('#name', 'Shift+A');
2020-05-07 22:33:35 +03:00
// < input id = name >
2020-04-15 20:53:47 +03:00
await page.press('#name', 'Shift+ArrowLeft');
```
2020-06-19 01:04:21 +03:00
Shortcuts such as `"Control+o"` or `"Control+Shift+T"` are supported as well. When specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
2020-04-15 20:53:47 +03:00
Note that you still need to specify the capital `A` in `Shift-A` to produce the capital character. `Shift-a` produces a lower-case one as if you had the `CapsLock` toggled.
2020-04-20 05:42:40 +03:00
#### API reference
2020-04-20 04:47:36 +03:00
- [page.press(selector, key[, options])](./api.md#pagepressselector-key-options) — main frame
- [frame.press(selector, key[, options])](./api.md#framepressselector-key-options) — given frame
- [elementHandle.press(key[, options])](./api.md#elementhandlepresskey-options) — given element
- [keyboard.press(key[, options])](./api.md#keyboardpresskey-options) — focused element
2020-04-15 20:53:47 +03:00
2020-04-20 04:47:36 +03:00
< br / >
## Upload files
```js
2020-05-03 03:21:46 +03:00
// Select one file
2020-04-20 04:47:36 +03:00
await page.setInputFiles('input#upload', 'myfile.pdf');
2020-05-03 03:21:46 +03:00
// Select multiple files
2020-04-20 04:47:36 +03:00
await page.setInputFiles('input#upload', ['file1.txt', 'file2.txt']);
2020-05-03 03:21:46 +03:00
// Remove all the selected files
await page.setInputFiles('input#upload', []);
// Upload buffer from memory
2020-04-20 04:47:36 +03:00
await page.setInputFiles('input#upload', {
2020-05-07 22:33:35 +03:00
name: 'file.txt',
mimeType: 'text/plain',
buffer: Buffer.from('this is test')
2020-04-20 04:47:36 +03:00
});
```
2020-05-03 03:21:46 +03:00
You can select input files for upload using the `page.setInputFiles` method. It expects first argument to point to an [input element ](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input ) with the type `"file"` . Multiple files can be passed in the array. If some of the file paths are relative, they are resolved relative to the [current working directory ](https://nodejs.org/api/process.html#process_process_cwd ). Empty array clears the selected files.
2020-04-20 05:42:40 +03:00
#### API reference
2020-04-20 04:47:36 +03:00
- [page.setInputFiles(selector, files[, options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagesetinputfilesselector-value-options)
- [frame.setInputFiles(selector, files[, options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#framesetinputfilesselector-value-options)
- [elementHandle.setInputFiles(files[, options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#elementhandlesetinputfilesfiles-options)
< br / >
## Focus element
2020-05-03 03:21:46 +03:00
For the dynamic pages that handle focus events, you can focus the given element.
2020-04-20 04:47:36 +03:00
```js
await page.focus('input#name');
```
2020-04-20 05:42:40 +03:00
#### API reference
2020-04-20 04:47:36 +03:00
- [page.focus(selector, [options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#pagefocusselector-options)
- [frame.focus(selector, [options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#framefocusselector-options)
- [elementHandle.focus([options])](https://github.com/microsoft/playwright/blob/master/docs/api.md#elementhandlefocus-options)
< br / >