appium-remote-debugger 15.2.11 → 15.2.13

package/lib/atoms.ts

@@ -0,0 +1,98 @@
+import { fs } from '@appium/support';
+import path from 'path';
+import _ from 'lodash';
+import { log } from './logger';
+import { getModuleRoot } from './utils';
+
+const ATOMS_CACHE: Record<string, Buffer> = {};
+
+/**
+ * Converts a value to a JSON string, handling undefined values specially.
+ *
+ * @param obj - The value to stringify.
+ * @returns A JSON string representation of the value, or 'undefined' if the value is undefined.
+ */
+function atomsStringify(obj: any): string {
+  if (typeof obj === 'undefined') {
+    return 'undefined';
+  }
+  return JSON.stringify(obj);
+}
+
+/**
+ * Loads an atom script from the atoms directory and caches it.
+ * If the atom has been loaded before, returns the cached version.
+ *
+ * @param atomName - The name of the atom to load (without the .js extension).
+ * @returns A promise that resolves to the atom script as a Buffer.
+ * @throws Error if the atom file cannot be loaded.
+ */
+export async function getAtom(atomName: string): Promise<Buffer> {
+  // check if we have already loaded and cached this atom
+  if (!_.has(ATOMS_CACHE, atomName)) {
+    const atomFileName = path.resolve(getModuleRoot(), 'atoms', `${atomName}.js`);
+    try {
+      ATOMS_CACHE[atomName] = await fs.readFile(atomFileName);
+    } catch {
+      throw new Error(`Unable to load Atom '${atomName}' from file '${atomFileName}'`);
+    }
+  }
+
+  return ATOMS_CACHE[atomName];
+}
+
+/**
+ * Wraps a script to execute it within a specific frame context.
+ * Uses the get_element_from_cache atom to access the frame element.
+ *
+ * @param script - The script to wrap.
+ * @param frame - The frame identifier to execute the script in.
+ * @returns A promise that resolves to the wrapped script string.
+ */
+async function wrapScriptForFrame(script: string, frame: string): Promise<string> {
+  log.debug(`Wrapping script for frame '${frame}'`);
+  const elFromCache = await getAtom('get_element_from_cache');
+  return `(function (window) { var document = window.document; ` +
+    `return (${script}); })((${elFromCache.toString('utf8')})(${atomsStringify(frame)}))`;
+}
+
+/**
+ * Generates a complete script string for executing a Selenium atom.
+ * Handles frame contexts and optional async callbacks.
+ *
+ * @param atom - The name of the atom to execute.
+ * @param args - Arguments to pass to the atom function. Defaults to empty array.
+ * @param frames - Array of frame identifiers to execute the atom in nested frames.
+ *                 Defaults to empty array (executes in default context).
+ * @param asyncCallBack - Optional callback function string for async execution.
+ *                        If provided, the atom will be called with this callback.
+ * @returns A promise that resolves to the complete script string ready for execution.
+ */
+export async function getScriptForAtom(
+  atom: string,
+  args: any[] = [],
+  frames: string[] = [],
+  asyncCallBack: string | null = null
+): Promise<string> {
+  const atomSrc = (await getAtom(atom)).toString('utf8');
+  let script: string;
+  if (frames.length > 0) {
+    script = atomSrc;
+    for (const frame of frames) {
+      script = await wrapScriptForFrame(script, frame);
+    }
+  } else {
+    log.debug(`Executing '${atom}' atom in default context`);
+    script = `(${atomSrc})`;
+  }
+
+  // add the arguments, as strings
+  args = args.map(atomsStringify);
+  if (asyncCallBack) {
+    script += `(${args.join(',')}, ${asyncCallBack}, true)`;
+  } else {
+    script += `(${args.join(',')})`;
+  }
+
+  return script;
+}

package/lib/logger.ts

@@ -0,0 +1,3 @@
+import { logger } from '@appium/support';
+
+export const log = logger.getLogger('RemoteDebugger');

package/lib/remote-debugger.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'events';
-import defaultLog from './logger';
+import { log as defaultLog } from './logger';
 import { RpcClientSimulator } from './rpc';
 import { getModuleProperties } from './utils';
 import * as connectMixins from './mixins/connect';

package/lib/rpc/rpc-client-real-device.js

@@ -1,4 +1,4 @@
-import log from '../logger';
+import { log } from '../logger';
 import { RpcClient } from './rpc-client';
 import { services } from 'appium-ios-device';
 

package/lib/rpc/rpc-client-simulator.js

@@ -1,4 +1,4 @@
-import log from '../logger';
+import { log } from '../logger';
 import _ from 'lodash';
 import B from 'bluebird';
 import net from 'net';

package/lib/rpc/rpc-client.js

@@ -1,6 +1,6 @@
 import { RemoteMessages } from './remote-messages';
 import { waitForCondition } from 'asyncbox';
-import log from '../logger';
+import { log } from '../logger';
 import _ from 'lodash';
 import B from 'bluebird';
 import RpcMessageHandler from './rpc-message-handler';

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

@@ -1,4 +1,4 @@
-import log from '../logger';
+import { log } from '../logger';
 import _ from 'lodash';
 import { util } from '@appium/support';
 import EventEmitters from 'events';

package/lib/{utils.js → utils.ts}

@@ -3,6 +3,8 @@ import { errorFromMJSONWPStatusCode } from '@appium/base-driver';
 import { util, node } from '@appium/support';
 import nodeFs from 'node:fs';
 import path from 'node:path';
+import type { StringRecord } from '@appium/types';
+import type { AppInfo, AppDict, Page } from './types';
 
 const MODULE_NAME = 'appium-remote-debugger';
 export const WEB_CONTENT_BUNDLE_ID = 'com.apple.WebKit.WebContent';
@@ -16,13 +18,13 @@ const ACCEPTED_PAGE_TYPES = [
 export const RESPONSE_LOG_LENGTH = 100;
 
 /**
- * Takes a dictionary from the remote debugger and makes a more manageable
- * dictionary whose keys are understandable
+ * Takes a dictionary from the remote debugger and converts it into a more
+ * manageable AppInfo object with understandable keys.
  *
- * @param {Record<string, any>} dict
- * @returns {[string, import('./types').AppInfo]}
+ * @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) {
+export function appInfoFromDict(dict: Record<string, any>): [string, AppInfo] {
   const id = dict.WIRApplicationIdentifierKey;
   const isProxy = _.isString(dict.WIRIsApplicationProxyKey)
     ? dict.WIRIsApplicationProxyKey.toLowerCase() === 'true'
@@ -30,8 +32,7 @@ export function appInfoFromDict (dict) {
   // automation enabled can be either from the keys
   //   - WIRRemoteAutomationEnabledKey (boolean)
   //   - WIRAutomationAvailabilityKey (string or boolean)
-  /** @type {boolean|string} */
-  let isAutomationEnabled = !!dict.WIRRemoteAutomationEnabledKey;
+  let isAutomationEnabled: boolean | string = !!dict.WIRRemoteAutomationEnabledKey;
   if (_.has(dict, 'WIRAutomationAvailabilityKey')) {
     if (_.isString(dict.WIRAutomationAvailabilityKey)) {
       isAutomationEnabled = dict.WIRAutomationAvailabilityKey === 'WIRAutomationAvailabilityUnknown'
@@ -41,8 +42,7 @@ export function appInfoFromDict (dict) {
       isAutomationEnabled = !!dict.WIRAutomationAvailabilityKey;
     }
   }
-  /** @type {import('./types').AppInfo} */
-  const entry = {
+  const entry: AppInfo = {
     id,
     isProxy,
     name: dict.WIRApplicationNameKey,
@@ -56,13 +56,13 @@ export function appInfoFromDict (dict) {
 }
 
 /**
- * Take a dictionary from the remote debugger and makes a more manageable
- * dictionary of pages available.
+ * 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 {import('@appium/types').StringRecord} pageDict
- * @returns {import('./types').Page[]}
+ * @param pageDict - Dictionary from the remote debugger containing page information.
+ * @returns An array of Page objects representing the available pages.
  */
-export function pageArrayFromDict (pageDict) {
+export function pageArrayFromDict(pageDict: StringRecord): Page[] {
   return _.values(pageDict)
     // count only WIRTypeWeb pages and ignore all others (WIRTypeJavaScript etc)
     .filter((dict) => _.isUndefined(dict.WIRTypeKey) || ACCEPTED_PAGE_TYPES.includes(dict.WIRTypeKey))
@@ -75,14 +75,16 @@ export function pageArrayFromDict (pageDict) {
 }
 
 /**
+ * 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 {string} bundleId
- * @param {import('./types').AppDict} appDict
- * @returns {string[]}
+ * @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, appDict) {
-  /** @type {string[]} */
-  const appIds = _.toPairs(appDict)
+export function appIdsForBundle(bundleId: string, appDict: AppDict): string[] {
+  const appIds: string[] = _.toPairs(appDict)
     .filter(([, data]) => data.bundleId === bundleId)
     .map(([key]) => key);
 
@@ -95,11 +97,15 @@ export function appIdsForBundle (bundleId, appDict) {
 }
 
 /**
- * @template {import('@appium/types').StringRecord} T
- * @param {T} params
- * @returns {T}
+ * 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 (params) {
+export function checkParams<T extends StringRecord>(params: T): T {
   // check if all parameters have a value
   const errors = _.toPairs(params)
     .filter(([, value]) => _.isNil(value))
@@ -111,30 +117,33 @@ export function checkParams (params) {
 }
 
 /**
- * @param {any} value
- * @param {boolean} [multiline=false]
- * @returns {string}
+ * Converts a value to a JSON string, removing noisy function properties
+ * that can muddy the logs.
+ *
+ * @param value - The value to stringify.
+ * @param multiline - If true, formats the JSON with indentation. Defaults to false.
+ * @returns A JSON string representation of the value with noisy properties removed.
  */
-export function simpleStringify (value, multiline = false) {
+export function simpleStringify(value: any, multiline: boolean = false): string {
   if (!value) {
     return JSON.stringify(value);
   }
 
-  // we get back objects sometimes with string versions of functions
-  // which muddy the logs
-  let cleanValue = _.clone(value);
-  for (const property of ['ceil', 'clone', 'floor', 'round', 'scale', 'toString']) {
-    delete cleanValue[property];
-  }
+  const cleanValue = removeNoisyProperties(_.clone(value));
   return multiline ? JSON.stringify(cleanValue, null, 2) : JSON.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 {any} res
- * @returns {any}
+ * @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) {
+export function convertJavascriptEvaluationResult(res: any): any {
   if (_.isUndefined(res)) {
     throw new Error(`Did not get OK result from remote debugger. Result was: ${_.truncate(simpleStringify(res), {length: RESPONSE_LOG_LENGTH})}`);
   } else if (_.isString(res)) {
@@ -156,23 +165,17 @@ export function convertJavascriptEvaluationResult (res) {
   // with either have an object with a `value` property (even if `null`),
   // or a plain object
   const value = _.has(res, 'value') ? res.value : res;
-
-  // get rid of noisy functions on objects
-  if (_.isObject(value)) {
-    for (const property of ['ceil', 'clone', 'floor', 'round', 'scale', 'toString']) {
-      delete value[property];
-    }
-  }
-  return value;
+  return removeNoisyProperties(value);
 }
 
 /**
- * Calculates the path to the current module's root folder
+ * Calculates the path to the current module's root folder.
+ * The result is memoized for performance.
  *
- * @returns {string} The full path to module root
- * @throws {Error} If the current module root folder cannot be determined
+ * @returns The full path to the module root directory.
+ * @throws Error if the module root folder cannot be determined.
  */
-export const getModuleRoot = _.memoize(function getModuleRoot () {
+export const getModuleRoot = _.memoize(function getModuleRoot(): 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`);
@@ -181,9 +184,27 @@ export const getModuleRoot = _.memoize(function getModuleRoot () {
 });
 
 /**
- * @returns {import('@appium/types').StringRecord}
+ * Reads and parses the package.json file from the module root.
+ *
+ * @returns The parsed package.json contents as a StringRecord.
  */
-export function getModuleProperties() {
+export function getModuleProperties(): StringRecord {
   const fullPath = path.resolve(getModuleRoot(), 'package.json');
   return JSON.parse(nodeFs.readFileSync(fullPath, 'utf8'));
 }
+
+/**
+ * Removes noisy function properties from an object that can muddy the logs.
+ * These properties are often added by JavaScript number objects and similar.
+ *
+ * @param obj - The object to clean.
+ * @returns The cleaned object.
+ */
+function removeNoisyProperties<T>(obj: T): T {
+  if (_.isObject(obj)) {
+    for (const property of ['ceil', 'clone', 'floor', 'round', 'scale', 'toString']) {
+      delete obj[property];
+    }
+  }
+  return obj;
+}

package/package.json

@@ -4,7 +4,7 @@
   "keywords": [
     "appium"
   ],
-  "version": "15.2.11",
+  "version": "15.2.13",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -36,7 +36,7 @@
     "@appium/base-driver": "^10.0.0-rc.1",
     "@appium/support": "^7.0.0-rc.1",
     "appium-ios-device": "^3.0.0",
-    "asyncbox": "^4.0.1",
+    "asyncbox": "^5.0.0",
     "async-lock": "^1.4.1",
     "bluebird": "^3.4.7",
     "glob": "^13.0.0",

package/lib/atoms.js

@@ -1,84 +0,0 @@
-import { fs } from '@appium/support';
-import path from 'path';
-import _ from 'lodash';
-import log from './logger';
-import { getModuleRoot } from './utils';
-
-const ATOMS_CACHE = {};
-
-/**
- * @param {any} obj
- * @returns {string}
- */
-function atomsStringify(obj) {
-  if (typeof obj === 'undefined') {
-    return 'undefined';
-  }
-  return JSON.stringify(obj);
-}
-
-/**
- *
- * @param {string} atomName
- * @returns {Promise<Buffer>}
- */
-async function getAtom (atomName) {
-  // check if we have already loaded and cached this atom
-  if (!_.has(ATOMS_CACHE, atomName)) {
-    const atomFileName = path.resolve(getModuleRoot(), 'atoms', `${atomName}.js`);
-    try {
-      ATOMS_CACHE[atomName] = await fs.readFile(atomFileName);
-    } catch {
-      throw new Error(`Unable to load Atom '${atomName}' from file '${atomFileName}'`);
-    }
-  }
-
-  return ATOMS_CACHE[atomName];
-}
-
-/**
- * @param {string} script
- * @param {string} frame
- * @returns {Promise<string>}
- */
-async function wrapScriptForFrame (script, frame) {
-  log.debug(`Wrapping script for frame '${frame}'`);
-  const elFromCache = await getAtom('get_element_from_cache');
-  return `(function (window) { var document = window.document; ` +
-    `return (${script}); })((${elFromCache.toString('utf8')})(${atomsStringify(frame)}))`;
-}
-
-/**
- *
- * @param {string} atom
- * @param {any[]} [args]
- * @param {string[]} [frames]
- * @param {string?} [asyncCallBack]
- * @returns {Promise<string>}
- */
-async function getScriptForAtom (atom, args = [], frames = [], asyncCallBack = null) {
-  const atomSrc = (await getAtom(atom)).toString('utf8');
-  let script;
-  if (frames.length > 0) {
-    script = atomSrc;
-    for (const frame of frames) {
-      script = await wrapScriptForFrame(script, frame);
-    }
-  } else {
-    log.debug(`Executing '${atom}' atom in default context`);
-    script = `(${atomSrc})`;
-  }
-
-  // add the arguments, as strings
-  args = args.map(atomsStringify);
-  if (asyncCallBack) {
-    script += `(${args.join(',')}, ${asyncCallBack}, true)`;
-  } else {
-    script += `(${args.join(',')})`;
-  }
-
-  return script;
-}
-
-export { getAtom, getScriptForAtom };
-export default getAtom;

package/lib/logger.js

@@ -1,6 +0,0 @@
-import { logger } from '@appium/support';
-
-
-const log = logger.getLogger('RemoteDebugger');
-
-export default log;