feat: Add 'mobile: calibrateWebToRealCoordinatesTranslation' API

docs/attach-to-running-wda.md

@@ -30,3 +30,8 @@ If the environment had port-forward to the connected device, it can be `http://l
 This method allows you to manage the WebDriverAgent application process by yourself.
 XCUITest driver simply attaches to the WebDriverAgent application process.
 It may improve the application performance.
+
+Some xcuitest driver APIs (for example the [mobile: calibrateWebToRealCoordinatesTranslation](./execute-methods.md#mobile-calibratewebtorealcoordinatestranslation) one) might still require to know
+the port number of the remote device if it is a real device. Providing
+`webDriverAgentUrl` capability might not be sufficient to recognize the remote port number in case it is different from the local one. Consider settings the `appium:wdaRemotePort` capability value
+in such case to supply the driver with the appropriate data.

docs/capabilities.md

@@ -52,6 +52,7 @@ Capability | Description
 |`appium:wdaStartupRetries`|Number of times to try to build and launch `WebDriverAgent` onto the device. Defaults to 2.|e.g., `4`|
 |`appium:wdaStartupRetryInterval`|Time, in ms, to wait between tries to build and launch `WebDriverAgent`. Defaults to 10000ms.|e.g., `20000`|
 |`appium:wdaLocalPort`|This value if specified, will be used to forward traffic from Mac host to real ios devices over USB. Default value is same as port number used by WDA on device.|e.g., `8100`|
+|`appium:wdaRemotePort`|This value if specified, will be used as the port number to start WDA HTTP server on the remote device. This is only relevant for real devices, because Simulator shares ports with its host. If `webDriverAgentUrl` is provided then it might be used to provide a hint for the remote port number if it differs from the default one. Default value is 8100.|e.g., `8100`|
 |`appium:wdaBaseUrl`| This value if specified, will be used as a prefix to build a custom `WebDriverAgent` url. It is different from `webDriverAgentUrl`, because if the latter is set then it expects `WebDriverAgent` to be already listening and skips the building phase. Defaults to `http://localhost` | e.g., `http://192.168.1.100`|
 |`appium:showXcodeLog`|Whether to display the output of the Xcode command used to run the tests. If this is `true`, there will be **lots** of extra logging at startup. Defaults to `false`|e.g., `true`|
 |`appium:iosInstallPause`|Time in milliseconds to pause between installing the application and starting `WebDriverAgent` on the device. Used particularly for larger applications. Defaults to `0`|e.g., `8000`|
@@ -122,7 +123,7 @@ Capability | Description
 |`appium:webviewConnectTimeout`|The time to wait, in `ms`, for the initial presence of webviews in MobileSafari or hybrid apps. Defaults to `0`|e.g., '5000'|
 |`appium:safariIgnoreWebHostnames`| Provide a list of hostnames (comma-separated) that the Safari automation tools should ignore. This is to provide a workaround to prevent a webkit bug where the web context is unintentionally changed to a 3rd party website and the test gets stuck. The common culprits are search engines (yahoo, bing, google) and `about:blank` |e.g. `'www.yahoo.com, www.bing.com, www.google.com, about:blank'`|
 |`appium:nativeWebTap`| Enable native, non-javascript-based taps being in web context mode. Defaults to `false`. Warning: sometimes the preciseness of native taps could be broken, because there is no reliable way to map web element coordinates to native ones. | `true` |
-|`appium:nativeWebTapStrict`| Enforce native taps to be done by XCUITest driver rather than WebDriverAgent. Only applicable if `nativeWebTap` is enabled. `false` by default | `false` |
+|`appium:nativeWebTapStrict`| Enabling this capability would skip the additional logic that tries to match web view elements to native ones by using their textual descriptions. Depending on the actual web view content this algorithm might sometimes be not very reliable and will slow down each click as we anyway fallback to the usual coordinates transformation flow if it fails. It is advised to enable strict tap if you use [mobile: calibrateWebToRealCoordinatesTranslation extension](./execute-methods.md#mobile-calibratewebtorealcoordinatestranslation). Only applicable if `nativeWebTap` is enabled. `false` by default | `true` |
 |`appium:safariInitialUrl`| Initial safari url, default is a local welcome page. Setting it to an empty string will skip the initial navigation. | e.g. `https://www.github.com` |
 |`appium:safariAllowPopups`| (Simulator only) Allow javascript to open new windows in Safari. Default keeps current sim setting. |`true` or `false`|
 |`appium:safariIgnoreFraudWarning`| (Simulator only) Prevent Safari from showing a fraudulent website warning. Default keeps current sim setting. |`true` or `false`|

docs/endpoints.md

@@ -65,7 +65,6 @@
 | POST   | /alert_text                              | text | |
 | POST   | /accept_alert                            | none | |
 | POST   | /dismiss_alert                           | none | |
-| POST   | /moveto                                  | | element, xoffset, yoffset |
 | POST   | /click                                   | | button |
 | POST   | /touch/click                             | element | |
 | POST   | /touch/flick                             | | element, xspeed, yspeed, xoffset, yoffset, speed |

docs/execute-methods.md

@@ -1201,6 +1201,36 @@ If the connection is disconnected, condition inducer will be automatically disab
 
 Either `true` or `false`, where `true` means disabling of the condition inducer has been successful
 
+### mobile: calibrateWebToRealCoordinatesTranslation
+
+Calibrates web to real coordinates translation.
+This API can only be called from Safari web context.
+It must load a custom page to the browser, and then restore
+the original one, so don't call it if you can potentially
+lose the current web app state.
+The outcome of this API is then used if `nativeWebTap` capability/setting is enabled.
+The returned value could also be used to manually transform web coordinates
+to real device ones in client scripts.
+
+It is adviced to call this API at least once before changing the device orientation
+or device screen layout as the recetly received value is cached for the session lifetime
+and may become obsolete.
+
+It is advised to enable `nativeWebTapStrict` capability/setting to speed up dynamic coordinates
+transformation if you use this extension.
+
+#### Returned Result
+
+An object with three properties used to properly shift Safari web element coordinates into native context:
+- `offsetX`: Webview X offset in real coordinates
+- `offsetY`: Webview Y offset in real coordinates
+- `pixelRatioX`: Webview X pixel ratio
+- `pixelRatioY`: Webview Y pixel ratio
+
+The following formulas are used for coordinates translation:
+`RealX = offsetX + webviewX * pixelRatioX`
+`RealY = offsetY + webviewY * pixelRatioY`
+
 ### mobile: updateSafariPreferences
 
 Updates preferences of Mobile Safari on Simulator

lib/commands/context.js

@@ -392,7 +392,6 @@ const helpers = {
     await this.remote.disconnect();
     this.curContext = null;
     this.curWebFrames = [];
-    this.curWebCoords = null;
     this.remote = null;
   },
   /**

lib/commands/gesture.js

@@ -97,43 +97,6 @@ export function gesturesChainToString(gestures, keysToInclude = ['options']) {
 }
 
 const commands = {
-  /**
-   * Move the mouse pointer to a particular screen location
-   *
-   * @param {string|Element} el - the element ID if the move is relative to an element
-   * @param {number} xoffset - the x offset
-   * @param {number} yoffset - the y offset
-   * @this {XCUITestDriver}
-   * @deprecated Use {@linkcode XCUITestDriver.performActions} instead
-   */
-  async moveTo(el, xoffset = 0, yoffset = 0) {
-    el = util.unwrapElement(el);
-
-    if (this.isWebContext()) {
-      throw new errors.UnknownMethodError(
-        'The moveTo command is not available in the web context. Use the Actions API in the ' +
-          'native context instead',
-      );
-    } else {
-      if (_.isNil(el)) {
-        if (!this.curCoords) {
-          throw new errors.UnknownError(
-            'Current cursor position unknown, please use moveTo with an element the first time.',
-          );
-        }
-        this.curCoords = {
-          x: this.curCoords.x + xoffset,
-          y: this.curCoords.y + yoffset,
-        };
-      } else {
-        let elPos = await this.getLocation(el);
-        this.curCoords = {
-          x: elPos.x + xoffset,
-          y: elPos.y + yoffset,
-        };
-      }
-    }
-  },
   /**
    * Shake the device
    * @this {XCUITestDriver}
@@ -767,19 +730,6 @@ const helpers = {
     }
     return coordinates;
   },
-  /**
-   * @this {XCUITestDriver}
-   */
-  applyMoveToOffset(firstCoordinates, secondCoordinates) {
-    if (secondCoordinates.areOffsets) {
-      return {
-        x: firstCoordinates.x + secondCoordinates.x,
-        y: firstCoordinates.y + secondCoordinates.y,
-      };
-    } else {
-      return secondCoordinates;
-    }
-  },
 };
 
 export default {...helpers, ...commands};

lib/commands/proxy-helper.js

@@ -49,9 +49,6 @@ const WDA_ROUTES = /** @type {const} */ ({
   '/wda/locked': {
     GET: 'isLocked',
   },
-  '/wda/tap/nil': {
-    POST: 'clickCoords',
-  },
   '/window/size': {
     GET: 'getWindowSize',
   },