# 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`[`int`]) – 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)

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

    Parameters:

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

  async click(timeout=None, visible_timeout=30, 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)

    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 being able to compute the elements box model

      - 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. Not reliable in on every webpage

    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)

    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 is_displayed()

    Whether the element is visible to a user.

    Return type:

      `bool`

  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]

    `this` refers to `globalThis` (=> window)

    see `Target.execute_raw_script` for argument descriptions

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

    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