feat(tap): support tap (microsoft#261)

Author: pavelfeldman

playwright/async_api.py

@@ -55,6 +55,7 @@
 )
 from playwright.input import Keyboard as KeyboardImpl
 from playwright.input import Mouse as MouseImpl
+from playwright.input import Touchscreen as TouchscreenImpl
 from playwright.js_handle import JSHandle as JSHandleImpl
 from playwright.network import Request as RequestImpl
 from playwright.network import Response as ResponseImpl
@@ -678,6 +679,26 @@ async def dblclick(
 mapping.register(MouseImpl, Mouse)
 
 
+class Touchscreen(AsyncBase):
+    def __init__(self, obj: TouchscreenImpl):
+        super().__init__(obj)
+
+    async def tap(self, x: float, y: float) -> NoneType:
+        """Touchscreen.tap
+
+        Dispatches a `touchstart` and `touchend` event with a single touch at the position (`x`,`y`).
+
+        Parameters
+        ----------
+        x : float
+        y : float
+        """
+        return mapping.from_maybe_impl(await self._impl_obj.tap(x=x, y=y))
+
+
+mapping.register(TouchscreenImpl, Touchscreen)
+
+
 class JSHandle(AsyncBase):
     def __init__(self, obj: JSHandleImpl):
         super().__init__(obj)
@@ -1130,6 +1151,53 @@ async def selectOption(
             )
         )
 
+    async def tap(
+        self,
+        modifiers: typing.Union[
+            typing.List[Literal["Alt", "Control", "Meta", "Shift"]]
+        ] = None,
+        position: MousePosition = None,
+        timeout: int = None,
+        force: bool = None,
+        noWaitAfter: bool = None,
+    ) -> NoneType:
+        """ElementHandle.tap
+
+        This method taps the element by performing the following steps:
+
+        Wait for actionability checks on the element, unless `force` option is set.
+        Scroll the element into view if needed.
+        Use page.touchscreen to tap in the center of the element, or the specified `position`.
+        Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
+
+        If the element is detached from the DOM at any moment during the action, this method rejects.
+        When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.
+
+        **NOTE** `elementHandle.tap()` requires that the `hasTouch` option of the browser context be set to true.
+
+        Parameters
+        ----------
+        modifiers : Optional[List[Literal['Alt', 'Control', 'Meta', 'Shift']]]
+            Modifier keys to press. Ensures that only these modifiers are pressed during the tap, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
+        position : Optional[{"x": float, "y": float}]
+            A point to tap relative to the top-left corner of element padding box. If not specified, taps 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`.
+        noWaitAfter : Optional[bool]
+            Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
+        """
+        return mapping.from_maybe_impl(
+            await self._impl_obj.tap(
+                modifiers=modifiers,
+                position=position,
+                timeout=timeout,
+                force=force,
+                noWaitAfter=noWaitAfter,
+            )
+        )
+
     async def fill(
         self, value: str, timeout: int = None, noWaitAfter: bool = None
     ) -> NoneType:
@@ -2344,6 +2412,57 @@ async def dblclick(
             )
         )
 
+    async def tap(
+        self,
+        selector: str,
+        modifiers: typing.Union[
+            typing.List[Literal["Alt", "Control", "Meta", "Shift"]]
+        ] = None,
+        position: MousePosition = None,
+        timeout: int = None,
+        force: bool = None,
+        noWaitAfter: bool = None,
+    ) -> NoneType:
+        """Frame.tap
+
+        This method taps an element matching `selector` by performing the following steps:
+
+        Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.
+        Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.
+        Scroll the element into view if needed.
+        Use page.touchscreen to tap the center of the element, or the specified `position`.
+        Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
+
+        When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.
+
+        **NOTE** `frame.tap()` requires that the `hasTouch` option of the browser context be set to true.
+
+        Parameters
+        ----------
+        selector : str
+            A selector to search for element to tap. If there are multiple elements satisfying the selector, the first will be tapped. See working with selectors for more details.
+        modifiers : Optional[List[Literal['Alt', 'Control', 'Meta', 'Shift']]]
+            Modifier keys to press. Ensures that only these modifiers are pressed during the tap, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
+        position : Optional[{"x": float, "y": float}]
+            A point to tap relative to the top-left corner of element padding box. If not specified, taps 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`.
+        noWaitAfter : Optional[bool]
+            Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
+        """
+        return mapping.from_maybe_impl(
+            await self._impl_obj.tap(
+                selector=selector,
+                modifiers=modifiers,
+                position=position,
+                timeout=timeout,
+                force=force,
+                noWaitAfter=noWaitAfter,
+            )
+        )
+
     async def fill(
         self, selector: str, value: str, timeout: int = None, noWaitAfter: bool = None
     ) -> NoneType:
@@ -3194,6 +3313,16 @@ def mouse(self) -> "Mouse":
         """
         return mapping.from_impl(self._impl_obj.mouse)
 
+    @property
+    def touchscreen(self) -> "Touchscreen":
+        """Page.touchscreen
+
+        Returns
+        -------
+        Touchscreen
+        """
+        return mapping.from_impl(self._impl_obj.touchscreen)
+
     @property
     def context(self) -> "BrowserContext":
         """Page.context
@@ -4404,6 +4533,59 @@ async def dblclick(
             )
         )
 
+    async def tap(
+        self,
+        selector: str,
+        modifiers: typing.Union[
+            typing.List[Literal["Alt", "Control", "Meta", "Shift"]]
+        ] = None,
+        position: MousePosition = None,
+        timeout: int = None,
+        force: bool = None,
+        noWaitAfter: bool = None,
+    ) -> NoneType:
+        """Page.tap
+
+        This method taps an element matching `selector` by performing the following steps:
+
+        Find an element match matching `selector`. If there is none, wait until a matching element is attached to the DOM.
+        Wait for actionability checks on the matched element, unless `force` option is set. If the element is detached during the checks, the whole action is retried.
+        Scroll the element into view if needed.
+        Use page.touchscreen to tap the center of the element, or the specified `position`.
+        Wait for initiated navigations to either succeed or fail, unless `noWaitAfter` option is set.
+
+        When all steps combined have not finished during the specified `timeout`, this method rejects with a TimeoutError. Passing zero timeout disables this.
+
+        **NOTE** `page.tap()` requires that the `hasTouch` option of the browser context be set to true.
+
+        Shortcut for page.mainFrame().tap().
+
+        Parameters
+        ----------
+        selector : str
+            A selector to search for element to tap. If there are multiple elements satisfying the selector, the first will be tapped. See working with selectors for more details.
+        modifiers : Optional[List[Literal['Alt', 'Control', 'Meta', 'Shift']]]
+            Modifier keys to press. Ensures that only these modifiers are pressed during the tap, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
+        position : Optional[{"x": float, "y": float}]
+            A point to tap relative to the top-left corner of element padding box. If not specified, taps 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`.
+        noWaitAfter : Optional[bool]
+            Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to `false`.
+        """
+        return mapping.from_maybe_impl(
+            await self._impl_obj.tap(
+                selector=selector,
+                modifiers=modifiers,
+                position=position,
+                timeout=timeout,
+                force=force,
+                noWaitAfter=noWaitAfter,
+            )
+        )
+
     async def fill(
         self, selector: str, value: str, timeout: int = None, noWaitAfter: bool = None
     ) -> NoneType:

playwright/element_handle.py

@@ -130,6 +130,16 @@ async def selectOption(
             params = {**params, **convert_select_option_values(values)}
         return await self._channel.send("selectOption", params)
 
+    async def tap(
+        self,
+        modifiers: List[KeyboardModifier] = None,
+        position: MousePosition = None,
+        timeout: int = None,
+        force: bool = None,
+        noWaitAfter: bool = None,
+    ) -> None:
+        await self._channel.send("tap", locals_to_params(locals()))
+
     async def fill(
         self, value: str, timeout: int = None, noWaitAfter: bool = None
     ) -> None:

playwright/frame.py

@@ -376,6 +376,17 @@ async def dblclick(
     ) -> None:
         await self._channel.send("dblclick", locals_to_params(locals()))
 
+    async def tap(
+        self,
+        selector: str,
+        modifiers: List[KeyboardModifier] = None,
+        position: MousePosition = None,
+        timeout: int = None,
+        force: bool = None,
+        noWaitAfter: bool = None,
+    ) -> None:
+        await self._channel.send("tap", locals_to_params(locals()))
+
     async def fill(
         self, selector: str, value: str, timeout: int = None, noWaitAfter: bool = None
     ) -> None:

playwright/helper.py

@@ -56,6 +56,23 @@ class MousePosition(TypedDict):
     y: float
 
 
+class FrameTapParams(TypedDict):
+    selector: str
+    force: Optional[bool]
+    noWaitAfter: bool
+    modifiers: Optional[List[KeyboardModifier]]
+    position: Optional[MousePosition]
+    timeout: int
+
+
+class FrameTapOptions(TypedDict):
+    force: Optional[bool]
+    noWaitAfter: bool
+    modifiers: Optional[List[KeyboardModifier]]
+    position: Optional[MousePosition]
+    timeout: int
+
+
 class FilePayload(TypedDict):
     name: str
     mimeType: str

playwright/input.py

@@ -77,3 +77,12 @@ async def dblclick(
         button: MouseButton = None,
     ) -> None:
         await self.click(x, y, delay=delay, button=button, clickCount=2)
+
+
+class Touchscreen:
+    def __init__(self, channel: Channel) -> None:
+        self._channel = channel
+        self._loop = channel._connection._loop
+
+    async def tap(self, x: float, y: float) -> None:
+        await self._channel.send("touchscreenTap", locals_to_params(locals()))

playwright/page.py

@@ -51,7 +51,7 @@
     parse_error,
     serialize_error,
 )
-from playwright.input import Keyboard, Mouse
+from playwright.input import Keyboard, Mouse, Touchscreen
 from playwright.js_handle import (
     JSHandle,
     Serializable,
@@ -96,6 +96,7 @@ class Page(ChannelOwner):
     accessibility: Accessibility
     keyboard: Keyboard
     mouse: Mouse
+    touchscreen: Touchscreen
 
     def __init__(
         self, parent: ChannelOwner, type: str, guid: str, initializer: Dict
@@ -104,6 +105,7 @@ def __init__(
         self.accessibility = Accessibility(self._channel)
         self.keyboard = Keyboard(self._channel)
         self.mouse = Mouse(self._channel)
+        self.touchscreen = Touchscreen(self._channel)
 
         self._main_frame: Frame = from_channel(initializer["mainFrame"])
         self._main_frame._page = self
@@ -631,6 +633,17 @@ async def dblclick(
     ) -> None:
         return await self._main_frame.dblclick(**locals_to_params(locals()))
 
+    async def tap(
+        self,
+        selector: str,
+        modifiers: List[KeyboardModifier] = None,
+        position: MousePosition = None,
+        timeout: int = None,
+        force: bool = None,
+        noWaitAfter: bool = None,
+    ) -> None:
+        return await self._main_frame.tap(**locals_to_params(locals()))
+
     async def fill(
         self, selector: str, value: str, timeout: int = None, noWaitAfter: bool = None
     ) -> None: