2020-04-20 04:47:36 +03:00
# Input
#### Contents
- [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 )
< 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
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 checks and force the click:
```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
// Type characted 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');
```
Shortcuts such as `"Control+o"` or `"Control+Shift+T"` are supported as well. When speficied with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
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 / >