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

package/lib/utils.js

@@ -0,0 +1,551 @@
+import * as xcode from '@limrun/appium-xcode';
+import {errors} from 'appium/driver';
+import {fs, net, util} from 'appium/support';
+import B from 'bluebird';
+import _ from 'lodash';
+import os from 'node:os';
+import path from 'node:path';
+import url from 'node:url';
+import * as semver from 'semver';
+import {exec} from 'teen_process';
+import iosGenericSimulators from './ios-generic-simulators';
+import log from './logger';
+import {PLATFORM_NAME_TVOS, PLATFORM_NAME_IOS} from './desired-caps';
+
+export const UDID_AUTO = 'auto';
+const MODULE_NAME = 'appium-xcuitest-driver';
+const DEFAULT_TIMEOUT_KEY = 'default';
+const XCTEST_LOG_FILES_PATTERNS = [
+  /^Session-WebDriverAgentRunner.*\.log$/i,
+  /^StandardOutputAndStandardError\.txt$/i,
+];
+const XCTEST_LOGS_CACHE_FOLDER_PREFIX = 'com.apple.dt.XCTest';
+export const NATIVE_WIN = 'NATIVE_APP';
+
+/**
+ * @privateRemarks Is the minimum version really Xcode 7.3?
+ * @returns {Promise<XcodeVersion>}
+ */
+async function getAndCheckXcodeVersion() {
+  /** @type {XcodeVersion} */
+  let version;
+  try {
+    version = /** @type {XcodeVersion} */ (await xcode.getVersion(true));
+  } catch (err) {
+    log.error(err);
+    throw new Error(`Could not determine Xcode version: ${err.message}`);
+  }
+
+  // we do not support Xcodes < 7.3,
+  if (version.versionFloat < 7.3) {
+    const msg = `Xcode ${version.versionString} is not supported. Please upgrade to version 7.3 or higher`;
+    log.error(msg);
+    throw new Error(msg);
+  }
+  return version;
+}
+
+/**
+ * @returns {Promise<string|null>}
+ */
+async function getAndCheckIosSdkVersion() {
+  try {
+    return '26';
+    return await xcode.getMaxIOSSDK();
+  } catch (err) {
+    throw log.errorWithException(`Could not determine iOS SDK version: ${err.message}`);
+  }
+}
+
+/**
+ * Get the generic simulator for a given IOS version and device type (iPhone, iPad)
+ *
+ * @param {string|number} platformVersion IOS version. e.g.) 13.0
+ * @param {string} deviceName Type of IOS device. Can be iPhone, iPad (possibly more in the future)
+ *
+ * @returns {string?} Generic iPhone or iPad simulator (if applicable)
+ */
+function getGenericSimulatorForIosVersion(platformVersion, deviceName) {
+  const genericSimulators = iosGenericSimulators[deviceName];
+  if (!genericSimulators) {
+    return null;
+  }
+
+  // Find the highest iOS version in the list that is below the provided version
+  let result = null;
+  const compareVersions = ([simOne], [simTwo]) =>
+    util.compareVersions(simOne, '<', simTwo) ? -1 : 1;
+  for (const [platformVersionFromList, iosSimulator] of genericSimulators.sort(compareVersions)) {
+    if (util.compareVersions(platformVersionFromList, '>', String(platformVersion))) {
+      break;
+    }
+    result = iosSimulator;
+  }
+  return result;
+}
+
+/**
+ *
+ * @param {string} platformVersion
+ * @param {string} deviceName
+ * @returns {string}
+ */
+function translateDeviceName(platformVersion, deviceName) {
+  if (!deviceName) {
+    return deviceName;
+  }
+  const deviceNameTranslated = getGenericSimulatorForIosVersion(
+    platformVersion,
+    `${deviceName}`.toLowerCase().trim(),
+  );
+  if (!deviceNameTranslated) {
+    return deviceName;
+  }
+
+  log.debug(`Changing deviceName from '${deviceName}' to '${deviceNameTranslated}'`);
+  return deviceNameTranslated;
+}
+
+/**
+ * @param {string[]} locations
+ * @returns {Promise<void>}
+ */
+async function clearLogs(locations) {
+  log.debug('Clearing log files');
+  const cleanupPromises = [];
+  for (const location of locations) {
+    if (!(await fs.exists(location))) {
+      continue;
+    }
+
+    cleanupPromises.push(
+      (async () => {
+        let size;
+        try {
+          const {stdout} = await exec('du', ['-sh', location]);
+          size = stdout.trim().split(/\s+/)[0];
+        } catch {}
+        try {
+          log.debug(`Deleting '${location}'. ${size ? `Freeing ${size}.` : ''}`);
+          await fs.rimraf(location);
+        } catch (err) {
+          log.warn(`Unable to delete '${location}': ${err.message}`);
+        }
+      })(),
+    );
+  }
+  if (!_.isEmpty(cleanupPromises)) {
+    await B.all(cleanupPromises);
+  }
+  log.debug('Finished clearing log files');
+}
+
+// This map contains derived data logs folders as keys
+// and values are the count of times the particular
+// folder has been scheduled for removal
+const derivedDataCleanupMarkers = new Map();
+
+async function markSystemFilesForCleanup(wda) {
+  if (!wda || !(await wda.retrieveDerivedDataPath())) {
+    log.warn(
+      'No WebDriverAgent derived data available, so unable to mark system files for cleanup',
+    );
+    return;
+  }
+
+  const logsRoot = path.resolve(await wda.retrieveDerivedDataPath(), 'Logs');
+  let markersCount = 0;
+  if (derivedDataCleanupMarkers.has(logsRoot)) {
+    markersCount = derivedDataCleanupMarkers.get(logsRoot);
+  }
+  derivedDataCleanupMarkers.set(logsRoot, ++markersCount);
+}
+
+async function clearSystemFiles(wda) {
+  // only want to clear the system files for the particular WDA xcode run
+  if (!wda || !(await wda.retrieveDerivedDataPath())) {
+    log.warn('No WebDriverAgent derived data available, so unable to clear system files');
+    return;
+  }
+
+  const logsRoot = path.resolve(await wda.retrieveDerivedDataPath(), 'Logs');
+  if (derivedDataCleanupMarkers.has(logsRoot)) {
+    let markersCount = derivedDataCleanupMarkers.get(logsRoot);
+    derivedDataCleanupMarkers.set(logsRoot, --markersCount);
+    if (markersCount > 0) {
+      log.info(
+        `Not cleaning '${logsRoot}' folder, because the other session does not expect it to be cleaned`,
+      );
+      return;
+    }
+  }
+  derivedDataCleanupMarkers.set(logsRoot, 0);
+
+  // Cleaning up big temporary files created by XCTest: https://github.com/appium/appium/issues/9410
+  const globPattern = `${os.tmpdir()}/${XCTEST_LOGS_CACHE_FOLDER_PREFIX}*/`;
+  const dstFolders = await fs.glob(globPattern);
+  if (_.isEmpty(dstFolders)) {
+    log.debug(`Did not find the temporary XCTest logs root at '${globPattern}'`);
+  } else {
+    // perform the cleanup asynchronously
+    /** @type {Promise[]} */
+    const promises = [];
+    for (const dstFolder of dstFolders) {
+      const promise = (async () => {
+        try {
+          await fs.walkDir(dstFolder, true, (itemPath, isDir) => {
+            if (isDir) {
+              return;
+            }
+            const fileName = path.basename(itemPath);
+            if (XCTEST_LOG_FILES_PATTERNS.some((p) => p.test(fileName))) {
+              fs.rimraf(itemPath);
+            }
+          });
+        } catch (e) {
+          log.debug(e.stack);
+          log.info(e.message);
+        }
+      })();
+      promises.push(promise);
+    }
+    log.debug(`Started XCTest logs cleanup in '${dstFolders}'`);
+    if (promises.length) {
+      await B.all(promises);
+    }
+  }
+
+  if (await fs.exists(logsRoot)) {
+    log.info(`Cleaning test logs in '${logsRoot}' folder`);
+    await clearLogs([logsRoot]);
+    return;
+  }
+  log.info(`There is no ${logsRoot} folder, so not cleaning files`);
+}
+
+async function checkAppPresent(app) {
+  log.debug(`Checking whether app '${app}' is actually present on file system`);
+  if (!(await fs.exists(app))) {
+    throw log.errorWithException(`Could not find app at '${app}'`);
+  }
+  log.debug('App is present');
+}
+
+/**
+ * Reads the content to the current module's package.json
+ *
+ * @returns {Promise<Record<string, any>>} The full path to module root
+ * @throws {Error} If the current module's package.json cannot be determined
+ */
+const getModuleManifest = _.memoize(async function getModuleManifest() {
+  let currentDir = path.dirname(path.resolve(__filename));
+  let isAtFsRoot = false;
+  while (!isAtFsRoot) {
+    const manifestPath = path.join(currentDir, 'package.json');
+    try {
+      if (await fs.exists(manifestPath)) {
+        const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+        if (manifest.name === MODULE_NAME) {
+          return manifest;
+        }
+      }
+    } catch {}
+    currentDir = path.dirname(currentDir);
+    isAtFsRoot = currentDir.length <= path.dirname(currentDir).length;
+  }
+  throw new Error(`Cannot find the package manifest of the ${MODULE_NAME} Node.js module`);
+});
+
+/**
+ * @typedef {Object} DriverInfo
+ * @property {string} version Driver version string
+ * @property {string} built Driver build timestamp
+ */
+
+/**
+ * @returns {DriverInfo}
+ */
+const getDriverInfo = _.memoize(async function getDriverInfo() {
+  const [stat, manifest] = await B.all([
+    fs.stat(path.resolve(__dirname, '..')),
+    getModuleManifest(),
+  ]);
+  return {
+    built: stat.mtime.toString(),
+    version: manifest.version,
+  };
+});
+
+function normalizeCommandTimeouts(value) {
+  // The value is normalized already
+  if (typeof value !== 'string') {
+    return value;
+  }
+
+  let result = {};
+  // Use as default timeout for all commands if a single integer value is provided
+  if (!isNaN(Number(value))) {
+    result[DEFAULT_TIMEOUT_KEY] = _.toInteger(value);
+    return result;
+  }
+
+  // JSON object has been provided. Let's parse it
+  try {
+    result = JSON.parse(value);
+    if (!_.isPlainObject(result)) {
+      throw new Error();
+    }
+  } catch {
+    throw log.errorWithException(
+      `"commandTimeouts" capability should be a valid JSON object. "${value}" was given instead`,
+    );
+  }
+  for (let [cmd, timeout] of _.toPairs(result)) {
+    if (!_.isInteger(timeout) || timeout <= 0) {
+      throw log.errorWithException(
+        `The timeout for "${cmd}" should be a valid natural number of milliseconds. "${timeout}" was given instead`,
+      );
+    }
+  }
+  return result;
+}
+
+async function printUser() {
+  try {
+    let {stdout} = await exec('whoami');
+    log.debug(`Current user: '${stdout.trim()}'`);
+  } catch (err) {
+    log.debug(`Unable to get username running server: ${err.message}`);
+  }
+}
+
+/**
+ * Get the IDs of processes listening on the particular system port.
+ * It is also possible to apply additional filtering based on the
+ * process command line.
+ *
+ * @param {string|number} port - The port number.
+ * @param {?Function} filteringFunc - Optional lambda function, which
+ *                                    receives command line string of the particular process
+ *                                    listening on given port, and is expected to return
+ *                                    either true or false to include/exclude the corresponding PID
+ *                                    from the resulting array.
+ * @returns {Promise<string[]>} - the list of matched process ids.
+ */
+async function getPIDsListeningOnPort(port, filteringFunc = null) {
+  const result = [];
+  try {
+    // This only works since Mac OS X El Capitan
+    const {stdout} = await exec('lsof', ['-ti', `tcp:${port}`]);
+    result.push(...stdout.trim().split(/\n+/));
+  } catch {
+    return result;
+  }
+
+  if (!_.isFunction(filteringFunc)) {
+    return result;
+  }
+  return await B.filter(result, async (x) => {
+    const {stdout} = await exec('ps', ['-p', x, '-o', 'command']);
+    return await filteringFunc(stdout);
+  });
+}
+
+/**
+ * @typedef {Object} UploadOptions
+ *
+ * @property {string} [user] - The name of the user for the remote authentication. Only works if `remotePath` is provided.
+ * @property {string} [pass] - The password for the remote authentication. Only works if `remotePath` is provided.
+ * @property {import('axios').Method} [method] - The http multipart upload method name. The 'PUT' one is used by default.
+ *                              Only works if `remotePath` is provided.
+ * @property {import('@appium/types').HTTPHeaders} [headers] - Additional headers mapping for multipart http(s) uploads
+ * @property {string} [fileFieldName] [file] - The name of the form field, where the file content BLOB should be stored for
+ *                                            http(s) uploads
+ * @property {Record<string, any> | [string, any][]} [formFields] - Additional form fields for multipart http(s) uploads
+ */
+
+/**
+ * Encodes the given local file to base64 and returns the resulting string
+ * or uploads it to a remote server using http/https or ftp protocols
+ * if `remotePath` is set
+ *
+ * @param {string} localPath - The path to an existing local file
+ * @param {string|null} [remotePath] - The path to the remote location, where
+ *                               this file should be uploaded
+ * @param {UploadOptions} uploadOptions - Set of upload options
+ * @returns {Promise<string>} Either an empty string if the upload was successful or
+ * base64-encoded file representation if `remotePath` is falsy
+ */
+async function encodeBase64OrUpload(localPath, remotePath = null, uploadOptions = {}) {
+  if (!(await fs.exists(localPath))) {
+    throw log.errorWithException(`The file at '${localPath}' does not exist or is not accessible`);
+  }
+
+  if (_.isEmpty(remotePath)) {
+    const {size} = await fs.stat(localPath);
+    log.debug(`The size of the file is ${util.toReadableSizeString(size)}`);
+    return (await util.toInMemoryBase64(localPath)).toString();
+  }
+
+  const {user, pass, method, headers, fileFieldName, formFields} = uploadOptions;
+  const options = {
+    method: method || 'PUT',
+    headers,
+    fileFieldName,
+    formFields,
+  };
+  if (user && pass) {
+    options.auth = {user, pass};
+  }
+  await net.uploadFile(localPath, /** @type {string} */ (remotePath), options);
+  return '';
+}
+
+/**
+ * Stops and removes all web socket handlers that are listening
+ * in scope of the current session.
+ *
+ * @this {XCUITestDriver}
+ * @returns {Promise<void>}
+ */
+export async function removeAllSessionWebSocketHandlers() {
+  if (!this.sessionId || !_.isFunction(this.server?.getWebSocketHandlers)) {
+    return;
+  }
+
+  const activeHandlers = await this.server.getWebSocketHandlers(this.sessionId);
+  for (const pathname of _.keys(activeHandlers)) {
+    await this.server.removeWebSocketHandler(pathname);
+  }
+}
+
+/**
+ * Returns true if the urlString is localhost
+ * @param {string} urlString
+ * @returns {boolean} Return true if the urlString is localhost
+ */
+function isLocalHost(urlString) {
+  try {
+    const hostname = /** @type {string} */ (url.parse(urlString).hostname);
+    return ['localhost', '127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(hostname);
+  } catch {
+    log.warn(`'${urlString}' cannot be parsed as a valid URL`);
+  }
+  return false;
+}
+
+/**
+ * Normalizes platformVersion to a valid iOS version string
+ *
+ * @param {string} originalVersion - Loose version number, that can be parsed by semver
+ * @return {string} iOS version number in <major>.<minor> format
+ * @throws {Error} if the version number cannot be parsed
+ */
+function normalizePlatformVersion(originalVersion) {
+  const normalizedVersion = semver.coerce(originalVersion);
+  if (!normalizedVersion) {
+    throw new Error(`The platform version '${originalVersion}' should be a valid version number`);
+  }
+  return `${normalizedVersion.major}.${normalizedVersion.minor}`;
+}
+
+/**
+ * Assert the presence of particular keys in the given object
+ *
+ * @param {string|Array<string>} argNames one or more key names
+ * @param {Object} opts the object to check
+ * @returns {Object} the same given object
+ */
+function requireArgs(argNames, opts = {}) {
+  for (const argName of _.isArray(argNames) ? argNames : [argNames]) {
+    if (!_.has(opts, argName)) {
+      throw new errors.InvalidArgumentError(`'${argName}' argument must be provided`);
+    }
+  }
+  return opts;
+}
+
+/**
+ * Asserts that the given driver is running on a Simulator and return
+ * the simlator instance.
+ *
+ * @param {string} action - Description of action
+ * @param {import('./driver').XCUITestDriver} driver
+ * @returns {Simulator}
+ */
+export function assertSimulator(action, driver) {
+  if (!driver.isSimulator()) {
+    throw new Error(`${_.upperFirst(action)} can only be performed on Simulator`);
+  }
+  return /** @type{Simulator} */ (driver.device);
+}
+
+/**
+ * Check if platform name is the TV OS one.
+ *
+ * @param {string|null|undefined} platformName
+ * @returns {boolean}
+ */
+export function isTvOs(platformName) {
+  return _.toLower(platformName ?? '') === _.toLower(PLATFORM_NAME_TVOS);
+}
+
+/**
+ * Return normalized platform name.
+ *
+ * @param {string|null|undefined} platformName
+ * @returns {string}
+ */
+export function normalizePlatformName(platformName) {
+  return isTvOs(platformName) ? PLATFORM_NAME_TVOS : PLATFORM_NAME_IOS;
+}
+
+/**
+ * @param {import('./driver').XCUITestDriverOpts} opts
+ * @returns {boolean}
+ */
+export function shouldSetInitialSafariUrl(opts) {
+  return !(opts.safariInitialUrl === '' || (opts.noReset && _.isNil(opts.safariInitialUrl)))
+    && !opts.initialDeeplinkUrl;
+}
+
+/**
+ * @param {import('./driver').XCUITestDriverOpts} opts
+ * @returns {boolean}
+ */
+export function isIos17OrNewer(opts) {
+  return !!opts.platformVersion && util.compareVersions(opts.platformVersion, '>=', '17.0');
+}
+
+/**
+ * @param {import('./driver').XCUITestDriverOpts} opts
+ * @returns {boolean}
+ */
+export function isIos18OrNewer(opts) {
+  return !!opts.platformVersion && util.compareVersions(opts.platformVersion, '>=', '18.0');
+}
+
+export {
+  getAndCheckXcodeVersion,
+  getAndCheckIosSdkVersion,
+  checkAppPresent,
+  getDriverInfo,
+  clearSystemFiles,
+  translateDeviceName,
+  normalizeCommandTimeouts,
+  DEFAULT_TIMEOUT_KEY,
+  markSystemFilesForCleanup,
+  printUser,
+  getPIDsListeningOnPort,
+  encodeBase64OrUpload,
+  isLocalHost,
+  normalizePlatformVersion,
+  clearLogs,
+  requireArgs,
+};
+
+/**
+ * @typedef {import('@limrun/appium-xcode').XcodeVersion} XcodeVersion
+ * @typedef {import('@limrun/appium-ios-simulator').Simulator} Simulator
+ * @typedef {import('./driver').XCUITestDriver} XCUITestDriver
+ */

package/lib/xcrun.js

@@ -0,0 +1,16 @@
+import {fs} from 'appium/support';
+
+const XCRUN = 'xcrun';
+
+async function requireXcrun() {
+  try {
+    return await fs.which(XCRUN);
+  } catch {
+    throw new Error(
+      `${XCRUN} has not been found in PATH. ` +
+        `Please make sure XCode development tools are installed`,
+    );
+  }
+}
+
+export {requireXcrun, XCRUN};