mokr.frame

Submodules

• mokr.frame.frame
• mokr.frame.manager
• mokr.frame.wait

Classes

Frame	Representative of a frame within a page, spawned from a
FrameManager	This class is an assistant class that helps with mokr.frame.Frame
WaitTask	Class used to monitor a remote frame for events to occur within

Package Contents

class mokr.frame.Frame(client: mokr.connection.DevtoolsConnection, parent_frame: Frame | None, frame_id: str)

Representative of a frame within a page, spawned from a mokr.frame.FrameManager in a mokr.browser.Page.

Parameters:

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

• parent_frame (Frame | None) – Parent Frame in tree, if any.

• frame_id (str) – Unique remote identifier.

property name: str

Get the name of the remote frame.

property url: str

The URL for the remote frame.

property parent_frame: Frame | None

The parent Frame in the tree. If the remote frame is the top or is detached, will return None.

property child_frames: list[Frame]

A list of all child `Frame`s in the tree.

property is_detached: bool

True if remote frame is detached to the page, otherwise False.

async execution_context() → mokr.execution.context.ExecutionContext | None

Return the newly created mokr.execution.ExecutionContext. Created by mokr.frame.FrameManager.

Returns:

mokr.execution.ExecutionContext.

Return type:

ExecutionContext

async evaluate_handle(page_function: str, *args: Any) → mokr.execution.context.JavascriptHandle

Execute a JavaScript function with given arguments. Runs this Frame’s mokr.execution.ExecutionContext.evaluate_handle.

Parameters:

page_function (str) – JavaScript function to run.

Returns:

mokr.execution.JavascriptHandle.

Return type:

JavascriptHandle

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

Execute a JavaScript function with given arguments. Runs this Frame’s mokr.execution.ExecutionContext.evaluate.

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:

• mokr.exceptions.NetworkError –

• either evaluating the function or requesting the resulting object. –

Returns:

The decoded object (dict) via

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

Return type:

dict | None

async query_selector(selector: str) → mokr.execution.handle.element.ElementHandle | None

Return the first element in the DOM 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[mokr.execution.handle.element.ElementHandle]

Return all elements in the DOM 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[mokr.execution.handle.element.ElementHandle]

Return all elements in the DOM 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 content() → str

Get encoded string representation of HTML in this Frame.

Returns:

HTML content.

Return type:

str

async set_content(html: str) → None

Set the value of the HTML on this Frame.

This does not change the value of the “document” request’s response, it only changes what is shown in the window.

Response values can be changed by intercepting requests or responses, see Page.on for more.

Parameters:

html (str) – HTML content to set to.

async embed_javascript(file_content: str = None, file_path: str = None, url: str = None, script_type: str = None) → mokr.execution.handle.element.ElementHandle

Add script tag to this Frame.

Parameters:

• file_content (str, optional) – Encoded file content for script to embed. If not given, must give file_path or url. Defaults to None.

• file_path (str, optional) – File path for script to embed. If not given, must give file_content or url. Defaults to None.

• url (str, optional) – URL for script to embed. If not given, must give file_content or file_path. Defaults to None.

• script_type (str, optional) – Use “module” to load as JavaScript ES6 module, if not given, defaults to “text/javascript”. Defaults to None.

Raises:

• ValueError – Raised if none of file_content, file_path, or url are given.

• PageError – Raised if error occurs sending embed request to remote connection (from ElementHandleError).

Returns:

Newly embedded element.

Return type:

ElementHandle

async embed_style(file_content: str = None, file_path: str = None, url: str = None) → mokr.execution.handle.element.ElementHandle

Add style tag to this Frame.

Parameters:

• file_content (str, optional) – Encoded file content for style to embed. If not given, must give file_path or url. Defaults to None.

• file_path (str, optional) – File path for style to embed. If not given, must give file_content or url. Defaults to None.

• url (str, optional) – URL for style to embed. If not given, must give file_content or file_path. Defaults to None.

Raises:

• ValueError – Raised if none of file_content, file_path, or url are given.

• PageError – Raised if error occurs sending embed request to remote connection (from ElementHandleError).

Returns:

Newly embedded element.

Return type:

ElementHandle

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

Click the first element that matches selector.

This method is a shortcut for running Frame.query_selector and then running mokr.execution.ElementHandle.click on the resultant ElementHandle. In either case, an element will be scrolled into view if needed, and the center of it clicked with the ElementHandle’s bound Page.mouse.

Parameters:

• selector (str) – Selector to query element by.

• 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:

PageError – Raised if no element is found with given selector.

async focus(selector: str) → None

Focus on the first element that matches selector.

Raises:

PageError – Raised if no element is found with given selector.

Parameters:

selector (str) – Selector to query element by.

async hover(selector: str) → None

Mouse hover over the first element that matches selector.

Raises:

PageError – Raised if no element is found with given selector.

Parameters:

selector (str) – Selector to query element by.

async select(selector: str, values: list[str]) → list[str]

Select options on a “select” element.

Parameters:

• selector (str) – Selector to query element by.

• values (list[str]) – List of string options to select by.

Returns:

List of selected values.

Return type:

list[str]

async tap(selector: str) → None

Tap the first element that matches selector.

This method is a shortcut for running Frame.query_selector and then running mokr.execution.ElementHandle.tap on the resultant ElementHandle. In either case, an element will be scrolled into view if needed, and the center of it clicked with the ElementHandle’s bound Page.touchscreen.

Parameters:

selector (str) – Selector to query element by.

Raises:

PageError – Raised if no element is found with given selector.

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

Focus on the first element that matches selector and type characters into it. Uses the newly created ElementHandle’s bound Page.keyboard.

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

Raises:

PageError – Raised if no element is found with given selector.

Parameters:

• selector (str) – Selector to query element by.

• text (str) – Text to type.

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

wait_for_timeout(timeout: int | float) → Awaitable[None]

Wait for the given amount of time. Same as asyncio.sleep.

Parameters:

timeout (int | float) – Time in milliseconds to wait.

Returns:

Task to be awaited.

Return type:

Awaitable[None]

wait_for_selector(selector: str, visible: bool = False, hidden: bool = False, timeout: int = 30000) → mokr.frame.wait.WaitTask

Wait for element that matches selector to appear in DOM. If element is in DOM already when called, return immediately.

Parameters:

• selector (str) – Selector to query element by.

• visible (bool, optional) – Element must also not be hidden. Defaults to False.

• hidden (bool, optional) – Element must also be hidden. Defaults to False.

• timeout (int, optional) – Time in milliseconds to wait. Defaults to 30000.

Raises:

MokrTimeoutError – Raised if timeout exceeded before element found.

Returns:

None.

Return type:

Awaitable[JavascriptHandle]

wait_for_xpath(xpath: str, visible: bool = False, hidden: bool = False, timeout: int = 30000) → mokr.frame.wait.WaitTask

Wait for element that matches xpath expression to appear in DOM. If element is in DOM already when called, return immediately.

Parameters:

• xpath (str) – Expression to query element by.

• visible (bool, optional) – Element must also not be hidden. Defaults to False.

• hidden (bool, optional) – Element must also be hidden. Defaults to False.

• timeout (int, optional) – Time in milliseconds to wait. Defaults to 30000.

Raises:

MokrTimeoutError – Raised if timeout exceeded before element found.

Returns:

None.

Return type:

Awaitable[JavascriptHandle]

wait_for_function(page_function: str, polling: Literal['raf', 'mutation'] | int | float, timeout: int = 30000) → Awaitable[mokr.execution.context.JavascriptHandle]

Wait until the given page_function returns a truthy value.

Parameters:

• page_function (str) – JavaScript function to run.

• polling (Literal["raf", "mutation"] | int | float, optional) – Polling type; if set to “raf”, executes continously in “requestAnimationFrame”, else if set to “mutation” executes only on DOM mutations. Defaults to “raf”.

• timeout (int, optional) – Time in milliseconds to wait. Defaults to 30000.

Returns:

JavascriptHandle from JavaScript

page_function successful result.

Return type:

Awaitable[JavascriptHandle]

async title() → str

Get the document title.

Returns:

Document title.

Return type:

str

class mokr.frame.FrameManager(client: mokr.connection.DevtoolsConnection, frame_tree: dict, page: mokr.browser.page.Page)

Bases: pyee.EventEmitter

This class is an assistant class that helps with mokr.frame.Frame management by creating them and by managing `mokr.execution.ExecutionContext`s.

Parameters:

• client (DevtoolsConnection) – mokr.execution.ExecutionContext of the mokr.browser.Page that spawned this.

• frame_tree (dict) – A representation of the hierarchy of remote frames on a page.

• page (Page) – The spawning mokr.browser.Page object.

property main_frame: mokr.frame.frame.Frame | None

The main remote frame (top of the frame tree).

frames() → list[mokr.frame.frame.Frame]

A list of all mokr.frame.Frame objects under this manager.

Returns:

All `mokr.frame.Frame`s controlled by this class.

Return type:

list[Frame]

frame(frame_id: str) → mokr.frame.frame.Frame | None

Return a frame with the given frame_id, if any.

Parameters:

frame_id (str) – Remote frame identifier.

Returns:

mokr.frame.Frame, if any match given frame_id.

Return type:

Frame | None

execution_context_by_id(context_id: str) → mokr.execution.context.ExecutionContext

Get a mokr.execution.ExecutionContext under this manager.

Parameters:

context_id (str) – Target context identifier.

Raises:

ElementHandleError – Raised if no context matches context_id.

Returns:

mokr.execution.ExecutionContext created

by this FrameManager with given context_id.

Return type:

ExecutionContext

create_javascript_handle(context: mokr.execution.context.ExecutionContext, remote_object: dict = None) → mokr.execution.context.JavascriptHandle

Create a mokr.execution.JavascriptHandle for given context.

Parameters:

• context (ExecutionContext) – mokr.execution.ExecutionContext to pass into initialisation.

• remote_object (dict, optional) – Remote object to be represented by new mokr.execution.JavascriptHandle. Defaults to None.

Returns:

_description_

Return type:

JavascriptHandle

class mokr.frame.WaitTask(frame: mokr.frame.frame.Frame, predicate_body: str, title: str, polling: Literal['raf', 'mutation'] | int | float, timeout: float, loop: asyncio.AbstractEventLoop, *args: Any)

Class used to monitor a remote frame for events to occur within a given timer interval.

Parameters:

• frame (Frame) – mokr.frame.Frame that spawned this WaitTask.

• predicate_body (str) – JavaScript function to return from.

• title (str) – Title to be used to contextualise error, if any.

• polling (Literal["raf", "mutation"] | int | float) – Polling type; if set to “raf”, executes continously in “requestAnimationFrame”, else if set to “mutation” executes only on DOM mutations. Defaults to “raf”.

• timeout (float) – Time in milliseconds to wait.

• loop (asyncio.AbstractEventLoop) – Running asyncio loop.

Raises:

ValueError – Raised if polling_type not “raf” or “mutation”.

promise

terminate(error: Exception) → None

Finish the task, if the promise is still not done, set the result with the given error, then remove this task from the parent mokr.frame.Frame.

Parameters:

error (Exception) – Error to raise if watched promise isn’t done.

async rerun() → None

Start polling for the expected condition.

Raises:

PageError – Raised if no mokr.execution.ExecutionContext attached to the parent mokr.frame.Frame.