ElementHandle
- extends: JSHandle
ElementHandle represents an in-page DOM element. ElementHandles can be created with the page.query_selector() method.
The use of ElementHandle is discouraged, use Locator objects and web-first assertions instead.
- Sync
- Async
href_element = page.query_selector("a")
href_element.click()
href_element = await page.query_selector("a")
await href_element.click()
ElementHandle prevents DOM element from garbage collection unless the handle is disposed with js_handle.dispose(). ElementHandles are auto-disposed when their origin frame gets navigated.
ElementHandle instances can be used as an argument in page.eval_on_selector() and page.evaluate() methods.
The difference between the Locator and ElementHandle is that the ElementHandle points to a particular element, while Locator captures the logic of how to retrieve an element.
In the example below, handle points to a particular DOM element on page. If that element changes text or is used by React to render an entirely different component, handle is still pointing to that very DOM element. This can lead to unexpected behaviors.
- Sync
- Async
handle = page.query_selector("text=Submit")
handle.hover()
handle.click()
handle = await page.query_selector("text=Submit")
await handle.hover()
await handle.click()
With the locator, every time the element
is used, up-to-date DOM element is located in the page using the selector. So in the snippet below, underlying DOM element is going to be located twice.
- Sync
- Async
locator = page.get_by_text("Submit")
locator.hover()
locator.click()
locator = page.get_by_text("Submit")
await locator.hover()
await locator.click()
Methods
bounding_box
Added in: v1.8This method returns the bounding box of the element, or null
if the element is not visible. The bounding box is calculated relative to the main frame viewport - which is usually the same as the browser window.
Scrolling affects the returned bounding box, similarly to Element.getBoundingClientRect. That means x
and/or y
may be negative.
Elements from child frames return the bounding box relative to the main frame, unlike the Element.getBoundingClientRect.
Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following snippet should click the center of the element.
Usage
- Sync
- Async
box = element_handle.bounding_box()
page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)
box = await element_handle.bounding_box()
await page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)
Returns
content_frame
Added in: v1.8Returns the content frame for element handles referencing iframe nodes, or null
otherwise
Usage
element_handle.content_frame()
Returns
owner_frame
Added in: v1.8Returns the frame containing the given element.
Usage
element_handle.owner_frame()
Returns
wait_for_element_state
Added in: v1.8Returns when the element satisfies the state
.
Depending on the state
parameter, this method waits for one of the actionability checks to pass. This method throws when the element is detached while waiting, unless waiting for the "hidden"
state.
"visible"
Wait until the element is visible."hidden"
Wait until the element is not visible or not attached. Note that waiting for hidden does not throw when the 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, this method will throw.
Usage
element_handle.wait_for_element_state(state)
element_handle.wait_for_element_state(state, **kwargs)
Arguments
-
state
"visible"|"hidden"|"stable"|"enabled"|"disabled"|"editable"#A state to wait for, see below for more details.
-
Maximum time in milliseconds. Defaults to
30000
(30 seconds). Pass0
to disable timeout. The default value can be changed by using the browser_context.set_default_timeout() or page.set_default_timeout() methods.
Returns
Deprecated
check
Added in: v1.8Use locator-based locator.check() instead. Read more about locators.
This method checks the element by performing the following steps:
- Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
- Wait for actionability checks on the element, unless
force
option is set. - Scroll the element into view if needed.
- Use page.mouse to click in the center of the element.
- Wait for initiated navigations to either succeed or fail, unless
no_wait_after
option is set. - Ensure that the element is now checked. If not, this method throws.
If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout
, this method throws a TimeoutError. Passing zero timeout disables this.
Usage
element_handle.check()
element_handle.check(**kwargs)
Arguments
-
Whether to bypass the actionability checks. Defaults to
false
. -
no_wait_after
bool (optional)#Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to
false
. -
position
Dict (optional) Added in: v1.11#A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
-
Maximum time in milliseconds. Defaults to
30000
(30 seconds). Pass0
to disable timeout. The default value can be changed by using the browser_context.set_default_timeout() or page.set_default_timeout() methods. -
trial
bool (optional) Added in: v1.11#When set, this method only performs the actionability checks and skips the action. Defaults to
false
. Useful to wait until the element is ready for the action without performing it.
Returns
click
Added in: v1.8Use locator-based locator.click() instead. Read more about locators.
This method clicks the element by performing the following steps:
- Wait for actionability checks on the element, unless
force
option is set. - Scroll the element into view if needed.
- Use page.mouse to click in the center of the element, or the specified
position
. - Wait for initiated navigations to either succeed or fail, unless
no_wait_after
option is set.
If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout
, this method throws a TimeoutError. Passing zero timeout disables this.
Usage
element_handle.click()
element_handle.click(**kwargs)
Arguments
-
button
"left"|"right"|"middle" (optional)#Defaults to
left
. -
defaults to 1. See UIEvent.detail.
-
Time to wait between
mousedown
andmouseup
in milliseconds. Defaults to 0. -
Whether to bypass the actionability checks. Defaults to
false
. -
modifiers
List["Alt"|"Control"|"Meta"|"Shift"] (optional)#Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
-
no_wait_after
bool (optional)#Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to
false
. -
A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
-
Maximum time in milliseconds. Defaults to
30000
(30 seconds). Pass0
to disable timeout. The default value can be changed by using the browser_context.set_default_timeout() or page.set_default_timeout() methods. -
trial
bool (optional) Added in: v1.11#When set, this method only performs the actionability checks and skips the action. Defaults to
false
. Useful to wait until the element is ready for the action without performing it.
Returns
dblclick
Added in: v1.8Use locator-based locator.dblclick() instead. Read more about locators.
This method double clicks the element by performing the following steps:
- Wait for actionability checks on the element, unless
force
option is set. - Scroll the element into view if needed.
- Use page.mouse to double click in the center of the element, or the specified
position
. - Wait for initiated navigations to either succeed or fail, unless
no_wait_after
option is set. Note that if the first click of thedblclick()
triggers a navigation event, this method will throw.
If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout
, this method throws a TimeoutError. Passing zero timeout disables this.
elementHandle.dblclick()
dispatches two click
events and a single dblclick
event.
Usage
element_handle.dblclick()
element_handle.dblclick(**kwargs)
Arguments
-
button
"left"|"right"|"middle" (optional)#Defaults to
left
. -
Time to wait between
mousedown
andmouseup
in milliseconds. Defaults to 0. -
Whether to bypass the actionability checks. Defaults to
false
. -
modifiers
List["Alt"|"Control"|"Meta"|"Shift"] (optional)#Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
-
no_wait_after
bool (optional)#Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to
false
. -
A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
-
Maximum time in milliseconds. Defaults to
30000
(30 seconds). Pass0
to disable timeout. The default value can be changed by using the browser_context.set_default_timeout() or page.set_default_timeout() methods. -
trial
bool (optional) Added in: v1.11#When set, this method only performs the actionability checks and skips the action. Defaults to
false
. Useful to wait until the element is ready for the action without performing it.
Returns
dispatch_event
Added in: v1.8Use locator-based locator.dispatch_event() instead. Read more about locators.
The snippet below dispatches the click
event on the element. Regardless of the visibility state of the element, click
is dispatched. This is equivalent to calling element.click().
Usage
- Sync
- Async
element_handle.dispatch_event("click")
await element_handle.dispatch_event("click")
Under the hood, it creates an instance of an event based on the given type
, initializes it with event_init
properties and dispatches it on the element. Events are composed
, cancelable
and bubble by default.
Since event_init
is event-specific, please refer to the events documentation for the lists of initial properties:
- DeviceMotionEvent
- DeviceOrientationEvent
- DragEvent
- Event
- FocusEvent
- KeyboardEvent
- MouseEvent
- PointerEvent
- TouchEvent
- WheelEvent
You can also specify JSHandle
as the property value if you want live objects to be passed into the event:
- Sync
- Async
# note you can only create data_transfer in chromium and firefox
data_transfer = page.evaluate_handle("new DataTransfer()")
element_handle.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})
# note you can only create data_transfer in chromium and firefox
data_transfer = await page.evaluate_handle("new DataTransfer()")
await element_handle.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})
Arguments
-
DOM event type:
"click"
,"dragstart"
, etc. -
event_init
EvaluationArgument (optional)#Optional event-specific initialization properties.
Returns
eval_on_selector
Added in: v1.9This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. Use locator.evaluate(), other Locator helper methods or web-first assertions instead.
Returns the return value of expression
.
The method finds an element matching the specified selector in the ElementHandle
s subtree and passes it as a first argument to expression
. If no elements match the selector, the method throws an error.
If expression
returns a Promise, then element_handle.eval_on_selector() would wait for the promise to resolve and return its value.
Usage
- Sync
- Async
tweet_handle = page.query_selector(".tweet")
assert tweet_handle.eval_on_selector(".like", "node => node.innerText") == "100"
assert tweet_handle.eval_on_selector(".retweets", "node => node.innerText") == "10"
tweet_handle = await page.query_selector(".tweet")
assert await tweet_handle.eval_on_selector(".like", "node => node.innerText") == "100"
assert await tweet_handle.eval_on_selector(".retweets", "node => node.innerText") == "10"
Arguments
-
A selector to query for.
-
JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked.
-
arg
EvaluationArgument (optional)#Optional argument to pass to
expression
.
Returns
eval_on_selector_all
Added in: v1.9In most cases, locator.evaluate_all(), other Locator helper methods and web-first assertions do a better job.
Returns the return value of 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 expression
.
If expression
returns a Promise, then element_handle.eval_on_selector_all() would wait for the promise to resolve and return its value.
Usage
<div class="feed">
<div class="tweet">Hello!</div>
<div class="tweet">Hi!</div>
</div>
- Sync
- Async
feed_handle = page.query_selector(".feed")
assert feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.innerText)") == ["hello!", "hi!"]
feed_handle = await page.query_selector(".feed")
assert await feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.innerText)") == ["hello!", "hi!"]
Arguments
-
A selector to query for.
-
JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked.
-
arg
EvaluationArgument (optional)#Optional argument to pass to
expression
.
Returns
fill
Added in: v1.8Use locator-based locator.fill() instead. Read more about locators.
This method waits for actionability checks, focuses the element, fills it and triggers an input
event after filling. Note that you can pass an empty string to clear the input field.
If the target element is not an <input>
, <textarea>
or [contenteditable]
element, this method 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.press_sequentially().
Usage
element_handle.fill(value)
element_handle.fill(value, **kwargs)
Arguments
-
Value to set for the
<input>
,<textarea>
or[contenteditable]
element. -
force
bool (optional) Added in: v1.13#Whether to bypass the actionability checks. Defaults to
false
. -
no_wait_after
bool (optional)#Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to
false
. -
Maximum time in milliseconds. Defaults to
30000
(30 seconds). Pass0
to disable timeout. The default value can be changed by using the browser_context.set_default_timeout() or page.set_default_timeout() methods.
Returns
focus
Added in: v1.8Use locator-based locator.focus() instead. Read more about locators.
Calls focus on the element.
Usage
element_handle.focus()
Returns
get_attribute
Added in: v1.8Use locator-based locator.get_attribute() instead. Read more about locators.
Returns element attribute value.
Usage
element_handle.get_attribute(name)
Arguments
Returns
hover
Added in: v1.8Use locator-based locator.hover() instead. Read more about locators.
This method hovers over the element by performing the following steps:
- Wait for actionability checks on the element, unless
force
option is set. - Scroll the element into view if needed.
- Use page.mouse to hover over the center of the element, or the specified
position
. - Wait for initiated navigations to either succeed or fail, unless
noWaitAfter
option is set.
If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout
, this method throws a TimeoutError. Passing zero timeout disables this.
Usage
element_handle.hover()
element_handle.hover(**kwargs)
Arguments
-
Whether to bypass the actionability checks. Defaults to
false
. -
modifiers
List["Alt"|"Control"|"Meta"|"Shift"] (optional)#Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
-
no_wait_after
bool (optional) Added in: v1.28#Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to
false
. -
A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
-
Maximum time in milliseconds. Defaults to
30000
(30 seconds). Pass0
to disable timeout. The default value can be changed by using the browser_context.set_default_timeout() or page.set_default_timeout() methods. -
trial
bool (optional) Added in: v1.11#When set, this method only performs the actionability checks and skips the action. Defaults to
false
. Useful to wait until the element is ready for the action without performing it.
Returns