appium-remote-debugger 15.9.0 → 15.10.0

package/lib/rpc/rpc-client.ts

@@ -1,19 +1,11 @@
 import {RemoteMessages} from './remote-messages';
-import {waitForCondition} from 'asyncbox';
+import {sleep, waitForCondition, withTimeout} from 'asyncbox';
 import {log} from '../logger';
 import RpcMessageHandler from './rpc-message-handler';
 import {util, timing} from '@appium/support';
 import {EventEmitter} from 'node:events';
 import AsyncLock from 'async-lock';
-import {
-  convertJavascriptEvaluationResult,
-  delay,
-  defaults,
-  isEmpty,
-  isPlainObject,
-  truncateString,
-  withTimeout,
-} from '../utils';
+import {convertJavascriptEvaluationResult, defaults} from '../utils';
 import type {StringRecord} from '@appium/types';
 import type {
   AppIdKey,
@@ -325,7 +317,7 @@ export class RpcClient {
       await waitForCondition(
         () => {
           target = this.getTarget(appIdKey, pageIdKey);
-          return !isEmpty(target);
+          return !util.isEmpty(target);
         },
         {
           waitMs,
@@ -339,6 +331,7 @@ export class RpcClient {
       }
       throw new Error(
         `No targets could be matched for the app '${appIdKey}' and page '${pageIdKey}' after ${waitMs}ms`,
+        {cause: err},
       );
     }
   }
@@ -441,7 +434,7 @@ export class RpcClient {
           __selector: cmd.__selector,
         };
 
-        const hasSocketData = isPlainObject(cmd.__argument?.WIRSocketDataKey);
+        const hasSocketData = util.isPlainObject(cmd.__argument?.WIRSocketDataKey);
         if (hasSocketData) {
           // make sure the message being sent has all the information that is needed
           const socketData = cmd.__argument.WIRSocketDataKey as StringRecord;
@@ -463,7 +456,7 @@ export class RpcClient {
               // a protocol change. Log and check during testing
               log.error(
                 `Received error from send that is not being waited for (id: ${msgId}): ` +
-                  truncateString(JSON.stringify(err), DATA_LOG_LENGTH),
+                  util.truncateString(JSON.stringify(err), DATA_LOG_LENGTH),
               );
               // reject, though it is very rare that this will be triggered, since
               // the promise is resolved directly after send. On the off chance,
@@ -479,7 +472,7 @@ export class RpcClient {
                 return reject(err);
               }
               log.debug(
-                `Received response from send (id: ${msgId}): '${truncateString(JSON.stringify(args), DATA_LOG_LENGTH)}'`,
+                `Received response from send (id: ${msgId}): '${util.truncateString(JSON.stringify(args), DATA_LOG_LENGTH)}'`,
               );
               resolve(args);
             },
@@ -492,7 +485,7 @@ export class RpcClient {
               );
             }
             log.debug(
-              `Received data response from send (id: ${msgId}): '${truncateString(JSON.stringify(value), DATA_LOG_LENGTH)}'`,
+              `Received data response from send (id: ${msgId}): '${util.truncateString(JSON.stringify(value), DATA_LOG_LENGTH)}'`,
             );
             resolve(value);
           });
@@ -580,7 +573,7 @@ export class RpcClient {
     }
     const {appIdKey, pageIdKey, pageReadinessDetector} = pendingPageTargetDetails;
 
-    if (!isPlainObject(this.targets[appIdKey])) {
+    if (!util.isPlainObject(this.targets[appIdKey])) {
       this.targets[appIdKey] = {
         lock: new AsyncLock({maxOccupationTime: this._targetCreationTimeoutMs}),
       } as PagesToTargets;
@@ -610,8 +603,8 @@ export class RpcClient {
 
       this._provisionedPages.add(pageIdKey);
       try {
-        await this.targets[appIdKey].lock.acquire(pageIdKey, async () => {
-          let wasInitialized = false;
+        await this.targets[appIdKey].lock.acquire(String(pageIdKey), async () => {
+          let wasInitialized: boolean;
           try {
             wasInitialized = await this._initializePage(appIdKey, pageIdKey, targetInfo.targetId);
           } finally {
@@ -666,7 +659,7 @@ export class RpcClient {
     }
 
     try {
-      await this.targets[appIdKey].lock.acquire(pageIdKey, async () => {
+      await this.targets[appIdKey].lock.acquire(String(pageIdKey), async () => {
         let wasInitialized = false;
         try {
           if (this._provisionedPages.has(pageIdKey)) {
@@ -929,7 +922,7 @@ export class RpcClient {
           const [connectedAppIdKey, pageDict] = await this.send('connectToApp', {appIdKey});
           // sometimes the connect logic happens, but with an empty dictionary
           // which leads to the remote debugger getting disconnected, and into a loop
-          if (isEmpty(pageDict)) {
+          if (util.isEmpty(pageDict)) {
             reject(new Error(EMPTY_PAGE_DICTIONARY_ERROR));
           } else {
             resolve([connectedAppIdKey, pageDict]);
@@ -993,10 +986,10 @@ export class RpcClient {
     const lock = appTargetsMap.lock;
     const timer = new timing.Timer().start();
     await Promise.all([
-      lock.acquire(pageIdKey, async () => await delay(0)),
+      lock.acquire(String(pageIdKey), async () => await sleep(0)),
       this._pageSelectionLock.acquire(
         toPageSelectionKey(appIdKey, pageIdKey),
-        async () => await delay(0),
+        async () => await sleep(0),
       ),
     ]);
     const durationMs = timer.getDuration().asMilliSeconds;
@@ -1230,7 +1223,7 @@ export class RpcClient {
         );
         return;
       }
-      await delay(100);
+      await sleep(100);
     }
     log.warn(
       `Page '${pageIdKey}' for app '${appIdKey}' is not ready after ` +

package/lib/rpc/rpc-message-handler.ts

@@ -1,6 +1,5 @@
 import {EventEmitter} from 'node:events';
 import {log} from '../logger';
-import {isPlainObject, truncateString} from '../utils';
 import {util} from '@appium/support';
 import type {StringRecord} from '@appium/types';
 
@@ -106,8 +105,8 @@ export default class RpcMessageHandler extends EventEmitter {
     try {
       return JSON.parse(plist.__argument.WIRMessageDataKey.toString('utf8'));
     } catch (err: any) {
-      log.error(`Unparseable message data: ${truncateString(JSON.stringify(plist), 100)}`);
-      throw new Error(`Unable to parse message data: ${err.message}`);
+      log.error(`Unparseable message data: ${util.truncateString(JSON.stringify(plist), 100)}`);
+      throw new Error(`Unable to parse message data: ${err.message}`, {cause: err});
     }
   }
 
@@ -213,7 +212,7 @@ export default class RpcMessageHandler extends EventEmitter {
         return new Error(message);
       }
       if (dataKey.error) {
-        if (isPlainObject(dataKey.error)) {
+        if (util.isPlainObject(dataKey.error)) {
           const dataKeyError = dataKey.error as DataErrorMessage;
           const error = new Error(defaultMessage);
           for (const key of Object.keys(dataKeyError)) {

package/lib/utils/async.ts

@@ -0,0 +1,32 @@
+import {DelayCancellation} from './errors';
+
+export type CancellableDelay = Promise<void> & {
+  cancel: () => void;
+};
+
+/**
+ * Returns a delay promise with a `cancel` method that rejects the promise.
+ *
+ * @param ms - Delay in milliseconds.
+ * @returns A cancellable delay promise.
+ */
+export function cancellableDelay(ms: number): CancellableDelay {
+  let timeoutId: NodeJS.Timeout | undefined;
+  let rejectFn: ((error: Error) => void) | undefined;
+
+  const promise = new Promise<void>((resolve, reject) => {
+    rejectFn = reject;
+    timeoutId = setTimeout(resolve, ms);
+  }) as CancellableDelay;
+
+  promise.cancel = () => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+      timeoutId = undefined;
+    }
+    rejectFn?.(new DelayCancellation());
+    rejectFn = undefined;
+  };
+
+  return promise;
+}

package/lib/utils/errors.ts

@@ -0,0 +1,19 @@
+/**
+ * Thrown when a cancellable delay is cancelled.
+ */
+export class DelayCancellation extends Error {
+  constructor(message: string = 'Delay cancelled') {
+    super(message);
+    this.name = 'DelayCancellation';
+  }
+}
+
+/**
+ * Error thrown when an async operation exceeds the configured timeout.
+ */
+export class TimeoutError extends Error {
+  constructor(message: string = 'Operation timed out') {
+    super(message);
+    this.name = 'TimeoutError';
+  }
+}

package/lib/utils/index.ts

@@ -0,0 +1,18 @@
+export {DelayCancellation, TimeoutError} from './errors';
+export type {CancellableDelay} from './async';
+export {cancellableDelay} from './async';
+export {defaults, deepEqual, checkParams} from './object';
+
+export {
+  WEB_CONTENT_BUNDLE_ID,
+  appInfoFromDict,
+  pageArrayFromDict,
+  appIdsForBundle,
+} from './inspector';
+export {
+  RESPONSE_LOG_LENGTH,
+  simpleStringify,
+  convertJavascriptEvaluationResult,
+} from './javascript';
+export {getModuleRoot, getModuleProperties} from './module';
+export {canUseWebInspectorShim} from './platform';

package/lib/utils/inspector.ts

@@ -0,0 +1,99 @@
+import {util} from '@appium/support';
+import type {StringRecord} from '@appium/types';
+import type {AppInfo, AppDict, Page} from '../types';
+
+export const WEB_CONTENT_BUNDLE_ID = 'com.apple.WebKit.WebContent';
+
+const INACTIVE_APP_CODE = 0;
+
+// values for the page `WIRTypeKey` entry
+const ACCEPTED_PAGE_TYPES = [
+  'WIRTypeWeb', // up to iOS 11.3
+  'WIRTypeWebPage', // iOS 11.4
+  'WIRTypePage', // iOS 11.4 webview
+];
+
+/**
+ * Takes a dictionary from the remote debugger and converts it into a more
+ * manageable AppInfo object with understandable keys.
+ *
+ * @param dict - Dictionary from the remote debugger containing application information.
+ * @returns A tuple containing the application ID and the AppInfo object.
+ */
+export function appInfoFromDict(dict: Record<string, any>): [string, AppInfo] {
+  const id = dict.WIRApplicationIdentifierKey;
+  const isProxy =
+    typeof dict.WIRIsApplicationProxyKey === 'string'
+      ? dict.WIRIsApplicationProxyKey.toLowerCase() === 'true'
+      : dict.WIRIsApplicationProxyKey;
+  // automation enabled can be either from the keys
+  //   - WIRRemoteAutomationEnabledKey (boolean)
+  //   - WIRAutomationAvailabilityKey (string or boolean)
+  let isAutomationEnabled: boolean | string = !!dict.WIRRemoteAutomationEnabledKey;
+  if (Object.hasOwn(dict, 'WIRAutomationAvailabilityKey')) {
+    if (typeof dict.WIRAutomationAvailabilityKey === 'string') {
+      isAutomationEnabled =
+        dict.WIRAutomationAvailabilityKey === 'WIRAutomationAvailabilityUnknown'
+          ? 'Unknown'
+          : dict.WIRAutomationAvailabilityKey === 'WIRAutomationAvailabilityAvailable';
+    } else {
+      isAutomationEnabled = !!dict.WIRAutomationAvailabilityKey;
+    }
+  }
+  const entry: AppInfo = {
+    id,
+    isProxy,
+    name: dict.WIRApplicationNameKey,
+    bundleId: dict.WIRApplicationBundleIdentifierKey,
+    hostId: dict.WIRHostApplicationIdentifierKey,
+    isActive: dict.WIRIsApplicationActiveKey !== INACTIVE_APP_CODE,
+    isAutomationEnabled,
+  };
+
+  return [id, entry];
+}
+
+/**
+ * Takes a dictionary from the remote debugger and converts it into an array
+ * of Page objects with understandable keys. Filters out non-web pages.
+ *
+ * @param pageDict - Dictionary from the remote debugger containing page information.
+ * @returns An array of Page objects representing the available pages.
+ */
+export function pageArrayFromDict(pageDict: StringRecord): Page[] {
+  return (
+    Object.values(pageDict)
+      // count only WIRTypeWeb pages and ignore all others (WIRTypeJavaScript etc)
+      .filter(
+        (dict) => dict.WIRTypeKey === undefined || ACCEPTED_PAGE_TYPES.includes(dict.WIRTypeKey),
+      )
+      .map((dict) => ({
+        id: dict.WIRPageIdentifierKey,
+        title: dict.WIRTitleKey,
+        url: dict.WIRURLKey,
+        isKey: dict.WIRConnectionIdentifierKey !== undefined,
+      }))
+  );
+}
+
+/**
+ * Finds all application identifier keys that match the given bundle ID.
+ * If no matches are found and the bundle ID is not WEB_CONTENT_BUNDLE_ID,
+ * falls back to searching for WEB_CONTENT_BUNDLE_ID.
+ *
+ * @param bundleId - The bundle identifier to search for.
+ * @param appDict - The application dictionary to search in.
+ * @returns An array of unique application identifier keys matching the bundle ID.
+ */
+export function appIdsForBundle(bundleId: string, appDict: AppDict): string[] {
+  const appIds: string[] = Object.entries(appDict)
+    .filter(([, data]) => data.bundleId === bundleId)
+    .map(([key]) => key);
+
+  // if nothing is found, try to get the generic app
+  if (appIds.length === 0 && bundleId !== WEB_CONTENT_BUNDLE_ID) {
+    return appIdsForBundle(WEB_CONTENT_BUNDLE_ID, appDict);
+  }
+
+  return util.uniq(appIds);
+}

package/lib/utils/javascript.ts

@@ -0,0 +1,89 @@
+import {errorFromMJSONWPStatusCode} from '@appium/base-driver';
+import {util} from '@appium/support';
+
+export const RESPONSE_LOG_LENGTH = 100;
+
+/**
+ * Converts a value to a best-effort JSON string for logging, removing noisy
+ * function properties from cloneable objects when possible.
+ *
+ * Falls back to `String(value)` when JSON serialization returns `undefined`
+ * or throws (for example, for functions, symbols, or circular structures).
+ *
+ * @param value - The value to stringify.
+ * @param multiline - If true, formats JSON output with indentation. Defaults to false.
+ * @returns A string representation suitable for logging.
+ */
+export function simpleStringify(value: any, multiline: boolean = false): string {
+  const stringify = (val: any): string => {
+    try {
+      return multiline
+        ? (JSON.stringify(val, null, 2) ?? String(val))
+        : (JSON.stringify(val) ?? String(val));
+    } catch {
+      return String(val);
+    }
+  };
+
+  if (!value) {
+    return stringify(value);
+  }
+
+  let cleanValue = value;
+  if (typeof value === 'object' && value !== null) {
+    try {
+      cleanValue = removeNoisyProperties(structuredClone(value));
+    } catch {
+      // Fall back to the original value when cloning fails (e.g., non-cloneable graph entries).
+      cleanValue = value;
+    }
+  }
+  return stringify(cleanValue);
+}
+
+/**
+ * Converts the result from a JavaScript evaluation in the remote debugger
+ * into a usable format. Handles errors, serialization, and cleans up noisy
+ * function properties.
+ *
+ * @param res - The raw result from the remote debugger's JavaScript evaluation.
+ * @returns The cleaned and converted result value.
+ * @throws Error if the result is undefined, has an unexpected type, or contains
+ *               an error status code.
+ */
+export function convertJavascriptEvaluationResult(res: any): any {
+  if (res === undefined) {
+    throw new Error(
+      `Did not get OK result from remote debugger. Result was: ${util.truncateString(simpleStringify(res), RESPONSE_LOG_LENGTH)}`,
+    );
+  } else if (typeof res === 'string') {
+    try {
+      res = JSON.parse(res);
+    } catch {
+      // we might get a serialized object, but we might not
+      // if we get here, it is just a value
+    }
+  } else if ((typeof res !== 'object' && typeof res !== 'function') || res === null) {
+    throw new Error(`Result has unexpected type: (${typeof res}).`);
+  }
+
+  if (Object.hasOwn(res, 'status') && res.status !== 0) {
+    // we got some form of error.
+    throw errorFromMJSONWPStatusCode(res.status, res.value.message || res.value);
+  }
+
+  // with either have an object with a `value` property (even if `null`),
+  // or a plain object
+  const value = Object.hasOwn(res, 'value') ? res.value : res;
+  return removeNoisyProperties(value);
+}
+
+function removeNoisyProperties<T>(obj: T): T {
+  if (obj && typeof obj === 'object') {
+    const record = obj as Record<string, unknown>;
+    for (const property of ['ceil', 'clone', 'floor', 'round', 'scale', 'toString']) {
+      delete record[property];
+    }
+  }
+  return obj;
+}

package/lib/utils/module.ts

@@ -0,0 +1,33 @@
+import {util, node} from '@appium/support';
+import nodeFs from 'node:fs';
+import path from 'node:path';
+import type {StringRecord} from '@appium/types';
+
+const MODULE_NAME = 'appium-remote-debugger';
+
+function resolveModuleRoot(): string {
+  const root = node.getModuleRootSync(MODULE_NAME, __filename);
+  if (!root) {
+    throw new Error(`Cannot find the root folder of the ${MODULE_NAME} Node.js module`);
+  }
+  return root;
+}
+
+/**
+ * Calculates the path to the current module's root folder.
+ * The result is memoized for performance.
+ *
+ * @returns The full path to the module root directory.
+ * @throws Error if the module root folder cannot be determined.
+ */
+export const getModuleRoot = util.memoize(resolveModuleRoot);
+
+/**
+ * Reads and parses the package.json file from the module root.
+ *
+ * @returns The parsed package.json contents as a StringRecord.
+ */
+export function getModuleProperties(): StringRecord {
+  const fullPath = path.resolve(getModuleRoot(), 'package.json');
+  return JSON.parse(nodeFs.readFileSync(fullPath, 'utf8'));
+}

package/lib/utils/object.ts

@@ -0,0 +1,55 @@
+import {util} from '@appium/support';
+import {isDeepStrictEqual} from 'node:util';
+import type {StringRecord} from '@appium/types';
+
+/**
+ * Creates a shallow object where undefined keys from `target` are filled
+ * from `defaultsObj`.
+ *
+ * @param target - The object with priority values.
+ * @param defaultsObj - The object providing fallback values.
+ * @returns A new object containing merged defaulted values.
+ */
+export function defaults<T extends Record<string, any>, U extends Record<string, any>>(
+  target: T,
+  defaultsObj: U,
+): T & U {
+  const result = {...target} as T & U;
+  for (const [key, value] of Object.entries(defaultsObj)) {
+    if (result[key as keyof (T & U)] === undefined) {
+      (result as any)[key] = value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Performs deep strict equality comparison.
+ *
+ * @param a - First value.
+ * @param b - Second value.
+ * @returns True when both values are deeply equal.
+ */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  return isDeepStrictEqual(a, b);
+}
+
+/**
+ * Validates that all parameters in the provided object have non-nil values.
+ * Throws an error if any parameters are missing (null or undefined).
+ *
+ * @template T - The type of the parameters object.
+ * @param params - An object containing parameters to validate.
+ * @returns The same parameters object if all values are valid.
+ * @throws Error if any parameters are missing, listing all missing parameter names.
+ */
+export function checkParams<T extends StringRecord>(params: T): T {
+  // check if all parameters have a value
+  const errors = Object.entries(params)
+    .filter(([, value]) => value == null)
+    .map(([param]) => param);
+  if (errors.length) {
+    throw new Error(`Missing ${util.pluralize('parameter', errors.length)}: ${errors.join(', ')}`);
+  }
+  return params;
+}

package/lib/utils/platform.ts

@@ -0,0 +1,10 @@
+import {util} from '@appium/support';
+
+/**
+ * Determines if the WebInspector shim can be used based on the provided iOS platform version.
+ * @param platformVersion - The iOS platform version string (e.g., "18.0", "17.5.1"), or undefined/null when unknown.
+ * @returns true if the WebInspector shim can be used, false otherwise
+ */
+export function canUseWebInspectorShim(platformVersion: string | undefined | null): boolean {
+  return !!platformVersion && util.compareVersions(platformVersion, '>=', '18.0');
+}

package/package.json

@@ -4,7 +4,7 @@
   "keywords": [
     "appium"
   ],
-  "version": "15.9.0",
+  "version": "15.10.0",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -33,7 +33,7 @@
   ],
   "dependencies": {
     "@appium/base-driver": "^10.0.0-rc.1",
-    "@appium/support": "^7.0.0-rc.1",
+    "@appium/support": "^7.2.2",
     "appium-ios-device": "^3.0.0",
     "async-lock": "^1.4.1",
     "asyncbox": "^6.1.0",
@@ -72,8 +72,14 @@
     "@appium/types": "^1.0.0-rc.1",
     "@semantic-release/changelog": "^6.0.1",
     "@semantic-release/git": "^10.0.1",
+    "@types/async-lock": "^1.4.2",
+    "@types/chai": "^5.2.3",
+    "@types/chai-as-promised": "^8.0.2",
+    "@types/finalhandler": "^1.2.4",
     "@types/mocha": "^10.0.1",
     "@types/node": "^25.0.0",
+    "@types/serve-static": "^2.2.0",
+    "@types/sinon": "^21.0.1",
     "appium-ios-simulator": "^8.0.0",
     "chai": "^6.0.0",
     "chai-as-promised": "^8.0.0",
@@ -85,7 +91,7 @@
     "prettier": "^3.0.0",
     "semantic-release": "^25.0.2",
     "serve-static": "^2.2.0",
-    "sinon": "^21.0.0",
+    "sinon": "^22.0.0",
     "ts-node": "^10.9.1",
     "typescript": "^6.0.3"
   }