WebElement

class selenium_driverless.types.webelement.WebElement(target, frame_id, isolated_exec_id, obj_id=None, node_id=None, backend_node_id=None, loop=None, class_name=None, context_id=None, is_iframe=False)

Represents a DOM element.

Generally, all interesting operations that interact with a document will be performed through this interface.

All method calls will do a freshness check to ensure that the element reference is still valid. This essentially determines whether the element is still attached to the DOM. If this test fails, then a StaleElementReferenceException is thrown, and all future calls to this instance will fail.

property obj_id: str

async returns the Runtime.RemoteObjectId for the element

property context_id

async the Runtime.ExecutionContextId

property node_id

async the DOM.NodeId

property content_document: WebElement

async gets the contentDocument element of the iframe (or frame). Returns None if this isn’t an iframe.

property shadow_roots: List[WebElement]

async gets a list of currently connected shadow root documents

property shadow_root: WebElement | None

async returns the (first) document for this element

property document_url

async gets the url if the element is an iframe, else returns None

property backend_node_id

async the DOM.BackendNodeId

property class_name

the ClassName of the element (if available)

async find_element(by, value, idx=0, timeout=None)

find an element in the current target

Parameters:

• by (str) – one of the locators at By

• value (str) – the actual query to find the element by

• timeout (Optional[float]) – how long to wait for the element to exist

• idx (int) – might be removed

Return type:

WebElement

async find_elements(by='id', value=None)

find multiple elements in the current target

Parameters:

• by (str) – one of the locators at By

• value (Optional[str]) – the actual query to find the elements by

async get_listeners(depth=3)

gets all listeners on the element. see DOMDebugger.getEventListeners

Parameters:

depth (int) – maximum depth (nested elements) to find listeners for

property source

async the OuterHtml of the element

async set_source(value)

sets the OuterHTML of the element

Parameters:

value (str) – the str to set the outerHtml to

async get_property(name)

Gets the given property of the element.

Parameters:

name (str) – the name of the property to get

Return type:

str

Note

this gets the JavaScript property (elem[name]), and not HTML property

property tag_name: str

This element’s tagName property.

property text: str

async The text of the element. (elem.textContent)

property value: str

async The value of the element. (elem.value)

async clear()

Clears the text if it’s a text entry element. (elem.value = "")

Return type:

None

async remove()

remove the element from the page//dom//html

async highlight(highlight=True)

highlight the element

Parameters:

highlight – whether to disable or enable highlight

Note

highlight automatically fades on any user-interaction, you might use a for-loop

async focus()

focuses the element (Dom.focus)

async is_clickable(listener_depth=3, box_model=None)

returns True if the element type is one of “a”, “button”, “command”, “details”, “input”, “select”, “textarea”, “video”, “map” otherwise checks for “click”, “mousedown” or “mouseup” event listeners on the element

Parameters:

listener_depth – the depth (nested elements) to get event-listeners for

async move_to(timeout=None, visible_timeout=10, spread_a=1, spread_b=1, bias_a=0.5, bias_b=0.5, border=0.05, scroll_to=True, box_model=None)

moves the mouse to the element see Elem.send_keys <selenium_driverless.types.webelement.WebElement.click> for details or the arguments()

Return type:

None

async click(timeout=None, visible_timeout=10, spread_a=1, spread_b=1, bias_a=0.5, bias_b=0.5, border=0.05, scroll_to=True, move_to=True, ensure_clickable=False, box_model=None)

Clicks the element.

Parameters:

• timeout (Optional[float]) – the time in seconds to take for clicking on the element

• visible_timeout (float) – the time in seconds to wait for the element to be at least partially visible

• spread_a (float) – spread over a

• spread_b (float) – spread over b

• bias_a (float) – bias over a (0-1)

• bias_b (float) – bias over b (0-1)

• border (float) – minimum border towards element edges (relative to element => 1). Random generated points outside that border get re-generated.

• scroll_to – whether to scroll to the element

• move_to (bool) – whether to move the mouse to the element

• ensure_clickable (Union[bool, int]) – whether to ensure that the element is clickable.

Return type:

None

Note

a spread of 1 is equivalent to 6 std. relative to the element. (=> 99.7 %)

async write(text, click_kwargs=None, click_on=True)

inserts literal text to the element

Warning

This method is generally detectable. You might consider using Elem.send_keys instead.

Parameters:

• text (str) – the text to send

• click_kwargs – arguments to pass for Elem.send_keys

• click_on (bool) – whether to click on the element before inserting the text

async set_file(path)

sets the file on the current element (has to accept files)

Parameters:

path (str) – the absolute path to the file

async set_files(paths)

sets files on the current element (has to accept files)

Parameters:

paths (List[str]) – the absolute paths to the files

async send_keys(text, click_kwargs=None, click_on=True)

send text & keys to the target

Parameters:

• text (str) – the text to send to the target

• click_kwargs (Optional[dict]) – arguments to pass for Elem.click

• click_on (bool) – whether to click on the element before sending the keys

Return type:

None

async mid_location(spread_a=1, spread_b=1, bias_a=0.5, bias_b=0.5, border=0.05, box_model=None)

returns random location in the element with probability close to the middle

Parameters:

• spread_a (float) – spread over a

• spread_b (float) – spread over b

• bias_a (float) – bias over a (0-1)

• bias_b (float) – bias over b (0-1)

• border (float) – minimum border towards element edges (relative to the element => 1). Random generated points outside that border get re-generated.

Return type:

List[int]

Note

a spread of 1 is equivalent to 6 std. relative to the element. (=> 99.7 %)

async submit()

Submits a form.

Warning

the current implementation likely is detectable. It’s recommended to use click instead if possible

property dom_attributes: dict

returns the dom attributes as a dict

Warning

this isn’t implemented properly yet and might change, use WebElement.execute_script <selenium_driverless.types.webelement.WelElement.execute_script() instead

async get_dom_attribute(name)

Gets the given attribute of the element. Only returns attributes declared in the element’s HTML markup.

Parameters:

name (str) – Name of the attribute to retrieve.

Return type:

str

Warning

this isn’t implemented properly yet and might change, use WebElement.execute_script <selenium_driverless.types.webelement.WelElement.execute_script() instead

async set_dom_attribute(name, value)

set a dom_attribute

Parameters:

• name (str) – the name of the DOM (=>html) attribute

• value (str) – the value to set the attribute to

async get_attribute(name)

Alias to WebElement.get_property.

Warning

this isn’t implemented properly yet and might change, use WebElement.execute_script <selenium_driverless.types.webelement.WelElement.execute_script() instead

async is_selected()

Returns whether the element is selected.

Can be used to check if a checkbox or radio button is selected.

Return type:

bool

async is_enabled()

Returns whether the element is enabled.

Return type:

bool

async p_visible(box_model=None)

Whether the element is visible to a user. This does not check the opacity, since the element might still be interactable. Returns the percentage (0.0 to 1.0) visible within the viewport and polygon of the area visible

Return type:

Tuple[float, Union[ndarray, list]]

async is_visible(box_model=None, minimum_p=0.0001)

returns true if the area of the element which is visible is bigger than minimum_p (0 to 1, percentage visible)

property location_once_scrolled_into_view: dict

scrolls to the element and returns the coordinates of it

async scroll_to(rect=None)

scroll to the element

Note

this isn’t properly implemented yet and might be detectable

property size: dict

async The size of the element.

async value_of_css_property(property_name)

Warning

NotImplemented

Return type:

str

property location: dict

The location of the element in the renderable canvas.

property rect: dict

A dictionary with the size and location of the element.

property box_model: dict

async returns the box model of the element. see DOM.BoxModel

property aria_role: str

async Returns the ARIA role of the current web element.

property accessible_name: str

async Returns the ARIA Level of the current webelement.

property screenshot_as_base64: str

async gets a screenshot as Base64 from the element

property screenshot_as_png: bytes

async Gets the screenshot of the current element as a binary data. (PNG format)

async screenshot(filename)

Saves a screenshot of the current element to a PNG image file.

Parameters:

filename – path to save the png to

Return type:

bool

property parent: WebElement

async The parent element this element

async execute_script(script, *args, max_depth=2, serialization=None, timeout=2, execution_context_id=None, unique_context=True)

executes JavaScript synchronously

return document

this and obj refers to the element here

see Target.execute_raw_script for argument descriptions

async execute_async_script(script, *args, max_depth=2, serialization=None, timeout=2, execution_context_id=None, unique_context=True)

executes JavaScript asynchronously

Warning

using execute_async_script is not recommended as it doesn’t handle exceptions correctly. Use Chrome.eval_async

resolve = arguments[arguments.length-1]

see Target.execute_raw_script for argument descriptions

async eval_async(script, *args, max_depth=2, serialization=None, timeout=2, execution_context_id=None, unique_context=True)

executes JavaScript asynchronously

res = await fetch("https://httpbin.org/get");
// mind CORS!
json = await res.json()
return json

this refers to the element

see Target.execute_raw_script for argument descriptions