chore: add launchApp via devicectl (#2354)

* add launchApp

* modify the logs

* bump wda

lib/devicectl.js

@@ -81,6 +81,14 @@ const XCRUN = 'xcrun';
  * @property {number} [timeout=120000] The timeout for pulling a file in milliseconds.
  */
 
+
+/**
+ * An option for launchApp method by devicectl.
+ * @typedef {Object} LaunchAppOptions
+ * @property {import('@appium/types').StringRecord<string|number>} [env] Bundle id to Environment variables for the launching app process.
+ * @property {boolean} [terminateExisting=false] Whether terminating the already running app.
+ */
+
 export class Devicectl {
   /**
    * @since Xcode 15, iOS 17
@@ -246,4 +254,31 @@ export class Devicectl {
     });
     return JSON.parse(stdout).result.apps;
   }
+
+  /**
+   * Launch the given bundle id application with the given environment variable.
+   * This method is over devicectl command, this it may take additional seconds to launch the app.
+   * Please use via WDA or via appium-ios-device as primary method to launch app if possible.
+   *
+   * @param {string} bundleId Bundle id to launch.
+   * @param {LaunchAppOptions} opts launching app with devicectl command options.
+   * @returns {Promise<void>}
+   * @throws {Error} If the launching app command fails. For example, the given bundle id did not exist.
+   */
+  async launchApp(bundleId, opts) {
+    const {
+      env,
+      terminateExisting = false
+    } = opts;
+
+    const subcommandOptions = [bundleId];
+    if (terminateExisting) {
+      subcommandOptions.push('--terminate-existing');
+    };
+    if (!_.isEmpty(env)) {
+      subcommandOptions.push('--environment-variables', JSON.stringify(_.mapValues(env, (v) => _.toString(v))));
+    };
+
+    await this.execute(['device', 'process', 'launch'], { subcommandOptions, asJson: false});
+  }
 }

package.json

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