mokr.execution.handle.element ============================= .. py:module:: mokr.execution.handle.element Attributes ---------- .. autoapisummary:: mokr.execution.handle.element.LOGGER Classes ------- .. autoapisummary:: mokr.execution.handle.element.ElementHandle Module Contents --------------- .. py:data:: LOGGER .. py:class:: ElementHandle(context: mokr.execution.context.ExecutionContext, client: mokr.connection.DevtoolsConnection, remote_object: dict, page: mokr.browser.page.Page, frame_manager: mokr.frame.FrameManager) Bases: :py:obj:`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. :param context: `mokr.execution.ExecutionContext` of the `mokr.frame.FrameManager` that spawned this. :type context: ExecutionContext :param client: Remote connection from parent. :type client: DevtoolsConnection :param remote_object: The raw response from the remote connection representing the object. :type remote_object: dict :param page: The `mokr.browser.Page` the element was located in. :type page: Page :param frame_manager: The parent `mokr.frame.FrameManager` that spawned this element. :type frame_manager: FrameManager .. py:method:: content_frame() -> mokr.frame.Frame | None :async: Return the content frame for this element or None if not within iframe. :returns: Target `mokr.frame.Frame` if within iframe. :rtype: Frame | None .. py:method:: content() -> str :async: .. py:method:: hover() -> None :async: Mouse hover over this element. :raises ElementHandleError: Raised if element is detached from DOM. .. py:method:: click(button: Literal['left', 'right', 'middle'] = 'left', click_count: int = 1, delay: int | float | None = 1000) -> None :async: 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. :param button: Mouse button to click with. Defaults to "left". :type button: Literal["left", "right", "middle"], optional :param click_count: Number of clicks to run. Defaults to 1. :type click_count: int, optional :param delay: Time in milliseconds to wait before each click. Defaults to 1000. :type delay: int | float | None, optional :raises ElementHandleError: Raised if element is detached from DOM. .. py:method:: upload_file(file_paths: list[str]) -> None :async: Set files at given `file_paths` as upload targets for this element. :param file_paths: List of file paths for upload. :type file_paths: list[str] .. py:method:: tap() -> None :async: 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. .. py:method:: focus() -> None :async: Focus on this element. .. py:method:: type_text(text: str, delay: int | float = 0) -> None :async: 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. :param text: Text to type. :type text: str :param delay: Time in milliseconds to wait between each character typed. Defaults to 0. :type delay: int | float, optional .. py:method:: press(key: str, delay: int | float | None = None) -> None :async: 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". :param key: Name of key. See `mokr.input.Keyboard.key_definitions`. :type key: str :param delay: Time in milliseconds to "hold" the key down. Defaults to None. :type delay: int | float | None, optional .. py:method:: bounding_box() -> dict[str, float] | None :async: 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. :rtype: dict[str, float] | None .. py:method:: box_model() -> dict | None :async: 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". :rtype: dict | None .. py:method:: 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 :async: Take a screenshot of the element. Will scroll element inyo the viewport, if needed. :param file_type: File type to save the image as. Defaults to "png" if None. :type file_type: Literal["png", "jpeg"] | None, optional :param file_path: Path to save image to. If given without `file_type`, the type will be inferred. Defaults to None. :type file_path: str | None, optional :param jpeg_quality: JPEG quality, 0-100 (only applicable if type is or is inferred to be JPEG. Defaults to 100 if None. :type jpeg_quality: int | None, optional :param omit_background: Make the background transparent if True. Not supported on Firefox. Defaults to False. :type omit_background: bool, optional :param encoding: Encoding type to return the image data as. Defaults to "binary". :type encoding: Literal["binary", "base64"], optional :param scale: Image scale, 0-1. Defaults to 1. :type scale: int | float, optional :raises ValueError: Raised if `file_type` isn't given and can't be inferred as a supported type from `file_path`, if given. :raises ElementHandleError: Raised if element is not visible (has no `mokr.execution.ElementHandle.bounding_box`). :returns: The image content. :rtype: bytes .. py:method:: query_selector(selector: str) -> ElementHandle | None :async: Return the first child element in this element that matches the selector, if any. :param selector: Element selector to locate. :type selector: str :returns: ElementHandle if found or None. :rtype: ElementHandle | None .. py:method:: query_selector_all(selector: str) -> list[ElementHandle] :async: Return all child elements in this element that match the selector, if any. :param selector: Element selector to locate. :type selector: str :returns: List of ElementHandle if any or empty list. :rtype: list[ElementHandle] .. py:method:: xpath(expression: str) -> list[ElementHandle] :async: Return all child elements in this element that match the expression, if any. :param expression: XPath expression to evaluate. :type expression: str :returns: List of ElementHandle if any or empty list. :rtype: list[ElementHandle] .. py:method:: is_in_viewport() -> bool :async: Evaluate if the element is withing the viewport. :returns: True if in viewport, else False. :rtype: bool