mokr.frame ========== .. py:module:: mokr.frame Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/mokr/frame/frame/index /autoapi/mokr/frame/manager/index /autoapi/mokr/frame/wait/index Classes ------- .. autoapisummary:: mokr.frame.Frame mokr.frame.FrameManager mokr.frame.WaitTask Package Contents ---------------- .. py:class:: 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`. :param client: `mokr.execution.ExecutionContext` of the `mokr.frame.FrameManager` that spawned this. :type client: DevtoolsConnection :param parent_frame: Parent `Frame` in tree, if any. :type parent_frame: Frame | None :param frame_id: Unique remote identifier. :type frame_id: str .. py:property:: name :type: str Get the name of the remote frame. .. py:property:: url :type: str The URL for the remote frame. .. py:property:: parent_frame :type: Frame | None The parent `Frame` in the tree. If the remote frame is the top or is detached, will return None. .. py:property:: child_frames :type: list[Frame] A list of all child `Frame`s in the tree. .. py:property:: is_detached :type: bool True if remote frame is detached to the page, otherwise False. .. py:method:: execution_context() -> mokr.execution.context.ExecutionContext | None :async: Return the newly created `mokr.execution.ExecutionContext`. Created by `mokr.frame.FrameManager`. :returns: `mokr.execution.ExecutionContext`. :rtype: ExecutionContext .. py:method:: evaluate_handle(page_function: str, *args: Any) -> mokr.execution.context.JavascriptHandle :async: Execute a JavaScript function with given arguments. Runs this `Frame`'s `mokr.execution.ExecutionContext.evaluate_handle`. :param page_function: JavaScript function to run. :type page_function: str :returns: `mokr.execution.JavascriptHandle`. :rtype: JavascriptHandle .. py:method:: evaluate(page_function: str, *args: Any, force_expr: bool = False) -> Any :async: Execute a JavaScript function with given arguments. Runs this `Frame`'s `mokr.execution.ExecutionContext.evaluate`. :param page_function: JavaScript function to run. :type page_function: str :param force_expr: If True, treat `page_function` as an expression. Otherwise, automatically determine if it is a function or an expression. Defaults to False. :type force_expr: bool :raises mokr.exceptions.NetworkError: :raises 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. :rtype: dict | None .. py:method:: query_selector(selector: str) -> mokr.execution.handle.element.ElementHandle | None :async: Return the first element in the DOM 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[mokr.execution.handle.element.ElementHandle] :async: Return all elements in the DOM 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[mokr.execution.handle.element.ElementHandle] :async: Return all elements in the DOM 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:: content() -> str :async: Get encoded string representation of HTML in this `Frame`. :returns: HTML content. :rtype: str .. py:method:: set_content(html: str) -> None :async: 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. :param html: HTML content to set to. :type html: str .. py:method:: embed_javascript(file_content: str = None, file_path: str = None, url: str = None, script_type: str = None) -> mokr.execution.handle.element.ElementHandle :async: Add script tag to this `Frame`. :param file_content: Encoded file content for script to embed. If not given, must give `file_path` or `url`. Defaults to None. :type file_content: str, optional :param file_path: File path for script to embed. If not given, must give `file_content` or `url`. Defaults to None. :type file_path: str, optional :param url: URL for script to embed. If not given, must give `file_content` or `file_path`. Defaults to None. :type url: str, optional :param script_type: Use "module" to load as JavaScript ES6 module, if not given, defaults to "text/javascript". Defaults to None. :type script_type: str, optional :raises ValueError: Raised if none of `file_content`, `file_path`, or `url` are given. :raises PageError: Raised if error occurs sending embed request to remote connection (from ElementHandleError). :returns: Newly embedded element. :rtype: ElementHandle .. py:method:: embed_style(file_content: str = None, file_path: str = None, url: str = None) -> mokr.execution.handle.element.ElementHandle :async: Add style tag to this `Frame`. :param file_content: Encoded file content for style to embed. If not given, must give `file_path` or `url`. Defaults to None. :type file_content: str, optional :param file_path: File path for style to embed. If not given, must give `file_content` or `url`. Defaults to None. :type file_path: str, optional :param url: URL for style to embed. If not given, must give `file_content` or `file_path`. Defaults to None. :type url: str, optional :raises ValueError: Raised if none of `file_content`, `file_path`, or `url` are given. :raises PageError: Raised if error occurs sending embed request to remote connection (from ElementHandleError). :returns: Newly embedded element. :rtype: ElementHandle .. py:method:: click(selector: str, button: Literal['left', 'right', 'middle'] = 'left', click_count: int = 1, delay: int | float | None = 1000) -> None :async: 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`. :param selector: Selector to query element by. :type selector: str :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 PageError: Raised if no element is found with given `selector`. .. py:method:: focus(selector: str) -> None :async: Focus on the first element that matches `selector`. :raises PageError: Raised if no element is found with given `selector`. :param selector: Selector to query element by. :type selector: str .. py:method:: hover(selector: str) -> None :async: Mouse hover over the first element that matches `selector`. :raises PageError: Raised if no element is found with given `selector`. :param selector: Selector to query element by. :type selector: str .. py:method:: select(selector: str, values: list[str]) -> list[str] :async: Select options on a "select" element. :param selector: Selector to query element by. :type selector: str :param values: List of string options to select by. :type values: list[str] :returns: List of selected values. :rtype: list[str] .. py:method:: tap(selector: str) -> None :async: 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`. :param selector: Selector to query element by. :type selector: str :raises PageError: Raised if no element is found with given `selector`. .. py:method:: type_text(selector: str, text: str, delay: int | float = 0) -> None :async: 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`. :param selector: Selector to query element by. :type selector: str :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:: wait_for_timeout(timeout: int | float) -> Awaitable[None] Wait for the given amount of time. Same as `asyncio.sleep`. :param timeout: Time in milliseconds to wait. :type timeout: int | float :returns: Task to be awaited. :rtype: Awaitable[None] .. py:method:: 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. :param selector: Selector to query element by. :type selector: str :param visible: Element must also not be hidden. Defaults to False. :type visible: bool, optional :param hidden: Element must also be hidden. Defaults to False. :type hidden: bool, optional :param timeout: Time in milliseconds to wait. Defaults to 30000. :type timeout: int, optional :raises MokrTimeoutError: Raised if timeout exceeded before element found. :returns: None. :rtype: Awaitable[JavascriptHandle] .. py:method:: 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. :param xpath: Expression to query element by. :type xpath: str :param visible: Element must also not be hidden. Defaults to False. :type visible: bool, optional :param hidden: Element must also be hidden. Defaults to False. :type hidden: bool, optional :param timeout: Time in milliseconds to wait. Defaults to 30000. :type timeout: int, optional :raises MokrTimeoutError: Raised if timeout exceeded before element found. :returns: None. :rtype: Awaitable[JavascriptHandle] .. py:method:: 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. :param page_function: JavaScript function to run. :type page_function: str :param polling: Polling type; if set to "raf", executes continously in "requestAnimationFrame", else if set to "mutation" executes only on DOM mutations. Defaults to "raf". :type polling: Literal["raf", "mutation"] | int | float, optional :param timeout: Time in milliseconds to wait. Defaults to 30000. :type timeout: int, optional :returns: JavascriptHandle from JavaScript `page_function` successful result. :rtype: Awaitable[JavascriptHandle] .. py:method:: title() -> str :async: Get the document title. :returns: Document title. :rtype: str .. py:class:: FrameManager(client: mokr.connection.DevtoolsConnection, frame_tree: dict, page: mokr.browser.page.Page) Bases: :py:obj:`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. :param client: `mokr.execution.ExecutionContext` of the `mokr.browser.Page` that spawned this. :type client: DevtoolsConnection :param frame_tree: A representation of the hierarchy of remote frames on a page. :type frame_tree: dict :param page: The spawning `mokr.browser.Page` object. :type page: Page .. py:property:: main_frame :type: mokr.frame.frame.Frame | None The main remote frame (top of the frame tree). .. py:method:: 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. :rtype: list[Frame] .. py:method:: frame(frame_id: str) -> mokr.frame.frame.Frame | None Return a frame with the given `frame_id`, if any. :param frame_id: Remote frame identifier. :type frame_id: str :returns: `mokr.frame.Frame`, if any match given `frame_id`. :rtype: Frame | None .. py:method:: execution_context_by_id(context_id: str) -> mokr.execution.context.ExecutionContext Get a `mokr.execution.ExecutionContext` under this manager. :param context_id: Target context identifier. :type context_id: str :raises ElementHandleError: Raised if no context matches `context_id`. :returns: `mokr.execution.ExecutionContext` created by this `FrameManager` with given `context_id`. :rtype: ExecutionContext .. py:method:: create_javascript_handle(context: mokr.execution.context.ExecutionContext, remote_object: dict = None) -> mokr.execution.context.JavascriptHandle Create a `mokr.execution.JavascriptHandle` for given context. :param context: `mokr.execution.ExecutionContext` to pass into initialisation. :type context: ExecutionContext :param remote_object: Remote object to be represented by new `mokr.execution.JavascriptHandle`. Defaults to None. :type remote_object: dict, optional :returns: _description_ :rtype: JavascriptHandle .. py:class:: 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. :param frame: `mokr.frame.Frame` that spawned this `WaitTask`. :type frame: Frame :param predicate_body: JavaScript function to return from. :type predicate_body: str :param title: Title to be used to contextualise error, if any. :type title: str :param polling: Polling type; if set to "raf", executes continously in "requestAnimationFrame", else if set to "mutation" executes only on DOM mutations. Defaults to "raf". :type polling: Literal["raf", "mutation"] | int | float :param timeout: Time in milliseconds to wait. :type timeout: float :param loop: Running asyncio loop. :type loop: asyncio.AbstractEventLoop :raises ValueError: Raised if `polling_type` not "raf" or "mutation". .. py:attribute:: promise .. py:method:: 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`. :param error: Error to raise if watched promise isn't done. :type error: Exception .. py:method:: rerun() -> None :async: Start polling for the expected condition. :raises PageError: Raised if no `mokr.execution.ExecutionContext` attached to the parent `mokr.frame.Frame`.