mokr.frame.frame

Attributes

LOGGER

Classes

Frame

Representative of a frame within a page, spawned from a

Module Contents

mokr.frame.frame.LOGGER
class mokr.frame.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:
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