@limrun/appium-xcuitest-driver 10.11.0-lim.3 → 10.14.6-lim.1

package/lib/commands/app-management.js

@@ -1,346 +0,0 @@
-import _ from 'lodash';
-import {fs, util} from 'appium/support';
-import {errors} from 'appium/driver';
-import {services} from 'appium-ios-device';
-import path from 'node:path';
-import B from 'bluebird';
-import {
-  SUPPORTED_EXTENSIONS,
-  onPostConfigureApp,
-  onDownloadApp,
-} from '../app-utils';
-
-/**
- * Installs the given application to the device under test.
- *
- * Please ensure the app is built for a correct architecture and is signed with a proper developer signature (for real devices) prior to calling this.
- * @param {string} app - See docs for `appium:app` capability
- * @param {number} [timeoutMs] - The maximum time to wait until app install is finished (in ms) on real devices.
- * If not provided, then the value of `appium:appPushTimeout` capability is used. If the capability is not provided then the default is 240000ms (4 minutes).
- * @param {boolean} [checkVersion] - If the application installation follows currently installed application's version status if provided.
- * No checking occurs if no this option.
- * @privateRemarks Link to capability docs
- * @returns {Promise<void>}
- * @this {XCUITestDriver}
- */
-export async function mobileInstallApp(app, timeoutMs, checkVersion) {
-  const srcAppPath = await this.helpers.configureApp(app, {
-    onPostProcess: onPostConfigureApp.bind(this),
-    onDownload: onDownloadApp.bind(this),
-    supportedExtensions: SUPPORTED_EXTENSIONS,
-  });
-  this.log.info(
-    `Installing '${srcAppPath}' to the ${this.isRealDevice() ? 'real device' : 'Simulator'} ` +
-      `with UDID '${this.device.udid}'`,
-  );
-  if (!(await fs.exists(srcAppPath))) {
-    throw this.log.errorWithException(
-      `The application at '${srcAppPath}' does not exist or is not accessible`,
-    );
-  }
-
-  const bundleId = await this.appInfosCache.extractBundleId(srcAppPath);
-  if (checkVersion) {
-    const {install} = await this.checkAutInstallationState({
-      enforceAppInstall: false,
-      fullReset: false,
-      noReset: false,
-      bundleId,
-      app: srcAppPath,
-    });
-
-    if (!install) {
-      this.log.info(`Skipping the installation of '${bundleId}'`);
-      return;
-    }
-  }
-
-  await this.device.installApp(
-    srcAppPath,
-    bundleId,
-    {
-      timeoutMs: timeoutMs ?? this.opts.appPushTimeout
-    },
-  );
-  this.log.info(`Installation of '${srcAppPath}' succeeded`);
-}
-
-/**
- * Checks whether the given application is installed on the device under test.
- * Offload app is handled as not installed.
- *
- * @param {string} bundleId - The bundle identifier of the application to be checked
- * @returns {Promise<boolean>} `true` if the application is installed; `false` otherwise
- * @this {XCUITestDriver}
- */
-export async function mobileIsAppInstalled(bundleId) {
-  const installed = await this.device.isAppInstalled(bundleId);
-  this.log.info(`App '${bundleId}' is${installed ? '' : ' not'} installed`);
-  return installed;
-}
-
-/**
- * Removes/uninstalls the given application from the device under test.
- * Offload app data could also be removed.
- *
- * @param {string} bundleId - The bundle identifier of the application to be removed
- * @returns {Promise<boolean>} `true` if the application has been removed successfully; `false` otherwise
- * @this {XCUITestDriver}
- */
-export async function mobileRemoveApp(bundleId) {
-  this.log.info(
-    `Uninstalling the application with bundle identifier '${bundleId}' ` +
-    `from the ${this.isRealDevice() ? 'real device' : 'Simulator'} with UDID '${this.device.udid}'`,
-  );
-  try {
-    await this.device.removeApp(bundleId);
-    this.log.info(`Removal of '${bundleId}' succeeded`);
-    return true;
-  } catch (err) {
-    this.log.warn(`Cannot remove '${bundleId}'. Original error: ${err.message}`);
-    return false;
-  }
-}
-
-/**
- * Executes the given app on the device under test.
- *
- * If the app is already running it will be activated. If the app is not installed or cannot be launched then an exception is thrown.
- * @param {string} bundleId - The bundle identifier of the application to be launched
- * @param {string|string[]} [args] - One or more command line arguments for the app. If the app is already running then this argument is ignored.
- * @param {object} [environment] - Environment variables mapping for the app. If the app is already running then this argument is ignored.
- * @returns {Promise<void>}
- * @this {XCUITestDriver}
- */
-export async function mobileLaunchApp(bundleId, args, environment) {
-  /** @type { {arguments?: any[], environment?: any, bundleId: string} } */
-  const launchOptions = {bundleId};
-  if (args) {
-    launchOptions.arguments = Array.isArray(args) ? args : [args];
-  }
-  if (environment) {
-    launchOptions.environment = environment;
-  }
-  await this.proxyCommand('/wda/apps/launch', 'POST', launchOptions);
-}
-
-/**
- * Terminates the given app on the device under test.
- *
- * This command performs termination via [XCTest's `terminate`](https://developer.apple.com/documentation/xctest/xcuiapplication/1500637-terminate) API. If the app is not installed an exception is thrown. If the app is not running then nothing is done.
- * @param {string} bundleId - The bundle identifier of the application to be terminated
- * @returns {Promise<boolean>} `true` if the app has been terminated successfully; `false` otherwise
- * @this {XCUITestDriver}
- */
-export async function mobileTerminateApp(bundleId) {
-  return /** @type {boolean} */ (
-    await this.proxyCommand('/wda/apps/terminate', 'POST', {bundleId})
-  );
-}
-
-/**
- * Activate the given app on the device under test.
- *
- * This pushes the app to the foreground if it is running in the background.  An exception is thrown if the app is not install or isn't running.  Nothing is done if the app is already in the foreground.
- *
- * @param {string} bundleId - The bundle identifier of the application to be activated
- * @returns {Promise<void>}
- * @this {XCUITestDriver}
- */
-export async function mobileActivateApp(bundleId) {
-  await this.proxyCommand('/wda/apps/activate', 'POST', {bundleId});
-}
-
-/**
- * Kill the given app on the real device under test by instruments service.
- *
- * If the app is not running or kill failed, then nothing is done.
- *
- * @remarks `appium-xcuitest-driver` v4.4 does not require `py-ios-device` to be installed.
- * @privateRemarks See implementation at https://github.com/YueChen-C/py-ios-device/blob/51f4683c5c3c385a015858ada07a5f1c62d3cf57/ios_device/cli/base.py#L220
- * @see https://github.com/YueChen-C/py-ios-device
- * @param {string} bundleId - The bundle identifier of the application to be killed
- * @returns {Promise<boolean>} `true` if the app has been killed successfully; `false` otherwise
- * @group Real Device Only
- * @this {XCUITestDriver}
- */
-export async function mobileKillApp(bundleId) {
-  if (!this.isRealDevice()) {
-    throw new errors.UnsupportedOperationError('A real device is required');
-  }
-
-  return await /** @type {import('../device/real-device-management').RealDevice} */ (this.device).terminateApp(
-    bundleId, String(this.opts.platformVersion)
-  );
-}
-
-/**
- * Queries the state of an installed application from the device under test.
- *
- * If the app with the given `bundleId` is not installed, an exception will be thrown.
- *
- * @param {string} bundleId - The bundle identifier of the application to be queried
- * @returns {Promise<AppState>} The actual application state code
- * @see https://developer.apple.com/documentation/xctest/xcuiapplicationstate?language=objc
- * @this {XCUITestDriver}
- */
-export async function mobileQueryAppState(bundleId) {
-  return /** @type {AppState} */ (await this.proxyCommand('/wda/apps/state', 'POST', {bundleId}));
-}
-
-/**
- * @param {string} appPath
- * @param {object} opts
- * @this {XCUITestDriver}
- */
-export async function installApp(appPath, {timeoutMs, strategy} = {}) {
-  // @ts-ignore Probably a TS bug
-  await this.mobileInstallApp(appPath, timeoutMs, strategy);
-}
-
-/**
- * @param {string} bundleId
- * @param {object} opts
- * @this {XCUITestDriver}
- */
-export async function activateApp(bundleId, opts = {}) {
-  const {environment, arguments: args} = opts;
-  // @ts-ignore Probably a TS bug
-  return await this.mobileLaunchApp(bundleId, args, environment);
-}
-
-/**
- * @param {string} bundleId
- * @this {XCUITestDriver}
- */
-export async function isAppInstalled(bundleId) {
-  return await this.mobileIsAppInstalled(bundleId);
-}
-
-/**
- * @param {string} bundleId
- * @this {XCUITestDriver}
- * @returns {Promise<boolean>}
- */
-export async function terminateApp(bundleId) {
-  return await this.mobileTerminateApp(bundleId);
-}
-
-/**
- * @param {string} bundleId
- * @this {XCUITestDriver}
- */
-export async function queryAppState(bundleId) {
-  return await this.mobileQueryAppState(bundleId);
-}
-
-/**
- * List applications installed on the real device under test
- *
- * Read [Pushing/Pulling files](https://appium.io/docs/en/writing-running-appium/ios/ios-xctest-file-movement/) for more details.
- * @param {'User'|'System'} applicationType - The type of applications to list.
- * @returns {Promise<Record<string,any>[]>} A list of apps where each item is a mapping of bundle identifiers to maps of platform-specific app properties.
- * @remarks Having `UIFileSharingEnabled` set to `true` in the return app properties map means this app supports file upload/download in its `documents` container.
- * @group Real Device Only
- */
-export async function mobileListApps(applicationType = 'User') {
-  if (!this.isRealDevice()) {
-    throw new errors.NotImplementedError(`This extension is only supported on real devices`);
-  }
-
-  const service = await services.startInstallationProxyService(this.device.udid);
-  try {
-    return await service.listApplications({applicationType});
-  } finally {
-    service.close();
-  }
-}
-
-/**
- * Deletes application data files, so it could start from the clean state next time
- * it is launched.
- * This API only works on a Simulator.
- *
- * @param {string} bundleId Application bundle identifier
- * @this {XCUITestDriver}
- * @returns {Promise<boolean>} true if any files from the app's data container have been deleted
- */
-export async function mobileClearApp(bundleId) {
-  if (this.isRealDevice()) {
-    throw new errors.NotImplementedError(
-      `This extension is only supported on simulators. ` +
-      `The only known way to clear app data on real devices ` +
-      `would be to uninstall the app then perform a fresh install of it.`
-    );
-  }
-
-  const simctl = /** @type {import('appium-ios-simulator').Simulator} */ (this.device).simctl;
-  const dataRoot = await simctl.getAppContainer(bundleId, 'data');
-  this.log.debug(`Got the data container root of ${bundleId} at '${dataRoot}'`);
-  if (!await fs.exists(dataRoot)) {
-    return false;
-  }
-
-  await this.mobileTerminateApp(bundleId);
-  const items = await fs.readdir(dataRoot);
-  if (!items.length) {
-    return false;
-  }
-
-  await B.all(items.map((item) => fs.rimraf(path.join(dataRoot, item))));
-  this.log.info(
-    `Cleaned up ${util.pluralize('item', items.length, true)} from ${bundleId}'s data container`
-  );
-  return true;
-}
-
-/**
- * Close app (simulate device home button). It is possible to restore
- * the app after the timeout or keep it minimized based on the parameter value.
- *
- * @param {number|{timeout: number?}} [seconds]
- * - any positive number of seconds: come back after X seconds
- * - any negative number of seconds or zero: never come back
- * - undefined/null: never come back
- * - {timeout: 5000}: come back after 5 seconds
- * - {timeout: null}, {timeout: -2}: never come back
- * @this {XCUITestDriver}
- */
-export async function background(seconds) {
-  const homescreen = '/wda/homescreen';
-  const deactivateApp = '/wda/deactivateApp';
-
-  let endpoint;
-  let params = {};
-  const selectEndpoint = (timeoutSeconds) => {
-    if (!util.hasValue(timeoutSeconds)) {
-      endpoint = homescreen;
-    } else if (!isNaN(timeoutSeconds)) {
-      const duration = parseFloat(timeoutSeconds);
-      if (duration >= 0) {
-        params = {duration};
-        endpoint = deactivateApp;
-      } else {
-        endpoint = homescreen;
-      }
-    }
-  };
-  if (seconds && !_.isNumber(seconds) && _.has(seconds, 'timeout')) {
-    const timeout = seconds.timeout;
-    selectEndpoint(isNaN(Number(timeout)) ? timeout : parseFloat(String(timeout)) / 1000.0);
-  } else {
-    selectEndpoint(seconds);
-  }
-  if (!endpoint) {
-    throw new errors.InvalidArgumentError(
-      `Argument value is expected to be a valid number. ` +
-        `${JSON.stringify(seconds)} has been provided instead`,
-    );
-  }
-  return await this.proxyCommand(endpoint, 'POST', params, endpoint !== homescreen);
-}
-
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- * @typedef {import('./enum').AppState} AppState
- */

package/lib/commands/appearance.js

@@ -1,71 +0,0 @@
-import _ from 'lodash';
-import {util} from 'appium/support';
-
-/**
- * Set the device's UI appearance style
- *
- * @since iOS 12.0
- * @param {'dark'|'light'} style - The appearance style to set
- * @throws {Error} if the current platform does not support UI appearance changes
- * @this {XCUITestDriver}
- */
-export async function mobileSetAppearance(style) {
-  if (!['light', 'dark'].includes(_.toLower(style))) {
-    throw new Error(`The 'style' value is expected to equal either 'light' or 'dark'`);
-  }
-  if (util.compareVersions(/** @type {string} */ (this.opts.platformVersion), '<', '12.0')) {
-    throw new Error('Changing appearance is only supported since iOS 12');
-  }
-
-  if (this.isSimulator()) {
-    try {
-      return void (await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).setAppearance(style));
-    } catch (e) {
-      this.log.debug(e.stack);
-    }
-  }
-  try {
-    return void (await this.proxyCommand('/wda/device/appearance', 'POST', {name: style}, false));
-  } catch (e) {
-    this.log.debug(e.stack);
-  }
-  // Fall back to the ugly Siri workaround if the current SDK is too old
-  await this.mobileSiriCommand(`Turn ${_.toLower(style) === 'dark' ? 'on' : 'off'} dark mode`);
-}
-
-/**
- * Get the device's UI appearance style.
- *
- * @since Xcode SDK 11
- * @returns {Promise<{style: Style}>}
- * @this {XCUITestDriver}
- */
-export async function mobileGetAppearance() {
-  if (util.compareVersions(/** @type {string} */ (this.opts.platformVersion), '<', '12.0')) {
-    return {style: 'unsupported'};
-  }
-
-  /** @type {Style|undefined} */
-  let style;
-  if (this.isSimulator()) {
-    try {
-      style = /** @type {Style} */ (
-        await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).getAppearance()
-      );
-    } catch {}
-  }
-  if (!style) {
-    style = /** @type {Style} */ (
-      /** @type {any} */ (await this.proxyCommand('/wda/device/info', 'GET'))
-        ?.userInterfaceStyle ?? 'unknown'
-    );
-  }
-  return {
-    style,
-  };
-}
-
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- * @typedef {import('./types').Style} Style
- */

package/lib/commands/audit.js

@@ -1,31 +0,0 @@
-/**
- * @typedef {Object} AccessibilityAuditItem
- * @property {string} detailedDescription The detailed description of the found accessibility issue.
- * @property {string} compactDescription The compact description of the found accessibility issue.
- * @property {string|number} auditType The name of the audit type this issue belongs to. Could be
- * a number if the type name is unknown.
- * @property {string} element The description of the element this issue was found for.
- */
-
-/**
- * Performs accessibility audit of the current application according to the given type or multiple types.
- *
- * @since Xcode 15/iOS 17
- * @param {string[]?} auditTypes - One or more type names to perform the audit for.
- * The full list of available names could be found at
- * https://developer.apple.com/documentation/xctest/xcuiaccessibilityaudittype?language=objc
- * If no type if provided explicitly then XCUIAccessibilityAuditTypeAll is assumed.
- *
- * @returns {Promise<AccessibilityAuditItem[]>} List of found issues or an empty list
- *
- * @this {XCUITestDriver}
- */
-export async function mobilePerformAccessibilityAudit(auditTypes) {
-  return /** @type {AccessibilityAuditItem[]} */ (
-    await this.proxyCommand('/wda/performAccessibilityAudit', 'POST', {auditTypes})
-  );
-}
-
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

package/lib/commands/biometric.js

@@ -1,52 +0,0 @@
-import {assertSimulator as _assertSimulator} from '../utils';
-
-const assertSimulator = (driver) => _assertSimulator.call(driver, 'Biometric enrollment');
-
-/**
- * Enrolls biometric authentication on a simulated device.
- *
- * @param {boolean} isEnabled - Whether to enable/disable biometric enrollment.
- * @throws {Error} If enrollment fails or the device is not a Simulator.
- * @group Simulator Only
- * @this {XCUITestDriver}
- */
-export async function mobileEnrollBiometric(isEnabled = true) {
-  assertSimulator(this);
-
-  await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).enrollBiometric(isEnabled);
-}
-
-/**
- * Emulates biometric match or non-match event on a simulated device.
- *
- * The biometric feature is expected to be already enrolled via {@linkcode mobileEnrollBiometric|mobile: enrollBiometric} before executing this.
- *
- * @param {import('./types').BiometricFeature} type - The biometric feature name.
- * @param {boolean} match - If `true`, simulate biometic match. If `false`, simulate biometric non-match.
- * @throws {Error} If matching fails or the device is not a Simulator.
- * @group Simulator Only
- * @this {XCUITestDriver}
- */
-export async function mobileSendBiometricMatch(type = 'touchId', match = true) {
-  assertSimulator(this);
-
-  await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).sendBiometricMatch(match, type);
-}
-
-/**
- * Checks whether the biometric feature is currently enrolled on a simulated device.
- *
- * @returns {Promise<boolean>} `true` if biometric is enrolled.
- * @throws {Error} If the detection fails or the device is not a Simulator.
- * @group Simulator Only
- * @this {XCUITestDriver}
- */
-export async function mobileIsBiometricEnrolled() {
-  assertSimulator(this);
-
-  return await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).isBiometricEnrolled();
-}
-
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

package/lib/commands/clipboard.js

@@ -1,35 +0,0 @@
-/**
- * Sets the primary clipboard's content on the device under test.
- *
- * @param {string} content - The content to be set as base64 encoded string.
- * @param {string} [contentType=plaintext] - The type of the content to set.
- *                                            Only `plaintext`, 'image and 'url' are supported.
- * @this {XCUITestDriver}
- */
-export async function setClipboard(content, contentType) {
-  await this.proxyCommand('/wda/setPasteboard', 'POST', {
-    content,
-    contentType,
-  });
-}
-
-/**
- * Gets the content of the primary clipboard on the device under test.
- *
- * @param {string} [contentType=plaintext] - The type of the content to get.
- *                                            Only `plaintext`, 'image and 'url' are supported.
- * @returns {Promise<string>} The actual clipboard content encoded into base64 string.
- * An empty string is returned if the clipboard contains no data.
- * @this {XCUITestDriver}
- */
-export async function getClipboard(contentType) {
-  return /** @type {string} */ (
-    await this.proxyCommand('/wda/getPasteboard', 'POST', {
-      contentType,
-    })
-  );
-}
-
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

package/lib/commands/content-size.js

@@ -1,68 +0,0 @@
-import _ from 'lodash';
-import {assertSimulator as _assertSimulator} from '../utils';
-import { errors } from 'appium/driver';
-
-const assertSimulator = (driver) => _assertSimulator.call(driver, 'Content size ui command');
-
-const CONTENT_SIZE = [
-    'extra-small',
-    'small',
-    'medium',
-    'large',
-    'extra-large',
-    'extra-extra-large',
-    'extra-extra-extra-large',
-    'accessibility-medium',
-    'accessibility-large',
-    'accessibility-extra-large',
-    'accessibility-extra-extra-large',
-    'accessibility-extra-extra-extra-large',
-    'increment',
-    'decrement'
-];
-
-/**
- * Sets content size for the given simulator.
- *
- * @since Xcode 15 (but lower xcode could have this command)
- * @param {ContentSizeAction} size - The content size action to set. Acceptable value is
- *                                   extra-small, small, medium, large, extra-large, extra-extra-large,
- *                                   extra-extra-extra-large, accessibility-medium, accessibility-large,
- *                                   accessibility-extra-large, accessibility-extra-extra-large,
- *                                   accessibility-extra-extra-extra-large with Xcode 16.2.
- * @throws {Error} if the current platform does not support content size appearance changes
- * @this {XCUITestDriver}
- */
-export async function mobileSetContentSize(size) {
-  const simulator = assertSimulator(this);
-
-  if (!CONTENT_SIZE.includes(_.lowerCase(size))) {
-    throw new errors.InvalidArgumentError(
-      `The 'size' value is expected to be one of ${CONTENT_SIZE.join(',')}`
-    );
-  }
-
-  await simulator.setContentSize(size);
-}
-
-/**
- * Retrieves the current content size value from the given simulator.
- *
- * @since Xcode 15 (but lower xcode could have this command)
- * @returns {Promise<ContentSizeResult>} the content size value. Possible return value is
- *                                 extra-small, small, medium, large, extra-large, extra-extra-large,
- *                                 extra-extra-extra-large, accessibility-medium, accessibility-large,
- *                                 accessibility-extra-large, accessibility-extra-extra-large,
- *                                 accessibility-extra-extra-extra-large,
- *                                 unknown or unsupported with Xcode 16.2.
- * @this {XCUITestDriver}
- */
-export async function mobileGetContentSize() {
-  return /** @type {ContentSizeResult} */ (await assertSimulator(this).getContentSize());
-}
-
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- * @typedef {import('./types').ContentSizeAction} ContentSizeAction
- * @typedef {import('./types').ContentSizeResult} ContentSizeResult
- */

package/lib/commands/deviceInfo.js

@@ -1,27 +0,0 @@
-import {utilities} from 'appium-ios-device';
-
-/**
- * Returns the miscellaneous information about the device under test.
- *
- * Since XCUITest driver v4.2.0, this includes device information via lockdown in a real device.
- *
- * @returns {Promise<DeviceInfo | (DeviceInfo & LockdownInfo)>} The response of `/wda/device/info'`
- * @this {import('../driver').XCUITestDriver}
- */
-export async function mobileGetDeviceInfo() {
-  const infoByWda = /** @type {import('./types').DeviceInfo} */ (
-    await this.proxyCommand('/wda/device/info', 'GET')
-  );
-
-  if (this.isRealDevice()) {
-    const lockdownInfo = await utilities.getDeviceInfo(this.device.udid);
-    return {...infoByWda, ...{lockdownInfo}};
-  }
-
-  return infoByWda;
-}
-
-/**
- * @typedef {import('./types').DeviceInfo} DeviceInfo
- * @typedef {import('./types').LockdownInfo} LockdownInfo
- */