appium-remote-debugger 15.2.9 → 15.2.11

package/lib/mixins/{execute.js → execute.ts}

@@ -14,37 +14,55 @@ import {
   getPageIdKey,
   getGarbageCollectOnExecute,
 } from './property-accessors';
+import type { RemoteDebugger } from '../remote-debugger';
+import type { AppIdKey, PageIdKey } from '../types';
 
 /* How many milliseconds to wait for webkit to return a response before timing out */
 const RPC_RESPONSE_TIMEOUT_MS = 5000;
 
 /**
- * Execute a Selenium atom in Safari
+ * Executes a Selenium atom in Safari by generating the atom script and
+ * executing it in the page context.
  *
- * @this {RemoteDebugger}
- * @param {string} atom Name of Selenium atom (see atoms/ directory)
- * @param {any[]} args Arguments passed to the atom
- * @param {string[]} frames
- * @returns {Promise<any>} The result received from the atom
+ * @param atom - Name of the Selenium atom to execute (see atoms/ directory).
+ * @param args - Arguments to pass to the atom function. Defaults to empty array.
+ * @param frames - Frame context array for frame-specific execution. Defaults to empty array.
+ * @returns A promise that resolves to the result received from the atom execution.
  */
-export async function executeAtom (atom, args = [], frames = []) {
+export async function executeAtom(
+  this: RemoteDebugger,
+  atom: string,
+  args: any[] = [],
+  frames: string[] = []
+): Promise<any> {
   this.log.debug(`Executing atom '${atom}' with 'args=${JSON.stringify(args)}; frames=${frames}'`);
   const script = await getScriptForAtom(atom, args, frames);
   const value = await this.execute(script);
-  this.log.debug(`Received result for atom '${atom}' execution: ${_.truncate(simpleStringify(value), {length: RESPONSE_LOG_LENGTH})}`);
+  this.log.debug(`Received result for atom '${atom}' execution: ${_.truncate(simpleStringify(value), {
+    length: RESPONSE_LOG_LENGTH
+  })}`);
   return value;
 }
 
 /**
- * @this {RemoteDebugger}
- * @param {string} atom
- * @param {any[]} [args]
- * @param {string[]} [frames]
- * @returns {Promise<any>}
+ * Executes a Selenium atom asynchronously by creating a Promise in the page context
+ * and waiting for the atom to resolve it. Falls back to polling if Runtime.awaitPromise
+ * is not available.
+ *
+ * @param atom - Name of the Selenium atom to execute (see atoms/ directory).
+ * @param args - Arguments to pass to the atom function. Defaults to empty array.
+ *               If args[2] is provided, it will be used as the timeout in milliseconds.
+ * @param frames - Frame context array for frame-specific execution. Defaults to empty array.
+ * @returns A promise that resolves to the result received from the atom execution.
  */
-export async function executeAtomAsync (atom, args = [], frames = []) {
+export async function executeAtomAsync(
+  this: RemoteDebugger,
+  atom: string,
+  args: any[] = [],
+  frames: string[] = []
+): Promise<any> {
   // helper to send directly to the web inspector
-  const evaluate = async (method, opts) => await this.requireRpcClient(true).send(method, Object.assign({
+  const evaluate = async (method: string, opts: any) => await this.requireRpcClient(true).send(method, Object.assign({
     appIdKey: getAppIdKey(this),
     pageIdKey: getPageIdKey(this),
     returnByValue: false,
@@ -76,7 +94,7 @@ export async function executeAtomAsync (atom, args = [], frames = []) {
   await this.execute(await getScriptForAtom(atom, args, frames, asyncCallBack));
 
   // wait for the promise to be resolved
-  let res;
+  let res: any;
   const subcommandTimeout = 1000; // timeout on individual commands
   try {
     res = await evaluate('Runtime.awaitPromise', {
@@ -85,7 +103,7 @@ export async function executeAtomAsync (atom, args = [], frames = []) {
       generatePreview: true,
       saveResult: true,
     });
-  } catch (err) {
+  } catch (err: any) {
     if (!err.message.includes(`'Runtime.awaitPromise' was not found`)) {
       throw err;
     }
@@ -127,13 +145,16 @@ export async function executeAtomAsync (atom, args = [], frames = []) {
 }
 
 /**
- * @this {RemoteDebugger}
- * @param {string} command
- * @param {boolean} [override] - Deprecated and unused
- * @returns {Promise<any>}
+ * Executes a JavaScript command in the page context and returns the result.
+ * Optionally performs garbage collection before execution if configured.
+ *
+ * @param command - The JavaScript command string to execute.
+ * @param override - Deprecated and unused parameter.
+ * @returns A promise that resolves to the result of the JavaScript evaluation,
+ *          converted to a usable format.
  */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-export async function execute (command, override) {
+export async function execute(this: RemoteDebugger, command: string, override?: boolean): Promise<any> {
   const {appIdKey, pageIdKey} = checkParams({
     appIdKey: getAppIdKey(this),
     pageIdKey: getPageIdKey(this),
@@ -145,8 +166,8 @@ export async function execute (command, override) {
 
   const rpcClient = this.requireRpcClient(true);
   await rpcClient.waitForPage(
-    /** @type {import('../types').AppIdKey} */ (appIdKey),
-    /** @type {import('../types').PageIdKey} */ (pageIdKey)
+    appIdKey as AppIdKey,
+    pageIdKey as PageIdKey
   );
   this.log.debug(`Sending javascript command: '${_.truncate(command, {length: 50})}'`);
   const res = await rpcClient.send('Runtime.evaluate', {
@@ -159,12 +180,21 @@ export async function execute (command, override) {
 }
 
 /**
- * @this {RemoteDebugger}
- * @param {string} objectId
- * @param {any} fn
- * @param {any[]} [args]
+ * Calls a JavaScript function on a remote object identified by objectId.
+ * Optionally performs garbage collection before execution if configured.
+ *
+ * @param objectId - The object identifier of the remote object to call the function on.
+ * @param fn - The function declaration string to execute on the object.
+ * @param args - Optional array of arguments to pass to the function.
+ * @returns A promise that resolves to the result of the function call,
+ *          converted to a usable format.
  */
-export async function callFunction (objectId, fn, args) {
+export async function callFunction(
+  this: RemoteDebugger,
+  objectId: string,
+  fn: string,
+  args?: any[]
+): Promise<any> {
   const {appIdKey, pageIdKey} = checkParams({
     appIdKey: getAppIdKey(this),
     pageIdKey: getPageIdKey(this),
@@ -186,7 +216,3 @@ export async function callFunction (objectId, fn, args) {
 
   return convertJavascriptEvaluationResult(res);
 }
-
-/**
- * @typedef {import('../remote-debugger').RemoteDebugger} RemoteDebugger
- */

package/lib/mixins/message-handlers.ts

@@ -0,0 +1,272 @@
+import { events } from './events';
+import {
+  pageArrayFromDict,
+  appInfoFromDict,
+} from '../utils';
+import _ from 'lodash';
+import {
+  setAppIdKey,
+  getAppDict,
+  getAppIdKey,
+  getBundleId,
+  getNavigatingToPage,
+  setCurrentState,
+  setConnectedDrivers,
+  getSkippedApps,
+} from './property-accessors';
+import type { RemoteDebugger } from '../remote-debugger';
+import type { StringRecord } from '@appium/types';
+import type { AppDict } from '../types';
+
+/*
+ * Generic callbacks used throughout the lifecycle of the Remote Debugger.
+ * These will be added to the prototype.
+ */
+
+/**
+ * Handles page change notifications from the remote debugger.
+ * Updates the page array for the specified application and emits a page change
+ * event if the pages have actually changed and navigation is not in progress.
+ *
+ * @param err - Error object if an error occurred, null or undefined otherwise.
+ * @param appIdKey - The application identifier key for which pages have changed.
+ * @param pageDict - Dictionary containing the new page information.
+ */
+export async function onPageChange(
+  this: RemoteDebugger,
+  err: Error | null | undefined,
+  appIdKey: string,
+  pageDict: StringRecord
+): Promise<void> {
+  if (_.isEmpty(pageDict)) {
+    return;
+  }
+
+  const currentPages = pageArrayFromDict(pageDict);
+  // save the page dict for this app
+  if (getAppDict(this)[appIdKey]) {
+    const previousPages = getAppDict(this)[appIdKey].pageArray;
+    // we have a pre-existing pageDict
+    if (previousPages && _.isEqual(previousPages, currentPages)) {
+      this.log.debug(
+        `Received page change notice for app '${appIdKey}' ` +
+        `but the listing has not changed. Ignoring.`
+      );
+      return;
+    }
+    // keep track of the page dictionary
+    getAppDict(this)[appIdKey].pageArray = currentPages;
+    this.log.debug(
+      `Pages changed for ${appIdKey}: ${JSON.stringify(previousPages)} -> ${JSON.stringify(currentPages)}`
+    );
+  }
+
+  if (getNavigatingToPage(this)) {
+    // in the middle of navigating, so reporting a page change will cause problems
+    return;
+  }
+
+  this.emit(events.EVENT_PAGE_CHANGE, {
+    appIdKey: appIdKey.replace('PID:', ''),
+    pageArray: currentPages,
+  });
+}
+
+/**
+ * Handles notifications when a new application connects to the remote debugger.
+ * Updates the application dictionary with the new application information.
+ *
+ * @param err - Error object if an error occurred, null or undefined otherwise.
+ * @param dict - Dictionary containing the new application information including
+ *               the WIRApplicationIdentifierKey.
+ */
+export async function onAppConnect(
+  this: RemoteDebugger,
+  err: Error | null | undefined,
+  dict: StringRecord
+): Promise<void> {
+  const appIdKey = dict.WIRApplicationIdentifierKey;
+  this.log.debug(`Notified that new application '${appIdKey}' has connected`);
+  updateAppsWithDict.bind(this)(dict);
+}
+
+/**
+ * Handles notifications when an application disconnects from the remote debugger.
+ * Removes the application from the dictionary and attempts to find a replacement
+ * if the disconnected app was the currently selected one. Emits a disconnect event
+ * if no applications remain.
+ *
+ * @param err - Error object if an error occurred, null or undefined otherwise.
+ * @param dict - Dictionary containing the disconnected application information
+ *               including the WIRApplicationIdentifierKey.
+ */
+export function onAppDisconnect(
+  this: RemoteDebugger,
+  err: Error | null | undefined,
+  dict: StringRecord
+): void {
+  const appIdKey = dict.WIRApplicationIdentifierKey;
+  this.log.debug(`Application '${appIdKey}' disconnected. Removing from app dictionary.`);
+  this.log.debug(`Current app is '${getAppIdKey(this)}'`);
+
+  // get rid of the entry in our app dictionary,
+  // since it is no longer available
+  delete getAppDict(this)[appIdKey];
+
+  // if the disconnected app is the one we are connected to, try to find another
+  if (getAppIdKey(this) === appIdKey) {
+    this.log.debug(`No longer have app id. Attempting to find new one.`);
+    setAppIdKey(this, getDebuggerAppKey.bind(this)(getBundleId(this) as string));
+  }
+
+  if (_.isEmpty(getAppDict(this))) {
+    // this means we no longer have any apps. what the what?
+    this.log.debug('Main app disconnected. Disconnecting altogether.');
+    this.emit(events.EVENT_DISCONNECT, true);
+  }
+}
+
+/**
+ * Handles notifications when an application's information is updated.
+ * Updates the application dictionary with the new information while preserving
+ * any existing page array data.
+ *
+ * @param err - Error object if an error occurred, null or undefined otherwise.
+ * @param dict - Dictionary containing the updated application information.
+ */
+export async function onAppUpdate(
+  this: RemoteDebugger,
+  err: Error | null | undefined,
+  dict: StringRecord
+): Promise<void> {
+  this.log.debug(`Notified that an application has been updated`);
+  updateAppsWithDict.bind(this)(dict);
+}
+
+/**
+ * Handles notifications containing the list of connected drivers.
+ * Updates the internal connected drivers list with the received information.
+ *
+ * @param err - Error object if an error occurred, null or undefined otherwise.
+ * @param drivers - Dictionary containing the connected driver list with
+ *                  WIRDriverDictionaryKey.
+ */
+export function onConnectedDriverList(
+  this: RemoteDebugger,
+  err: Error | null | undefined,
+  drivers: StringRecord
+): void {
+  setConnectedDrivers(this, drivers.WIRDriverDictionaryKey);
+  this.log.debug(`Received connected driver list: ${JSON.stringify(this.connectedDrivers)}`);
+}
+
+/**
+ * Handles notifications about the current automation availability state.
+ * This state changes when 'Remote Automation' setting in Safari's advanced settings
+ * is toggled. The state can be either WIRAutomationAvailabilityAvailable or
+ * WIRAutomationAvailabilityNotAvailable.
+ *
+ * @param err - Error object if an error occurred, null or undefined otherwise.
+ * @param state - Dictionary containing the automation availability state with
+ *                WIRAutomationAvailabilityKey.
+ */
+export function onCurrentState(
+  this: RemoteDebugger,
+  err: Error | null | undefined,
+  state: StringRecord
+): void {
+  setCurrentState(this, state.WIRAutomationAvailabilityKey);
+  // This state changes when 'Remote Automation' in 'Settings app' > 'Safari' > 'Advanced' > 'Remote Automation' changes
+  // WIRAutomationAvailabilityAvailable or WIRAutomationAvailabilityNotAvailable
+  this.log.debug(`Received connected automation availability state: ${JSON.stringify(this.currentState)}`);
+}
+
+/**
+ * Handles notifications containing the list of connected applications.
+ * Translates the received information into the application dictionary format,
+ * filtering out any applications that are in the skipped apps list.
+ *
+ * @param err - Error object if an error occurred, null or undefined otherwise.
+ * @param apps - Dictionary containing the connected applications list.
+ */
+export async function onConnectedApplicationList(
+  this: RemoteDebugger,
+  err: Error | null | undefined,
+  apps: StringRecord
+): Promise<void> {
+  this.log.debug(`Received connected applications list: ${_.keys(apps).join(', ')}`);
+
+  // translate the received information into an easier-to-manage
+  // hash with app id as key, and app info as value
+  const newDict: AppDict = {};
+  for (const dict of _.values(apps)) {
+    const [id, entry] = appInfoFromDict(dict);
+    if (getSkippedApps(this).includes(entry.name)) {
+      continue;
+    }
+    newDict[id] = entry;
+  }
+  // update the object's list of apps
+  _.defaults(getAppDict(this), newDict);
+}
+
+/**
+ * Given a bundle ID, finds the correct remote debugger app identifier key
+ * that is currently connected. Also handles proxy applications that may act
+ * on behalf of the requested bundle ID.
+ *
+ * @param bundleId - The bundle identifier to search for.
+ * @returns The application identifier key if found, undefined otherwise.
+ *          If a proxy application is found, returns the proxy's app ID instead.
+ */
+export function getDebuggerAppKey(this: RemoteDebugger, bundleId: string): string | undefined {
+  let appId: string | undefined;
+  for (const [key, data] of _.toPairs(getAppDict(this))) {
+    if (data.bundleId === bundleId) {
+      appId = key;
+      break;
+    }
+  }
+  // now we need to determine if we should pick a proxy for this instead
+  if (appId) {
+    this.log.debug(`Found app id key '${appId}' for bundle '${bundleId}'`);
+    let proxyAppId: string | undefined;
+    for (const [key, data] of _.toPairs(getAppDict(this))) {
+      if (data.isProxy && data.hostId === appId) {
+        this.log.debug(`Found separate bundleId '${data.bundleId}' ` +
+                  `acting as proxy for '${bundleId}', with app id '${key}'`);
+        // set the app id... the last one will be used, so just keep re-assigning
+        proxyAppId = key;
+      }
+    }
+    if (proxyAppId) {
+      appId = proxyAppId;
+      this.log.debug(`Using proxied app id '${appId}'`);
+    }
+  }
+
+  return appId;
+}
+
+/**
+ * Updates the application dictionary with information from the provided dictionary.
+ * Preserves existing page array data if the application already exists in the dictionary.
+ * Attempts to set the app ID key if one is not currently set.
+ *
+ * @param dict - Dictionary containing application information to add or update.
+ */
+function updateAppsWithDict(this: RemoteDebugger, dict: StringRecord): void {
+  // get the dictionary entry into a nice form, and add it to the
+  // application dictionary
+  const [id, entry] = appInfoFromDict(dict);
+  if (getAppDict(this)[id]?.pageArray) {
+    // preserve the page dictionary for this entry
+    entry.pageArray = getAppDict(this)[id].pageArray;
+  }
+  getAppDict(this)[id] = entry;
+
+  // try to get the app id from our connected apps
+  if (!getAppIdKey(this)) {
+    setAppIdKey(this, getDebuggerAppKey.bind(this)(getBundleId(this) as string));
+  }
+}

package/lib/mixins/misc.ts

@@ -0,0 +1,136 @@
+import { checkParams } from '../utils';
+import B, { TimeoutError as BTimeoutError } from 'bluebird';
+import {
+  getAppIdKey,
+  getPageIdKey,
+} from './property-accessors';
+import type { RemoteDebugger } from '../remote-debugger';
+
+const SAFARI_BUNDLE_ID = 'com.apple.mobilesafari';
+const GARBAGE_COLLECT_TIMEOUT_MS = 5000;
+
+/**
+ * Launches Safari application on the device by sending a launch command
+ * to the remote debugger.
+ */
+export async function launchSafari(this: RemoteDebugger): Promise<void> {
+  await this.requireRpcClient().send('launchApplication', {
+    bundleId: SAFARI_BUNDLE_ID
+  });
+}
+
+/**
+ * Starts recording the timeline by registering an event listener and
+ * sending the Timeline.start command to the remote debugger.
+ *
+ * @param fn - Event listener function that will be called when timeline events are recorded.
+ * @returns A promise that resolves when the timeline recording has started.
+ */
+export async function startTimeline(
+  this: RemoteDebugger,
+  fn: import('../types').EventListener
+): Promise<any> {
+  this.log.debug('Starting to record the timeline');
+  this.requireRpcClient().on('Timeline.eventRecorded', fn);
+  return await this.requireRpcClient().send('Timeline.start', {
+    appIdKey: getAppIdKey(this),
+    pageIdKey: getPageIdKey(this),
+  });
+}
+
+/**
+ * Stops recording the timeline by sending the Timeline.stop command
+ * to the remote debugger.
+ */
+export async function stopTimeline(this: RemoteDebugger): Promise<any> {
+  this.log.debug('Stopping to record the timeline');
+  await this.requireRpcClient().send('Timeline.stop', {
+    appIdKey: getAppIdKey(this),
+    pageIdKey: getPageIdKey(this),
+  });
+}
+
+/**
+ * Overrides the user agent string for the current page.
+ * Note: This may not work for mobile Safari.
+ *
+ * @param value - The user agent string to set.
+ * @returns A promise that resolves when the user agent has been overridden.
+ */
+export async function overrideUserAgent(this: RemoteDebugger, value: string): Promise<any> {
+  this.log.debug('Setting overrideUserAgent');
+  return await this.requireRpcClient().send('Page.overrideUserAgent', {
+    appIdKey: getAppIdKey(this),
+    pageIdKey: getPageIdKey(this),
+    value,
+  });
+}
+
+/**
+ * Checks whether JavaScript execution is currently blocked on the page
+ * by attempting to execute a simple JavaScript command with a timeout.
+ *
+ * @param timeoutMs - The maximum amount of milliseconds to wait for a JavaScript
+ *                    command response. Defaults to 1000ms.
+ * @returns A promise that resolves to true if JavaScript execution is blocked,
+ *          false if it is not blocked.
+ */
+export async function isJavascriptExecutionBlocked(
+  this: RemoteDebugger,
+  timeoutMs: number = 1000
+): Promise<boolean> {
+  try {
+    await B.resolve(
+      this.requireRpcClient().send('Runtime.evaluate', {
+        expression: '1+1;',
+        returnByValue: true,
+        appIdKey: getAppIdKey(this),
+        pageIdKey: getPageIdKey(this),
+      })
+    ).timeout(timeoutMs);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Triggers garbage collection on the page's JavaScript heap.
+ * This method will gracefully handle cases where garbage collection cannot
+ * be performed (e.g., when not connected to a page).
+ *
+ * @param timeoutMs - Maximum time in milliseconds to wait for garbage collection
+ *                    to complete. Defaults to GARBAGE_COLLECT_TIMEOUT_MS (5000ms).
+ */
+export async function garbageCollect(
+  this: RemoteDebugger,
+  timeoutMs: number = GARBAGE_COLLECT_TIMEOUT_MS
+): Promise<void> {
+  this.log.debug(`Garbage collecting with ${timeoutMs}ms timeout`);
+
+  try {
+    checkParams({
+      appIdKey: getAppIdKey(this),
+      pageIdKey: getPageIdKey(this),
+    });
+  } catch {
+    this.log.debug(`Unable to collect garbage at this time`);
+    return;
+  }
+
+  try {
+    await B.resolve(this.requireRpcClient().send(
+      'Heap.gc', {
+        appIdKey: getAppIdKey(this),
+        pageIdKey: getPageIdKey(this),
+      })
+    ).timeout(timeoutMs);
+    this.log.debug(`Garbage collection successful`);
+  } catch (e: any) {
+    if (e instanceof BTimeoutError) {
+      this.log.debug(`Garbage collection timed out after ${timeoutMs}ms`);
+    } else {
+      this.log.debug(`Unable to collect garbage: ${e.message}`);
+    }
+  }
+}