mokr.execution.handle.element

Module Contents

Classes

ElementHandle

Representation of a DOM element.

Attributes

LOGGER

mokr.execution.handle.element.LOGGER
class mokr.execution.handle.element.ElementHandle(context: mokr.execution.context.ExecutionContext, client: mokr.connection.DevtoolsConnection, remote_object: dict, page: mokr.browser.page.Page, frame_manager: mokr.frame.FrameManager)

Bases: mokr.execution.context.JavascriptHandle

Representation of a DOM element.

Creation of an ElementHandle blocks the remote DOM element from garbage collection unless it is disposed manually or the parent frame is navigated from.

Parameters:

  • context (ExecutionContext) – mokr.execution.ExecutionContext of the mokr.frame.FrameManager that spawned this.

  • client (DevtoolsConnection) – Remote connection from parent.

  • remote_object (dict) – The raw response from the remote connection representing the object.

  • page (Page) – The mokr.browser.Page the element was located in.

  • frame_manager (FrameManager) – The parent mokr.frame.FrameManager that spawned this element.

async content_frame() → mokr.frame.Frame | None

Return the content frame for this element or None if not within iframe.

Returns:

Target mokr.frame.Frame if within iframe.

Return type:

Frame | None

async content() → str
async hover() → None

Mouse hover over this element.

Raises:

ElementHandleError – Raised if element is detached from DOM.

async click(button: Literal[left, right, middle] = 'left', click_count: int = 1, delay: int | float | None = 1000) → None

Click the center of this element with the bound ElementHandle._page.mouse.

If not in view, this will attempt to scroll the element into view.

Parameters:

  • button (Literal["left", "right", "middle"], optional) – Mouse button to click with. Defaults to “left”.

  • click_count (int, optional) – Number of clicks to run. Defaults to 1.

  • delay (int | float | None, optional) – Time in milliseconds to wait before each click. Defaults to 1000.

Raises:

ElementHandleError – Raised if element is detached from DOM.

async upload_file(file_paths: list[str]) → None

Set files at given file_paths as upload targets for this element.

Parameters:

file_paths (list[str]) – List of file paths for upload.

async tap() → None

Tap the center of this element with the bound ElementHandle._page.touchscreen.

If not in view, this will attempt to scroll the element into view.

Raises:

ElementHandleError – Raised if element is detached from DOM.

async focus() → None

Focus on this element.

async type_text(text: str, delay: int | float = 0) → None

Focus this element and type characters into it. Uses bound ElementHandle._page.keyboard.

Note that modifier keys do not alter text case, meaning sending mokr.input.Keyboard.press("shift") and typing ElementHandle.type_text("mokr") will not type “MOKR” into the it.

Parameters:

  • text (str) – Text to type.

  • delay (int | float, optional) – Time in milliseconds to wait between each character typed. Defaults to 0.

async press(key: str, delay: int | float | None = None) → None

Focus this element and press the given key by sending mokr.input.Keyboard.down and mokr.input.Keyboard.up events, with the given delay in between.

Modifier keys effect this method, meaning sending mokr.input.Keyboard.press("shift") and then mokr.input.Keyboard.press("m") will type an uppercase “M”.

Parameters:

  • key (str) – Name of key. See mokr.input.Keyboard.key_definitions.

  • delay (int | float | None, optional) – Time in milliseconds to “hold” the key down. Defaults to None.

async bounding_box() → dict[str, float] | None

Return the bounding box for this element, if visible. Othwerise, return None.

Returns:

Dictionary keyed with “x”, “y”, “width”,

and “height”, if visible. Othwerwise, None.

Return type:

dict[str, float] | None

async box_model() → dict | None

Return the box model for this element, if visible. Otherwise, None.

Returns:

If not visible, None. Othwerwise, Dictionary keyed with

”content”, “padding”, “border”, “margin”, “width”, and “height”. Each key value will be a dictionary containing “x” and “y”.

Return type:

dict | None

async screenshot(file_type: Literal[png, jpeg] | None = None, file_path: str | None = None, jpeg_quality: int | None = None, omit_background: bool = False, encoding: Literal[binary, base64] = 'binary', scale: int | float = 1) → bytes

Take a screenshot of the element. Will scroll element inyo the viewport, if needed.

Parameters:

  • file_type (Literal["png", "jpeg"] | None, optional) – File type to save the image as. Defaults to “png” if None.

  • file_path (str | None, optional) – Path to save image to. If given without file_type, the type will be inferred. Defaults to None.

  • jpeg_quality (int | None, optional) – JPEG quality, 0-100 (only applicable if type is or is inferred to be JPEG. Defaults to 100 if None.

  • omit_background (bool, optional) – Make the background transparent if True. Not supported on Firefox. Defaults to False.

  • encoding (Literal["binary", "base64"], optional) – Encoding type to return the image data as. Defaults to “binary”.

  • scale (int | float, optional) – Image scale, 0-1. Defaults to 1.

Raises:

  • ValueError – Raised if file_type isn’t given and can’t be inferred as a supported type from file_path, if given.

  • ElementHandleError – Raised if element is not visible (has no mokr.execution.ElementHandle.bounding_box).

Returns:

The image content.

Return type:

bytes

async query_selector(selector: str) → ElementHandle | None

Return the first child element in this element that matches the selector, if any.

Parameters:

selector (str) – Element selector to locate.

Returns:

ElementHandle if found or None.

Return type:

ElementHandle | None

async query_selector_all(selector: str) → list[ElementHandle]

Return all child elements in this element that match the selector, if any.

Parameters:

selector (str) – Element selector to locate.

Returns:

List of ElementHandle if any or empty list.

Return type:

list[ElementHandle]

async xpath(expression: str) → list[ElementHandle]

Return all child elements in this element that match the expression, if any.

Parameters:

expression (str) – XPath expression to evaluate.

Returns:

List of ElementHandle if any or empty list.

Return type:

list[ElementHandle]

async is_in_viewport() → bool

Evaluate if the element is withing the viewport.

Returns:

True if in viewport, else False.

Return type:

bool