Skip to main content
Version: 1.15

Input

Text input#

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>, [contenteditable] and <label> associated with an input or textarea.

// Text inputawait page.fill('#name', 'Peter');
// Date inputawait page.fill('#date', '2020-02-02');
// Time inputawait page.fill('#time', '13:15');
// Local datetime inputawait page.fill('#local', '2020-03-02T05:15');
// Input through labelawait page.fill('text=First Name', 'Peter');

API reference#


Checkboxes and radio buttons#

This is the easiest way to check and uncheck a checkbox or a radio button. This method can be used with input[type=checkbox], input[type=radio], [role=checkbox] or label associated with checkbox or radio button.

// Check the checkboxawait page.check('#agree');
// Assert the checked stateexpect(await page.isChecked('#agree')).toBeTruthy()
// Uncheck by input <label>.await page.uncheck('#subscribe-label');
// Select the radio buttonawait page.check('text=XL');

API reference#


Select options#

Selects one or multiple options in the <select> element. You can specify option value, label or elementHandle to select. Multiple options can be selected.

// Single selection matching the valueawait page.selectOption('select#colors', 'blue');
// Single selection matching the labelawait page.selectOption('select#colors', { label: 'Blue' });
// Multiple selected itemsawait page.selectOption('select#colors', ['red', 'green', 'blue']);
// Select the option via element handleconst option = await page.$('#best-option');await page.selectOption('select#colors', option);

API reference#


Mouse click#

Performs a simple human click.

// Generic clickawait page.click('button#submit');
// Double clickawait page.dblclick('#item');
// Right clickawait page.click('#item', { button: 'right' });
// Shift + clickawait page.click('#item', { modifiers: ['Shift'] });
// Hover over elementawait page.hover('#item');
// Click the top left cornerawait page.click('#item', { position: { x: 0, y: 0} });

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

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:

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() behavior via simply dispatching a click event on the element:

await page.dispatchEvent('button#submit', 'click');

API reference#


Type characters#

Type into the field character by character, as if it was a user with a real keyboard.

// Type character by characterawait page.type('#area', 'Hello World!');

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.

note

Most of the time, page.fill(selector, value[, options]) will just work. You only need to type characters if there is special keyboard handling on the page.

API reference#


Keys and shortcuts#

// Hit Enterawait page.press('#submit', 'Enter');
// Dispatch Control+Rightawait page.press('#name', 'Control+ArrowRight');
// Press $ sign on keyboardawait 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 property of the keyboard events:

Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape,ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight,ArrowUp, F1 - F12, Digit0 - Digit9, KeyA - KeyZ, etc.
  • You can alternatively specify a single character you'd like to produce such as "a" or "#".
  • Following modification shortcuts are also supported: Shift, Control, Alt, Meta.

Simple version produces a single character. This character is case-sensitive, so "a" and "A" will produce different results.

// <input id=name>await page.press('#name', 'Shift+A');
// <input id=name>await page.press('#name', 'Shift+ArrowLeft');

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.

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.

API reference#


Upload files#

You can select input files for upload using the page.setInputFiles(selector, files[, options]) method. It expects first argument to point to an input element 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. Empty array clears the selected files.

// Select one fileawait page.setInputFiles('input#upload', 'myfile.pdf');
// Select multiple filesawait page.setInputFiles('input#upload', ['file1.txt', 'file2.txt']);
// Remove all the selected filesawait page.setInputFiles('input#upload', []);
// Upload buffer from memoryawait page.setInputFiles('input#upload', {  name: 'file.txt',  mimeType: 'text/plain',  buffer: Buffer.from('this is test')});

If you don't have input element in hand (it is created dynamically), you can handle the page.on('filechooser') event or use a corresponding waiting method upon your action:

const [fileChooser] = await Promise.all([  page.waitForEvent('filechooser'),  page.click('upload')]);await fileChooser.setFiles('myfile.pdf');

API reference#


Focus element#

For the dynamic pages that handle focus events, you can focus the given element.

await page.focus('input#name');

API reference#