ElementHandle.boundingBox() method
Async method that returns the bounding box of the element, or null if the element is not visible. Returns an Object with properties: x (float) - the x coordinate of the element in pixels; y (float) - the y coordinate of the element in pixels; width (float) - the width of the element in pixels; height (float) - the height of the element in pixels. The bounding box is calculated relative to the main frame viewport. Scrolling affects the returned bounding box. Elements from child frames return the bounding box relative to the main frame. Available since v1.8.
ElementHandle.click() method
Async method that clicks the element by performing the following steps: 1) Wait for actionability checks on the element, unless force option is set. 2) Scroll the element into view if needed. 3) Use Page.mouse to click in the center of the element, or the specified position. 4) Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set. If the element is detached from the DOM during the action, throws. When all steps combined have not finished during the specified timeout, throws TimeoutError. Passing zero timeout disables this. Options: button, clickCount, delay, position, modifiers, force, scroll, noWaitAfter, timeout, signal, trial, steps. Discouraged; use Locator.click instead. Available since v1.8.
ElementHandle.contentFrame() method
Async method that returns the content frame for element handles referencing iframe nodes, or null otherwise. Available since v1.8.
ElementHandle.dblclick() method
Async method that double clicks the element by performing the following steps: 1) Wait for actionability checks on the element, unless force option is set. 2) Scroll the element into view if needed. 3) Use Page.mouse to double click in the center of the element, or the specified position. If the element is detached from the DOM during the action, throws. When all steps combined have not finished during the specified timeout, throws TimeoutError. Passing zero timeout disables this. The method dispatches two click events and a single dblclick event. Options: button, delay, position, modifiers, force, scroll, noWaitAfter, timeout, signal, trial, steps. Discouraged; use Locator.dblclick instead. Available since v1.8.
ElementHandle.dispatchEvent() method
Async method that dispatches a DOM event on the element. Parameters: type (string) - DOM event type like 'click', 'dragstart', etc.; eventInit (optional EvaluationArgument) - event-specific initialization properties. The method creates an instance of an event based on the given type, initializes it with eventInit properties, and dispatches it on the element. Events are composed, cancelable and bubble by default. JSHandle can be specified as property value if you want live objects to be passed into the event. Discouraged; use Locator.dispatchEvent instead. Available since v1.8.
ElementHandle.evalOnSelector() method example
const tweetHandle = await page.$('.tweet');
expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');
ElementHandle.isHidden() method
Async method that returns whether the element is hidden, the opposite of visible. Returns boolean. Discouraged; use Locator.isHidden instead. Available since v1.8.
ElementHandle.evalOnSelectorAll() method
Async method that returns the return value of the expression. The method finds all elements matching the specified selector in the ElementHandle's subtree and passes an array of matched elements as a first argument to the expression. If no elements match the selector, passes empty array. If the expression returns a Promise, waits for the promise to resolve and returns its value. Parameters: selector (query selector string), expression (function or string), arg (optional EvaluationArgument) - optional argument to pass to the expression. Returns Serializable. Discouraged; in most cases Locator.evaluateAll and other Locator helper methods and web-first assertions do a better job. Available since v1.9. Python alias: eval_on_selector_all. JavaScript alias: $$eval.
ElementHandle.fill() method
Async method that waits for actionability checks, focuses the element, fills it and triggers an input event after filling. You can pass an empty string to clear the input field. If the target element is not an <input>, <textarea> or [contenteditable] element, throws an error. However, if the element is inside the <label> element that has an associated control, the control will be filled instead. To send fine-grained keyboard events, use Locator.pressSequentially. Parameters: value (string) - value to set for the <input>, <textarea> or [contenteditable] element. Options: force, noWaitAfter, timeout, signal. Discouraged; use Locator.fill instead. Available since v1.8.
ElementHandle.focus() method
Async method that calls focus on the element. Discouraged; use Locator.focus instead. Available since v1.8.
ElementHandle.getAttribute() method
Async method that returns element attribute value. Parameter: name (string) - attribute name to get the value for. Returns null or string. Discouraged; use Locator.getAttribute instead. Available since v1.8.
ElementHandle.hover() method
Async method that hovers over the element by performing the following steps: 1) Wait for actionability checks on the element, unless force option is set. 2) Scroll the element into view if needed. 3) Use Page.mouse to hover over the center of the element, or the specified position. If the element is detached from the DOM during the action, throws. When all steps combined have not finished during the specified timeout, throws TimeoutError. Passing zero timeout disables this. Options: position, modifiers, force, scroll, timeout, signal, trial, noWaitAfter. Discouraged; use Locator.hover instead. Available since v1.8.
ElementHandle.innerText() method
Async method that returns the element.innerText. Returns string. Discouraged; use Locator.innerText instead. Available since v1.8.
ElementHandle.inputValue() method
Async method that returns input.value for the selected <input> or <textarea> or <select> element. Throws for non-input elements. However, if the element is inside the <label> element that has an associated control, returns the value of the control. Returns string. Option: timeout (deprecated, ignored; value is returned immediately). Discouraged; use Locator.inputValue instead. Available since v1.13.
ElementHandle.isChecked() method
Async method that returns whether the element is checked. Throws if the element is not a checkbox or radio input. Returns boolean. Discouraged; use Locator.isChecked instead. Available since v1.8.
ElementHandle.isEditable() method
Async method that returns whether the element is editable. Returns boolean. Discouraged; use Locator.isEditable instead. Available since v1.8.
ElementHandle.isEnabled() method
Async method that returns whether the element is enabled. Returns boolean. Discouraged; use Locator.isEnabled instead. Available since v1.8.
ElementHandle.isVisible() method
Async method that returns whether the element is visible. Returns boolean. Discouraged; use Locator.isVisible instead. Available since v1.8.
ElementHandle.ownerFrame() method
Async method that returns the frame containing the given element. Returns null or Frame. Available since v1.8.
ElementHandle.press() method
Async method that focuses the element, and then uses Keyboard.down and Keyboard.up. Parameter: key (string) - name of the key to press or a single character to generate, such as ArrowLeft or a. Can specify intended keyboardEvent.key value or single character. Supports special keys F1-F12, Digit0-Digit9, KeyA-KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp, etc. Supports modification shortcuts: Shift, Control, Alt, Meta, ShiftLeft, ControlOrMeta. Supports shortcuts like Control+o, Control++, Control+Shift+T. Holding down Shift will type text in upper case. Single character key is case-sensitive. Options: delay (float, defaults to 0), noWaitAfter, timeout, signal. Discouraged; use Locator.press instead. Available since v1.8.
ElementHandle.querySelectorAll() method
Async method that finds all elements matching the specified selector in the ElementHandle's subtree. If no elements match the selector, returns empty array. Parameter: selector (query selector string). Returns Array of ElementHandle. Discouraged; use Page.locator instead. Available since v1.9. Python alias: query_selector_all. JavaScript alias: $$.
ElementHandle.screenshot() method
Async method that captures a screenshot of the page, clipped to the size and position of this particular element. If the element is covered by other elements, it will not be visible on the screenshot. If the element is a scrollable container, only the currently scrolled content will be visible on the screenshot. The method waits for actionability checks, then scrolls element into view before taking a screenshot. If the element is detached from DOM, throws an error. Returns Buffer with the captured screenshot. Options: timeout, signal, maskColor, style. Discouraged; use Locator.screenshot instead. Available since v1.8.
ElementHandle.scrollIntoViewIfNeeded() method
Async method that waits for actionability checks, then tries to scroll element into view, unless it is completely visible as defined by IntersectionObserver's ratio. Throws when elementHandle does not point to an element connected to a Document or a ShadowRoot. Options: timeout, signal. Discouraged; use Locator.scrollIntoViewIfNeeded instead. Available since v1.8.
ElementHandle.selectOption() method
Async method that waits for actionability checks, waits until all specified options are present in the <select> element and selects these options. If the target element is not a <select> element, throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead. Returns array of option values that have been successfully selected. Triggers a change and input event once all options have been selected. Parameter: values (can be string, array of strings, or object with label/value/index). Options: force, noWaitAfter, timeout, signal. Python parameters: element, index, value, label. Discouraged; use Locator.selectOption instead. Available since v1.8.
ElementHandle.setChecked() method
Async method that checks or unchecks an element by performing the following steps: 1) Ensure that element is a checkbox or a radio input; if not, throws. 2) If the element already has the right checked state, returns immediately. 3) Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried. 4) Scroll the element into view if needed. 5) Use Page.mouse to click in the center of the element. 6) Ensure that the element is now checked or unchecked; if not, throws. When all steps combined have not finished during the specified timeout, throws TimeoutError. Passing zero timeout disables this. Parameter: checked (boolean). Options: force, scroll, noWaitAfter, position, timeout, signal, trial. Discouraged; use Locator.setChecked instead. Available since v1.15.
ElementHandle.setInputFiles() method
Async method that sets the value of the file input to the file paths or files. If some filePaths are relative paths, they are resolved relative to the current working directory. For empty array, clears the selected files. For inputs with [webkitdirectory] attribute, only a single directory path is supported. This method expects ElementHandle to point to an input element. However, if the element is inside the <label> element that has an associated control, targets the control instead. Parameter: files (file paths or files). Options: noWaitAfter, timeout, signal. Discouraged; use Locator.setInputFiles instead. Available since v1.8.
ElementHandle.tap() method
Async method that taps the element by performing the following steps: 1) Wait for actionability checks on the element, unless force option is set. 2) Scroll the element into view if needed. 3) Use Page.touchscreen to tap the center of the element, or the specified position. If the element is detached from the DOM during the action, throws. When all steps combined have not finished during the specified timeout, throws TimeoutError. Passing zero timeout disables this. Requires that the hasTouch option of the browser context be set to true. Options: position, modifiers, force, scroll, noWaitAfter, timeout, signal, trial. Discouraged; use Locator.tap instead. Available since v1.8.
ElementHandle.textContent() method
Async method that returns the node.textContent. Returns null or string. Discouraged; use Locator.textContent instead. Available since v1.8.
ElementHandle.type() method
Async method that focuses the element, and then sends a keydown, keypress/input, and keyup event for each character in the text. To press a special key, like Control or ArrowDown, use ElementHandle.press. Parameter: text (string) - text to type into a focused element. Options: delay (float, defaults to 0), noWaitAfter, timeout, signal. Deprecated; in most cases, use Locator.fill instead. You only need to press keys one by one if there is special keyboard handling on the page, in which case use Locator.pressSequentially. Available since v1.8.
ElementHandle.uncheck() method
Async method that unchecks the element by performing the following steps: 1) Ensure that element is a checkbox or a radio input; if not, throws. If the element is already unchecked, returns immediately. 2) Wait for actionability checks on the element, unless force option is set. 3) Scroll the element into view if needed. 4) Use Page.mouse to click in the center of the element. 5) Ensure that the element is now unchecked; if not, throws. If the element is detached from the DOM during the action, throws. When all steps combined have not finished during the specified timeout, throws TimeoutError. Passing zero timeout disables this. Options: position, force, scroll, noWaitAfter, timeout, signal, trial. Discouraged; use Locator.uncheck instead. Available since v1.8.
ElementHandle.waitForElementState() method
Async method that returns when the element satisfies the state parameter. Depending on the state parameter, waits for one of the actionability checks to pass. Throws when the element is detached while waiting, unless waiting for the 'hidden' state. Valid states: 'visible' - wait until the element is visible; 'hidden' - wait until the element is not visible or not attached (does not throw when element detaches); 'stable' - wait until the element is both visible and stable; 'enabled' - wait until the element is enabled; 'disabled' - wait until the element is not enabled; 'editable' - wait until the element is editable. If the element does not satisfy the condition for the timeout milliseconds, throws. Parameter: state (ElementState - one of 'visible', 'hidden', 'stable', 'enabled', 'disabled', 'editable'). Options: timeout, signal. Available since v1.8.
ElementHandle.waitForSelector() method
Async method that returns element specified by selector when it satisfies state option. Returns null if waiting for hidden or detached. Waits for the selector relative to the element handle to satisfy state option (either appear/disappear from dom, or become visible/hidden). If at the moment of calling the method the selector already satisfies the condition, returns immediately. If the selector doesn't satisfy the condition for the timeout milliseconds, throws. Does not work across navigations; use Page.waitForSelector instead. Parameter: selector (query selector string). Options: state, timeout, signal, strict. Discouraged; use web assertions that assert visibility or Locator.waitFor instead. Available since v1.8.