feat: Unify gesture extensions (#2313)

docs/reference/execute-methods.md

@@ -920,7 +920,7 @@ _Important_: The implemntation of this extension relies on several undocumented
 
 Name | Type | Required | Description | Example
 --- | --- | --- | --- | ---
-elementId ("element" prior to Appium v 1.22) | string | no | The internal element identifier (as hexadecimal hash string) to scroll on (e.g. the container). Application element will be used if this argument is not set | fe50b60b-916d-420b-8728-ee2072ec53eb
+elementId ("element" prior to Appium v 1.22) | string | no | The internal element identifier (as hexadecimal hash string) to scroll on (e.g. the container). The active application element will be used instead if this parameter is not provided. | fe50b60b-916d-420b-8728-ee2072ec53eb
 name | string | no | The accessibility id of the child element, to which scrolling is performed. The same result can be achieved by setting _predicateString_ argument to 'name == accessibilityId'. Has no effect if _elementId_ is not a container | cell12
 direction | Either 'up', 'down', 'left' or 'right' | yes | The main difference from [swipe](#mobile-swipe) call with the same argument is that _scroll_ will try to move the current viewport exactly to the next/previous page (the term "page" means the content, which fits into a single device screen) | down
 predicateString | string | no | The NSPredicate locator of the child element, to which the scrolling should be performed. Has no effect if _elementId_ is not a container | label == "foo"
@@ -941,7 +941,7 @@ Performs pinch gesture on the given element or on the application element.
 
 Name | Type | Required | Description | Example
 --- | --- | --- | --- | ---
-elementId ("element" prior to Appium v 1.22) | string | no | The internal element identifier (as hexadecimal hash string) to pinch on. Application element will be used instead if this parameter is not provided | fe50b60b-916d-420b-8728-ee2072ec53eb
+elementId ("element" prior to Appium v 1.22) | string | no | The internal element identifier (as hexadecimal hash string) to pinch on. The active application element will be used instead if this parameter is not provided. | fe50b60b-916d-420b-8728-ee2072ec53eb
 scale | number | yes | Pinch scale of type float. Use a scale between 0 and 1 to "pinch close" or zoom out and a scale greater than 1 to "pinch open" or zoom in. | 0.5
 velocity | number | yes | The velocity of the pinch in scale factor per second (float value) | 2.2
 
@@ -964,9 +964,9 @@ Performs double tap gesture on the given element or on the screen.
 
 Name | Type | Required | Description | Example
 --- | --- | --- | --- | ---
-elementId ("element" prior to Appium v 1.22) | string | no if x and y are set | The internal element identifier (as hexadecimal hash string) to double tap on | fe50b60b-916d-420b-8728-ee2072ec53eb
-x | number | no if elementId is set | Screen x tap coordinate of type float. | 100
-y | number | no if elementId is set | Screen y tap coordinate of type float. | 100
+elementId ("element" prior to Appium v 1.22) | string | no | The internal element identifier (as hexadecimal hash string) to double tap on. The active application element will be used instead if this parameter is not provided. | fe50b60b-916d-420b-8728-ee2072ec53eb
+x | number | no | Horizontal coordinate offset. | 100
+y | number | no | Vertical coordinate offset. | 100
 
 #### Examples
 
@@ -983,17 +983,17 @@ Performs long press gesture on the given element or on the screen.
 
 Name | Type | Required | Description | Example
 --- | --- | --- | --- | ---
-elementId ("element" prior to Appium v 1.22) | string | no if x and y are set | The internal element identifier (as hexadecimal hash string) to long tap on | fe50b60b-916d-420b-8728-ee2072ec53eb
+elementId ("element" prior to Appium v 1.22) | string | no | The internal element identifier (as hexadecimal hash string) to long tap on. The active application element will be used instead if this parameter is not provided. | fe50b60b-916d-420b-8728-ee2072ec53eb
 duration | number | yes | The float duration of press action in seconds | 1.5
-x | number | no if elementId is set | Screen x tap coordinate of type float. | 100
-y | number | no if elementId is set | Screen y tap coordinate of type float. | 100
+x | number | no | Horizontal coordinate offset. | 100
+y | number | no | Vertical coordinate offset. | 100
 
 #### Examples
 
 ```csharp
 // c#
 Dictionary<string, object> tfLongTap = new Dictionary<string, object>();
-tfLongTap.Add("element", element.Id);
+tfLongTap.Add("elementId", element.Id);
 tfLongTap.Add("duration", 2.0);
 ((IJavaScriptExecutor)driver).ExecuteScript("mobile: touchAndHold", tfLongTap);
 ```
@@ -1010,14 +1010,14 @@ Performs two finger tap gesture on the given element or on the application eleme
 
 Name | Type | Required | Description | Example
 --- | --- | --- | --- | ---
-elementId ("element" prior to Appium v 1.22) | string | no | The internal element identifier (as hexadecimal hash string) to tap on. Application element will be used instead if this parameter is not provided | fe50b60b-916d-420b-8728-ee2072ec53eb
+elementId ("element" prior to Appium v 1.22) | string | no | The internal element identifier (as hexadecimal hash string) to tap on. The active application element will be used instead if this parameter is not provided. | fe50b60b-916d-420b-8728-ee2072ec53eb
 
 #### Examples
 
 ```csharp
 // c#
 Dictionary<string, object> tfTap = new Dictionary<string, object>();
-tfTap.Add("element", element.Id);
+tfTap.Add("elementId", element.Id);
 ((IJavaScriptExecutor)driver).ExecuteScript("mobile: twoFingerTap", tfTap);
 ```
 
@@ -1033,9 +1033,9 @@ Performs tap gesture by coordinates on the given element or on the screen.
 
 Name | Type | Required | Description | Example
 --- | --- | --- | --- | ---
-elementId ("element" prior to Appium v 1.22) | string | no | The internal element identifier (as hexadecimal hash string) to tap on. _x_ and _y_ tap coordinates will be calulated relatively to the current element position on the screen if this argument is provided. Otherwise they should be calculated relatively to the active application element. | fe50b60b-916d-420b-8728-ee2072ec53eb
-x | number | yes | Screen x tap coordinate of type float. | 100
-y | number | yes | Screen y tap coordinate of type float. | 100
+elementId ("element" prior to Appium v 1.22) | string | no | The internal element identifier (as hexadecimal hash string) to tap on. _x_ and _y_ tap coordinates will be calculated relatively to the current element position on the screen if this argument is provided. Otherwise they should be calculated relatively to the active application element. | fe50b60b-916d-420b-8728-ee2072ec53eb
+x | number | yes | Horizontal coordinate offset. | 100
+y | number | yes | Vertical coordinate offset. | 100
 
 ### mobile: dragFromToForDuration
 
@@ -1064,7 +1064,7 @@ params.put("fromX", 100);
 params.put("fromY", 100);
 params.put("toX", 200);
 params.put("toY", 200);
-params.put("element", ((RemoteWebElement) element).getId());
+params.put("elementId", ((RemoteWebElement) element).getId());
 js.executeScript("mobile: dragFromToForDuration", params);
 ```
 
@@ -1103,7 +1103,7 @@ Performs [rotate](https://developer.apple.com/documentation/xctest/xcuielement/1
 
 Name | Type | Required | Description | Example
 --- | --- | --- | --- | ---
-elementId ("element" prior to Appium v 1.22) | string | yes | Internal element id (as hexadecimal hash string) to perform rotation on | fe50b60b-916d-420b-8728-ee2072ec53eb
+elementId ("element" prior to Appium v 1.22) | string | no | Internal element id (as hexadecimal hash string) to perform rotation on. The active application element will be used instead if this parameter is not provided. | fe50b60b-916d-420b-8728-ee2072ec53eb
 rotation | number | yes | The rotation of the gesture in radians | Math.PI
 velocity | number | yes | The velocity of the rotation gesture in radians per second | Math.PI / 4
 
@@ -1117,7 +1117,7 @@ js.executeScript("mobile: rotateElement", ImmutableMap.of(
     "rotation", -Math.PI / 2,
     // in approximately two seconds
     "velocity", Math.PI / 4,
-    "element", ((RemoteWebElement) element).getId()
+    "elementId", ((RemoteWebElement) element).getId()
 ));
 ```
 
@@ -1133,19 +1133,24 @@ Sends one or more taps with one or more touch points since Appium 1.17.1.
 
 Name | Type | Required | Description | Example
 --- | --- | --- | --- | ---
-elementId ("element" prior to Appium v 1.22) | string | yes | The internal element identifier (as hexadecimal hash string) to perform one or more taps. | fe50b60b-916d-420b-8728-ee2072ec53eb
-numberOfTaps | number | yes | The number of taps | 2
-numberOfTouches | number | yes | The number of touch points | 2
+elementId ("element" prior to Appium v 1.22) | string | no | The internal element identifier (as hexadecimal hash string) to perform one or more taps. The active application element will be used instead if this parameter is not provided.| fe50b60b-916d-420b-8728-ee2072ec53eb
+numberOfTaps | number | no | The number of taps. 1 by default | 2
+numberOfTouches | number | no | The number of touch points. 1 by default | 2
 
 #### Examples
 
 ```ruby
 # Ruby
 e = @driver.find_element :id, 'target element'
 # Taps the element with a single touch point twice
-@driver.execute_script 'mobile: tapWithNumberOfTaps', {element: e.ref, numberOfTaps: 2, numberOfTouches: 1}
+@driver.execute_script 'mobile: tapWithNumberOfTaps', {elementId: e.ref, numberOfTaps: 2, numberOfTouches: 1}
 ```
 
+- numberOfTaps=1, numberOfTouches=1 -> "vanilla" single tap
+- numberOfTaps=2, numberOfTouches=1 -> double tap
+- numberOfTaps=3, numberOfTouches=1 -> tripple tap
+- numberOfTaps=2, numberOfTouches=2 -> double tap with two fingers
+
 #### Reference
 [tapWithNumberOfTaps:numberOfTouches:](https://developer.apple.com/documentation/xctest/xcuielement/1618671-tapwithnumberoftaps)