async_api.py

# Copyright (c) Microsoft Corporation.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.


import pathlib
import sys
import typing

if sys.version_info >= (3, 8):  # pragma: no cover
    from typing import Literal
else:  # pragma: no cover
    from typing_extensions import Literal

from playwright.accessibility import Accessibility as AccessibilityImpl
from playwright.async_base import AsyncBase, AsyncEventContextManager, mapping
from playwright.browser import Browser as BrowserImpl
from playwright.browser_context import BrowserContext as BrowserContextImpl
from playwright.browser_server import BrowserServer as BrowserServerImpl
from playwright.browser_type import BrowserType as BrowserTypeImpl
from playwright.cdp_session import CDPSession as CDPSessionImpl
from playwright.chromium_browser_context import (
    ChromiumBrowserContext as ChromiumBrowserContextImpl,
)
from playwright.console_message import ConsoleMessage as ConsoleMessageImpl
from playwright.dialog import Dialog as DialogImpl
from playwright.download import Download as DownloadImpl
from playwright.element_handle import ElementHandle as ElementHandleImpl
from playwright.file_chooser import FileChooser as FileChooserImpl
from playwright.frame import Frame as FrameImpl
from playwright.helper import (
    ConsoleMessageLocation,
    Credentials,
    DeviceDescriptor,
    Error,
    FilePayload,
    FloatRect,
    Geolocation,
    IntSize,
    MousePosition,
    PdfMargins,
    ProxyServer,
    RequestFailure,
    SelectOption,
    Viewport,
)
from playwright.input import Keyboard as KeyboardImpl
from playwright.input import Mouse as MouseImpl
from playwright.js_handle import JSHandle as JSHandleImpl
from playwright.network import Request as RequestImpl
from playwright.network import Response as ResponseImpl
from playwright.network import Route as RouteImpl
from playwright.page import BindingCall as BindingCallImpl
from playwright.page import Page as PageImpl
from playwright.page import Worker as WorkerImpl
from playwright.playwright import Playwright as PlaywrightImpl
from playwright.selectors import Selectors as SelectorsImpl

NoneType = type(None)


class Request(AsyncBase):
    def __init__(self, obj: RequestImpl):
        super().__init__(obj)

    @property
    def url(self) -> str:
        """Request.url

        Returns
        -------
        str
            URL of the request.
        """
        return mapping.from_maybe_impl(self._impl_obj.url)

    @property
    def resourceType(self) -> str:
        """Request.resourceType

        Contains the request's resource type as it was perceived by the rendering engine.
        ResourceType will be one of the following: `document`, `stylesheet`, `image`, `media`, `font`, `script`, `texttrack`, `xhr`, `fetch`, `eventsource`, `websocket`, `manifest`, `other`.

        Returns
        -------
        str
        """
        return mapping.from_maybe_impl(self._impl_obj.resourceType)

    @property
    def method(self) -> str:
        """Request.method

        Returns
        -------
        str
            Request's method (GET, POST, etc.)
        """
        return mapping.from_maybe_impl(self._impl_obj.method)

    @property
    def postData(self) -> typing.Union[str, NoneType]:
        """Request.postData

        Returns
        -------
        Optional[str]
            Request's post body, if any.
        """
        return mapping.from_maybe_impl(self._impl_obj.postData)

    @property
    def postDataJSON(self) -> typing.Union[typing.Dict, NoneType]:
        """Request.postDataJSON

        When the response is `application/x-www-form-urlencoded` then a key/value object of the values will be returned. Otherwise it will be parsed as JSON.

        Returns
        -------
        Optional[Dict]
            Parsed request's body for `form-urlencoded` and JSON as a fallback if any.
        """
        return mapping.from_maybe_impl(self._impl_obj.postDataJSON)

    @property
    def postDataBuffer(self) -> typing.Union[bytes, NoneType]:
        """Request.postDataBuffer

        Returns
        -------
        Optional[bytes]
            Request's post body in a binary form, if any.
        """
        return mapping.from_maybe_impl(self._impl_obj.postDataBuffer)

    @property
    def headers(self) -> typing.Dict[str, str]:
        """Request.headers

        Returns
        -------
        Dict[str, str]
            An object with HTTP headers associated with the request. All header names are lower-case.
        """
        return mapping.from_maybe_impl(self._impl_obj.headers)

    @property
    def frame(self) -> "Frame":
        """Request.frame

        Returns
        -------
        Frame
            A Frame that initiated this request.
        """
        return mapping.from_impl(self._impl_obj.frame)

    @property
    def redirectedFrom(self) -> typing.Union["Request", NoneType]:
        """Request.redirectedFrom

        When the server responds with a redirect, Playwright creates a new Request object. The two requests are connected by `redirectedFrom()` and `redirectedTo()` methods. When multiple server redirects has happened, it is possible to construct the whole redirect chain by repeatedly calling `redirectedFrom()`.
        For example, if the website `http://example.com` redirects to `https://example.com`:
        If the website `https://google.com` has no redirects:

        Returns
        -------
        Optional[Request]
            Request that was redirected by the server to this one, if any.
        """
        return mapping.from_impl_nullable(self._impl_obj.redirectedFrom)

    @property
    def redirectedTo(self) -> typing.Union["Request", NoneType]:
        """Request.redirectedTo

        This method is the opposite of request.redirectedFrom():

        Returns
        -------
        Optional[Request]
            New request issued by the browser if the server responded with redirect.
        """
        return mapping.from_impl_nullable(self._impl_obj.redirectedTo)

    @property
    def failure(self) -> typing.Union[RequestFailure, NoneType]:
        """Request.failure

        The method returns `null` unless this request has failed, as reported by
        `requestfailed` event.
        Example of logging of all the failed requests:

        Returns
        -------
        Optional[{"errorText": str}]
            Object describing request failure, if any
        """
        return mapping.from_maybe_impl(self._impl_obj.failure)

    async def response(self) -> typing.Union["Response", NoneType]:
        """Request.response

        Returns
        -------
        Optional[Response]
            A matching Response object, or `null` if the response was not received due to error.
        """
        return mapping.from_impl_nullable(await self._impl_obj.response())

    def isNavigationRequest(self) -> bool:
        """Request.isNavigationRequest

        Whether this request is driving frame's navigation.

        Returns
        -------
        bool
        """
        return mapping.from_maybe_impl(self._impl_obj.isNavigationRequest())


mapping.register(RequestImpl, Request)


class Response(AsyncBase):
    def __init__(self, obj: ResponseImpl):
        super().__init__(obj)

    @property
    def url(self) -> str:
        """Response.url

        Contains the URL of the response.

        Returns
        -------
        str
        """
        return mapping.from_maybe_impl(self._impl_obj.url)

    @property
    def ok(self) -> bool:
        """Response.ok

        Contains a boolean stating whether the response was successful (status in the range 200-299) or not.

        Returns
        -------
        bool
        """
        return mapping.from_maybe_impl(self._impl_obj.ok)

    @property
    def status(self) -> int:
        """Response.status

        Contains the status code of the response (e.g., 200 for a success).

        Returns
        -------
        int
        """
        return mapping.from_maybe_impl(self._impl_obj.status)

    @property
    def statusText(self) -> str:
        """Response.statusText

        Contains the status text of the response (e.g. usually an "OK" for a success).

        Returns
        -------
        str
        """
        return mapping.from_maybe_impl(self._impl_obj.statusText)

    @property
    def headers(self) -> typing.Dict[str, str]:
        """Response.headers

        Returns
        -------
        Dict[str, str]
            An object with HTTP headers associated with the response. All header names are lower-case.
        """
        return mapping.from_maybe_impl(self._impl_obj.headers)

    @property
    def request(self) -> "Request":
        """Response.request

        Returns
        -------
        Request
            A matching Request object.
        """
        return mapping.from_impl(self._impl_obj.request)

    @property
    def frame(self) -> "Frame":
        """Response.frame

        Returns
        -------
        Frame
            A Frame that initiated this response.
        """
        return mapping.from_impl(self._impl_obj.frame)

    async def finished(self) -> typing.Union[Error, NoneType]:
        """Response.finished

        Returns
        -------
        Optional[Error]
            Waits for this response to finish, returns failure error if request failed.
        """
        return mapping.from_maybe_impl(await self._impl_obj.finished())

    async def body(self) -> bytes:
        """Response.body

        Returns
        -------
        bytes
            Promise which resolves to a buffer with response body.
        """
        return mapping.from_maybe_impl(await self._impl_obj.body())

    async def text(self) -> str:
        """Response.text

        Returns
        -------
        str
            Promise which resolves to a text representation of response body.
        """
        return mapping.from_maybe_impl(await self._impl_obj.text())

    async def json(self) -> typing.Union[typing.Dict, typing.List]:
        """Response.json

        This method will throw if the response body is not parsable via `JSON.parse`.

        Returns
        -------
        Union[Dict, List]
            Promise which resolves to a JSON representation of response body.
        """
        return mapping.from_maybe_impl(await self._impl_obj.json())


mapping.register(ResponseImpl, Response)


class Route(AsyncBase):
    def __init__(self, obj: RouteImpl):
        super().__init__(obj)

    @property
    def request(self) -> "Request":
        """Route.request

        Returns
        -------
        Request
            A request to be routed.
        """
        return mapping.from_impl(self._impl_obj.request)

    async def abort(self, errorCode: str = None) -> NoneType:
        """Route.abort

        Aborts the route's request.

        Parameters
        ----------
        errorCode : Optional[str]
            Optional error code. Defaults to `failed`, could be
            one of the following:
             - `'aborted'` - An operation was aborted (due to user action)
             - `'accessdenied'` - Permission to access a resource, other than the network, was denied
             - `'addressunreachable'` - The IP address is unreachable. This usually means
             - that there is no route to the specified host or network.
             - `'blockedbyclient'` - The client chose to block the request.
             - `'blockedbyresponse'` - The request failed because the response was delivered along with requirements which are not met ('X-Frame-Options' and 'Content-Security-Policy' ancestor checks, for instance).
             - `'connectionaborted'` - A connection timed out as a result of not receiving an ACK for data sent.
             - `'connectionclosed'` - A connection was closed (corresponding to a TCP FIN).
             - `'connectionfailed'` - A connection attempt failed.
             - `'connectionrefused'` - A connection attempt was refused.
             - `'connectionreset'` - A connection was reset (corresponding to a TCP RST).
             - `'internetdisconnected'` - The Internet connection has been lost.
             - `'namenotresolved'` - The host name could not be resolved.
             - `'timedout'` - An operation timed out.
             - `'failed'` - A generic failure occurred.
        """
        return mapping.from_maybe_impl(await self._impl_obj.abort(errorCode=errorCode))

    async def fulfill(
        self,
        status: int = None,
        headers: typing.Union[typing.Dict[str, str]] = None,
        body: typing.Union[str, bytes] = None,
        path: typing.Union[str, pathlib.Path] = None,
        contentType: str = None,
    ) -> NoneType:
        """Route.fulfill

        Fulfills route's request with given response.
        An example of fulfilling all requests with 404 responses:
        An example of serving static file:

        Parameters
        ----------
        status : Optional[int]
            Response status code, defaults to `200`.
        headers : Optional[Dict[str, str]]
            Optional response headers. Header values will be converted to a string.
        body : Union[str, bytes, NoneType]
            Optional response body.
        path : Union[str, pathlib.Path, NoneType]
            Optional file path to respond with. The content type will be inferred from file extension. If `path` is a relative path, then it is resolved relative to current working directory.
        contentType : Optional[str]
            If set, equals to setting `Content-Type` response header.
        """
        return mapping.from_maybe_impl(
            await self._impl_obj.fulfill(
                status=status,
                headers=mapping.to_impl(headers),
                body=body,
                path=path,
                contentType=contentType,
            )
        )

    async def continue_(
        self,
        method: str = None,
        headers: typing.Union[typing.Dict[str, str]] = None,
        postData: typing.Union[str, bytes] = None,
    ) -> NoneType:
        """Route.continue_

        Continues route's request with optional overrides.

        Parameters
        ----------
        method : Optional[str]
            If set changes the request method (e.g. GET or POST)
        headers : Optional[Dict[str, str]]
            If set changes the request HTTP headers. Header values will be converted to a string.
        postData : Union[str, bytes, NoneType]
            If set changes the post data of request
        """
        return mapping.from_maybe_impl(
            await self._impl_obj.continue_(
                method=method, headers=mapping.to_impl(headers), postData=postData
            )
        )


mapping.register(RouteImpl, Route)


class Keyboard(AsyncBase):
    def __init__(self, obj: KeyboardImpl):
        super().__init__(obj)

    async def down(self, key: str) -> NoneType:
        """Keyboard.down

        Dispatches a `keydown` event.
        `key` can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the `key` values can be found here. Examples of the keys are:
        `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
        Following modification shortcuts are also suported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
        Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
        If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different respective texts.
        If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`, subsequent key presses will be sent with that modifier active. To release the modifier key, use `keyboard.up`.
        After the key is pressed once, subsequent calls to `keyboard.down` will have repeat set to true. To release the key, use `keyboard.up`.

        **NOTE** Modifier keys DO influence `keyboard.down`. Holding down `Shift` will type the text in upper case.

        Parameters
        ----------
        key : str
            Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
        """
        return mapping.from_maybe_impl(await self._impl_obj.down(key=key))

    async def up(self, key: str) -> NoneType:
        """Keyboard.up

        Dispatches a `keyup` event.

        Parameters
        ----------
        key : str
            Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
        """
        return mapping.from_maybe_impl(await self._impl_obj.up(key=key))

    async def insertText(self, text: str) -> NoneType:
        """Keyboard.insertText

        Dispatches only `input` event, does not emit the `keydown`, `keyup` or `keypress` events.

        **NOTE** Modifier keys DO NOT effect `keyboard.insertText`. Holding down `Shift` will not type the text in upper case.

        Parameters
        ----------
        text : str
            Sets input to the specified text value.
        """
        return mapping.from_maybe_impl(await self._impl_obj.insertText(text=text))

    async def type(self, text: str, delay: int = None) -> NoneType:
        """Keyboard.type

        Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text.
        To press a special key, like `Control` or `ArrowDown`, use `keyboard.press`.

        **NOTE** Modifier keys DO NOT effect `keyboard.type`. Holding down `Shift` will not type the text in upper case.

        Parameters
        ----------
        text : str
            A text to type into a focused element.
        delay : Optional[int]
            Time to wait between key presses in milliseconds. Defaults to 0.
        """
        return mapping.from_maybe_impl(
            await self._impl_obj.type(text=text, delay=delay)
        )

    async def press(self, key: str, delay: int = None) -> NoneType:
        """Keyboard.press

        `key` can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the `key` values can be found here. Examples of the keys are:
        `F1` - `F12`, `Digit0`- `Digit9`, `KeyA`- `KeyZ`, `Backquote`, `Minus`, `Equal`, `Backslash`, `Backspace`, `Tab`, `Delete`, `Escape`, `ArrowDown`, `End`, `Enter`, `Home`, `Insert`, `PageDown`, `PageUp`, `ArrowRight`, `ArrowUp`, etc.
        Following modification shortcuts are also suported: `Shift`, `Control`, `Alt`, `Meta`, `ShiftLeft`.
        Holding down `Shift` will type the text that corresponds to the `key` in the upper case.
        If `key` is a single character, it is case-sensitive, so the values `a` and `A` will generate different respective texts.
        Shortcuts such as `key: "Control+o"` or `key: "Control+Shift+T"` are supported as well. When speficied with the modifier, modifier is pressed and being held while the subsequent key is being pressed.
        Shortcut for `keyboard.down` and `keyboard.up`.

        Parameters
        ----------
        key : str
            Name of the key to press or a character to generate, such as `ArrowLeft` or `a`.
        delay : Optional[int]
            Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
        """
        return mapping.from_maybe_impl(await self._impl_obj.press(key=key, delay=delay))


mapping.register(KeyboardImpl, Keyboard)


class Mouse(AsyncBase):
    def __init__(self, obj: MouseImpl):
        super().__init__(obj)

    async def move(self, x: float, y: float, steps: int = None) -> NoneType:
        """Mouse.move

        Dispatches a `mousemove` event.

        Parameters
        ----------
        x : float
        y : float
        steps : Optional[int]
            defaults to 1. Sends intermediate `mousemove` events.
        """
        return mapping.from_maybe_impl(await self._impl_obj.move(x=x, y=y, steps=steps))

    async def down(
        self, button: Literal["left", "right", "middle"] = None, clickCount: int = None
    ) -> NoneType:
        """Mouse.down

        Dispatches a `mousedown` event.

        Parameters
        ----------
        button : Optional[Literal['left', 'right', 'middle']]
            Defaults to `left`.
        clickCount : Optional[int]
            defaults to 1. See UIEvent.detail.
        """
        return mapping.from_maybe_impl(
            await self._impl_obj.down(button=button, clickCount=clickCount)
        )

    async def up(
        self, button: Literal["left", "right", "middle"] = None, clickCount: int = None
    ) -> NoneType:
        """Mouse.up

        Dispatches a `mouseup` event.

        Parameters
        ----------
        button : Optional[Literal['left', 'right', 'middle']]
            Defaults to `left`.
        clickCount : Optional[int]
            defaults to 1. See UIEvent.detail.
        """
        return mapping.from_maybe_impl(
            await self._impl_obj.up(button=button, clickCount=clickCount)
        )

    async def click(
        self,
        x: float,
        y: float,
        delay: int = None,
        button: Literal["left", "right", "middle"] = None,
        clickCount: int = None,
    ) -> NoneType:
        """Mouse.click

        Shortcut for `mouse.move`, `mouse.down` and `mouse.up`.

        Parameters
        ----------
        x : float
        y : float
        delay : Optional[int]
            Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
        button : Optional[Literal['left', 'right', 'middle']]
            Defaults to `left`.
        clickCount : Optional[int]
            defaults to 1. See UIEvent.detail.
        """
        return mapping.from_maybe_impl(
            await self._impl_obj.click(
                x=x, y=y, delay=delay, button=button, clickCount=clickCount
            )
        )

    async def dblclick(
        self,
        x: float,
        y: float,
        delay: int = None,
        button: Literal["left", "right", "middle"] = None,
    ) -> NoneType:
        """Mouse.dblclick

        Shortcut for `mouse.move`, `mouse.down`, `mouse.up`, `mouse.down` and `mouse.up`.

        Parameters
        ----------
        x : float
        y : float
        delay : Optional[int]
            Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
        button : Optional[Literal['left', 'right', 'middle']]
            Defaults to `left`.
        """
        return mapping.from_maybe_impl(
            await self._impl_obj.dblclick(x=x, y=y, delay=delay, button=button)
        )


mapping.register(MouseImpl, Mouse)


class JSHandle(AsyncBase):
    def __init__(self, obj: JSHandleImpl):
        super().__init__(obj)

    async def evaluate(
        self, expression: str, arg: typing.Any = None, force_expr: bool = None
    ) -> typing.Any:
        """JSHandle.evaluate

        This method passes this handle as the first argument to `pageFunction`.
        If `pageFunction` returns a Promise, then `handle.evaluate` would wait for the promise to resolve and return its value.
        Examples:

        Parameters
        ----------
        expression : str
            Function to be evaluated in browser context
        force_expr : bool
            Whether to treat given expression as JavaScript evaluate expression, even though it looks like an arrow function
        arg : Optional[Any]
            Optional argument to pass to `pageFunction`

        Returns
        -------
        Any
            Promise which resolves to the return value of `pageFunction`
        """
        return mapping.from_maybe_impl(
            await self._impl_obj.evaluate(
                expression=expression, arg=mapping.to_impl(arg), force_expr=force_expr
            )
        )

    async def evaluateHandle(
        self, expression: str, arg: typing.Any = None, force_expr: bool = None
    ) -> "JSHandle":
        """JSHandle.evaluateHandle

        This method passes this handle as the first argument to `pageFunction`.
        The only difference between `jsHandle.evaluate` and `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle` returns in-page object (JSHandle).
        If the function passed to the `jsHandle.evaluateHandle` returns a Promise, then `jsHandle.evaluateHandle` would wait for the promise to resolve and return its value.
        See page.evaluateHandle() for more details.

        Parameters
        ----------
        expression : str
            Function to be evaluated
        force_expr : bool
            Whether to treat given expression as JavaScript evaluate expression, even though it looks like an arrow function
        arg : Optional[Any]
            Optional argument to pass to `pageFunction`

        Returns
        -------
        JSHandle
            Promise which resolves to the return value of `pageFunction` as in-page object (JSHandle)
        """
        return mapping.from_impl(
            await self._impl_obj.evaluateHandle(
                expression=expression, arg=mapping.to_impl(arg), force_expr=force_expr
            )
        )

    async def getProperty(self, propertyName: str) -> "JSHandle":
        """JSHandle.getProperty

        Fetches a single property from the referenced object.

        Parameters
        ----------
        propertyName : str
            property to get

        Returns
        -------
        JSHandle
        """
        return mapping.from_impl(
            await self._impl_obj.getProperty(propertyName=propertyName)
        )

    async def getProperties(self) -> typing.Dict[str, "JSHandle"]:
        """JSHandle.getProperties

        The method returns a map with **own property names** as keys and JSHandle instances for the property values.

        Returns
        -------
        Dict[str, JSHandle]
        """
        return mapping.from_impl_dict(await self._impl_obj.getProperties())

    def asElement(self) -> typing.Union["ElementHandle", NoneType]:
        """JSHandle.asElement

        Returns either `null` or the object handle itself, if the object handle is an instance of ElementHandle.

        Returns
        -------
        Optional[ElementHandle]
        """
        return mapping.from_impl_nullable(self._impl_obj.asElement())

    async def dispose(self) -> NoneType:
        """JSHandle.dispose

        The `jsHandle.dispose` method stops referencing the element handle.
        """
        return mapping.from_maybe_impl(await self._impl_obj.dispose())

    async def jsonValue(self) -> typing.Any:
        """JSHandle.jsonValue

        Returns a JSON representation of the object. If the object has a
        `toJSON`
        function, it **will not be called**.

        **NOTE** The method will return an empty JSON object if the referenced object is not stringifiable. It will throw an error if the object has circular references.

        Returns
        -------
        Any
        """
        return mapping.from_maybe_impl(await self._impl_obj.jsonValue())


mapping.register(JSHandleImpl, JSHandle)


class ElementHandle(JSHandle):
    def __init__(self, obj: ElementHandleImpl):
        super().__init__(obj)

    def asElement(self) -> typing.Union["ElementHandle", NoneType]:
        """ElementHandle.asElement

        Returns either `null` or the object handle itself, if the object handle is an instance of ElementHandle.

        Returns
        -------
        Optional[ElementHandle]
        """
        return mapping.from_impl_nullable(self._impl_obj.asElement())

    async def ownerFrame(self) -> typing.Union["Frame", NoneType]:
        """ElementHandle.ownerFrame

        Returns
        -------
        Optional[Frame]
            Returns the frame containing the given element.
        """
        return mapping.from_impl_nullable(await self._impl_obj.ownerFrame())

    async def contentFrame(self) -> typing.Union["Frame", NoneType]:
        """ElementHandle.contentFrame

        Returns
        -------
        Optional[Frame]
            Resolves to the content frame for element handles referencing iframe nodes, or `null` otherwise
        """
        return mapping.from_impl_nullable(await self._impl_obj.contentFrame())

    async def getAttribute(self, name: str) -> typing.Union[str, NoneType]:
        """ElementHandle.getAttribute

        Returns element attribute value.

        Parameters
        ----------
        name : str
            Attribute name to get the value for.

        Returns
        -------
        Optional[str]
        """
        return mapping.from_maybe_impl(await self._impl_obj.getAttribute(name=name))

    async def textContent(self) -> typing.Union[str, NoneType]:
        """ElementHandle.textContent

        Returns
        -------
        Optional[str]
            Resolves to the `node.textContent`.
        """
        return mapping.from_maybe_impl(await self._impl_obj.textContent())

    async def innerText(self) -> str:
        """ElementHandle.innerText

        Returns
        -------
        str
            Resolves to the `element.innerText`.
        """
        return mapping.from_maybe_impl(await self._impl_obj.innerText())

    async def innerHTML(self) -> str:
        """ElementHandle.innerHTML

        Returns
        -------
        str
            Resolves to the `element.innerHTML`.
        """
        return mapping.from_maybe_impl(await self._impl_obj.innerHTML())

    async def dispatchEvent(self, type: str, eventInit: typing.Dict = None) -> NoneType:
        """ElementHandle.dispatchEvent

        The snippet below dispatches the `click` event on the element. Regardless of the visibility state of the elment, `click` is dispatched. This is equivalend to calling `element.click()`.
        Under the hood, it creates an instance of an event based on the given `type`, initializes it with `eventInit` properties and dispatches it on the element. Events are `composed`, `cancelable` and bubble by default.
        Since `eventInit` is event-specific, please refer to the events documentation for the lists of initial properties:

        DragEvent
        FocusEvent
        KeyboardEvent
        MouseEvent
        PointerEvent
        TouchEvent
        Event

        You can also specify `JSHandle` as the property value if you want live objects to be passed into the event:

        Parameters
        ----------
        type : str
            DOM event type: `"click"`, `"dragstart"`, etc.
        eventInit : Optional[Dict]
            event-specific initialization properties.
        """
        return mapping.from_maybe_impl(
            await self._impl_obj.dispatchEvent(
                type=type, eventInit=mapping.to_impl(eventInit)
            )
        )

    async def scrollIntoViewIfNeeded(self, timeout: int = None) -> NoneType:
        """ElementHandle.scrollIntoViewIfNeeded

        This method waits for actionability checks, then tries to scroll element into view, unless it is completely visible as defined by IntersectionObserver's `ratio`.
        Throws when `elementHandle` does not point to an element connected to a Document or a ShadowRoot.

        Parameters
        ----------
        timeout : Optional[int]
            Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods.
        """
        return mapping.from_maybe_impl(
            await self._impl_obj.scrollIntoViewIfNeeded(timeout=timeout)
        )

    async def hover(
        self,
        modifiers: typing.Union[
            typing.List[Literal["Alt", "Control", "Meta", "Shift"]]
        ] = None,
        position: MousePosition = None,
        timeout: int = None,
        force: bool = None,
    ) -> NoneType:
        """ElementHandle.hover

        This method scrolls element into view if needed, and then uses page.mouse to hover over the center of the element.
        If the element is detached from DOM, the method throws an error.

        Parameters
        ----------
        modifiers : Optional[List[Literal['Alt', 'Control', 'Meta', 'Shift']]]
            Modifier keys to press. Ensures that only these modifiers are pressed during the hover, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
        position : Optional[{"x": float, "y": float}]
            A point to hover relative to the top-left corner of element padding box. If not specified, hovers over some visible point of the element.
        timeout : Optional[int]
            Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods.
        force : Optional[bool]
            Whether to bypass the actionability checks. Defaults to `false`.
        """
        return mapping.from_maybe_impl(
            await self._impl_obj.hover(
                modifiers=modifiers, position=position, timeout=timeout, force=force
            )
        )

    async def click(
        self,
        modifiers: typing.Union[
            typing.List[Literal["Alt", "Control", "Meta", "Shift"]]
        ] = None,
        position: MousePosition = None,
        delay: int = None,
        button: Literal["left", "right", "middle"] = None,
        clickCount: int = None,
        timeout: int = None,
        force: bool = None,
        noWaitAfter: bool = None,
    ) -> NoneType:
        """ElementHandle.click

        This method scrolls element into view if needed, and then uses page.mouse to click in the center of the element.
        If the element is detached from DOM, the method throws an error.

        Parameters
        ----------
        modifiers : Optional[List[Literal['Alt', 'Control', 'Meta', 'Shift']]]
            Modifier keys to press. Ensures that only these modifiers are pressed during the click, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
        position : Optional[{"x": float, "y": float}]
            A point to click relative to the top-left corner of element padding box. If not specified, clicks to some visible point of the element.
        delay : Optional[int]
            Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
        button : Optional[Literal['left', 'right', 'middle']]
            Defaults to `left`.
        clickCount : Optional[int]
            defaults to 1. See UIEvent.detail.
        timeout : Optional[int]
            Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods.
        force : Optional[bool]
            Whether to bypass the actionability checks. Defaults to `false`.