appium-xcuitest-driver 12.2.1 → 12.3.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [12.3.0](https://github.com/appium/appium-xcuitest-driver/compare/v12.2.1...v12.3.0) (2026-08-08)
+
+### Features
+
+* Add customizable exponential backoff for tunnel reconnect retries ([#2936](https://github.com/appium/appium-xcuitest-driver/issues/2936)) ([84ed39d](https://github.com/appium/appium-xcuitest-driver/commit/84ed39dcaf274368f28fed85c980cf7d23ce470e))
+
 ## [12.2.1](https://github.com/appium/appium-xcuitest-driver/compare/v12.2.0...v12.2.1) (2026-08-07)
 
 ### Miscellaneous Chores

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-xcuitest-driver",
-  "version": "12.2.1",
+  "version": "12.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-xcuitest-driver",
-      "version": "12.2.1",
+      "version": "12.3.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/css-locator-to-native": "^1.0.1",
@@ -572,9 +572,9 @@
       }
     },
     "node_modules/appium-remote-debugger": {
-      "version": "16.1.0",
-      "resolved": "https://registry.npmjs.org/appium-remote-debugger/-/appium-remote-debugger-16.1.0.tgz",
-      "integrity": "sha512-oKI3eOPpnmyGwaVgVAkcbkE8Jpdml1YqP2DOK28Uh28nuwxqEatWMOAhU/SMaHIcDib2oTUmHKXlKSlNzzbxXQ==",
+      "version": "16.4.0",
+      "resolved": "https://registry.npmjs.org/appium-remote-debugger/-/appium-remote-debugger-16.4.0.tgz",
+      "integrity": "sha512-Rr0u0CNZPte2aEBozGIUJxRclzyqNUkBBrDZLo4rxwwEfnalFcpWfTJa9/f1YtkdakMfTRysJA3YFwmGuVFQ8w==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/base-driver": "^10.0.0-rc.1",
@@ -786,9 +786,9 @@
       }
     },
     "node_modules/bare-url": {
-      "version": "2.4.7",
-      "resolved": "https://registry.npmjs.org/bare-url/-/bare-url-2.4.7.tgz",
-      "integrity": "sha512-o8CRCiJtib+ycO3mE4A5UChtGX4dDP2XxsWVu9P+Zc3H8tcmKwNVEDoDTXmwN+uuMhfKeT7/i7Y26xS8W7ohoA==",
+      "version": "2.5.1",
+      "resolved": "https://registry.npmjs.org/bare-url/-/bare-url-2.5.1.tgz",
+      "integrity": "sha512-cD5ciQuKlx+eumTCfqbfiL+fhQm+dHbVNB/cX4+d+I/nx4JsVop9VoFEPAs5RJ6I84QR6bZIBjpd2kjDOYeWcg==",
       "license": "Apache-2.0",
       "dependencies": {
         "bare-path": "^3.0.0"
@@ -3620,9 +3620,9 @@
       "license": "ISC"
     },
     "node_modules/ws": {
-      "version": "8.21.2",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.2.tgz",
-      "integrity": "sha512-54dMVAo4WIe6SKy3vBgN+9bJZqqQ8IMRevAkOLQALhi49qkkQDQfWdAZ8KQlXiEabw88ARXXdUrlvtbKQX+aKw==",
+      "version": "8.21.3",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.3.tgz",
+      "integrity": "sha512-201TZ/kPWxoPr/OKWjquZR1SWKXcvxdH+e1xrx89b3YbmzLMFCLfnaG1HFIgWzJOEWZ7MvpK++odZufgYR50Rw==",
       "license": "MIT",
       "engines": {
         "node": ">=10.0.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-xcuitest-driver",
-  "version": "12.2.1",
+  "version": "12.3.0",
   "description": "Appium driver for iOS using XCUITest for backend",
   "keywords": [
     "appium",

package/scripts/lib/retry-policy.mjs

@@ -0,0 +1,127 @@
+export const DEFAULT_DISCONNECT_RETRY_INTERVAL_MS = 1000;
+export const DEFAULT_DISCONNECT_RETRY_BACKOFF_MULTIPLIER = 2;
+export const DEFAULT_DISCONNECT_RETRY_BACKOFF_MAX_INTERVAL_MS = 30_000;
+export const DEFAULT_DISCONNECT_RETRY_BACKOFF_JITTER = 0.5;
+
+/**
+ * @abstract
+ * Common attempt-counting behavior shared by all retry policies. Subclasses only need to implement
+ * `getDelayMs()`.
+ */
+export class RetryPolicy {
+  /**
+   * @param {{maxAttempts: number | null, intervalMs: number}} opts - maxAttempts: null disables
+   * retries entirely; 0 means unlimited retries
+   */
+  constructor({maxAttempts, intervalMs}) {
+    if (new.target === RetryPolicy) {
+      throw new TypeError('RetryPolicy is abstract and cannot be instantiated directly');
+    }
+    this.maxAttempts = maxAttempts;
+    this._intervalMs = intervalMs;
+  }
+
+  get isEnabled() {
+    return this.maxAttempts !== null;
+  }
+
+  /**
+   * @param {number} attemptsMade - number of attempts already made
+   * @returns {boolean}
+   */
+  hasAttemptsRemaining(attemptsMade) {
+    const {maxAttempts} = this;
+    if (maxAttempts === null) {
+      return false;
+    }
+    return maxAttempts === 0 || attemptsMade < maxAttempts;
+  }
+
+  /**
+   * @abstract
+   * @param {number} _attempt - 1-based number of the attempt about to be made
+   * @returns {number}
+   */
+  getDelayMs(_attempt) {
+    throw new Error('Not implemented');
+  }
+}
+
+/**
+ * Fixed-interval retry policy: waits the same delay between every attempt.
+ */
+export class FixedIntervalRetryPolicy extends RetryPolicy {
+  /**
+   * @param {number} _attempt - 1-based number of the attempt about to be made
+   * @returns {number}
+   */
+  getDelayMs(_attempt) {
+    return this._intervalMs;
+  }
+}
+
+/**
+ * Exponential-backoff retry policy: the delay grows by a multiplier on each attempt, capped at a
+ * configured maximum.
+ */
+export class ExponentialBackoffRetryPolicy extends RetryPolicy {
+  /**
+   * @param {{maxAttempts: number | null, intervalMs: number, backoffMultiplier: number, backoffMaxIntervalMs: number, jitter: number}} opts
+   * - jitter: fraction of the delay to randomize away, in [0, 1]. 0 always returns the exact
+   * computed delay; 1 returns a value uniformly distributed between 0 and the computed delay.
+   * Jitter spreads out devices that dropped together instead of having them retry in lockstep and
+   * stay synchronised once they reach the cap.
+   */
+  constructor({maxAttempts, intervalMs, backoffMultiplier, backoffMaxIntervalMs, jitter}) {
+    super({maxAttempts, intervalMs});
+    if (backoffMaxIntervalMs < intervalMs) {
+      throw new Error(
+        `Invalid disconnect retry backoff max interval: ${backoffMaxIntervalMs}. ` +
+          `Expected a value >= the initial interval (${intervalMs}).`,
+      );
+    }
+    if (jitter < 0 || jitter > 1) {
+      throw new Error(`Invalid disconnect retry backoff jitter: ${jitter}. Expected a value between 0 and 1.`);
+    }
+    this._backoffMultiplier = backoffMultiplier;
+    this._backoffMaxIntervalMs = backoffMaxIntervalMs;
+    this._jitter = jitter;
+  }
+
+  /**
+   * @param {number} attempt - 1-based number of the attempt about to be made
+   * @returns {number}
+   */
+  getDelayMs(attempt) {
+    const delayMs = this._intervalMs * this._backoffMultiplier ** (attempt - 1);
+    const cappedDelayMs = Math.min(delayMs, this._backoffMaxIntervalMs);
+    return Math.round(cappedDelayMs * (1 - this._jitter * Math.random()));
+  }
+}
+
+/**
+ * @param {{strategy: 'fixed' | 'exponential', maxAttempts: number | null, intervalMs: number, backoffMultiplier?: number, backoffMaxIntervalMs?: number, jitter?: number}} opts
+ * @returns {RetryPolicy}
+ */
+export function createDisconnectRetryPolicy({
+  strategy,
+  maxAttempts,
+  intervalMs,
+  backoffMultiplier = DEFAULT_DISCONNECT_RETRY_BACKOFF_MULTIPLIER,
+  backoffMaxIntervalMs = DEFAULT_DISCONNECT_RETRY_BACKOFF_MAX_INTERVAL_MS,
+  jitter = DEFAULT_DISCONNECT_RETRY_BACKOFF_JITTER,
+}) {
+  if (strategy === 'fixed') {
+    return new FixedIntervalRetryPolicy({maxAttempts, intervalMs});
+  }
+  if (strategy === 'exponential') {
+    return new ExponentialBackoffRetryPolicy({
+      maxAttempts,
+      intervalMs,
+      backoffMultiplier,
+      backoffMaxIntervalMs,
+      jitter,
+    });
+  }
+  throw new Error(`Invalid disconnect retry strategy: ${strategy}. Expected 'fixed' or 'exponential'.`);
+}

package/scripts/tunnel-creation.mjs

@@ -27,6 +27,14 @@ import {Command} from 'commander';
 
 import {parsePositiveIntegerOption} from './lib/options.mjs';
 import {startTimeoutProgressLogger} from './lib/progress.mjs';
+import {
+  createDisconnectRetryPolicy,
+  DEFAULT_DISCONNECT_RETRY_BACKOFF_JITTER,
+  DEFAULT_DISCONNECT_RETRY_BACKOFF_MAX_INTERVAL_MS,
+  DEFAULT_DISCONNECT_RETRY_BACKOFF_MULTIPLIER,
+  DEFAULT_DISCONNECT_RETRY_INTERVAL_MS,
+  FixedIntervalRetryPolicy,
+} from './lib/retry-policy.mjs';
 import {assertRoot} from './lib/root.mjs';
 
 const log = logger.getLogger('TunnelCreation');
@@ -65,9 +73,11 @@ class TunnelCreator {
     /** @type {Map<string, import('appium-ios-remotexpc').AppleTVTunnelService>} */
     this._appletvTunnelServicesByUdid = new Map();
     this._isCleaningUp = false;
-    /** @type {number | null} */
-    this._disconnectRetryMaxAttempts = null;
-    this._disconnectRetryIntervalMs = 1000;
+    /** @type {import('./lib/retry-policy.mjs').RetryPolicy} */
+    this._disconnectRetryPolicy = new FixedIntervalRetryPolicy({
+      maxAttempts: null,
+      intervalMs: DEFAULT_DISCONNECT_RETRY_INTERVAL_MS,
+    });
   }
 
   get tunnelRegistryPort() {
@@ -83,12 +93,10 @@ class TunnelCreator {
   }
 
   /**
-   * @param {number | null} maxAttempts - null disables retries; 0 means unlimited retries
-   * @param {number} intervalMs
+   * @param {import('./lib/retry-policy.mjs').RetryPolicy} policy
    */
-  setDisconnectRetryPolicy(maxAttempts, intervalMs) {
-    this._disconnectRetryMaxAttempts = maxAttempts;
-    this._disconnectRetryIntervalMs = intervalMs;
+  setDisconnectRetryPolicy(policy) {
+    this._disconnectRetryPolicy = policy;
   }
 
   /**
@@ -576,10 +584,6 @@ class TunnelCreator {
         if (!this._isRetryEnabledForUdid(udid)) {
           return;
         }
-        const maxAttempts = this._disconnectRetryMaxAttempts;
-        if (maxAttempts === null) {
-          return;
-        }
 
         const device = this._usbDevicesByUdid.get(udid);
         const isAppleTV = this._appleTVDeviceIds.has(udid);
@@ -587,17 +591,19 @@ class TunnelCreator {
           return;
         }
 
-        let attempt = 0;
+        const policy = this._disconnectRetryPolicy;
+        let attemptsMade = 0;
         while (!this._isCleaningUp) {
-          if (maxAttempts !== 0 && attempt >= maxAttempts) {
+          if (!policy.hasAttemptsRemaining(attemptsMade)) {
             log.warn(`Retry limit reached for ${udid}; keeping it removed from the registry`);
             return;
           }
-          attempt += 1;
+          attemptsMade += 1;
+          const delayMs = policy.getDelayMs(attemptsMade);
           log.warn(
-            `Retrying tunnel creation for ${udid} (attempt ${attempt}${maxAttempts === 0 ? ', unlimited' : `/${maxAttempts}`}) in ${this._disconnectRetryIntervalMs}ms...`,
+            `Retrying tunnel creation for ${udid} (attempt ${attemptsMade}${policy.maxAttempts === 0 ? ', unlimited' : `/${policy.maxAttempts}`}) in ${delayMs}ms...`,
           );
-          await sleep(this._disconnectRetryIntervalMs);
+          await sleep(delayMs);
 
           try {
             this._registryServer?.markTunnelPending(udid);
@@ -635,8 +641,7 @@ class TunnelCreator {
    */
   _isRetryEnabledForUdid(udid) {
     return (
-      (this._usbDevicesByUdid.has(udid) || this._appleTVDeviceIds.has(udid)) &&
-      this._disconnectRetryMaxAttempts !== null
+      (this._usbDevicesByUdid.has(udid) || this._appleTVDeviceIds.has(udid)) && this._disconnectRetryPolicy.isEnabled
     );
   }
 
@@ -800,6 +805,43 @@ function parseNonNegativeIntegerOption(value, label) {
   return count;
 }
 
+/**
+ * @param {string} value
+ * @returns {'fixed' | 'exponential'}
+ */
+function parseRetryStrategyOption(value) {
+  if (value !== 'fixed' && value !== 'exponential') {
+    throw new Error(`Invalid disconnect retry strategy: ${value}. Expected 'fixed' or 'exponential'.`);
+  }
+  return value;
+}
+
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {number}
+ */
+function parseRetryBackoffMultiplierOption(value, label) {
+  const multiplier = Number.parseFloat(value);
+  if (!Number.isFinite(multiplier) || multiplier <= 1) {
+    throw new Error(`Invalid ${label}: ${value}. Expected a number greater than 1.`);
+  }
+  return multiplier;
+}
+
+/**
+ * @param {string} value
+ * @param {string} label
+ * @returns {number}
+ */
+function parseRetryBackoffJitterOption(value, label) {
+  const jitter = Number.parseFloat(value);
+  if (!Number.isFinite(jitter) || jitter < 0 || jitter > 1) {
+    throw new Error(`Invalid ${label}: ${value}. Expected a number between 0 and 1.`);
+  }
+  return jitter;
+}
+
 /**
  * @param {string} value
  * @param {string[]} previous
@@ -906,11 +948,38 @@ async function main() {
       'Max tunnel recreation attempts after unexpected disconnect: 0 = unlimited; omit to disable retries',
       (value) => parseNonNegativeIntegerOption(value, 'disconnect retry max attempts'),
     )
+    .option(
+      '--disconnect-retry-strategy <strategy>',
+      "Delay strategy between tunnel recreation attempts: 'fixed' or 'exponential'",
+      (value) => parseRetryStrategyOption(value),
+      'fixed',
+    )
     .option(
       '--disconnect-retry-interval-ms <ms>',
-      'Delay between tunnel recreation attempts in milliseconds (default 1000)',
+      'Delay between tunnel recreation attempts in milliseconds. ' +
+        'With --disconnect-retry-strategy exponential, this is the initial delay, before it starts growing',
       (value) => parsePositiveIntegerOption(value, 'disconnect retry interval'),
-      1000,
+      DEFAULT_DISCONNECT_RETRY_INTERVAL_MS,
+    )
+    .option(
+      '--disconnect-retry-backoff-multiplier <factor>',
+      'Factor the delay grows by on each attempt when --disconnect-retry-strategy is exponential (must be > 1)',
+      (value) => parseRetryBackoffMultiplierOption(value, 'disconnect retry backoff multiplier'),
+      DEFAULT_DISCONNECT_RETRY_BACKOFF_MULTIPLIER,
+    )
+    .option(
+      '--disconnect-retry-backoff-max-interval-ms <ms>',
+      'Upper bound on the delay between tunnel recreation attempts when --disconnect-retry-strategy is exponential',
+      (value) => parsePositiveIntegerOption(value, 'disconnect retry backoff max interval'),
+      DEFAULT_DISCONNECT_RETRY_BACKOFF_MAX_INTERVAL_MS,
+    )
+    .option(
+      '--disconnect-retry-backoff-jitter <factor>',
+      'Fraction of the delay to randomize away on each attempt when --disconnect-retry-strategy is exponential, ' +
+        'between 0 (no jitter) and 1 (full jitter). Spreads out devices that dropped together instead of having ' +
+        'them retry in lockstep',
+      (value) => parseRetryBackoffJitterOption(value, 'disconnect retry backoff jitter'),
+      DEFAULT_DISCONNECT_RETRY_BACKOFF_JITTER,
     );
 
   program.parse(process.argv);
@@ -922,6 +991,24 @@ async function main() {
   const shouldRunUsbFlow = !hasRequestedAppleTVIds || hasRequestedUdids;
   const shouldRunAppleTVFlow = !hasRequestedUdids || hasRequestedAppleTVIds;
 
+  /** @type {import('./lib/retry-policy.mjs').RetryPolicy} */
+  let disconnectRetryPolicy;
+  try {
+    disconnectRetryPolicy = createDisconnectRetryPolicy({
+      strategy: options.disconnectRetryStrategy,
+      maxAttempts: options.disconnectRetryMaxAttempts ?? null,
+      intervalMs: options.disconnectRetryIntervalMs,
+      backoffMultiplier: options.disconnectRetryBackoffMultiplier,
+      backoffMaxIntervalMs: options.disconnectRetryBackoffMaxIntervalMs,
+      jitter: options.disconnectRetryBackoffJitter,
+    });
+  } catch (err) {
+    // program.error() never returns (it exits the process); the throw below is unreachable and
+    // only here so TS can see disconnectRetryPolicy is always assigned past this point.
+    program.error(/** @type {Error} */ (err).message);
+    throw err;
+  }
+
   await assertRoot(path.parse(fileURLToPath(import.meta.url)).name);
 
   const tunnelCreator = new TunnelCreator({
@@ -953,10 +1040,7 @@ async function main() {
       });
     }
 
-    tunnelCreator.setDisconnectRetryPolicy(
-      options.disconnectRetryMaxAttempts ?? null,
-      options.disconnectRetryIntervalMs,
-    );
+    tunnelCreator.setDisconnectRetryPolicy(disconnectRetryPolicy);
 
     await tunnelCreator.startRegistryServer();