feat: Add the appium:initialDeeplinkUrl capabilility (#2324)

docs/reference/capabilities.md

@@ -27,6 +27,7 @@ about capabilities, refer to the [Appium documentation](https://appium.io/docs/e
 | <div style="width:10em">Capability</div> | Description |
 | --- | --- |
 | `appium:bundleId` | Bundle identifier of the app under test, for example `com.mycompany.myapp`. The capability value is calculated automatically if `app` is provided. If neither `app` or `bundleId` capability is provided then XCUITest driver starts from the Home screen. |
+| `appium:initialDeeplinkUrl` | A deeplink URL used to run either the application assigned to `appium:bundleId`, or the default application assigned to handle the particular deeplink protocol if `appium:bundleId` is not set. If provided in combination with `browserName=safari` then makes Safari to start with the given URL preloaded, which speeds up the session startup. The value of `appium:initialSafariUrl` capability is ignored in such case. An error is thrown on session init if either the value of the capability is not a valid URL, or XCTest was not able to associate it with any existing app, or the actual iOS version is below *16.4* |
 | `appium:app` | Full path to the application to be tested (the app must be located on the same machine where the server is running). `.ipa` and `.app` application extensions are supported. Zipped `.app` bundles are supported as well. Could also be an URL to a remote location. If neither of the `app` or `bundleId` capabilities are provided then the driver starts from the Home screen and expects the test to know what to do next. Do not provide both `app` and `browserName` capabilities at once. |
 | `appium:enforceAppInstall` | If set to `false` it will make xcuitest driver to verify whether the app version currently installed on the device under test is older than the one, which is provided as `appium:app` value. No app reinstall is going to happen if the candidate app has the same or older version number than the already installed copy of it. The version number used for comparison must be provided as [CFBundleVersion](https://developer.apple.com/documentation/bundleresources/information_property_list/cfbundleversion) [Semantic Versioning](https://semver.org/)-compatible value in the application's Info.plist. No validation is performed by default, e.g. the provided app is always (re)installed, which could potentially slow down your test suites. The application data might be cached on real devices under particular circumstances when `appium:enforceAppInstall` is `true` if the application under test remained on the device under a certain situation. Please check [troubleshooting](../guides/troubleshooting.md#leftover-application-data-on-real-devices) for more details regarding obsolete application data cleanup on real devices. Available since XCUITest driver 4.19.0. | false |
 | `appium:localizableStringsDir` | Where to look for localizable strings in the application bundle. Defaults to `en.lproj` |

lib/desired-caps.js

@@ -36,6 +36,9 @@ const desiredCapConstraints = /** @type {const} */ ({
   safariInitialUrl: {
     isString: true,
   },
+  initialDeeplinkUrl: {
+    isString: true,
+  },
   safariAllowPopups: {
     isBoolean: true,
   },

lib/driver.js

@@ -2,7 +2,7 @@ import IDB from 'appium-idb';
 import {getSimulator} from 'appium-ios-simulator';
 import {WebDriverAgent} from 'appium-webdriveragent';
 import {BaseDriver, DeviceSettings} from 'appium/driver';
-import {fs, mjpeg, util} from 'appium/support';
+import {fs, mjpeg, util, timing} from 'appium/support';
 import AsyncLock from 'async-lock';
 import {retry, retryInterval} from 'asyncbox';
 import B from 'bluebird';
@@ -643,19 +643,16 @@ class XCUITestDriver extends BaseDriver {
       await this.activateRecentWebview();
     }
     if (this.isSafari()) {
-      if (
-        !(
-          this.opts.safariInitialUrl === '' ||
-          (this.opts.noReset && _.isNil(this.opts.safariInitialUrl))
-        )
-      ) {
+      if (shouldSetInitialSafariUrl(this.opts)) {
         this.log.info(
           `About to set the initial Safari URL to '${this.getCurrentUrl()}'.` +
             `Use 'safariInitialUrl' capability in order to customize it`,
         );
         await this.setUrl(this.getCurrentUrl());
       } else {
-        this.setCurrentUrl(await this.getUrl());
+        const currentUrl = await this.getUrl();
+        this.log.info(`Current URL: ${currentUrl}`);
+        this.setCurrentUrl(currentUrl);
       }
     }
   }
@@ -1404,13 +1401,19 @@ class XCUITestDriver extends BaseDriver {
     } else if (this.opts.autoDismissAlerts) {
       wdaCaps.defaultAlertAction = 'dismiss';
     }
+    if (this.opts.initialDeeplinkUrl) {
+      this.log.info(`The deeplink URL will be set to ${this.opts.initialDeeplinkUrl}`);
+      wdaCaps.initialUrl = this.opts.initialDeeplinkUrl;
+    }
 
+    const timer = new timing.Timer().start();
     await this.proxyCommand('/session', 'POST', {
       capabilities: {
         firstMatch: [wdaCaps],
         alwaysMatch: {},
       },
     });
+    this.log.info(`WDA session startup took ${timer.getDuration().asMilliSeconds.toFixed(0)}ms`);
   }
 
   // Override Proxy methods from BaseDriver
@@ -2230,6 +2233,15 @@ class XCUITestDriver extends BaseDriver {
   mobileListXCTestsInTestBundle = commands.xctestExtensions.mobileListXCTestsInTestBundle;
 }
 
+/**
+ * @param {XCUITestDriverOpts} opts
+ * @returns {boolean}
+ */
+function shouldSetInitialSafariUrl(opts) {
+  return !(opts.safariInitialUrl === '' || (opts.noReset && _.isNil(opts.safariInitialUrl)))
+    && !opts.initialDeeplinkUrl;
+}
+
 export default XCUITestDriver;
 export {XCUITestDriver};
 

lib/types.ts

@@ -47,6 +47,7 @@ export interface WDASettings {
  */
 export interface WDACapabilities {
   bundleId?: string;
+  initialUrl?: string;
   arguments: string[];
   environment: Record<string, string>;
   eventloopIdleDelaySec: number;

package.json

@@ -81,7 +81,7 @@
     "appium-ios-device": "^2.5.4",
     "appium-ios-simulator": "^5.5.1",
     "appium-remote-debugger": "^10.0.0",
-    "appium-webdriveragent": "^6.0.0",
+    "appium-webdriveragent": "^6.1.0",
     "appium-xcode": "^5.1.4",
     "async-lock": "^1.4.0",
     "asyncbox": "^3.0.0",