diff --git a/README.md b/README.md index 2c1d9343..3a0600c4 100644 --- a/README.md +++ b/README.md @@ -124,10 +124,12 @@ For example, some changes in the Selenium binding could break the Appium client. - `MultiAction` and `TouchAction` are deprecated. Please use W3C WebDriver actions or `mobile:` extensions - `launch_app`, `close_app`, and `reset` are deprecated. Please read [issues#15807](https://github.com/appium/appium/issues/15807) for more details -#### MultiAction/TouchAction to W3C actions +#### MultiAction/TouchAction and ActionHelpers Shortcuts to W3C Actions + +The interaction shortcut methods on `ActionHelpers` (`scroll`, `drag_and_drop`, `tap`, `swipe`, and `flick`) are deprecated because gesture behavior varies across drivers and pointer types (for example, Android UiAutomator2 handles `POINTER_TOUCH` and `POINTER_MOUSE` inputs differently in the underlying UIAutomator framework). Build W3C WebDriver actions directly with `ActionChains` / `ActionBuilder` instead. Some elements can be handled with `touch` pointer action instead of the default `mouse` pointer action in the Selenium Python client. -For example, the below action builder is to replace the default one with the `touch` pointer action. +For example, the below action builder is to replace the default one with the `touch` pointer action: ```python from selenium.webdriver import ActionChains @@ -136,7 +138,7 @@ from selenium.webdriver.common.actions.action_builder import ActionBuilder from selenium.webdriver.common.actions.pointer_input import PointerInput actions = ActionChains(driver) -# override as 'touch' pointer action +# override as 'touch' pointer action (or use interaction.POINTER_MOUSE for mouse input) actions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, 'touch')) actions.w3c_actions.pointer_action.move_to_location(start_x, start_y) actions.w3c_actions.pointer_action.pointer_down() diff --git a/appium/webdriver/extensions/action_helpers.py b/appium/webdriver/extensions/action_helpers.py index be32ca9f..669b4a77 100644 --- a/appium/webdriver/extensions/action_helpers.py +++ b/appium/webdriver/extensions/action_helpers.py @@ -19,7 +19,7 @@ from selenium.webdriver.common.actions.action_builder import ActionBuilder from selenium.webdriver.common.actions.mouse_button import MouseButton from selenium.webdriver.common.actions.pointer_input import PointerInput -from typing_extensions import Self +from typing_extensions import Self, deprecated from appium.webdriver.webelement import WebElement @@ -29,9 +29,14 @@ class ActionHelpers: + @deprecated('Please use W3C actions (ActionChains/ActionBuilder) or mobile: gesture extensions instead.') def scroll(self, origin_el: WebElement, destination_el: WebElement, duration: int | None = None) -> Self: """Scrolls from one element to another + .. deprecated:: + Please use W3C actions (`ActionChains` / `ActionBuilder`) or driver-specific + `mobile:` gesture extensions instead. + Args: origin_el: the element from which to begin scrolling (center of element) destination_el: the element to scroll to (center of element) @@ -63,9 +68,14 @@ def scroll(self, origin_el: WebElement, destination_el: WebElement, duration: in actions.perform() return self + @deprecated('Please use W3C actions (ActionChains/ActionBuilder) or mobile: gesture extensions instead.') def drag_and_drop(self, origin_el: WebElement, destination_el: WebElement, pause: float | None = None) -> Self: """Drag the origin element to the destination element + .. deprecated:: + Please use W3C actions (`ActionChains` / `ActionBuilder`) or driver-specific + `mobile:` gesture extensions instead. + Args: origin_el: the element to drag destination_el: the element to drag to @@ -84,10 +94,15 @@ def drag_and_drop(self, origin_el: WebElement, destination_el: WebElement, pause actions.perform() return self + @deprecated('Please use W3C actions (ActionChains/ActionBuilder) or mobile: gesture extensions instead.') def tap(self, positions: list[tuple[int, int]], duration: int | None = None) -> Self: """Taps on an particular place with up to five fingers, holding for a certain time + .. deprecated:: + Please use W3C actions (`ActionChains` / `ActionBuilder`) or driver-specific + `mobile:` gesture extensions instead. + Args: positions: an array of tuples representing the x/y coordinates of the fingers to tap. Length can be up to five. @@ -132,9 +147,14 @@ def tap(self, positions: list[tuple[int, int]], duration: int | None = None) -> actions.perform() return self + @deprecated('Please use W3C actions (ActionChains/ActionBuilder) or mobile: gesture extensions instead.') def swipe(self, start_x: int, start_y: int, end_x: int, end_y: int, duration: int = 0) -> Self: """Swipe from one point to another point, for an optional duration. + .. deprecated:: + Please use W3C actions (`ActionChains` / `ActionBuilder`) or driver-specific + `mobile:` gesture extensions instead. + Args: start_x: x-coordinate at which to start start_y: y-coordinate at which to start @@ -161,9 +181,14 @@ def swipe(self, start_x: int, start_y: int, end_x: int, end_y: int, duration: in actions.perform() return self + @deprecated('Please use W3C actions (ActionChains/ActionBuilder) or mobile: gesture extensions instead.') def flick(self, start_x: int, start_y: int, end_x: int, end_y: int) -> Self: """Flick from one point to another point. + .. deprecated:: + Please use W3C actions (`ActionChains` / `ActionBuilder`) or driver-specific + `mobile:` gesture extensions instead. + Args: start_x: x-coordinate at which to start start_y: y-coordinate at which to start