mokr.execution

Submodules

Classes

ExecutionContext

Class to handle execution of JavaScript functions, element manipulation,

ElementHandle

Representation of a DOM element.

JavascriptHandle

Representative of a JavaScript object within the frame.

Package Contents

class mokr.execution.ExecutionContext(client: mokr.connection.DevtoolsConnection, context_payload: dict, object_handle_factory: Any, frame: mokr.frame.Frame = None)

Class to handle execution of JavaScript functions, element manipulation, and associated runtime error translation.

Parameters:

  • client (DevtoolsConnection) – Remote connection from parent.

  • context_payload (dict) – Context from triggering event.

  • object_handle_factory (Any) – Factory for handling remote objects. Should create mokr.execution.JavascriptHandle based objects.

  • frame (Frame, optional) – The mokr.frame.Frame that spawned this. Defaults to None.

property frame: mokr.frame.Frame | None

Parent mokr.frame.Frame that spawned this.

async evaluate(page_function: str, *args: Any, force_expr: bool = False) → Any

Run ExecutionContext.evaluate_handle and try to run mokr.execution.JavascriptHandle.json on the result to return the object as a dictionary.

Parameters:

  • page_function (str) – JavaScript function to run.

  • force_expr (bool) – If True, treat page_function as an expression. Otherwise, automatically determine if it is a function or an expression. Defaults to False.

Raises:
Returns:

The decoded object (dict) via

mokr.execution.JavascriptHandle.json or None if a known error occurs decoding it.

Return type:

dict | None

async evaluate_handle(page_function: str, *args: Any, force_expr: bool = False, eval_script_url_suffix: str | None = None) → mokr.execution.handle.javascript.JavascriptHandle

Execute a JavaScript function with given arguments.

Parameters:

page_function (str) – JavaScript function to run.

Raises:

ElementHandleError – Raised if execution fails.

Returns:

mokr.execution.JavascriptHandle.

Return type:

JavascriptHandle

async query_objects(javascript_handle: mokr.execution.handle.javascript.JavascriptHandle) → mokr.execution.handle.javascript.JavascriptHandle

Query all objects with the given mokr.execution.JavascriptHandle’s get_property("objectId").

Parameters:

javascript_handle (JavascriptHandle) – A valid (not disposed) mokr.execution.JavascriptHandle object.

Raises:

ElementHandleError – Raised if the given handle is disposed, or does not have an “objectId” remote property (primitive type).

Returns:

A mokr.execution.JavascriptHandle initialised

from the remot response.

Return type:

JavascriptHandle

class mokr.execution.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

class mokr.execution.JavascriptHandle(context: mokr.execution.context.ExecutionContext, client: mokr.connection.DevtoolsConnection, remote_object: dict)

Representative of a JavaScript object within the frame. JavascriptHandles are created automatically by mokr.frame.FrameManager and mokr.browser.WebWorker.

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.

property execution_context: mokr.execution.context.ExecutionContext

Get mokr.execution.ExecutionContext of this handle.

async get_property(property_name: str) → JavascriptHandle

Get a property of the remote object related to this handle.

Parameters:

property_name (str) – Name of the target property.

Returns:

Newly created JavascriptHandle from the result.

Return type:

JavascriptHandle

async get_properties() → dict[str, JavascriptHandle]

Get all properties of the remote object related to this handle.

Returns:

Dictionary keyed as “property name” to

newly created `JavascriptHandle`s from the results.

Return type:

dict[str, JavascriptHandle]

async json() → dict

Get and JSONify the values of the remote object this handle represents.

Returns:

Dictionary of JSONified values.

Return type:

dict

async dispose() → None

Stop referencing this handle. Allows it to be garbage-collected by the browser.

to_string() → str

Get a string representation of the remote object this represents.

Returns:

String representation of remote object. May contain

object data or just the type.

Return type:

str