appium-xcuitest-driver 7.6.1 → 7.7.0

package/lib/driver.js

@@ -384,6 +384,14 @@ class XCUITestDriver extends BaseDriver {
     return didMerge;
   }
 
+  /**
+   * @returns {Simulator|RealDevice}
+   */
+  get device() {
+    // @ts-ignore This property should exist
+    return this.opts?.device;
+  }
+
   isXcodebuildNeeded() {
     return !(CAP_NAMES_NO_XCODEBUILD_REQUIRED.some((x) => Boolean(this.opts[x])));
   }
@@ -484,6 +492,7 @@ class XCUITestDriver extends BaseDriver {
     this.log.info(
       `Determining device to run tests on: udid: '${udid}', real device: ${realDevice}`,
     );
+    // TODO: extract device out of opts to a separate driver property
     // @ts-expect-error - do not assign arbitrary properties to `this.opts`
     this.opts.device = device;
     this.opts.udid = udid;
@@ -499,22 +508,18 @@ class XCUITestDriver extends BaseDriver {
         this.log.info(
           `Setting simulator devices set path to '${this.opts.simulatorDevicesSetPath}'`,
         );
-        // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-        this.opts.device.devicesSetPath = this.opts.simulatorDevicesSetPath;
+        (/** @type {Simulator} */ (this.device)).devicesSetPath = this.opts.simulatorDevicesSetPath;
       }
     }
 
     // at this point if there is no platformVersion, get it from the device
-    // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-    if (!this.opts.platformVersion && this.opts.device) {
-      // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-      this.opts.platformVersion = await this.opts.device.getPlatformVersion();
+    if (!this.opts.platformVersion) {
+      this.opts.platformVersion = await this.device.getPlatformVersion();
       this.log.info(
         `No platformVersion specified. Using device version: '${this.opts.platformVersion}'`,
       );
     }
 
-    // @ts-expect-error - do not assign arbitrary properties to `this.opts`
     const normalizedVersion = normalizePlatformVersion(this.opts.platformVersion);
     if (this.opts.platformVersion !== normalizedVersion) {
       this.log.info(
@@ -604,8 +609,7 @@ class XCUITestDriver extends BaseDriver {
       !this.opts.app &&
       this.opts.bundleId &&
       !this.isSafari() &&
-      // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-      !(await this.opts.device.isAppInstalled(this.opts.bundleId))
+      !(await this.device.isAppInstalled(this.opts.bundleId))
     ) {
       this.log.errorAndThrow(`App with bundle identifier '${this.opts.bundleId}' unknown`);
     }
@@ -614,8 +618,7 @@ class XCUITestDriver extends BaseDriver {
       if (this.opts.permissions) {
         this.log.debug('Setting the requested permissions before WDA is started');
         for (const [bundleId, permissionsMapping] of _.toPairs(JSON.parse(this.opts.permissions))) {
-          // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-          await this.opts.device.setPermissions(bundleId, permissionsMapping);
+          await /** @type {Simulator} */ (this.device).setPermissions(bundleId, permissionsMapping);
         }
       }
 
@@ -628,15 +631,14 @@ class XCUITestDriver extends BaseDriver {
         const methodName = `${
           this.opts.calendarAccessAuthorized ? 'enable' : 'disable'
         }CalendarAccess`;
-        // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-        await this.opts.device[methodName](this.opts.bundleId);
+        await this.device[methodName](this.opts.bundleId);
       }
     }
 
     // @ts-expect-error - do not assign arbitrary properties to `this.opts`
     await this.startWda(this.opts.sessionId);
 
-    if (this.opts.orientation) {
+    if (_.isString(this.opts.orientation)) {
       await this.setInitialOrientation(this.opts.orientation);
       this.logEvent('orientationSet');
     }
@@ -663,12 +665,11 @@ class XCUITestDriver extends BaseDriver {
    * Start the simulator and initialize based on capabilities
    */
   async initSimulator() {
-    // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-    const device = this.opts.device;
+    const device = /** @type {Simulator} */ (this.device);
 
     if (this.opts.shutdownOtherSimulators) {
       this.assertFeatureEnabled(SHUTDOWN_OTHER_FEAT_NAME);
-      await shutdownOtherSimulators(device);
+      await shutdownOtherSimulators.bind(this)();
     }
 
     await this.startSim();
@@ -679,17 +680,21 @@ class XCUITestDriver extends BaseDriver {
       this.logEvent('customCertInstalled');
     }
 
-    if (await setSafariPrefs(device, this.opts)) {
+    if (await setSafariPrefs.bind(this)()) {
       this.log.debug('Safari preferences have been updated');
     }
 
-    if (await setLocalizationPrefs(device, this.opts)) {
+    if (await setLocalizationPrefs.bind(this)()) {
       this.log.debug('Localization preferences have been updated');
     }
 
+    /** @type {Promise[]} */
     const promises = ['reduceMotion', 'reduceTransparency', 'autoFillPasswords']
       .filter((optName) => _.isBoolean(this.opts[optName]))
-      .map((optName) => device[`set${_.upperFirst(optName)}`](this.opts[optName]));
+      .map((optName) => {
+        this.log.info(`Setting ${optName} to ${this.opts[optName]}`);
+        return device[`set${_.upperFirst(optName)}`](this.opts[optName]);
+      });
     await B.all(promises);
 
     if (this.opts.launchWithIDB) {
@@ -886,16 +891,14 @@ class XCUITestDriver extends BaseDriver {
 
   /**
    *
-   * @param {XCUITestDriverOpts} [opts]
+   * @param {boolean} [enforceSimulatorShutdown=false]
    */
-  async runReset(opts) {
+  async runReset(enforceSimulatorShutdown = false) {
     this.logEvent('resetStarted');
     if (this.isRealDevice()) {
-      // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-      await runRealDeviceReset(this.opts.device, opts || this.opts);
+      await runRealDeviceReset.bind(this)();
     } else {
-      // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-      await runSimulatorReset(this.opts.device, opts || this.opts);
+      await runSimulatorReset.bind(this)(enforceSimulatorShutdown);
     }
     this.logEvent('resetComplete');
   }
@@ -944,18 +947,13 @@ class XCUITestDriver extends BaseDriver {
     }
 
     if (this.opts.resetOnSessionStartOnly === false) {
-      await this.runReset(
-        Object.assign({}, this.opts, {
-          enforceSimulatorShutdown: true,
-        }),
-      );
+      await this.runReset(true);
     }
 
-    // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-    const simulatorDevice = this.isSimulator() ? this.opts.device : null;
+    const simulatorDevice = this.isSimulator() ? /** @type {Simulator} */ (this.device) : null;
     if (simulatorDevice && this.lifecycleData.createSim) {
       this.log.debug(`Deleting simulator created for this run (udid: '${simulatorDevice.udid}')`);
-      await shutdownSimulator(simulatorDevice);
+      await shutdownSimulator.bind(this)();
       await simulatorDevice.delete();
     }
 
@@ -1168,19 +1166,16 @@ class XCUITestDriver extends BaseDriver {
     this.opts.deviceName = translateDeviceName(this.opts.platformVersion, this.opts.deviceName);
 
     const setupVersionCaps = async () => {
+      const iosSdkVersion = await getAndCheckIosSdkVersion();
       // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-      this.opts.iosSdkVersion = await getAndCheckIosSdkVersion();
-      // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-      this.log.info(`iOS SDK Version set to '${this.opts.iosSdkVersion}'`);
-      // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-      if (!this.opts.platformVersion && this.opts.iosSdkVersion) {
+      this.opts.iosSdkVersion = iosSdkVersion;
+      this.log.info(`iOS SDK Version set to '${iosSdkVersion}'`);
+      if (!this.opts.platformVersion && iosSdkVersion) {
         this.log.info(
-          // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-          `No platformVersion specified. Using the latest version Xcode supports: '${this.opts.iosSdkVersion}'. ` +
+          `No platformVersion specified. Using the latest version Xcode supports: '${iosSdkVersion}'. ` +
             `This may cause problems if a simulator does not exist for this platform version.`,
         );
-        // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-        this.opts.platformVersion = normalizePlatformVersion(this.opts.iosSdkVersion);
+        this.opts.platformVersion = normalizePlatformVersion(iosSdkVersion);
       }
     };
 
@@ -1195,11 +1190,10 @@ class XCUITestDriver extends BaseDriver {
           );
           await setupVersionCaps();
 
-          // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-          const device = await getExistingSim(this.opts);
+          const device = await getExistingSim.bind(this)();
           if (!device) {
             // No matching Simulator is found. Throw an error
-            this.log.errorAndThrow(
+            throw this.log.errorWithException(
               `Cannot detect udid for ${this.opts.deviceName} Simulator running iOS ${this.opts.platformVersion}`,
             );
           }
@@ -1221,6 +1215,7 @@ class XCUITestDriver extends BaseDriver {
             try {
               const device = await getSimulator(this.opts.udid, {
                 devicesSetPath: this.opts.simulatorDevicesSetPath,
+                logger: this.log,
               });
               return {device, realDevice: false, udid: this.opts.udid};
             } catch (ign) {
@@ -1230,7 +1225,7 @@ class XCUITestDriver extends BaseDriver {
         }
       }
 
-      const device = getRealDeviceObj(this.opts.udid, this.log);
+      const device = getRealDeviceObj.bind(this)();
       return {device, realDevice: true, udid: this.opts.udid};
     }
 
@@ -1245,8 +1240,7 @@ class XCUITestDriver extends BaseDriver {
       );
     } else {
       // figure out the correct simulator to use, given the desired capabilities
-      // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-      const device = await getExistingSim(this.opts);
+      const device = await getExistingSim.bind(this)();
       // check for an existing simulator
       if (device) {
         return {device, realDevice: false, udid: device.udid};
@@ -1260,20 +1254,21 @@ class XCUITestDriver extends BaseDriver {
   }
 
   async startSim() {
+    /** @type {import('appium-ios-simulator').DevicePreferences} */
+    const devicePreferences = {};
+    /** @type {import('appium-ios-simulator').RunOptions} */
     const runOpts = {
       scaleFactor: this.opts.scaleFactor,
       connectHardwareKeyboard: !!this.opts.connectHardwareKeyboard,
       pasteboardAutomaticSync: this.opts.simulatorPasteboardAutomaticSync ?? 'off',
       isHeadless: !!this.opts.isHeadless,
       tracePointer: this.opts.simulatorTracePointer,
-      devicePreferences: {},
+      devicePreferences,
     };
 
     // add the window center, if it is specified
-    // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-    if (this.opts.SimulatorWindowCenter) {
-      // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-      runOpts.devicePreferences.SimulatorWindowCenter = this.opts.SimulatorWindowCenter;
+    if (this.opts.simulatorWindowCenter) {
+      devicePreferences.SimulatorWindowCenter = this.opts.simulatorWindowCenter;
     }
 
     if (_.isInteger(this.opts.simulatorStartupTimeout)) {
@@ -1285,23 +1280,22 @@ class XCUITestDriver extends BaseDriver {
     const orientation = _.isString(this.opts.orientation) && this.opts.orientation.toUpperCase();
     switch (orientation) {
       case 'LANDSCAPE':
-        runOpts.devicePreferences.SimulatorWindowOrientation = 'LandscapeLeft';
-        runOpts.devicePreferences.SimulatorWindowRotationAngle = 90;
+        devicePreferences.SimulatorWindowOrientation = 'LandscapeLeft';
+        devicePreferences.SimulatorWindowRotationAngle = 90;
         break;
       case 'PORTRAIT':
-        runOpts.devicePreferences.SimulatorWindowOrientation = 'Portrait';
-        runOpts.devicePreferences.SimulatorWindowRotationAngle = 0;
+        devicePreferences.SimulatorWindowOrientation = 'Portrait';
+        devicePreferences.SimulatorWindowRotationAngle = 0;
         break;
     }
 
-    // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-    await this.opts.device.run(runOpts);
+    await /** @type {Simulator} */ (this.device).run(runOpts);
   }
 
   async createSim() {
     this.lifecycleData.createSim = true;
     // create sim for caps
-    const sim = await createSim(this.opts);
+    const sim = await createSim.bind(this)();
     this.log.info(`Created simulator with udid '${sim.udid}'.`);
     return sim;
   }
@@ -1670,15 +1664,13 @@ class XCUITestDriver extends BaseDriver {
     const {install, skipUninstall} = await this.checkAutInstallationState();
     if (install) {
       if (this.isRealDevice()) {
-        // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-        await installToRealDevice(this.opts.device, this.opts.app, this.opts.bundleId, {
+        await installToRealDevice.bind(this)(this.opts.app, this.opts.bundleId, {
           skipUninstall,
           timeout: this.opts.appPushTimeout,
           strategy: this.opts.appInstallStrategy,
         });
       } else {
-        // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-        await installToSimulator(this.opts.device, this.opts.app, this.opts.bundleId, {
+        await installToSimulator.bind(this)(this.opts.app, this.opts.bundleId, {
           skipUninstall,
           newSimulator: this.lifecycleData?.createSim,
         });
@@ -1693,6 +1685,10 @@ class XCUITestDriver extends BaseDriver {
     }
   }
 
+  /**
+   * @param {string|string[]} otherApps
+   * @returns {Promise<void>}
+   */
   async installOtherApps(otherApps) {
     /** @type {string[]|undefined} */
     let appsList;
@@ -1712,9 +1708,7 @@ class XCUITestDriver extends BaseDriver {
     const appIds = await B.all(appPaths.map((appPath) => extractBundleId(appPath)));
     for (const [appId, appPath] of _.zip(appIds, appPaths)) {
       if (this.isRealDevice()) {
-        await installToRealDevice(
-          // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-          this.opts.device,
+        await installToRealDevice.bind(this)(
           appPath,
           appId,
           {
@@ -1724,10 +1718,7 @@ class XCUITestDriver extends BaseDriver {
           },
         );
       } else {
-        await installToSimulator(
-          // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-          this.opts.device,
-          // @ts-ignore the path should always be defined
+        await installToSimulator.bind(this)(
           appPath,
           appId,
           {
@@ -1738,6 +1729,10 @@ class XCUITestDriver extends BaseDriver {
     }
   }
 
+  /**
+   * @param {string} orientation
+   * @returns {Promise<void>}
+   */
   async setInitialOrientation(orientation) {
     const dstOrientation = _.toUpper(orientation);
     if (!SUPPORTED_ORIENATIONS.includes(dstOrientation)) {
@@ -1756,6 +1751,10 @@ class XCUITestDriver extends BaseDriver {
     }
   }
 
+  /**
+   * @param {string} [cmdName]
+   * @returns {number|undefined}
+   */
   _getCommandTimeout(cmdName) {
     if (this.opts.commandTimeouts) {
       if (cmdName && _.has(this.opts.commandTimeouts, cmdName)) {
@@ -1792,14 +1791,11 @@ class XCUITestDriver extends BaseDriver {
       `Installing prebuilt WDA at '${this.opts.prebuiltWDAPath}'. ` +
       `Bundle identifier: ${candidateBundleId}.`
     );
-    // @ts-expect-error - do not assign arbitrary properties to `this.opts`
-    const device = this.opts.device;
 
     // Note: The CFBundleVersion in the test bundle was always 1.
     // It may not be able to compare with the installed versio.
     if (this.isRealDevice()) {
-      await installToRealDevice(
-        device,
+      await installToRealDevice.bind(this)(
         this.opts.prebuiltWDAPath,
         candidateBundleId,
         {
@@ -1809,7 +1805,10 @@ class XCUITestDriver extends BaseDriver {
         },
       );
     } else {
-      await installToSimulator(device, this.opts.prebuiltWDAPath, candidateBundleId);
+      await installToSimulator.bind(this)(
+        this.opts.prebuiltWDAPath,
+        candidateBundleId
+      );
     }
   }
 
@@ -2266,4 +2265,6 @@ export {XCUITestDriver};
  * @typedef {import('./commands/types').FullContext} FullContext
  * @typedef {import('./types').WDACapabilities} WDACapabilities
  * @typedef {import('appium-xcode').XcodeVersion} XcodeVersion
- */
+ * @typedef {import('appium-ios-simulator').Simulator} Simulator
+ * @typedef {import('./real-device').RealDevice} RealDevice
+ */

package/lib/real-device-management.js

@@ -1,9 +1,8 @@
 import {utilities} from 'appium-ios-device';
 import RealDevice from './real-device';
-import log from './logger';
 import {SAFARI_BUNDLE_ID} from './app-utils';
 
-async function getConnectedDevices() {
+export async function getConnectedDevices() {
   return await utilities.getConnectedDevices();
 }
 
@@ -11,24 +10,25 @@ async function getConnectedDevices() {
  * @param {string} udid
  * @returns {Promise<string>}
  */
-async function getOSVersion(udid) {
+export async function getOSVersion(udid) {
   return await utilities.getOSVersion(udid);
 }
 
 /**
- * @param {RealDevice} device
- * @param {import('./driver').XCUITestDriverOpts} opts
+ * @this {import('./driver').XCUITestDriver}
  * @returns {Promise<void>}
  */
-async function resetRealDevice(device, opts) {
-  const {bundleId, fullReset} = opts;
+export async function resetRealDevice() {
+  const {bundleId, fullReset} = this.opts;
   if (!bundleId) {
     return;
   }
 
+  const device = /** @type {RealDevice} */ (this.device);
+
   if (bundleId === SAFARI_BUNDLE_ID) {
-    log.debug('Reset requested. About to terminate Safari');
-    await device.terminateApp(bundleId, opts.platformVersion);
+    this.log.debug('Reset requested. About to terminate Safari');
+    await device.terminateApp(bundleId, String(this.opts.platformVersion));
     return;
   }
 
@@ -36,33 +36,33 @@ async function resetRealDevice(device, opts) {
     return;
   }
 
-  log.debug(`Reset: fullReset requested. Will try to uninstall the app '${bundleId}'.`);
+  this.log.debug(`Reset: fullReset requested. Will try to uninstall the app '${bundleId}'.`);
   if (!(await device.isAppInstalled(bundleId))) {
-    log.debug('Reset: app not installed. No need to uninstall');
+    this.log.debug('Reset: app not installed. No need to uninstall');
     return;
   }
+
   try {
     await device.remove(bundleId);
   } catch (err) {
-    log.error(`Reset: could not remove '${bundleId}' from device: ${err.message}`);
+    this.log.error(`Reset: could not remove '${bundleId}' from device: ${err.message}`);
     throw err;
   }
-  log.debug(`Reset: removed '${bundleId}'`);
+  this.log.debug(`Reset: removed '${bundleId}'`);
 }
 
 /**
- * @param {RealDevice} device
- * @param {import('./driver').XCUITestDriverOpts} opts
+ * @this {import('./driver').XCUITestDriver}
  * @returns {Promise<void>}
  */
-async function runRealDeviceReset(device, opts) {
-  if (!opts.noReset || opts.fullReset) {
-    log.debug('Reset: running ios real device reset flow');
-    if (!opts.noReset) {
-      await resetRealDevice(device, opts);
+export async function runRealDeviceReset() {
+  if (!this.opts.noReset || this.opts.fullReset) {
+    this.log.debug('Reset: running ios real device reset flow');
+    if (!this.opts.noReset) {
+      await resetRealDevice.bind(this)();
     }
   } else {
-    log.debug('Reset: fullReset not set. Leaving as is');
+    this.log.debug('Reset: fullReset not set. Leaving as is');
   }
 }
 
@@ -76,28 +76,30 @@ async function runRealDeviceReset(device, opts) {
  */
 
 /**
- * @param {RealDevice} device The device instance
+ * @this {import('./driver').XCUITestDriver}
  * @param {string} [app] The app to the path
  * @param {string} [bundleId] The bundle id to ensure it is already installed and uninstall it
- * @param {InstallOptions} [opts]
+ * @param {InstallOptions} [opts={}]
  */
-async function installToRealDevice(device, app, bundleId, opts) {
+export async function installToRealDevice(app, bundleId, opts = {}) {
+  const device = /** @type {RealDevice} */ (this.device);
+
   if (!device.udid || !app || !bundleId) {
-    log.debug('No device id, app or bundle id, not installing to real device.');
+    this.log.debug('No device id, app or bundle id, not installing to real device.');
     return;
   }
 
-  const {skipUninstall, strategy, timeout} = opts ?? {};
+  const {skipUninstall, strategy, timeout} = opts;
 
   if (!skipUninstall) {
-    log.info(`Reset requested. Removing app with id '${bundleId}' from the device`);
+    this.log.info(`Reset requested. Removing app with id '${bundleId}' from the device`);
     await device.remove(bundleId);
   }
-  log.debug(`Installing '${app}' on device with UUID '${device.udid}'...`);
+  this.log.debug(`Installing '${app}' on device with UUID '${device.udid}'...`);
 
   try {
     await device.install(app, timeout, strategy);
-    log.debug('The app has been installed successfully.');
+    this.log.debug('The app has been installed successfully.');
   } catch (e) {
     // Want to clarify the device's application installation state in this situation.
 
@@ -113,29 +115,20 @@ async function installToRealDevice(device, app, bundleId, opts) {
     // If the error was by below error case, we could recover the situation
     // by uninstalling the device's app bundle id explicitly regard less the app exists on the device or not (e.g. offload app).
     // [XCUITest] Error installing app '/path/to.app': Unexpected data: {"Error":"MismatchedApplicationIdentifierEntitlement","ErrorDescription":"Upgrade's application-identifier entitlement string (TEAM_ID.com.kazucocoa.example) does not match installed application's application-identifier string (ANOTHER_TEAM_ID.com.kazucocoa.example); rejecting upgrade."}
-    log.info(`The application identified by '${bundleId}' cannot be installed because it might ` +
+    this.log.info(`The application identified by '${bundleId}' cannot be installed because it might ` +
       `be already cached on the device, probably with a different signature. ` +
       `Will try to remove it and install a new copy. Original error: ${e.message}`);
     await device.remove(bundleId);
     await device.install(app, timeout, strategy);
-    log.debug('The app has been installed after one retrial.');
+    this.log.debug('The app has been installed after one retrial.');
   }
 }
 
 /**
- * @param {string} udid
- * @param {import('@appium/types').AppiumLogger} logger
+ * @this {import('./driver').XCUITestDriver}
  * @returns {RealDevice}
  */
-function getRealDeviceObj(udid, logger) {
-  log.debug(`Creating iDevice object with udid '${udid}'`);
-  return new RealDevice(udid, logger);
+export function getRealDeviceObj() {
+  this.log.debug(`Creating iDevice object with udid '${this.opts.udid}'`);
+  return new RealDevice(this.opts.udid, this.log);
 }
-
-export {
-  getConnectedDevices,
-  getOSVersion,
-  runRealDeviceReset,
-  installToRealDevice,
-  getRealDeviceObj,
-};