appium-xcuitest-driver 10.8.3 → 10.9.0

package/lib/{simulator-management.js → device/simulator-management.ts}

@@ -1,25 +1,25 @@
-import {getSimulator} from 'appium-ios-simulator';
+import {getSimulator, type Simulator, type LocalizationOptions} from 'appium-ios-simulator';
 import {Simctl} from 'node-simctl';
 import {resetTestProcesses} from 'appium-webdriveragent';
 import _ from 'lodash';
 import {util, timing} from 'appium/support';
-import {UDID_AUTO, normalizePlatformName} from './utils';
-import {buildSafariPreferences} from './app-utils';
+import {UDID_AUTO, normalizePlatformName} from '../utils';
+import {buildSafariPreferences} from '../app-utils';
+import type { XCUITestDriver } from '../driver';
 
 const APPIUM_SIM_PREFIX = 'appiumTest';
 
 /**
  * Create a new simulator with `appiumTest-` prefix and return the object.
  *
- * @this {import('./driver').XCUITestDriver}
- * @returns {Promise<object>} Simulator object associated with the udid passed in.
+ * @returns Simulator object associated with the udid passed in.
  */
-export async function createSim() {
+export async function createSim(this: XCUITestDriver): Promise<Simulator> {
   const {simulatorDevicesSetPath: devicesSetPath, deviceName, platformVersion} = this.opts;
   const platform = normalizePlatformName(this.opts.platformName);
   const simctl = new Simctl({devicesSetPath});
   if (!deviceName) {
-    let deviceNames = 'none';
+    let deviceNames: string | string[] = 'none';
     try {
       deviceNames = (await simctl
         .getDevices(platformVersion, platform))
@@ -47,22 +47,12 @@ export async function createSim() {
   });
 }
 
-/**
- * @typedef {Object} SimulatorLookupOptions
- * @property {string} [deviceName] - The name of the device to lookup
- * @property {string} platformVersion - The platform version string
- * @property {string} [simulatorDevicesSetPath] - The full path to the simulator devices set
- * @property {string} [udid] - Simulator udid
- * @property {string} [platformName] The name of the current platform
- */
-
 /**
  * Get an existing simulator matching the provided capabilities.
  *
- * @this {import('./driver').XCUITestDriver}
- * @returns {Promise<import('./driver').Simulator|null>} The matched Simulator instance or `null` if no matching  device is found.
+ * @returns The matched Simulator instance or `null` if no matching device is found.
  */
-export async function getExistingSim() {
+export async function getExistingSim(this: XCUITestDriver): Promise<Simulator | null> {
   const {
     platformVersion,
     deviceName,
@@ -72,7 +62,7 @@ export async function getExistingSim() {
   } = this.opts;
 
   const platform = normalizePlatformName(platformName);
-  const selectSim = async (/** @type {{ udid: string; platform: string; }} */ dev) =>
+  const selectSim = async (dev: { udid: string; platform: string; }): Promise<Simulator> =>
     await getSimulator(dev.udid, {
       platform,
       checkExistence: false,
@@ -82,7 +72,7 @@ export async function getExistingSim() {
     });
 
   const simctl = new Simctl({devicesSetPath});
-  let devicesMap;
+  let devicesMap: Record<string, any[]> | undefined;
   if (udid && _.toLower(udid) !== UDID_AUTO) {
     this.log.debug(`Looking for an existing Simulator with UDID '${udid}'`);
     devicesMap = await simctl.getDevices(null, platform);
@@ -123,21 +113,23 @@ export async function getExistingSim() {
 }
 
 /**
- * @this {import('./driver').XCUITestDriver}
+ * Shutdown simulator
  */
-export async function shutdownSimulator() {
-  const device = /** @type {import('./driver').Simulator} */ (this.device);
+export async function shutdownSimulator(this: XCUITestDriver): Promise<void> {
+  const device = this.device as Simulator;
   // stop XCTest processes if running to avoid unexpected side effects
   await resetTestProcesses(device.udid, true);
   await device.shutdown();
 }
 
 /**
- * @this {import('./driver').XCUITestDriver}
- * @property {boolean} [enforceSimulatorShutdown=false]
- * @returns {Promise<void>}
+ * Run simulator reset
+ * @param enforceSimulatorShutdown Whether to enforce simulator shutdown
  */
-export async function runSimulatorReset(enforceSimulatorShutdown = false) {
+export async function runSimulatorReset(
+  this: XCUITestDriver,
+  enforceSimulatorShutdown: boolean = false
+): Promise<void> {
   const {
     noReset,
     fullReset,
@@ -152,7 +144,7 @@ export async function runSimulatorReset(enforceSimulatorShutdown = false) {
     this.log.debug('Reset: noReset is on. Leaving simulator as is');
     return;
   }
-  const device = /** @type {import('./driver').Simulator} */ (this.device);
+  const device = this.device as Simulator;
 
   if (!this.device) {
     this.log.debug('Reset: no device available. Skipping');
@@ -165,7 +157,7 @@ export async function runSimulatorReset(enforceSimulatorShutdown = false) {
     const isKeychainsBackupSuccessful = (keychainsExcludePatterns || keepKeyChains) && (await device.backupKeychains());
     await device.clean();
     if (isKeychainsBackupSuccessful) {
-      await device.restoreKeychains(keychainsExcludePatterns || []);
+      await device.restoreKeychains(keychainsExcludePatterns?.split(',')?.map(_.trim) || []);
       this.log.info(`Successfully restored keychains after full reset`);
     } else if (keychainsExcludePatterns || keepKeyChains) {
       this.log.warn(
@@ -194,8 +186,8 @@ export async function runSimulatorReset(enforceSimulatorShutdown = false) {
           await device.scrubApp(bundleId);
         }
       } catch (err) {
-        this.log.debug(err.stack);
-        this.log.warn(err.message);
+        this.log.debug((err as Error).stack);
+        this.log.warn((err as Error).message);
         this.log.warn(
           `Reset: could not scrub ${
             isSafari ? 'Safari browser' : 'application with id "' + this.opts.bundleId + '"'
@@ -205,36 +197,30 @@ export async function runSimulatorReset(enforceSimulatorShutdown = false) {
     }
 
     if (enforceSimulatorShutdown && (await device.isRunning())) {
-      await shutdownSimulator.bind(this)(device);
+      await shutdownSimulator.bind(this)();
     }
   }
 }
 
 /**
- * @typedef {Object} InstallOptions
- *
- * @property {boolean} [skipUninstall] Whether to skip app uninstall before installing it
- * @property {boolean} [newSimulator=false] Whether the simulator is brand new
- */
-
-/**
- * @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={}]
+ * Install app to simulator
+ * @param app The app to the path
+ * @param bundleId The bundle id to ensure it is already installed and uninstall it
+ * @param opts Install options
  */
 export async function installToSimulator(
-  app,
-  bundleId,
-  opts = {},
-) {
+  this: XCUITestDriver,
+  app: string,
+  bundleId?: string,
+  opts: SimulatorInstallOptions = {},
+): Promise<void> {
   if (!app) {
     this.log.debug('No app path is given. Nothing to install.');
     return;
   }
 
   const {skipUninstall, newSimulator = false} = opts;
-  const device = /** @type {import('./driver').Simulator} */ (this.device);
+  const device = this.device as Simulator;
 
   if (!skipUninstall && !newSimulator && bundleId && (await device.isAppInstalled(bundleId))) {
     this.log.debug(`Reset requested. Removing app with id '${bundleId}' from the device`);
@@ -248,10 +234,10 @@ export async function installToSimulator(
 }
 
 /**
- * @this {import('./driver').XCUITestDriver}
+ * Shutdown other simulators
  */
-export async function shutdownOtherSimulators() {
-  const device = /** @type {import('./driver').Simulator} */ (this.device);
+export async function shutdownOtherSimulators(this: XCUITestDriver): Promise<void> {
+  const device = this.device as Simulator;
   const simctl = new Simctl({
     devicesSetPath: device.devicesSetPath,
   });
@@ -281,30 +267,27 @@ export async function shutdownOtherSimulators() {
 /**
  * Configures Safari options based on the given session capabilities
  *
- * @this {import('./driver').XCUITestDriver}
- * @return {Promise<boolean>} true if any preferences have been updated
+ * @returns true if any preferences have been updated
  */
-export async function setSafariPrefs() {
+export async function setSafariPrefs(this: XCUITestDriver): Promise<boolean> {
   const prefs = buildSafariPreferences(this.opts);
   if (_.isEmpty(prefs)) {
     return false;
   }
 
   this.log.debug(`About to update Safari preferences: ${JSON.stringify(prefs)}`);
-  await /** @type {import('./driver').Simulator} */ (this.device).updateSafariSettings(prefs);
+  await (this.device as Simulator).updateSafariSettings(prefs);
   return true;
 }
 
 /**
  * Changes Simulator localization preferences
  *
- * @this {import('./driver').XCUITestDriver}
- * @returns {Promise<boolean>} True if preferences were changed
+ * @returns True if preferences were changed
  */
-export async function setLocalizationPrefs() {
+export async function setLocalizationPrefs(this: XCUITestDriver): Promise<boolean> {
   const {language, locale, calendarFormat, skipSyncUiDialogTranslation} = this.opts;
-  /** @type {import('appium-ios-simulator').LocalizationOptions} */
-  const l10nConfig = {};
+  const l10nConfig: LocalizationOptions = {};
   if (language) {
     l10nConfig.language = {name: language, skipSyncUiDialogTranslation };
   }
@@ -319,6 +302,30 @@ export async function setLocalizationPrefs() {
   }
 
   this.log.debug(`About to update localization preferences: ${JSON.stringify(l10nConfig)}`);
-  await /** @type {import('./driver').Simulator} */ (this.device).configureLocalization(l10nConfig);
+  await (this.device as Simulator).configureLocalization(l10nConfig);
   return true;
 }
+
+//#region Type Definitions
+
+export interface SimulatorLookupOptions {
+  /** The name of the device to lookup */
+  deviceName?: string;
+  /** The platform version string */
+  platformVersion: string;
+  /** The full path to the simulator devices set */
+  simulatorDevicesSetPath?: string;
+  /** Simulator udid */
+  udid?: string;
+  /** The name of the current platform */
+  platformName?: string;
+}
+
+export interface SimulatorInstallOptions {
+  /** Whether to skip app uninstall before installing it */
+  skipUninstall?: boolean;
+  /** Whether the simulator is brand new */
+  newSimulator?: boolean;
+}
+
+//#endregion