@limrun/appium-xcuitest-driver 10.4.3-lim.1

package/lib/real-device-clients/py-ios-device-client.ts

@@ -0,0 +1,149 @@
+import {exec, SubProcess} from 'teen_process';
+import {fs, util, tempDir} from 'appium/support';
+import path from 'path';
+import { BaseDeviceClient } from './base-device-client';
+import type { BaseDeviceClientOptions, InstallProfileArgs } from './base-device-client';
+import type { TeenProcessExecResult } from 'teen_process';
+import type { CertificateList } from '../commands/types';
+
+// https://github.com/YueChen-C/py-ios-device
+
+const BINARY_NAME = 'pyidevice';
+const CRASH_REPORT_EXT = '.ips';
+
+export interface PyideviceOptions extends BaseDeviceClientOptions {
+  udid: string;
+}
+
+interface ExecuteOptions {
+  cwd?: string;
+  format?: string | null;
+  logStdout?: boolean;
+  asynchronous?: boolean;
+}
+
+export class Pyidevice extends BaseDeviceClient {
+  private readonly _udid: string;
+  private _binaryPath: string | null;
+
+  constructor(opts: PyideviceOptions) {
+    super({log: opts.log});
+    this._udid = opts.udid;
+    this._binaryPath = null;
+  }
+
+  override async assertExists(isStrict = true): Promise<boolean> {
+    if (this._binaryPath) {
+      return true;
+    }
+
+    try {
+      this._binaryPath = await fs.which(BINARY_NAME);
+      return true;
+    } catch {
+      if (isStrict) {
+        throw new Error(
+          `${BINARY_NAME} binary cannot be found in PATH. ` +
+            `Please make sure it is installed. Visit https://github.com/YueChen-C/py-ios-device for ` +
+            `more details.`,
+        );
+      }
+      return false;
+    }
+  }
+
+  override async listProfiles(): Promise<CertificateList> {
+    const {stdout} = await this.execute(['profiles', 'list']) as TeenProcessExecResult<string>;
+    return JSON.parse(stdout);
+  }
+
+  override async installProfile(args: InstallProfileArgs): Promise<void> {
+    const {profilePath, payload} = args;
+    if (!profilePath && !payload) {
+      throw new Error('Either the full path to the profile or its payload must be provided');
+    }
+
+    let tmpRoot: string | undefined;
+    let srcPath = profilePath;
+    try {
+      if (!srcPath) {
+        tmpRoot = await tempDir.openDir();
+        srcPath = path.join(tmpRoot, 'cert.pem');
+        if (Buffer.isBuffer(payload)) {
+          await fs.writeFile(srcPath, payload);
+        } else {
+          await fs.writeFile(srcPath, payload as string, 'utf8');
+        }
+      }
+      await this.execute(['profiles', 'install', '--path', srcPath], {
+        logStdout: true,
+      });
+    } finally {
+      if (tmpRoot) {
+        await fs.rimraf(tmpRoot);
+      }
+    }
+  }
+
+  override async removeProfile(name: string): Promise<string> {
+    return (
+      await this.execute(['profiles', 'remove', '--name', name], {logStdout: true}) as TeenProcessExecResult<string>
+    ).stdout;
+  }
+
+  override async listCrashes(): Promise<string[]> {
+    const {stdout} = await this.execute(['crash', 'list']) as TeenProcessExecResult<string>;
+    // Example output:
+    // ['.', '..', 'SiriSearchFeedback-2023-12-06-144043.ips', '
+    // SiriSearchFeedback-2024-05-22-194219.ips', 'JetsamEvent-2024-05-23-225056.ips',
+    // 'JetsamEvent-2023-09-18-090920.ips', 'JetsamEvent-2024-05-16-054529.ips',
+    // 'Assistant']
+    return JSON.parse(stdout.replace(/'/g, '"'))
+      .filter((x: string) => x.endsWith(CRASH_REPORT_EXT));
+  }
+
+  override async exportCrash(name: string, dstFolder: string): Promise<void> {
+    await this.execute(['crash', 'export', '--name', name], {
+      logStdout: true,
+      // The tool exports crash reports to the current working dir
+      cwd: dstFolder,
+    });
+  }
+
+  override async collectPcap(dstFile: string): Promise<SubProcess> {
+    return await this.execute(['pcapd', dstFile], {
+      format: null,
+      asynchronous: true,
+    }) as SubProcess;
+  }
+
+  private async execute(
+    args: string[],
+    opts: ExecuteOptions = {}
+  ): Promise<TeenProcessExecResult<string> | SubProcess> {
+    await this.assertExists();
+    const {cwd, format = 'json', logStdout = false, asynchronous = false} = opts;
+
+    const finalArgs = [...args, '--udid', this._udid, '--network'];
+    if (format) {
+      finalArgs.push('--format', format);
+    }
+    const binaryPath = this._binaryPath as string;
+    const cmdStr = util.quote([binaryPath, ...finalArgs]);
+    this.log.debug(`Executing ${cmdStr}`);
+    try {
+      if (asynchronous) {
+        const result = new SubProcess(binaryPath, finalArgs, {cwd});
+        await result.start(0);
+        return result;
+      }
+      const result = await exec(binaryPath, finalArgs, {cwd});
+      if (logStdout) {
+        this.log.debug(`Command output: ${result.stdout}`);
+      }
+      return result;
+    } catch (e) {
+      throw new Error(`'${cmdStr}' failed. Original error: ${e.stderr || e.stdout || e.message}`);
+    }
+  }
+}

package/lib/real-device-management.js

@@ -0,0 +1,133 @@
+import _ from 'lodash';
+import {buildSafariPreferences} from './app-utils';
+import { getConnectedDevices } from './real-device';
+
+const DEFAULT_APP_INSTALLATION_TIMEOUT_MS = 8 * 60 * 1000;
+
+/**
+ * @typedef {Object} InstallOptions
+ *
+ * @property {boolean} [skipUninstall] Whether to skip app uninstall before installing it
+ * @property {number} [timeout=480000] App install timeout
+ * @property {boolean} [shouldEnforceUninstall] Whether to enforce the app uninstallation. e.g. fullReset, or enforceAppInstall is true
+ */
+
+/**
+ * @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={}]
+ */
+export async function installToRealDevice(app, bundleId, opts = {}) {
+  const device = /** @type {RealDevice} */ (this.device);
+
+  if (!device.udid || !app || !bundleId) {
+    this.log.debug('No device id, app or bundle id, not installing to real device.');
+    return;
+  }
+
+  const {
+    skipUninstall,
+    timeout = DEFAULT_APP_INSTALLATION_TIMEOUT_MS,
+  } = opts;
+
+  if (!skipUninstall) {
+    this.log.info(`Reset requested. Removing app with id '${bundleId}' from the device`);
+    await device.remove(bundleId);
+  }
+  this.log.debug(`Installing '${app}' on the device with UUID '${device.udid}'`);
+
+  try {
+    await device.install(app, bundleId, {
+      timeoutMs: timeout,
+    });
+    this.log.debug('The app has been installed successfully.');
+  } catch (e) {
+    // Want to clarify the device's application installation state in this situation.
+
+    if (!skipUninstall || !e.message.includes('MismatchedApplicationIdentifierEntitlement')) {
+      // Other error cases that could not be recoverable by here.
+      // Exact error will be in the log.
+
+      // We cannot recover 'ApplicationVerificationFailed' situation since this reason is clearly the app's provisioning profile was invalid.
+      // [XCUITest] Error installing app '/path/to.app': Unexpected data: {"Error":"ApplicationVerificationFailed","ErrorDetail":-402620395,"ErrorDescription":"Failed to verify code signature of /path/to.app : 0xe8008015 (A valid provisioning profile for this executable was not found.)"}
+      throw e;
+    }
+
+    // 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."}
+    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, bundleId, {
+      timeoutMs: timeout,
+    });
+    this.log.debug('The app has been installed after one retrial.');
+  }
+}
+
+/**
+ * @this {import('./driver').XCUITestDriver}
+ * @returns {Promise<void>}
+ */
+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 /** @type {RealDevice} */ (this.device).reset(this.opts);
+    }
+  } else {
+    this.log.debug('Reset: fullReset not set. Leaving as is');
+  }
+}
+
+/**
+ * Configures Safari startup options based on the given session capabilities.
+ *
+ * !!! This method mutates driver options.
+ *
+ * @this {import('./driver').XCUITestDriver}
+ * @return {boolean} true if process arguments have been modified
+ */
+export function applySafariStartupArgs() {
+  const prefs = buildSafariPreferences(this.opts);
+  if (_.isEmpty(prefs)) {
+    return false;
+  }
+
+  const args = _.toPairs(prefs)
+    .flatMap(([key, value]) => [_.startsWith(key, '-') ? key : `-${key}`, String(value)]);
+  this.log.debug(`Generated Safari command line arguments: ${args.join(' ')}`);
+  if (_.isPlainObject(this.opts.processArguments)) {
+    this.opts.processArguments.args = [...(this.opts.processArguments.args ?? []), ...args];
+  } else {
+    this.opts.processArguments = {args};
+  }
+  return true;
+}
+
+/**
+ * @this {XCUITestDriver}
+ * @returns {Promise<string>}
+ */
+export async function detectUdid() {
+  this.log.debug('Auto-detecting real device udid...');
+  const udids = await getConnectedDevices();
+  if (_.isEmpty(udids)) {
+    throw new Error('No real devices are connected to the host');
+  }
+  const udid = udids[udids.length - 1];
+  if (udids.length > 1) {
+    this.log.info(`Multiple devices found: ${udids.join(', ')}`);
+    this.log.info(`Choosing '${udid}'. Consider settings the 'udid' capability if another device must be selected`);
+  }
+  this.log.debug(`Detected real device udid: '${udid}'`);
+  return udid;
+}
+
+/**
+ * @typedef {import('./real-device').RealDevice} RealDevice}
+ * @typedef {import('./driver').XCUITestDriver} XCUITestDriver
+ */

package/lib/real-device.js

@@ -0,0 +1,347 @@
+import {timing, util, fs} from 'appium/support';
+import path from 'path';
+import {services, utilities, INSTRUMENT_CHANNEL} from 'appium-ios-device';
+import B, {TimeoutError} from 'bluebird';
+import defaultLogger from './logger';
+import _ from 'lodash';
+import {SAFARI_BUNDLE_ID} from './app-utils';
+import {pushFile, pushFolder, IO_TIMEOUT_MS} from './ios-fs-helpers';
+import { Devicectl } from 'node-devicectl';
+
+const APPLICATION_INSTALLED_NOTIFICATION = 'com.apple.mobile.application_installed';
+const APPLICATION_NOTIFICATION_TIMEOUT_MS = 30 * 1000;
+const INSTALLATION_STAGING_DIR = 'PublicStaging';
+
+/**
+ * @returns {Promise<string[]>}
+ */
+export async function getConnectedDevices() {
+  if (['yes', 'true', '1'].includes(_.toLower(process.env.APPIUM_XCUITEST_PREFER_DEVICECTL))) {
+    return (await new Devicectl('').listDevices())
+      .map(({hardwareProperties}) => hardwareProperties?.udid)
+      .filter(Boolean);
+  }
+  return await utilities.getConnectedDevices();
+}
+
+/**
+ * @typedef {Object} InstallOptions
+ * @param {number} [timeoutMs=240000] Application installation timeout in milliseconds
+ */
+
+/**
+ * @typedef {Object} InstallOrUpgradeOptions
+ * @property {number} timeout Install/upgrade timeout in milliseconds
+ * @property {boolean} isUpgrade Whether it is an app upgrade or a new install
+ */
+
+export class RealDevice {
+  /**
+   * @param {string} udid
+   * @param {import('@appium/types').AppiumLogger} [logger]
+   */
+  constructor(udid, logger) {
+    this.udid = udid;
+    this._log = logger ?? defaultLogger;
+    this.devicectl = new Devicectl(this.udid);
+  }
+
+  /**
+   * @returns {import('@appium/types').AppiumLogger}
+   */
+  get log() {
+    return this._log;
+  }
+
+  /**
+   * @param {string} bundleId
+   */
+  async remove(bundleId) {
+    const service = await services.startInstallationProxyService(this.udid);
+    try {
+      await service.uninstallApplication(bundleId);
+    } finally {
+      service.close();
+    }
+  }
+
+  /**
+   * @param {string} bundleId
+   */
+  async removeApp(bundleId) {
+    await this.remove(bundleId);
+  }
+
+  /**
+   *
+   * @param {string} appPath
+   * @param {string} bundleId
+   * @param {InstallOptions} [opts={}]
+   */
+  async install(appPath, bundleId, opts = {}) {
+    const {
+      timeoutMs = IO_TIMEOUT_MS,
+    } = opts;
+    const timer = new timing.Timer().start();
+    const afcService = await services.startAfcService(this.udid);
+    try {
+      let bundlePathOnPhone;
+      if ((await fs.stat(appPath)).isFile()) {
+        // https://github.com/doronz88/pymobiledevice3/blob/6ff5001f5776e03b610363254e82d7fbcad4ef5f/pymobiledevice3/services/installation_proxy.py#L75
+        bundlePathOnPhone = `/${path.basename(appPath)}`;
+        await pushFile(afcService, appPath, bundlePathOnPhone, {
+          timeoutMs,
+        });
+      } else {
+        bundlePathOnPhone = `${INSTALLATION_STAGING_DIR}/${bundleId}`;
+        await pushFolder(afcService, appPath, bundlePathOnPhone, {
+          enableParallelPush: true,
+          timeoutMs,
+        });
+      }
+      await this.installOrUpgradeApplication(
+        bundlePathOnPhone,
+        {
+          timeout: Math.max(timeoutMs - timer.getDuration().asMilliSeconds, 60000),
+          isUpgrade: await this.isAppInstalled(bundleId),
+        }
+      );
+    } catch (err) {
+      this.log.debug(err.stack);
+      let errMessage = `Cannot install the ${bundleId} application`;
+      if (err instanceof TimeoutError) {
+        errMessage += `. Consider increasing the value of 'appPushTimeout' capability (the current value equals to ${timeoutMs}ms)`;
+      }
+      errMessage += `. Original error: ${err.message}`;
+      throw new Error(errMessage);
+    } finally {
+      afcService.close();
+    }
+    this.log.info(
+      `The installation of '${bundleId}' succeeded after ${timer.getDuration().asMilliSeconds.toFixed(0)}ms`
+    );
+  }
+
+  /**
+   * @param {string} bundlePathOnPhone
+   * @param {InstallOrUpgradeOptions} opts
+   */
+  async installOrUpgradeApplication(bundlePathOnPhone, {isUpgrade, timeout}) {
+    const notificationService = await services.startNotificationProxyService(this.udid);
+    const installationService = await services.startInstallationProxyService(this.udid);
+    const appInstalledNotification = new B((resolve) => {
+      notificationService.observeNotification(APPLICATION_INSTALLED_NOTIFICATION, {
+        notification: resolve,
+      });
+    });
+    const clientOptions = {PackageType: 'Developer'};
+    try {
+      if (isUpgrade) {
+        this.log.debug(
+          `An upgrade of the existing application is going to be performed. ` +
+          `Will timeout in ${timeout.toFixed(0)} ms`
+        );
+        await installationService.upgradeApplication(bundlePathOnPhone, clientOptions, timeout);
+      } else {
+        this.log.debug(
+          `A new application installation is going to be performed. ` +
+          `Will timeout in ${timeout.toFixed(0)} ms`
+        );
+        await installationService.installApplication(bundlePathOnPhone, clientOptions, timeout);
+      }
+      try {
+        await appInstalledNotification.timeout(
+          APPLICATION_NOTIFICATION_TIMEOUT_MS,
+          `Could not get the application installed notification within ` +
+            `${APPLICATION_NOTIFICATION_TIMEOUT_MS}ms but we will continue`,
+        );
+      } catch (e) {
+        this.log.warn(e.message);
+      }
+    } finally {
+      installationService.close();
+      notificationService.close();
+    }
+  }
+
+  /**
+   * Alias for {@linkcode install}
+   * @param {string} appPath
+   * @param {string} bundleId
+   * @param {InstallOptions} [opts={}]
+   */
+  async installApp(appPath, bundleId, opts = {}) {
+    return await this.install(appPath, bundleId, opts);
+  }
+
+  /**
+   * Return an application object if test app has 'bundleid'.
+   * The target bundleid can be User and System apps.
+   *
+   * @param {string} bundleId The bundleId to ensure it is installed
+   * @return {Promise<boolean>} Returns True if the app is installed
+   * on the device under test.
+   */
+  async isAppInstalled(bundleId) {
+    return Boolean(await this.fetchAppInfo(bundleId));
+  }
+
+  /**
+   * Fetches various attributes, like bundle id, version, entitlements etc. of
+   * an installed application.
+   *
+   * @param {string} bundleId the bundle identifier of an app to check
+   * @param {string|string[]|undefined} returnAttributes If provided then
+   * only fetches the requested attributes of the app into the resulting object.
+   * Some apps may have too many attributes, so it makes sense to limit these
+   * by default if you don't need all of them.
+   * @returns {Promise<Object|undefined>} Either app info as an object or undefined
+   * if the app is not found.
+   */
+  async fetchAppInfo(bundleId, returnAttributes = ['CFBundleIdentifier', 'CFBundleVersion']) {
+    const service = await services.startInstallationProxyService(this.udid);
+    try {
+      return (
+        await service.lookupApplications({
+          bundleIds: bundleId,
+          // https://github.com/appium/appium/issues/18753
+          returnAttributes,
+        })
+      )[bundleId];
+    } finally {
+      service.close();
+    }
+  }
+
+  /**
+   * @param {string} bundleId
+   * @param {string} platformVersion
+   * @returns {Promise<boolean>}
+   */
+  async terminateApp(bundleId, platformVersion) {
+    let instrumentService;
+    let installProxyService;
+    try {
+      installProxyService = await services.startInstallationProxyService(this.udid);
+      const apps = await installProxyService.listApplications({
+        returnAttributes: ['CFBundleIdentifier', 'CFBundleExecutable']
+      });
+      if (!apps[bundleId]) {
+        this.log.info(`The bundle id '${bundleId}' did not exist`);
+        return false;
+      }
+      const executableName = apps[bundleId].CFBundleExecutable;
+      this.log.debug(`The executable name for the bundle id '${bundleId}' was '${executableName}'`);
+
+      // 'devicectl' has overhead (generally?) than the instrument service via appium-ios-device,
+      // so hre uses the 'devicectl' only for iOS 17+.
+      if (util.compareVersions(platformVersion, '>=', '17.0')) {
+        this.log.debug(`Calling devicectl to kill the process`);
+
+        const pids = (await this.devicectl.listProcesses())
+          .filter(({executable}) => executable.endsWith(`/${executableName}`))
+          .map(({processIdentifier}) => processIdentifier);
+        if (_.isEmpty(pids)) {
+          this.log.info(`The process of the bundle id '${bundleId}' was not running`);
+          return false;
+        }
+        await this.devicectl.sendSignalToProcess(pids[0], 2);
+      } else {
+        instrumentService = await services.startInstrumentService(this.udid);
+
+        // The result of "runningProcesses" includes `bundle_id` key in iOS 16+ (possibly a specific 16.x+)
+        // then here may not be necessary to find a process with `CFBundleExecutable`
+        // after dropping older iOS version support.
+        const processes = await instrumentService.callChannel(
+          INSTRUMENT_CHANNEL.DEVICE_INFO,
+          'runningProcesses',
+        );
+        const process = processes.selector.find((process) => process.name === executableName);
+        if (!process) {
+          this.log.info(`The process of the bundle id '${bundleId}' was not running`);
+          return false;
+        }
+          await instrumentService.callChannel(
+          INSTRUMENT_CHANNEL.PROCESS_CONTROL,
+          'killPid:',
+          `${process.pid}`,
+        );
+      }
+    } catch (err) {
+      this.log.warn(`Failed to kill '${bundleId}'. Original error: ${err.stderr || err.message}`);
+      return false;
+    } finally {
+      if (installProxyService) {
+        installProxyService.close();
+      }
+      if (instrumentService) {
+        instrumentService.close();
+      }
+    }
+    return true;
+  }
+
+  /**
+   * @param {string} bundleName The name of CFBundleName in Info.plist
+   *
+   * @returns {Promise<string[]>} A list of User level apps' bundle ids which has
+   *                          'CFBundleName' attribute as 'bundleName'.
+   */
+  async getUserInstalledBundleIdsByBundleName(bundleName) {
+    const service = await services.startInstallationProxyService(this.udid);
+    try {
+      const applications = await service.listApplications({
+        applicationType: 'User', returnAttributes: ['CFBundleIdentifier', 'CFBundleName']
+      });
+      return _.reduce(
+        applications,
+        (acc, {CFBundleName}, key) => {
+          if (CFBundleName === bundleName) {
+            acc.push(key);
+          }
+          return acc;
+        },
+        /** @type {string[]} */ ([]),
+      );
+    } finally {
+      service.close();
+    }
+  }
+
+  /**
+   * @returns {Promise<string>}
+   */
+  async getPlatformVersion() {
+    return await utilities.getOSVersion(this.udid);
+  }
+
+  /**
+   * @param {import('./driver').XCUITestDriverOpts} opts
+   * @returns {Promise<void>}
+   */
+  async reset({bundleId, fullReset}) {
+    if (!bundleId || !fullReset || bundleId === SAFARI_BUNDLE_ID) {
+      // Safari cannot be removed as system app.
+      // Safari process handling will be managed by WDA
+      // with noReset, forceAppLaunch or shouldTerminateApp capabilities.
+      return;
+    }
+
+    this.log.debug(`Reset: fullReset requested. Will try to uninstall the app '${bundleId}'.`);
+    if (!(await this.isAppInstalled(bundleId))) {
+      this.log.debug('Reset: app not installed. No need to uninstall');
+      return;
+    }
+
+    try {
+      await this.remove(bundleId);
+    } catch (err) {
+      this.log.error(`Reset: could not remove '${bundleId}' from device: ${err.message}`);
+      throw err;
+    }
+    this.log.debug(`Reset: removed '${bundleId}'`);
+  }
+
+}
+
+export default RealDevice;