appium-xcuitest-driver 11.12.2 → 11.13.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [11.13.0](https://github.com/appium/appium-xcuitest-driver/compare/v11.12.2...v11.13.0) (2026-06-20)
+
+### Features
+
+* Make Apple TV discovery timeout configurable ([#2882](https://github.com/appium/appium-xcuitest-driver/issues/2882)) ([e9e006b](https://github.com/appium/appium-xcuitest-driver/commit/e9e006b5de99930e41602dc5e540ad0d3a375244))
+
 ## [11.12.2](https://github.com/appium/appium-xcuitest-driver/compare/v11.12.1...v11.12.2) (2026-06-19)
 
 ### Bug Fixes

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-xcuitest-driver",
-  "version": "11.12.2",
+  "version": "11.13.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-xcuitest-driver",
-      "version": "11.12.2",
+      "version": "11.13.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/css-locator-to-native": "^1.0.1",
@@ -41,7 +41,7 @@
         "@semantic-release/changelog": "^6.0.3",
         "@semantic-release/git": "^10.0.1",
         "@types/mocha": "^10.0.1",
-        "@types/node": "^25.0.0",
+        "@types/node": "^26.0.0",
         "@types/portscanner": "^2.1.1",
         "chai": "^6.0.0",
         "chai-as-promised": "^8.0.0",
@@ -63,7 +63,7 @@
         "npm": ">=10"
       },
       "optionalDependencies": {
-        "appium-ios-remotexpc": "^5.1.0"
+        "appium-ios-remotexpc": "^5.1.5"
       },
       "peerDependencies": {
         "appium": "^3.0.0-rc.2"
@@ -288,6 +288,18 @@
         "url": "https://opencollective.com/libvips"
       }
     },
+    "node_modules/@appium/support/node_modules/semver": {
+      "version": "7.8.4",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.4.tgz",
+      "integrity": "sha512-rUCObTnP32Q08R2uuIrt7r9PlEonuTmtuXYcW6s5kjdlj3xbnwe+21yXptAUYcMAABLkYYTtnmzb3w3EDZfueA==",
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/@appium/support/node_modules/sharp": {
       "version": "0.35.1",
       "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.35.1.tgz",
@@ -513,13 +525,13 @@
       }
     },
     "node_modules/appium-ios-remotexpc": {
-      "version": "5.1.0",
-      "resolved": "https://registry.npmjs.org/appium-ios-remotexpc/-/appium-ios-remotexpc-5.1.0.tgz",
-      "integrity": "sha512-/q6C2Rwreg69p6R/d29nkdjQewJzjenIAhGPHQiO5PM51JHcPXB6DPwVL5O49iin0eAGgFahp33aGsX+92WANA==",
+      "version": "5.1.6",
+      "resolved": "https://registry.npmjs.org/appium-ios-remotexpc/-/appium-ios-remotexpc-5.1.6.tgz",
+      "integrity": "sha512-PNuFaoL5X0bL04RRNqb6EmEtUYRsd6rmMHm9biHmvtBWPeq7WIBdlFkB5Z5qOyiOjb0TXE9WdvGwzw47QcFUJw==",
       "license": "Apache-2.0",
       "optional": true,
       "dependencies": {
-        "@appium/strongbox": "^1.0.0-rc.1",
+        "@appium/strongbox": "^1.1.2",
         "@appium/support": "^7.2.2",
         "@xmldom/xmldom": "^0.x",
         "appium-ios-tuntap": "^1.0.0",
@@ -537,9 +549,9 @@
       }
     },
     "node_modules/appium-ios-simulator": {
-      "version": "8.2.2",
-      "resolved": "https://registry.npmjs.org/appium-ios-simulator/-/appium-ios-simulator-8.2.2.tgz",
-      "integrity": "sha512-NmpbM+CpnSHNoEvCYWXkzvh+fhNd8pcYhpIirw/hvlVbZnG/Gs0Bw6+sU20uOw8O/uzziEgC6odogzpJ4AO70Q==",
+      "version": "8.2.3",
+      "resolved": "https://registry.npmjs.org/appium-ios-simulator/-/appium-ios-simulator-8.2.3.tgz",
+      "integrity": "sha512-naM9JLNT7uZv+IVCMNMtifgiRbiNvRZ0e1SHPo2xPa4dF0vKlqSDdA7WVFguh3V+Sfty3L6HCVY6VRdbyQ+2Ew==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/support": "^7.2.2",
@@ -597,9 +609,9 @@
       }
     },
     "node_modules/appium-webdriveragent": {
-      "version": "14.2.0",
-      "resolved": "https://registry.npmjs.org/appium-webdriveragent/-/appium-webdriveragent-14.2.0.tgz",
-      "integrity": "sha512-2x0aN/mpbLfs7CqJvKeaunq3s+I+jN//qqk6jRuf1e32pNv3Z/RSkoO/ibeVpXgIWlOntBnt4pEsQX0pYifCuQ==",
+      "version": "14.2.1",
+      "resolved": "https://registry.npmjs.org/appium-webdriveragent/-/appium-webdriveragent-14.2.1.tgz",
+      "integrity": "sha512-iHFi+ViRzBOeIjSZZ+R94lVUdGCHBplA8GmDhNxd/0PGh0IfuAlfvz8n3/7AvApebpgjMArKcowGXILo0SwE1A==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/base-driver": "^10.3.0",
@@ -3063,9 +3075,9 @@
       "optional": true
     },
     "node_modules/semver": {
-      "version": "7.8.4",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.4.tgz",
-      "integrity": "sha512-rUCObTnP32Q08R2uuIrt7r9PlEonuTmtuXYcW6s5kjdlj3xbnwe+21yXptAUYcMAABLkYYTtnmzb3w3EDZfueA==",
+      "version": "7.8.5",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
+      "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
       "license": "ISC",
       "bin": {
         "semver": "bin/semver.js"

package/package.json

@@ -8,7 +8,7 @@
     "xcuitest",
     "xctest"
   ],
-  "version": "11.12.2",
+  "version": "11.13.0",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -107,7 +107,7 @@
     "ws": "^8.13.0"
   },
   "optionalDependencies": {
-    "appium-ios-remotexpc": "^5.1.0"
+    "appium-ios-remotexpc": "^5.1.5"
   },
   "scripts": {
     "build": "tsc -b",
@@ -151,7 +151,7 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/mocha": "^10.0.1",
-    "@types/node": "^25.0.0",
+    "@types/node": "^26.0.0",
     "@types/portscanner": "^2.1.1",
     "chai": "^6.0.0",
     "chai-as-promised": "^8.0.0",

package/scripts/lib/options.mjs

@@ -0,0 +1,12 @@
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {number}
+ */
+export function parsePositiveIntegerOption(value, label) {
+  const num = Number.parseInt(value, 10);
+  if (!Number.isFinite(num) || num <= 0) {
+    throw new Error(`Invalid ${label}: ${value}. Expected a positive integer.`);
+  }
+  return num;
+}

package/scripts/lib/progress.mjs

@@ -0,0 +1,44 @@
+/**
+ * Logs a timeout-based progress bar while an operation without native progress callbacks is running.
+ *
+ * @param {{log: {info: (message: string) => void}, label: string, startedAt: number, timeoutMs: number, barWidth: number, intervalMs: number}} opts
+ * @returns {{succeed: (message?: string) => void, fail: (message?: string) => void}}
+ */
+export function startTimeoutProgressLogger({log, label, startedAt, timeoutMs, barWidth, intervalMs}) {
+  /** @type {NodeJS.Timeout | null} */
+  let timer = null;
+  let isStopped = false;
+
+  const logProgress = (status, isComplete = false) => {
+    const elapsedMs = performance.now() - startedAt;
+    const boundedElapsedMs = Math.min(elapsedMs, timeoutMs);
+    const progress = isComplete ? 1 : boundedElapsedMs / timeoutMs;
+    const filledWidth = Math.round(progress * barWidth);
+    const emptyWidth = barWidth - filledWidth;
+    const bar = `${'#'.repeat(filledWidth)}${'-'.repeat(emptyWidth)}`;
+    log.info(`${label}: [${bar}]${status && status !== 'waiting' ? ` - ${status}` : ''}`);
+  };
+
+  const stop = (status, isComplete = false) => {
+    if (isStopped) {
+      return;
+    }
+    isStopped = true;
+    if (timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+    logProgress(status, isComplete);
+  };
+
+  logProgress('waiting');
+  timer = setInterval(() => {
+    logProgress('waiting');
+  }, intervalMs);
+  timer.unref?.();
+
+  return {
+    succeed: (message = 'done') => stop(message, true),
+    fail: (message = 'failed') => stop(message),
+  };
+}

package/scripts/lib/root.mjs

@@ -0,0 +1,15 @@
+/**
+ * Ensures a driver helper script is run with elevated privileges on platforms that expose getuid.
+ *
+ * @param {string} scriptName
+ */
+export function assertRoot(scriptName) {
+  if (typeof process.getuid !== 'function') {
+    return;
+  }
+  if (process.getuid() !== 0) {
+    throw new Error(
+      `This script must be run as root (e.g. sudo appium driver run xcuitest ${scriptName} ...).`,
+    );
+  }
+}

package/scripts/pair-appletv.mjs

@@ -16,27 +16,26 @@
  *                             - Device name (e.g. "Living Room")
  *                             - Device identifier (e.g. "AA:BB:CC:DD:EE:FF")
  *                             - Device index (e.g. "0", "1", "2")
+ *   --discovery-timeout-ms <ms>
+ *                             Apple TV pairing discovery timeout in milliseconds
  */
 
 import {logger} from 'appium/support.js';
 import {Command} from 'commander';
 import {AppleTVPairingService, UserInputService} from 'appium-ios-remotexpc';
 
-const log = logger.getLogger('AppleTVPairing');
+import {parsePositiveIntegerOption} from './lib/options.mjs';
+import {startTimeoutProgressLogger} from './lib/progress.mjs';
+import {assertRoot} from './lib/root.mjs';
 
-function assertRoot() {
-  if (typeof process.getuid !== 'function') {
-    return;
-  }
-  if (process.getuid() !== 0) {
-    throw new Error(
-      'This script must be run as root (e.g. sudo appium driver run xcuitest pair-appletv ...).',
-    );
-  }
-}
+const log = logger.getLogger('AppleTVPairing');
+const APPLETV_PAIRING_DISCOVERY_PROGRESS_INTERVAL_MS = 1000;
+const DEFAULT_APPLETV_PAIRING_DISCOVERY_TIMEOUT_MS =
+  Number(process.env.APPLETV_DISCOVERY_TIMEOUT) || 10_000;
+const APPLETV_PAIRING_DISCOVERY_PROGRESS_BAR_WIDTH = 24;
 
 async function main() {
-  assertRoot();
+  assertRoot('pair-appletv');
   const program = new Command();
   program
     .name('appium driver run xcuitest pair-appletv')
@@ -44,6 +43,12 @@ async function main() {
     .option(
       '-d, --device <selector>',
       'Apple TV device selector (name, identifier, or index)',
+    )
+    .option(
+      '--discovery-timeout-ms <ms>',
+      'Apple TV pairing discovery timeout in milliseconds',
+      (value) => parsePositiveIntegerOption(value, 'discovery timeout'),
+      DEFAULT_APPLETV_PAIRING_DISCOVERY_TIMEOUT_MS,
     );
 
   program.parse(process.argv);
@@ -52,9 +57,25 @@ async function main() {
   const userInput = new UserInputService();
   const pairingService = new AppleTVPairingService(userInput);
 
-  const result = await pairingService.discoverAndPair(options.device);
+  const devices = await discoverAppleTVPairingDevices(
+    pairingService,
+    options.discoveryTimeoutMs,
+  );
+  if (devices.length === 0) {
+    log.info(getNoAppleTVPairingDevicesMessage());
+    return;
+  }
+
+  const result = await pairingService.discoverAndPair(options.device, {
+    devices,
+    discoveryTimeoutMs: options.discoveryTimeoutMs,
+  });
 
   if (!result.success) {
+    if (isNoAppleTVPairingDevicesFoundError(result.error)) {
+      log.info(getNoAppleTVPairingDevicesMessage());
+      return;
+    }
     throw result.error ?? new Error('Pairing failed');
   }
 
@@ -64,5 +85,57 @@ async function main() {
   );
 }
 
+/**
+ * @param {import('appium-ios-remotexpc').AppleTVPairingService} pairingService
+ * @param {number} discoveryTimeoutMs
+ * @returns {Promise<AppleTVDevice[]>}
+ */
+async function discoverAppleTVPairingDevices(pairingService, discoveryTimeoutMs) {
+  const startedAt = performance.now();
+  const pairingDiscoveryProgress = startTimeoutProgressLogger({
+    log,
+    label: 'Waiting for Apple TV pairing discovery',
+    startedAt,
+    timeoutMs: discoveryTimeoutMs,
+    barWidth: APPLETV_PAIRING_DISCOVERY_PROGRESS_BAR_WIDTH,
+    intervalMs: APPLETV_PAIRING_DISCOVERY_PROGRESS_INTERVAL_MS,
+  });
+
+  try {
+    const devices = await pairingService.discoverDevices({
+      timeoutMs: discoveryTimeoutMs,
+    });
+    pairingDiscoveryProgress.succeed(
+      `Apple TV pairing discovery completed: ${devices.length} device(s) found`,
+    );
+    return devices;
+  } catch (err) {
+    pairingDiscoveryProgress.fail('Apple TV pairing discovery failed');
+    throw err;
+  }
+}
+
+/**
+ * @param {unknown} err
+ * @returns {boolean}
+ */
+function isNoAppleTVPairingDevicesFoundError(err) {
+  return (
+    err instanceof Error &&
+    (err.message === getNoAppleTVPairingDevicesMessage() ||
+      ('code' in err && err.code === 'NO_DEVICES'))
+  );
+}
+
+/**
+ * @returns {string}
+ */
+function getNoAppleTVPairingDevicesMessage() {
+  return 'No Apple TV pairing devices found. Please ensure your Apple TV is on the same network and in pairing mode.';
+}
 
 await main();
+
+/**
+ * @typedef {import('appium-ios-remotexpc').AppleTVDevice} AppleTVDevice
+ */

package/scripts/tunnel-creation.mjs

@@ -24,19 +24,28 @@ import {
 import {strongbox, BaseItem} from '@appium/strongbox';
 import {Command} from 'commander';
 
+import {parsePositiveIntegerOption} from './lib/options.mjs';
+import {startTimeoutProgressLogger} from './lib/progress.mjs';
+import {assertRoot} from './lib/root.mjs';
+
 const log = logger.getLogger('TunnelCreation');
 const TUNNEL_REGISTRY_PORT = 'tunnelRegistryPort';
 const DEFAULT_TUNNEL_REGISTRY_PORT = 42314;
 const WIRELESS_APPLETV_DISCOVERY_PROGRESS_INTERVAL_MS = 1000;
-const WIRELESS_APPLETV_DISCOVERY_TIMEOUT_MS = 10_000;
+const DEFAULT_WIRELESS_APPLETV_DISCOVERY_TIMEOUT_MS = 10_000;
 const WIRELESS_APPLETV_DISCOVERY_PROGRESS_BAR_WIDTH = 24;
 
 /**
  * TunnelCreator class for managing tunnel creation and related operations (USB and optional Apple TV over WiFi).
  */
 class TunnelCreator {
-  constructor() {
+  /**
+   * @param {{appleTVDiscoveryTimeoutMs?: number}} [opts]
+   */
+  constructor(opts = {}) {
     this._tunnelRegistryPort = DEFAULT_TUNNEL_REGISTRY_PORT;
+    this._appleTVDiscoveryTimeoutMs =
+      opts.appleTVDiscoveryTimeoutMs ?? DEFAULT_WIRELESS_APPLETV_DISCOVERY_TIMEOUT_MS;
     /** @type {import('appium-ios-remotexpc').TunnelRegistryServer | null} */
     this._registryServer = null;
     /** @type {import('appium-ios-remotexpc').TunnelReadinessCoordinator} */
@@ -412,13 +421,14 @@ class TunnelCreator {
 
   /**
    * @param {string[] | undefined} specificDeviceIds
-   * @returns {{startedAt: number, promise: Promise<{devices: AppleTVDevice[] | null, error: unknown | null}>}}
+   * @returns {{startedAt: number, timeoutMs: number, promise: Promise<{devices: AppleTVDevice[] | null, error: unknown | null}>}}
    */
   prefetchAppleTVDevices(specificDeviceIds) {
     const startedAt = performance.now();
     if (specificDeviceIds && specificDeviceIds.length > 0) {
       return {
         startedAt,
+        timeoutMs: this._appleTVDiscoveryTimeoutMs,
         promise: Promise.resolve({devices: null, error: null}),
       };
     }
@@ -426,7 +436,7 @@ class TunnelCreator {
     const promise = (async () => {
       try {
         const devices = await tunnelService.discoverDevices({
-          timeoutMs: WIRELESS_APPLETV_DISCOVERY_TIMEOUT_MS,
+          timeoutMs: this._appleTVDiscoveryTimeoutMs,
         });
         return {devices, error: null};
       } catch (err) {
@@ -437,7 +447,7 @@ class TunnelCreator {
         } catch {}
       }
     })();
-    return {startedAt, promise};
+    return {startedAt, timeoutMs: this._appleTVDiscoveryTimeoutMs, promise};
   }
 
   /**
@@ -454,7 +464,7 @@ class TunnelCreator {
 
     const startResult = await tunnelService.startTunnel(undefined, udid, {
       devices: prefetchedDevice ? [prefetchedDevice] : undefined,
-      discoveryTimeoutMs: WIRELESS_APPLETV_DISCOVERY_TIMEOUT_MS,
+      discoveryTimeoutMs: this._appleTVDiscoveryTimeoutMs,
     });
     if (!startResult.tcpSocket) {
       throw new Error('Apple TV TCP socket to listener port not established');
@@ -740,14 +750,15 @@ function isNoAppleTVDevicesFoundError(err) {
 }
 
 /**
- * @param {{startedAt: number, promise: Promise<{devices: AppleTVDevice[] | null, error: unknown | null}>}} discovery
+ * @param {{startedAt: number, timeoutMs: number, promise: Promise<{devices: AppleTVDevice[] | null, error: unknown | null}>}} discovery
  * @returns {Promise<AppleTVDevice[] | null>}
  */
 async function waitForAppleTVDiscovery(discovery) {
   const wirelessDiscoveryProgress = startTimeoutProgressLogger({
+    log,
     label: 'Waiting for wireless Apple TV discovery',
     startedAt: discovery.startedAt,
-    timeoutMs: WIRELESS_APPLETV_DISCOVERY_TIMEOUT_MS,
+    timeoutMs: discovery.timeoutMs,
     barWidth: WIRELESS_APPLETV_DISCOVERY_PROGRESS_BAR_WIDTH,
     intervalMs: WIRELESS_APPLETV_DISCOVERY_PROGRESS_INTERVAL_MS,
   });
@@ -775,51 +786,6 @@ async function sleep(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-/**
- * Logs a timeout-based progress bar while an operation without native progress callbacks is running.
- *
- * @param {{label: string, startedAt: number, timeoutMs: number, barWidth: number, intervalMs: number}} opts
- * @returns {{succeed: (message?: string) => void, fail: (message?: string) => void}}
- */
-function startTimeoutProgressLogger({label, startedAt, timeoutMs, barWidth, intervalMs}) {
-  /** @type {NodeJS.Timeout | null} */
-  let timer = null;
-  let isStopped = false;
-
-  const logProgress = (status, isComplete = false) => {
-    const elapsedMs = performance.now() - startedAt;
-    const boundedElapsedMs = Math.min(elapsedMs, timeoutMs);
-    const progress = isComplete ? 1 : boundedElapsedMs / timeoutMs;
-    const filledWidth = Math.round(progress * barWidth);
-    const emptyWidth = barWidth - filledWidth;
-    const bar = `${'#'.repeat(filledWidth)}${'-'.repeat(emptyWidth)}`;
-    log.info(`${label}: [${bar}]${status && status !== 'waiting' ? ` - ${status}` : ''}`);
-  };
-
-  const stop = (status, isComplete = false) => {
-    if (isStopped) {
-      return;
-    }
-    isStopped = true;
-    if (timer) {
-      clearInterval(timer);
-      timer = null;
-    }
-    logProgress(status, isComplete);
-  };
-
-  logProgress('waiting');
-  timer = setInterval(() => {
-    logProgress('waiting');
-  }, intervalMs);
-  timer.unref?.();
-
-  return {
-    succeed: (message = 'done') => stop(message, true),
-    fail: (message = 'failed') => stop(message),
-  };
-}
-
 /**
  * @param {string} value
  * @param {string} label
@@ -846,19 +812,6 @@ function parseNonNegativeIntegerOption(value, label) {
   return count;
 }
 
-/**
- * @param {string} value
- * @param {string} label
- * @returns {number}
- */
-function parsePositiveIntegerOption(value, label) {
-  const num = Number.parseInt(value, 10);
-  if (!Number.isFinite(num) || num <= 0) {
-    throw new Error(`Invalid ${label}: ${value}. Expected a positive integer.`);
-  }
-  return num;
-}
-
 /**
  * @param {string} value
  * @param {string[]} previous
@@ -932,19 +885,8 @@ function setupCleanupHandlers(tunnelCreator) {
   return cleanupOnce;
 }
 
-function assertRoot() {
-  if (typeof process.getuid !== 'function') {
-    return;
-  }
-  if (process.getuid() !== 0) {
-    throw new Error(
-      'This script must be run as root (e.g. sudo appium driver run xcuitest tunnel-creation ...).',
-    );
-  }
-}
-
 async function main() {
-  assertRoot();
+  assertRoot('tunnel-creation');
   const program = new Command();
   program
     .name('appium driver run xcuitest tunnel-creation')
@@ -968,6 +910,12 @@ async function main() {
       collectStringValues,
       [],
     )
+    .option(
+      '--appletv-discovery-timeout-ms <ms>',
+      'Apple TV wireless discovery timeout in milliseconds',
+      (value) => parsePositiveIntegerOption(value, 'Apple TV discovery timeout'),
+      DEFAULT_WIRELESS_APPLETV_DISCOVERY_TIMEOUT_MS,
+    )
     .option(
       '--disconnect-retry-max-attempts <count>',
       'Max tunnel recreation attempts after unexpected disconnect: 0 = unlimited; omit to disable retries',
@@ -989,7 +937,9 @@ async function main() {
   const shouldRunUsbFlow = !hasRequestedAppleTVIds || hasRequestedUdids;
   const shouldRunAppleTVFlow = !hasRequestedUdids || hasRequestedAppleTVIds;
 
-  const tunnelCreator = new TunnelCreator();
+  const tunnelCreator = new TunnelCreator({
+    appleTVDiscoveryTimeoutMs: options.appletvDiscoveryTimeoutMs,
+  });
   const cleanupOnce = setupCleanupHandlers(tunnelCreator);
 
   try {
@@ -1126,7 +1076,7 @@ await main();
  */
 
 /**
- * @typedef {Awaited<ReturnType<import('appium-ios-remotexpc').AppleTVTunnelService['discoverDevices']>>[number]} AppleTVDevice
+ * @typedef {import('appium-ios-remotexpc').AppleTVDevice} AppleTVDevice
  */
 
 /**