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

package/lib/commands/biometric.ts

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

package/lib/commands/{certificate.js → certificate.ts}

@@ -9,6 +9,9 @@ import {exec} from 'teen_process';
 import {findAPortNotInUse, checkPortStatus} from 'portscanner';
 import {Pyidevice} from '../device/clients/py-ios-device-client';
 import {errors} from 'appium/driver';
+import type {Simulator} from 'appium-ios-simulator';
+import type {XCUITestDriver} from '../driver';
+import type {CertificateList} from './types';
 
 const CONFIG_EXTENSION = 'mobileconfig';
 const HOST_PORT_RANGE = [38200, 38299];
@@ -62,11 +65,8 @@ const OPEN_SSL_PATTERN = /,\sCN\s=\s([^,]+)/;
 
 /**
  * Parses the common name of the certificate from the given string.
- *
- * @param {string} stringCertificate
- * @returns {string} The common name of the certificate
  */
-export function parseCommonName(stringCertificate) {
+export function parseCommonName(stringCertificate: string): string {
   const result = [LIBRE_SSL_PATTERN, OPEN_SSL_PATTERN].reduce((acc, r) => {
     if (acc) {
       return acc;
@@ -87,22 +87,28 @@ export function parseCommonName(stringCertificate) {
  * certificates on Simulator over CLI.
  *
  * On real devices (or simulators before Xcode SDK 11.4), Apple provides no "official" way to do this via the command line.  In such a case (and also as a fallback if CLI setup fails), this method tries to wrap the certificate into `.mobileconfig` format, then deploys the wrapped file to the internal HTTP server so that it can be opened via mobile Safari. This command then goes through the profile installation procedure by clicking the necessary buttons using WebDriverAgent.
- * @param {string} content - Base64-encoded content of the public certificate in [PEM](https://knowledge.digicert.com/quovadis/ssl-certificates/ssl-general-topics/what-is-pem-format.html) format
- * @param {string} [commonName] - Common name of the certificate. If this is not set, the command will try to parse it from the provided `content`.
- * @param {boolean} isRoot - Defines where the certificate should be installed; either the Trusted Root Store (`true`) or the Keychain (`false`). On environments other than Xcode 11.4+ Simulator, this option is ignored.
- * @returns {Promise<string|void>} The content of the generated `.mobileconfig` file as
+ * @param content - Base64-encoded content of the public certificate in [PEM](https://knowledge.digicert.com/quovadis/ssl-certificates/ssl-general-topics/what-is-pem-format.html) format
+ * @param commonName - Common name of the certificate. If this is not set, the command will try to parse it from the provided `content`.
+ * @param isRoot - Defines where the certificate should be installed; either the Trusted Root Store (`true`) or the Keychain (`false`). On environments other than Xcode 11.4+ Simulator, this option is ignored.
+ * @returns The content of the generated `.mobileconfig` file as
  * a base64-encoded string. This config might be useful for debugging purposes.  If the certificate has been successfully set via CLI, then nothing is returned.
- * @this {XCUITestDriver}
  */
-export async function mobileInstallCertificate(content, commonName, isRoot = true) {
+export async function mobileInstallCertificate(
+  this: XCUITestDriver,
+  content: string,
+  commonName?: string,
+  isRoot = true,
+): Promise<string | void> {
   if (_.isEmpty(content)) {
     throw new Error('Certificate content should not be empty');
   }
 
   if (this.isSimulator()) {
     try {
-      const methodName = isRoot ? 'addRootCertificate' : 'addCertificate';
-      await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).simctl[methodName](Buffer.from(content, 'base64').toString(), {
+      const methodName: 'addRootCertificate' | 'addCertificate' = isRoot
+        ? 'addRootCertificate'
+        : 'addCertificate';
+      await (this.device as Simulator).simctl[methodName](Buffer.from(content, 'base64').toString(), {
         raw: true,
       });
       return;
@@ -188,11 +194,12 @@ export async function mobileInstallCertificate(content, commonName, isRoot = tru
           }
         }
       } else {
-        await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).openUrl(certUrl);
+        await (this.device as Simulator).openUrl(certUrl);
       }
 
       let isCertAlreadyInstalled = false;
-      if (util.compareVersions(/** @type {string} */ (this.opts.platformVersion), '>=', '12.2')) {
+      const platformVersion = this.opts.platformVersion ?? '';
+      if (util.compareVersions(platformVersion, '>=', '12.2')) {
         if (await installPost122Certificate(this, cn)) {
           await clickElement(this, Settings.Profile);
           await trustCertificateInPreferences(this, cn);
@@ -238,17 +245,19 @@ export async function mobileInstallCertificate(content, commonName, isRoot = tru
  *
  * @see https://github.com/YueChen-C/py-ios-device
  * @since 4.19.2
- * @param {string} name - Name of the profile
- * @returns {Promise<string>} Returns status acknowledgment status if
- * tht certificate is successfully removed or 'None' (basically just
- * forwards the original pyidevice output)
+ * @param name - Name of the profile
+ * @returns Status acknowledgment if
+ * the certificate is successfully removed or 'None' (forwards pyidevice output)
  * @throws {Error} If attempting to remove certificates for a simulated device or if `py-ios-device` is not installed
  * @group Real Device Only
  */
-export async function mobileRemoveCertificate(name) {
+export async function mobileRemoveCertificate(this: XCUITestDriver, name: string): Promise<string> {
   if (!this.isRealDevice()) {
     throw new errors.NotImplementedError('This extension is only supported on real devices');
   }
+  if (!this.opts.udid) {
+    throw new Error('udid capability is required');
+  }
   const client = new Pyidevice({
     udid: this.opts.udid,
     log: this.log,
@@ -263,11 +272,10 @@ export async function mobileRemoveCertificate(name) {
  * This only works _if and only if_ `py-ios-device` is installed on the same machine Appium is running on.
  * @since 4.10.0
  * @see https://github.com/YueChen-C/py-ios-device
- * @returns {Promise<import('./types').CertificateList>} An object describing the certificates installed on the real device.
+ * @returns An object describing the certificates installed on the real device.
  * @throws {Error} If attempting to list certificates for a simulated device or if `py-ios-device` is not installed
- * @this {XCUITestDriver}
  */
-export async function mobileListCertificates() {
+export async function mobileListCertificates(this: XCUITestDriver): Promise<CertificateList> {
   if (!this.isRealDevice()) {
     throw new errors.NotImplementedError('This extension is only supported on real devices');
   }
@@ -287,9 +295,9 @@ export async function mobileListCertificates() {
  * Extracts the common name of the certificate from the given buffer.
  *
  * @param {Buffer} certBuffer
- * @returns {Promise<string>} The common name of the certificate
+ * @returns The common name of the certificate
  */
-async function extractCommonName(certBuffer) {
+async function extractCommonName(certBuffer: Buffer): Promise<string> {
   const tempCert = await tempDir.open({
     prefix: 'cert',
     suffix: '.cer',
@@ -315,12 +323,12 @@ async function extractCommonName(certBuffer) {
  * for more details on such profiles.
  *
  * @param {Buffer} certBuffer - The actual content of PEM certificate encoded into NodeJS buffer
- * @param {string} commonName - Certificate's common name
+ * @param commonName - Certificate's common name
  * @returns {Object} The encoded structure of the given certificate, which is ready to be passed
  * as an argument to plist builder
  * @throws {Error} If the given certificate cannot be parsed
  */
-function toMobileConfig(certBuffer, commonName) {
+function toMobileConfig(certBuffer: Buffer, commonName: string): Record<string, any> {
   const getUUID = () => util.uuidV4().toUpperCase();
   const contentUuid = getUUID();
   return {
@@ -345,8 +353,12 @@ function toMobileConfig(certBuffer, commonName) {
   };
 }
 
-async function clickElement(driver, locator, options = {}) {
-  let element = null;
+async function clickElement(
+  driver: XCUITestDriver,
+  locator: {type: string; value: string},
+  options: {timeout?: number; skipIfInvisible?: boolean} = {},
+): Promise<boolean> {
+  let element: any = null;
   const {timeout = 5000, skipIfInvisible = false} = options;
   const lookupDelay = 500;
   try {
@@ -365,7 +377,7 @@ async function clickElement(driver, locator, options = {}) {
   return true;
 }
 
-async function installPre122Certificate(driver) {
+async function installPre122Certificate(driver: XCUITestDriver): Promise<boolean> {
   // Accept Safari alert
   await clickElement(driver, Button.Allow, {
     // certificate load might take some time on slow machines
@@ -393,7 +405,7 @@ async function installPre122Certificate(driver) {
   return true;
 }
 
-async function trustCertificateInPreferences(driver, name) {
+async function trustCertificateInPreferences(driver: XCUITestDriver, name: string): Promise<void> {
   await clickElement(driver, Settings.General);
   await clickElement(driver, Settings.About);
   const switchLocator = {
@@ -401,14 +413,12 @@ async function trustCertificateInPreferences(driver, name) {
     value: `**/XCUIElementTypeCell[\`label == '${name}'\`]/**/XCUIElementTypeSwitch`,
   };
   await retry(5, async () => {
-    await driver.mobileSwipe({
-      element: await driver.findNativeElementOrElements(
-        'class name',
-        'XCUIElementTypeTable',
-        false,
-      ),
-      direction: 'up',
-    });
+    const tableEl = await driver.findNativeElementOrElements(
+      'class name',
+      'XCUIElementTypeTable',
+      false,
+    );
+    await driver.mobileSwipe('up', undefined, tableEl);
     await clickElement(driver, Settings.Certificate_Trust_Settings, {
       timeout: 500,
     });
@@ -433,7 +443,7 @@ async function trustCertificateInPreferences(driver, name) {
   }
 }
 
-async function installPost122Certificate(driver, name) {
+async function installPost122Certificate(driver: XCUITestDriver, name: string): Promise<boolean> {
   // Accept Safari alert
   await clickElement(driver, Button.Allow, {
     // certificate load might take some time on slow machines
@@ -466,14 +476,12 @@ async function installPost122Certificate(driver, name) {
       break;
     }
 
-    await driver.mobileSwipe({
-      element: await driver.findNativeElementOrElements(
-        'class name',
-        'XCUIElementTypeTable',
-        false,
-      ),
-      direction: 'up',
-    });
+    const tableEl = await driver.findNativeElementOrElements(
+      'class name',
+      'XCUIElementTypeTable',
+      false,
+    );
+    await driver.mobileSwipe('up', undefined, tableEl);
   }
   if (!isCertFound) {
     throw new Error(`'${name}' cannot be found in the certificates list`);
@@ -498,6 +506,3 @@ async function installPost122Certificate(driver, name) {
   return true;
 }
 
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

package/lib/commands/clipboard.ts

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

package/lib/commands/{condition.js → condition.ts}

@@ -1,24 +1,25 @@
 import {INSTRUMENT_CHANNEL, services} from 'appium-ios-device';
 import _ from 'lodash';
 import { isIos18OrNewer } from '../utils';
+import type {XCUITestDriver} from '../driver';
+import type {DVTServiceWithConnection} from 'appium-ios-remotexpc';
+import type {Condition} from './types';
 
 /**
  * Get all available ConditionInducer configuration information, which can be used with
  * {@linkcode XCUITestDriver.enableConditionInducer}
- * @returns {Promise<Condition[]>}
  * @since 4.9.0
  * @see {@link https://help.apple.com/xcode/mac/current/#/dev308429d42}
- * @this {XCUITestDriver}
  */
-export async function listConditionInducers() {
+export async function listConditionInducers(this: XCUITestDriver): Promise<Condition[]> {
   requireConditionInducerCompatibleDevice.call(this);
 
   if (isIos18OrNewer(this.opts)) {
     const dvtConnection = await startRemoteXPC(this.device.udid);
     try {
       const result = await dvtConnection.conditionInducer.list();
-      return /** @type {Condition[]} */ (result);
-    } catch (err) {
+      return result as Condition[];
+    } catch (err: any) {
       this.log.error(`Failed to list condition inducers via RemoteXPC: ${err.message}`);
       throw err;
     } finally {
@@ -50,15 +51,18 @@ export async function listConditionInducers() {
  * (Note: the socket needs to remain connected during operation)
  * (Note: Device conditions are available only for real devices running iOS 13.0 and later.)
  *
- * @param {string} conditionID - Determine which condition IDs are available with the {@linkcode XCUITestDriver.listConditionInducers} command
- * @param {string} profileID - Determine which profile IDs are available with the {@linkcode XCUITestDriver.listConditionInducers} command
- * @returns {Promise<boolean>} `true` if enabling the condition succeeded
+ * @param conditionID - Determine which condition IDs are available with the {@linkcode XCUITestDriver.listConditionInducers} command
+ * @param profileID - Determine which profile IDs are available with the {@linkcode XCUITestDriver.listConditionInducers} command
+ * @returns `true` if enabling the condition succeeded
  * @throws {Error} If you try to start another Condition and the previous Condition has not stopped
  * @since 4.9.0
  * @see {@link https://help.apple.com/xcode/mac/current/#/dev308429d42}
- * @this {XCUITestDriver}
  */
-export async function enableConditionInducer(conditionID, profileID) {
+export async function enableConditionInducer(
+  this: XCUITestDriver,
+  conditionID: string,
+  profileID: string,
+): Promise<boolean> {
   requireConditionInducerCompatibleDevice.call(this);
 
   if (isIos18OrNewer(this.opts)) {
@@ -76,7 +80,7 @@ export async function enableConditionInducer(conditionID, profileID) {
 
       this.log.info(`Successfully enabled condition profile: ${profileID}`);
       return true;
-    } catch (err) {
+    } catch (err: any) {
       await closeRemoteXPC.call(this);
       throw this.log.errorWithException(`Condition inducer '${profileID}' cannot be enabled: '${err.message}'`);
     }
@@ -109,12 +113,11 @@ export async function enableConditionInducer(conditionID, profileID) {
  * condition inducer will be automatically disabled
  *
  * (Note: this is also automatically called upon session cleanup)
- * @returns {Promise<boolean>} `true` if disable the condition succeeded
+ * @returns `true` if disable the condition succeeded
  * @since 4.9.0
  * @see {@link https://help.apple.com/xcode/mac/current/#/dev308429d42}
- * @this {XCUITestDriver}
  */
-export async function disableConditionInducer() {
+export async function disableConditionInducer(this: XCUITestDriver): Promise<boolean> {
   requireConditionInducerCompatibleDevice.call(this);
 
   if (isIos18OrNewer(this.opts)) {
@@ -127,7 +130,7 @@ export async function disableConditionInducer() {
       await this._remoteXPCConditionInducerConnection.conditionInducer.disable();
       this.log.info('Successfully disabled condition inducer');
       return true;
-    } catch (err) {
+    } catch (err: any) {
       this.log.warn(`Failed to disable condition inducer via RemoteXPC: ${err.message}`);
       return false;
     } finally {
@@ -158,81 +161,22 @@ export async function disableConditionInducer() {
   }
 }
 
-/**
- * @this {XCUITestDriver}
- * @returns {void}
- */
-function requireConditionInducerCompatibleDevice() {
+function requireConditionInducerCompatibleDevice(this: XCUITestDriver): void {
   if (this.isSimulator()) {
     throw this.log.errorWithException('Condition inducer only works on real devices');
   }
 }
 
-/**
- * @param {string} udid
- * @returns {Promise<DVTServiceWithConnection>}
- */
-async function startRemoteXPC(udid) {
+async function startRemoteXPC(udid: string): Promise<DVTServiceWithConnection> {
   const {Services} = await import('appium-ios-remotexpc');
   return Services.startDVTService(udid);
 }
 
-/**
- * @this {XCUITestDriver}
- * @returns {Promise<void>}
- */
-async function closeRemoteXPC() {
+async function closeRemoteXPC(this: XCUITestDriver): Promise<void> {
   if (this._remoteXPCConditionInducerConnection) {
     await this._remoteXPCConditionInducerConnection.remoteXPC.close();
     this._remoteXPCConditionInducerConnection = null;
   }
 }
 
-/**
- * @typedef {import('appium-ios-remotexpc', {with: {'resolution-mode': 'import'}}).DVTServiceWithConnection} DVTServiceWithConnection
- */
-
-/**
- * @typedef {Object} Profile
- * @property {string} name
- * @property {string} identifier the property is profileID used in {@linkcode XCUITestDriver.enableConditionInducer}
- * @property {string} description Configuration details
- */
-
-/**
- * We can use the returned data to determine whether the Condition is enabled and the currently enabled configuration information
- * @typedef {Object} Condition
- * @property {Profile[]} profiles
- * @property {string} identifier the property is conditionID used in {@linkcode XCUITestDriver.enableConditionInducer}
- * @property {boolean} profilesSorted
- * @property {boolean} isDestructive
- * @property {boolean} isInternal
- * @property {boolean} isActive `true` if this condition identifier is enabled
- * @property {string} activeProfile  enabled profiles identifier
- * @example {
- *     "profiles": [
- *          {
- *             "name": "100% packet loss",
- *             "identifier": "SlowNetwork100PctLoss",  // MobileEnableConditionInducer profileID
- *             "description": "Name: 100% Loss Scenario\n
- *                             Downlink Bandwidth: 0 Mbps\n
- *                             Downlink Latency:0 ms\n
- *                             Downlink Packet Loss Ratio: 100%\n
- *                             Uplink Bandwidth: 0 Mbps\n
- *                             Uplink Latency: 0 ms\n
- *                             Uplink Packet Loss Ratio: 100%"
- *         }
- *     ],
- *     "profilesSorted": true,
- *     "identifier": "SlowNetworkCondition",    // MobileEnableConditionInducer conditionID
- *     "isDestructive": false,
- *     "isInternal": false,
- *     "activeProfile": "",
- *     "name": "Network Link",
- *     "isActive": false
- * }
- */
 
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

package/lib/commands/content-size.ts

@@ -0,0 +1,67 @@
+import _ from 'lodash';
+import {assertSimulator as _assertSimulator} from '../utils';
+import { errors } from 'appium/driver';
+import type {XCUITestDriver} from '../driver';
+import type {ContentSizeAction, ContentSizeResult} from './types';
+import type {Simulator} from 'appium-ios-simulator';
+
+const assertSimulator = (driver: XCUITestDriver): Simulator => _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'
+] as const;
+
+/**
+ * Sets content size for the given simulator.
+ *
+ * @since Xcode 15 (but lower xcode could have this command)
+ * @param 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 If the current platform does not support content size appearance changes
+ */
+export async function mobileSetContentSize(
+  this: XCUITestDriver,
+  size: ContentSizeAction,
+): Promise<void> {
+  if (!(CONTENT_SIZE as readonly string[]).includes(_.lowerCase(size))) {
+    throw new errors.InvalidArgumentError(
+      `The 'size' value is expected to be one of ${CONTENT_SIZE.join(',')}`
+    );
+  }
+
+  await assertSimulator(this).setContentSize(size);
+}
+
+/**
+ * Retrieves the current content size value from the given simulator.
+ *
+ * @since Xcode 15 (but lower xcode could have this command)
+ * @returns 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.
+ */
+export async function mobileGetContentSize(
+  this: XCUITestDriver,
+): Promise<ContentSizeResult> {
+  return await assertSimulator(this).getContentSize() as ContentSizeResult;
+}
+