Playwright · API reference · all subjects

form interaction methods

35 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Frame.check() method parameters and options

Frame.check() is an async, discouraged method. Parameters: selector (matches an element to check). Options: force (boolean, skip actionability checks), scroll (boolean, scroll into view), noWaitAfter (boolean), position (object with x, y coordinates), strict (boolean, error if multiple elements match), timeout (float in milliseconds or number in milliseconds for JS), signal (AbortSignal). Returns: awaitable, returns on completion.

Frame.fill() method parameters and options

Frame.fill() is an async, discouraged method that fills an input element. Parameters: selector, value (string to fill). Options: force (boolean), noWaitAfter (boolean), strict (boolean), timeout (float/number), signal (AbortSignal). Works with <input>, <textarea>, and [contenteditable] elements. Empty string clears the field. Triggers input event after filling. If element is inside <label> with associated control, fills the control instead.

Frame.inputValue() method parameters and return type

Frame.inputValue() is an async, discouraged method that returns string. Parameters: selector. Options: strict (boolean), timeout (float/number), signal (AbortSignal). Returns input.value for <input>, <textarea>, or <select> element. Throws for non-input elements unless element is inside <label> with associated control.

Frame.selectOption() method parameters, options and return type

Frame.selectOption() is an async, discouraged method that returns Array<string>. Parameters: selector, values (options to select - string values or objects with label/value/index). Options: force (boolean), noWaitAfter (boolean), strict (boolean), timeout (float/number), signal (AbortSignal). For Python: element, index, value, label parameters instead. Waits for matching <select> element, actionability checks, all options to be present, then selects them. If element inside <label> with control, uses control instead. Returns array of successfully selected option values. Triggers change and input events.

Frame.setChecked() method parameters and options

Frame.setChecked() is an async, discouraged method. Parameters: selector, checked (boolean). Options: force (boolean), scroll (boolean), noWaitAfter (boolean), position (object), strict (boolean), timeout (float/number), signal (AbortSignal), trial (boolean). Checks or unchecks element by finding it, ensuring it's checkbox/radio, checking actionability, scrolling if needed, and clicking with mouse.

Frame.setInputFiles() method parameters and options

Frame.setInputFiles() is an async, discouraged method. Parameters: selector, files (file paths or file objects). Options: noWaitAfter (boolean), strict (boolean), timeout (float/number), signal (AbortSignal). Sets value of file input to file paths or files. Relative paths resolved relative to current working directory. Empty array clears selected files. Expects selector to point to <input> element, but if inside <label> with associated control, targets control instead.

Frame.type sends keydown, keypress, keyup events for each character

Frame.type sends a keydown, keypress/input, and keyup event for each character in the text. It can be used to send fine-grained keyboard events. To fill values in form fields, use Frame.fill instead. To press special keys like Control or ArrowDown, use Keyboard.press.

Frame.type parameters and options

Frame.type accepts the following parameters and options: - selector (required): input selector, since v1.8 - text (required, string): text to type into a focused element, since v1.8 - delay (optional, float): time to wait between key presses in milliseconds, defaults to 0, since v1.8 - noWaitAfter (optional): removed, since v1.8 - strict (optional): since v1.14 - timeout (optional): since v1.8 - signal (optional): since v1.8

Frame.uncheck method and steps

Frame.uncheck is discouraged and locator-based Locator.uncheck should be used instead. The method checks an element matching the selector by: 1) Finding an element matching the selector, waiting if none exists; 2) Ensuring the element is a checkbox or radio input, throwing if not, returning immediately if already unchecked; 3) Waiting for actionability checks unless force option is set, retrying if detached; 4) Scrolling element into view if needed; 5) Using Page.mouse to click in the center; 6) Ensuring the element is now unchecked, throwing if not. Throws TimeoutError if not finished during specified timeout. Passing zero timeout disables this.

Frame.uncheck parameters and options

Frame.uncheck accepts the following parameters and options: - selector (required): input selector, since v1.8 - force (optional): since v1.8 - scroll (optional): since v1.62 - noWaitAfter (optional): removed, since v1.8 - position (optional): since v1.11 - strict (optional): since v1.14 - timeout (optional): since v1.8 - signal (optional): since v1.8 - trial (optional): since v1.11

Locator.check() method

Locator.check() is an async method that ensures a checkbox or radio element is checked. Performs actionability checks, scrolls into view, clicks the center of the element, and verifies it is checked. Throws if not a checkbox/radio, or if already checked. Supports options: position, force, scroll, noWaitAfter, timeout, signal, and trial.

Locator.clear() method

Locator.clear() is an async method that clears the input field by waiting for actionability checks, focusing the element, clearing it, and triggering an input event. Throws if the target element is not an <input>, <textarea>, or [contenteditable] element, unless the element is inside a <label> with an associated control. Supports options: force, noWaitAfter, timeout, and signal.

Locator.fill() method

Locator.fill() is an async method that sets a value to an input field. Waits for actionability checks, focuses the element, clears it, and triggers an input event. Supports passing empty string to clear the field. Throws if target is not <input>, <textarea>, or [contenteditable], unless inside a <label> with an associated control. Takes parameter 'value' of type string. Supports options: force, noWaitAfter, timeout, and signal.

Locator.selectOption() returns Array<string> of selected values

Locator.selectOption() selects option(s) in a <select> element and returns an Array of string values that have been successfully selected. It waits for actionability checks and until all specified options are present. Parameters: values (varies by language - string/SelectOption/array). Options: force, noWaitAfter, timeout, signal. For Python, specific parameters include: element (ElementHandle), index (int), value (string or array of strings), label (string). Triggers change and input events once all options are selected. Available since v1.14.

Locator.selectText() selects all text content of element

Locator.selectText() waits for actionability checks, then focuses the element and selects all its text content. If the element is inside a <label> with an associated control, the control's text is selected instead. Options: force, timeout, signal. Available since v1.14.

Locator.setChecked() sets checkbox or radio element state

Locator.setChecked() sets the state of a checkbox or radio element by checking or unchecking it. Parameter: checked (boolean). Steps: ensures element is checkbox/radio, returns immediately if already in correct state, waits for actionability checks (unless force option set), scrolls into view if needed, uses mouse click to change state, verifies new state. Options: force, scroll, noWaitAfter, position, timeout, signal, trial. Available since v1.15.

Locator.setInputFiles() uploads files to input[type=file]

Locator.setInputFiles() sets the value of a file input element to specified file paths or file objects. For inputs with webkitdirectory attribute, only a single directory path is supported. Parameter: files (paths, FilePayload objects, or empty array to clear). Accepts relative paths resolved relative to current working directory. For Python, can pass file dicts with 'name', 'mimeType', and 'buffer' keys. Options: noWaitAfter, timeout, signal. Available since v1.14.

Locator.type() is deprecated; use fill() or pressSequentially()

Locator.type() is deprecated and should be replaced with Locator.fill() in most cases, or Locator.pressSequentially() if special keyboard handling is needed. It focuses the element and sends keydown, keypress/input, and keyup events for each character. Parameters: text (string). Options: delay (float, defaults to 0), noWaitAfter, timeout, signal. Available since v1.14.

Locator.uncheck() ensures checkbox or radio is unchecked

Locator.uncheck() unchecks a checkbox or radio element by: ensuring element is checkbox/radio input, returning immediately if already unchecked, waiting for actionability checks (unless force option set), scrolling into view if needed, using Page.mouse to click center, verifying element is now unchecked. Options: position, force, scroll, noWaitAfter, timeout, signal, trial. Available since v1.14.

Locator.selectOption() example selecting multiple options

Example showing Locator.selectOption() usage for multiple selection: ```python # single selection matching the value or label await element.select_option("blue") # single selection matching the label await element.select_option(label="blue") # multiple selection for blue, red and green options await element.select_option(value=["red", "green", "blue"]) ```

Locator.setChecked() example checking a checkbox

Example showing Locator.setChecked() usage: ```python await page.get_by_role("checkbox").set_checked(True) ``` This sets the checkbox state to checked (True).

Locator.setInputFiles() example uploading single and multiple files

Example showing Locator.setInputFiles() usage: ```python # Select one file await page.get_by_label("Upload file").set_input_files('myfile.pdf') # Select multiple files await page.get_by_label("Upload files").set_input_files(['file1.txt', 'file2.txt']) # Select a directory await page.get_by_label("Upload directory").set_input_files('mydir') # Remove all the selected files await page.get_by_label("Upload file").set_input_files([]) # Upload buffer from memory await page.get_by_label("Upload file").set_input_files( files=[ {"name": "test.txt", "mimeType": "text/plain", "buffer": b"this is a test"} ], ) ```

Locator.uncheck() example unchecking a checkbox

Example showing Locator.uncheck() usage: ```python await page.get_by_role("checkbox").uncheck() ``` This unchecks a checkbox element.

input-files: FilePayload for file operations

The files parameter accepts path, Array<path>, Object, or Array<Object>. FilePayload object has: name (string, file name), mimeType (string, file type), buffer (Buffer, file content). Used for file uploads.

input-checked: checked parameter for checkbox operations

The checked parameter is type boolean (C# alias: checkedState). Whether to check or uncheck the checkbox.

select-options-values for Java, JS, C#

The values parameter accepts null, string, ElementHandle, Array<string>, Object, Array<ElementHandle>, or Array<Object> (alias-java: SelectOption). Object has optional: value (string), label (string), index (int). If <select> has multiple, all matching selected, else first. Strings match values and labels.

python-select-options parameters

Python select has: element (optional ElementHandle or Array<ElementHandle>), index (optional int or Array<int>), value (optional string or Array<string>; if multiple, all selected, else first), label (optional string or Array<string>; if multiple, all selected, else first).

Page.check checks checkbox or radio input

The async method Page.check (since v1.8, discouraged - use Locator.check instead) checks an element matching the selector by: finding the element, ensuring it's a checkbox or radio input, waiting for actionability checks, scrolling into view if needed, using Page.mouse to click in the center, and ensuring it's now checked. Returns undefined. Throws TimeoutError if not completed in time. Parameters: selector. Options: force, scroll, noWaitAfter, position, strict, timeout, signal, trial.

Page.fill - fill input or textarea

Page.fill() is an async method (since v1.8, discouraged in favor of Locator.fill) that waits for an element matching a selector, performs actionability checks, focuses the element, fills it with a value, and triggers an input event. It accepts: selector (CSS selector string), value (string to fill). Options: force (boolean, since v1.13), noWaitAfter (since v1.8), strict (boolean, since v1.14), timeout (number, since v1.8), signal (AbortSignal). The method works with input, textarea, or contenteditable elements, or controls inside label elements. It throws an error for non-input elements.

Page.focus - focus an element

Page.focus() is an async method (since v1.8, discouraged in favor of Locator.focus) that fetches an element matching a selector and focuses it. It accepts: selector (CSS selector string). Options: strict (boolean, since v1.14), timeout (number, since v1.8), signal (AbortSignal). If no element matches, the method waits until a matching element appears in the DOM.

Page.selectOption method

Page.selectOption() (async, added in v1.8, discouraged in favor of Locator.selectOption) waits for element matching selector, waits for actionability, and selects specified options. Returns an array of option values that were successfully selected. Triggers 'change' and 'input' events once all options are selected. If the element is inside a label with an associated control, the control is used instead.

Page.selectOption example

```js // Single selection matching the value or label page.selectOption('select#colors', 'blue'); // single selection matching the label page.selectOption('select#colors', { label: 'Blue' }); // multiple selection page.selectOption('select#colors', ['red', 'green', 'blue']); ``` This demonstrates single and multiple selection for select elements.

Page.setChecked method

Page.setChecked() (async, added in v1.15, discouraged in favor of Locator.setChecked) checks or unchecks an element matching selector. Performs actionability checks, scrolls into view if needed, and uses Page.mouse to click the center. Ensures element is checkbox or radio input. If element already has correct checked state, returns immediately. Options: force, scroll (v1.62), noWaitAfter, position, strict, timeout, signal, trial.

Page.setInputFiles method

Page.setInputFiles() (async, added in v1.8, discouraged in favor of Locator.setInputFiles) sets the value of file input to specified file paths or files. Relative paths are resolved relative to current working directory. Accepts empty array to clear selected files. For inputs with webkitdirectory attribute, only single directory path supported. Expects selector to point to input element; if inside label with associated control, targets control instead. Options: noWaitAfter, strict, timeout, signal.

Page.uncheck method

Page.uncheck() (async, added in v1.8, discouraged in favor of Locator.uncheck) unchecks an element matching selector. Waits for actionability checks (unless force option set), scrolls into view if needed, uses Page.mouse to click center. Ensures element is checkbox or radio input; returns immediately if already unchecked. Options: force, scroll (v1.62), noWaitAfter, position, strict, timeout, signal, trial (v1.11).

Give your agent this brain