appium-remote-debugger 15.2.9 → 15.2.11

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

@@ -19,6 +19,8 @@ import {
   getAdditionalBundleIds,
 } from './property-accessors';
 import { NEW_APP_CONNECTED_ERROR, EMPTY_PAGE_DICTIONARY_ERROR } from '../rpc/rpc-client';
+import type { RemoteDebugger } from '../remote-debugger';
+import type { AppDict, Page, AppIdKey, PageIdKey, AppPage } from '../types';
 
 const APP_CONNECT_TIMEOUT_MS = 0;
 const APP_CONNECT_INTERVAL_MS = 100;
@@ -32,11 +34,11 @@ const SAFARI_VIEW_BUNDLE_ID = 'com.apple.SafariViewService';
 const WILDCARD_BUNDLE_ID = '*';
 
 /**
- *
- * @this {RemoteDebugger}
- * @returns {Promise<void>}
+ * Sends a connection key request to the Web Inspector.
+ * This method only waits to ensure the socket connection works, as the response
+ * from Web Inspector can take a long time.
  */
-export async function setConnectionKey () {
+export async function setConnectionKey(this: RemoteDebugger): Promise<void> {
   this.log.debug('Sending connection key request');
 
   // send but only wait to make sure the socket worked
@@ -45,12 +47,17 @@ export async function setConnectionKey () {
 }
 
 /**
+ * Establishes a connection to the remote debugger and initializes the RPC client.
+ * Sets up event listeners for debugger-level events and waits for applications
+ * to be reported if a timeout is specified.
  *
- * @this {RemoteDebugger}
- * @param {number} [timeout=APP_CONNECT_TIMEOUT_MS]
- * @returns {Promise<import('../types').AppDict>}
+ * @param timeout - Maximum time in milliseconds to wait for applications to be reported.
+ *                  Defaults to 0 (no waiting). If provided, the method will wait up to
+ *                  this duration for applications to appear in the app dictionary.
+ * @returns A promise that resolves to the application dictionary containing all
+ *          connected applications.
  */
-export async function connect (timeout = APP_CONNECT_TIMEOUT_MS) {
+export async function connect(this: RemoteDebugger, timeout: number = APP_CONNECT_TIMEOUT_MS): Promise<AppDict> {
   this.setup();
 
   // initialize the rpc client
@@ -91,7 +98,7 @@ export async function connect (timeout = APP_CONNECT_TIMEOUT_MS) {
       }
     }
     return this.appDict;
-  } catch (err) {
+  } catch (err: any) {
     this.log.error(`Error setting connection key: ${err.message}`);
     await this.disconnect();
     throw err;
@@ -99,25 +106,36 @@ export async function connect (timeout = APP_CONNECT_TIMEOUT_MS) {
 }
 
 /**
- *
- * @this {RemoteDebugger}
- * @returns {Promise<void>}
+ * Disconnects from the remote debugger by closing the RPC client connection,
+ * emitting a disconnect event, and performing cleanup via teardown.
  */
-export async function disconnect () {
+export async function disconnect(this: RemoteDebugger): Promise<void> {
   await getRcpClient(this)?.disconnect();
   this.emit(events.EVENT_DISCONNECT, true);
   this.teardown();
 }
 
 /**
+ * Selects an application from the available connected applications.
+ * Searches for an app matching the provided URL and bundle IDs, then returns
+ * all pages from the selected application.
  *
- * @this {RemoteDebugger}
- * @param {string?} [currentUrl=null]
- * @param {number} [maxTries=SELECT_APP_RETRIES]
- * @param {boolean} [ignoreAboutBlankUrl=false]
- * @returns {Promise<import('../types').Page[]>}
+ * @param currentUrl - Optional URL to match when selecting an application.
+ *                     If provided, the method will try to find an app containing
+ *                     a page with this URL.
+ * @param maxTries - Maximum number of retry attempts when searching for an app.
+ *                   Defaults to SELECT_APP_RETRIES (20).
+ * @param ignoreAboutBlankUrl - If true, pages with 'about:blank' URL will be
+ *                              excluded from the results. Defaults to false.
+ * @returns A promise that resolves to an array of Page objects from the selected
+ *          application. Returns an empty array if no applications are connected.
  */
-export async function selectApp (currentUrl = null, maxTries = SELECT_APP_RETRIES, ignoreAboutBlankUrl = false) {
+export async function selectApp(
+  this: RemoteDebugger,
+  currentUrl: string | null = null,
+  maxTries: number = SELECT_APP_RETRIES,
+  ignoreAboutBlankUrl: boolean = false
+): Promise<Page[]> {
   this.log.debug('Selecting application');
 
   const timer = new timing.Timer().start();
@@ -135,8 +153,7 @@ export async function selectApp (currentUrl = null, maxTries = SELECT_APP_RETRIE
   // translate the dictionary into a useful form, and return to sender
   this.log.debug(`Finally selecting app ${getAppIdKey(this)}`);
 
-  /** @type {import('../types').Page[]} */
-  const fullPageArray = [];
+  const fullPageArray: Page[] = [];
   for (const [app, info] of _.toPairs(getAppDict(this))) {
     if (!_.isArray(info.pageArray) || !info.isActive) {
       continue;
@@ -157,14 +174,22 @@ export async function selectApp (currentUrl = null, maxTries = SELECT_APP_RETRIE
 }
 
 /**
+ * Selects a specific page within an application and forwards socket setup.
+ * Optionally waits for the page to be ready based on the page load strategy.
  *
- * @this {RemoteDebugger}
- * @param {import('../types').AppIdKey} appIdKey
- * @param {import('../types').PageIdKey} pageIdKey
- * @param {boolean} [skipReadyCheck]
- * @returns {Promise<void>}
+ * @param appIdKey - The application identifier key. Will be prefixed with 'PID:'
+ *                    if not already present.
+ * @param pageIdKey - The page identifier key to select.
+ * @param skipReadyCheck - If true, skips the page readiness check. Defaults to false.
+ *                         When false, the method will wait for the page to be ready
+ *                         according to the configured page load strategy.
  */
-export async function selectPage (appIdKey, pageIdKey, skipReadyCheck = false) {
+export async function selectPage(
+  this: RemoteDebugger,
+  appIdKey: AppIdKey,
+  pageIdKey: PageIdKey,
+  skipReadyCheck: boolean = false
+): Promise<void> {
   const fullAppIdKey = _.startsWith(`${appIdKey}`, 'PID:') ? `${appIdKey}` : `PID:${appIdKey}`;
   setAppIdKey(this, fullAppIdKey);
   setPageIdKey(this, pageIdKey);
@@ -175,7 +200,7 @@ export async function selectPage (appIdKey, pageIdKey, skipReadyCheck = false) {
 
   const pageReadinessDetector = skipReadyCheck ? undefined : {
     timeoutMs: this.pageLoadMs,
-    readinessDetector: (/** @type {string} */ readyState) => this.isPageLoadingCompleted(readyState),
+    readinessDetector: (readyState: string) => this.isPageLoadingCompleted(readyState),
   };
   await this.requireRpcClient().selectPage(fullAppIdKey, pageIdKey, pageReadinessDetector);
 
@@ -183,16 +208,87 @@ export async function selectPage (appIdKey, pageIdKey, skipReadyCheck = false) {
 }
 
 /**
+ * Finds app keys based on assigned bundle IDs from the app dictionary.
+ * When bundleIds includes a wildcard ('*'), returns all app keys in the app dictionary.
+ * Also handles proxy applications that may act on behalf of other bundle IDs.
  *
- * @this {RemoteDebugger}
- * @param {string?} currentUrl
- * @param {number} maxTries
- * @param {boolean} ignoreAboutBlankUrl
- * @returns {Promise<import('../types').AppPage>}
+ * @param bundleIds - Array of bundle identifiers to match against. If the array
+ *                    contains a wildcard ('*'), all apps will be returned.
+ * @returns Array of application identifier keys that match the provided bundle IDs.
  */
-async function searchForApp (currentUrl, maxTries, ignoreAboutBlankUrl) {
-  /** @type {string[]} */
-  const bundleIds = _.compact(
+export function getPossibleDebuggerAppKeys(this: RemoteDebugger, bundleIds: string[]): string[] {
+  const appDict = getAppDict(this);
+
+  if (bundleIds.includes(WILDCARD_BUNDLE_ID)) {
+    this.log.info(
+      'Returning all apps because the list of matching bundle identifiers includes a wildcard'
+    );
+    return _.keys(appDict);
+  }
+
+  // go through the possible bundle identifiers
+  const possibleBundleIds = _.uniq([
+    WEB_CONTENT_BUNDLE_ID,
+    WEB_CONTENT_PROCESS_BUNDLE_ID,
+    SAFARI_VIEW_PROCESS_BUNDLE_ID,
+    SAFARI_VIEW_BUNDLE_ID,
+    ...bundleIds,
+  ]);
+  this.log.debug(
+    `Checking for apps with matching bundle identifiers: ${possibleBundleIds.join(', ')}`
+  );
+  const proxiedAppIds: string[] = [];
+  for (const bundleId of possibleBundleIds) {
+    // now we need to determine if we should pick a proxy for this instead
+    for (const appId of appIdsForBundle(bundleId, appDict)) {
+      if (proxiedAppIds.includes(appId)) {
+        continue;
+      }
+
+      proxiedAppIds.push(appId);
+      this.log.debug(`Found app id key '${appId}' for bundle '${bundleId}'`);
+      for (const [key, data] of _.toPairs(appDict)) {
+        if (data.isProxy && data.hostId === appId && !proxiedAppIds.includes(key)) {
+          this.log.debug(
+            `Found separate bundleId '${data.bundleId}' ` +
+            `acting as proxy for '${bundleId}', with app id '${key}'`
+          );
+          proxiedAppIds.push(key);
+        }
+      }
+    }
+  }
+
+  this.log.debug(
+    `You may also consider providing more values to 'additionalWebviewBundleIds' ` +
+    `capability to match other applications. Add a wildcard ('*') to match all apps.`
+  );
+
+  return _.uniq(proxiedAppIds);
+}
+
+/**
+ * Searches for an application matching the given criteria by retrying with
+ * exponential backoff. Attempts to connect to apps matching the bundle IDs
+ * and optionally filters by URL.
+ *
+ * @param currentUrl - Optional URL to match when searching for a page.
+ *                     If provided, only apps containing a page with this URL
+ *                     will be considered.
+ * @param maxTries - Maximum number of retry attempts.
+ * @param ignoreAboutBlankUrl - If true, pages with 'about:blank' URL will be
+ *                              ignored during the search.
+ * @returns A promise that resolves to an AppPage object containing the matched
+ *          app ID key and page dictionary.
+ * @throws Error if no valid webapp can be connected after all retry attempts.
+ */
+async function searchForApp(
+  this: RemoteDebugger,
+  currentUrl: string | null,
+  maxTries: number,
+  ignoreAboutBlankUrl: boolean
+): Promise<AppPage> {
+  const bundleIds: string[] = _.compact(
     [
       getBundleId(this),
       ...(getAdditionalBundleIds(this) ?? []),
@@ -200,9 +296,9 @@ async function searchForApp (currentUrl, maxTries, ignoreAboutBlankUrl) {
     ]
   );
   let retryCount = 0;
-  return /** @type {import('../types').AppPage} */ (await retryInterval(maxTries, SELECT_APP_RETRY_SLEEP_MS, async () => {
+  return await retryInterval(maxTries, SELECT_APP_RETRY_SLEEP_MS, async () => {
     logApplicationDictionary.bind(this)();
-    const possibleAppIds = getPossibleDebuggerAppKeys.bind(this)(/** @type {string[]} */ (bundleIds));
+    const possibleAppIds = getPossibleDebuggerAppKeys.bind(this)(bundleIds);
     this.log.debug(`Trying out the possible app ids: ${possibleAppIds.join(', ')} (try #${retryCount + 1} of ${maxTries})`);
     for (const attemptedAppIdKey of possibleAppIds) {
       const appInfo = getAppDict(this)[attemptedAppIdKey];
@@ -236,7 +332,7 @@ async function searchForApp (currentUrl, maxTries, ignoreAboutBlankUrl) {
         } else {
           this.log.debug('Received app, but no match was found. Trying again.');
         }
-      } catch (err) {
+      } catch (err: any) {
         if (![NEW_APP_CONNECTED_ERROR, EMPTY_PAGE_DICTIONARY_ERROR].some((msg) => msg === err.message)) {
           this.log.debug(err.stack);
         }
@@ -247,18 +343,25 @@ async function searchForApp (currentUrl, maxTries, ignoreAboutBlankUrl) {
     throw new Error(
       `Could not connect to a valid webapp. Make sure it is debuggable and has at least one active page.`
     );
-  }));
+  }) as Promise<AppPage>;
 }
 
 /**
+ * Searches through the application dictionary to find a page matching the given URL.
+ * Only considers active applications with non-empty page arrays.
  *
- * @this {RemoteDebugger}
- * @param {Record<string, import('../types').AppInfo>} appsDict
- * @param {string?} currentUrl
- * @param {boolean} [ignoreAboutBlankUrl]
- * @returns {import('../types').AppPage?}
+ * @param appsDict - The application dictionary to search through.
+ * @param currentUrl - Optional URL to match. If provided, only pages with this exact
+ *                     URL or with this URL followed by '/' will be considered.
+ * @param ignoreAboutBlankUrl - If true, pages with 'about:blank' URL will be ignored.
+ * @returns An AppPage object if a matching page is found, null otherwise.
  */
-function searchForPage (appsDict, currentUrl = null, ignoreAboutBlankUrl = false) {
+function searchForPage(
+  this: RemoteDebugger,
+  appsDict: AppDict,
+  currentUrl: string | null = null,
+  ignoreAboutBlankUrl: boolean = false
+): AppPage | null {
   for (const appDict of _.values(appsDict)) {
     if (!appDict || !appDict.isActive || !appDict.pageArray || _.isEmpty(appDict.pageArray)) {
       continue;
@@ -278,10 +381,11 @@ function searchForPage (appsDict, currentUrl = null, ignoreAboutBlankUrl = false
 }
 
 /**
- * @this {RemoteDebugger}
- * @returns {void}
+ * Logs the current application dictionary to the debug log.
+ * Displays all applications, their properties, and their associated pages
+ * in a formatted structure.
  */
-function logApplicationDictionary () {
+function logApplicationDictionary(this: RemoteDebugger): void {
   this.log.debug('Current applications available:');
   for (const [app, info] of _.toPairs(getAppDict(this))) {
     this.log.debug(`    Application: "${app}"`);
@@ -302,67 +406,3 @@ function logApplicationDictionary () {
     }
   }
 }
-
-/**
- * Find app keys based on assigned bundleIds from appDict
- * When bundleIds includes a wildcard ('*'), returns all appKeys in appDict.
- *
- * @this {RemoteDebugger}
- * @param {string[]} bundleIds
- * @returns {string[]}
- */
-export function getPossibleDebuggerAppKeys(bundleIds) {
-  const appDict = getAppDict(this);
-
-  if (bundleIds.includes(WILDCARD_BUNDLE_ID)) {
-    this.log.info(
-      'Returning all apps because the list of matching bundle identifiers includes a wildcard'
-    );
-    return _.keys(appDict);
-  }
-
-  // go through the possible bundle identifiers
-  const possibleBundleIds = _.uniq([
-    WEB_CONTENT_BUNDLE_ID,
-    WEB_CONTENT_PROCESS_BUNDLE_ID,
-    SAFARI_VIEW_PROCESS_BUNDLE_ID,
-    SAFARI_VIEW_BUNDLE_ID,
-    ...bundleIds,
-  ]);
-  this.log.debug(
-    `Checking for apps with matching bundle identifiers: ${possibleBundleIds.join(', ')}`
-  );
-  /** @type {string[]} */
-  const proxiedAppIds = [];
-  for (const bundleId of possibleBundleIds) {
-    // now we need to determine if we should pick a proxy for this instead
-    for (const appId of appIdsForBundle(bundleId, appDict)) {
-      if (proxiedAppIds.includes(appId)) {
-        continue;
-      }
-
-      proxiedAppIds.push(appId);
-      this.log.debug(`Found app id key '${appId}' for bundle '${bundleId}'`);
-      for (const [key, data] of _.toPairs(appDict)) {
-        if (data.isProxy && data.hostId === appId && !proxiedAppIds.includes(key)) {
-          this.log.debug(
-            `Found separate bundleId '${data.bundleId}' ` +
-            `acting as proxy for '${bundleId}', with app id '${key}'`
-          );
-          proxiedAppIds.push(key);
-        }
-      }
-    }
-  }
-
-  this.log.debug(
-    `You may also consider providing more values to 'additionalWebviewBundleIds' ` +
-    `capability to match other applications. Add a wildcard ('*') to match all apps.`
-  );
-
-  return _.uniq(proxiedAppIds);
-}
-
-/**
- * @typedef {import('../remote-debugger').RemoteDebugger} RemoteDebugger
- */

package/lib/mixins/cookies.ts

@@ -0,0 +1,61 @@
+import {
+  getAppIdKey,
+  getPageIdKey,
+} from './property-accessors';
+import type { RemoteDebugger } from '../remote-debugger';
+import type { StringRecord } from '@appium/types';
+
+/**
+ * Retrieves all cookies for the current page by sending a Page.getCookies
+ * command to the remote debugger.
+ *
+ * @returns A promise that resolves to a dictionary containing the cookies.
+ */
+export async function getCookies(this: RemoteDebugger): Promise<StringRecord> {
+  this.log.debug('Getting cookies');
+  return await this.requireRpcClient().send('Page.getCookies', {
+    appIdKey: getAppIdKey(this),
+    pageIdKey: getPageIdKey(this),
+  });
+}
+
+/**
+ * Sets a cookie on the current page by sending a Page.setCookie command
+ * to the remote debugger.
+ *
+ * @param cookie - Dictionary containing the cookie properties to set.
+ * @returns A promise that resolves when the cookie has been set.
+ */
+export async function setCookie(
+  this: RemoteDebugger,
+  cookie: StringRecord
+): Promise<any> {
+  this.log.debug('Setting cookie');
+  return await this.requireRpcClient().send('Page.setCookie', {
+    appIdKey: getAppIdKey(this),
+    pageIdKey: getPageIdKey(this),
+    cookie,
+  });
+}
+
+/**
+ * Deletes a cookie from the current page by sending a Page.deleteCookie
+ * command to the remote debugger.
+ *
+ * @param cookieName - The name of the cookie to delete.
+ * @param url - The URL associated with the cookie to delete.
+ * @returns A promise that resolves when the cookie has been deleted.
+ */
+export async function deleteCookie(
+  this: RemoteDebugger,
+  cookieName: string,
+  url: string
+): Promise<any> {
+  this.log.debug(`Deleting cookie '${cookieName}' on '${url}'`);
+  return await this.requireRpcClient().send('Page.deleteCookie', {
+    appIdKey: getAppIdKey(this),
+    pageIdKey: getPageIdKey(this),
+    cookieName,
+    url,
+  });
+}

package/lib/mixins/events.ts

@@ -0,0 +1,91 @@
+import {
+  getClientEventListeners,
+} from './property-accessors';
+import type { RemoteDebugger } from '../remote-debugger';
+import type { EventListener } from '../types';
+
+// event emitted publically
+export const events = {
+  EVENT_PAGE_CHANGE: 'remote_debugger_page_change',
+  EVENT_FRAMES_DETACHED: 'remote_debugger_frames_detached',
+  EVENT_DISCONNECT: 'remote_debugger_disconnect',
+} as const;
+
+/**
+ * Adds a client event listener to the RPC client and tracks it for later removal.
+ * The listener will be called when the specified event is emitted by the remote debugger.
+ *
+ * @param eventName - The name of the event to listen for.
+ * @param listener - The event listener function to call when the event is emitted.
+ */
+export function addClientEventListener(
+  this: RemoteDebugger,
+  eventName: string,
+  listener: EventListener
+): void {
+  getClientEventListeners(this)[eventName] ??= [];
+  getClientEventListeners(this)[eventName].push(listener);
+  this.requireRpcClient().on(eventName, listener);
+}
+
+/**
+ * Removes all client event listeners for the specified event name from the RPC client.
+ * This will stop listening for the event and clean up the tracked listeners.
+ *
+ * @param eventName - The name of the event to stop listening for.
+ */
+export function removeClientEventListener(
+  this: RemoteDebugger,
+  eventName: string
+): void {
+  for (const listener of (getClientEventListeners(this)[eventName] || [])) {
+    this.requireRpcClient().off(eventName, listener);
+  }
+}
+
+/**
+ * Starts listening for JavaScript console messages by registering listeners
+ * for Console.messageAdded and Console.messageRepeatCountUpdated events.
+ *
+ * @param listener - The event listener function to call when console messages are received.
+ */
+export function startConsole(
+  this: RemoteDebugger,
+  listener: EventListener
+): void {
+  this.log.debug('Starting to listen for JavaScript console');
+  this.addClientEventListener('Console.messageAdded', listener);
+  this.addClientEventListener('Console.messageRepeatCountUpdated', listener);
+}
+
+/**
+ * Stops listening for JavaScript console messages by removing listeners
+ * for Console.messageAdded and Console.messageRepeatCountUpdated events.
+ */
+export function stopConsole(this: RemoteDebugger): void {
+  this.log.debug('Stopping to listen for JavaScript console');
+  this.removeClientEventListener('Console.messageAdded');
+  this.removeClientEventListener('Console.messageRepeatCountUpdated');
+}
+
+/**
+ * Starts listening for network events by registering a listener for NetworkEvent.
+ * This aggregates all Network.* events into a single NetworkEvent.
+ *
+ * @param listener - The event listener function to call when network events are received.
+ */
+export function startNetwork(
+  this: RemoteDebugger,
+  listener: EventListener
+): void {
+  this.log.debug('Starting to listen for network events');
+  this.addClientEventListener('NetworkEvent', listener);
+}
+
+/**
+ * Stops listening for network events by removing the listener for NetworkEvent.
+ */
+export function stopNetwork(this: RemoteDebugger): void {
+  this.log.debug('Stopping to listen for network events');
+  this.removeClientEventListener('NetworkEvent');
+}