appium-remote-debugger 15.2.9 → 15.2.10

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

@@ -13,6 +13,8 @@ import {
   getPageIdKey,
   setNavigatingToPage,
 } from './property-accessors';
+import type { RemoteDebugger } from '../remote-debugger';
+import type { AppIdKey, PageIdKey } from '../types';
 
 export const DEFAULT_PAGE_READINESS_TIMEOUT_MS = 20 * 1000;
 const PAGE_READINESS_CHECK_INTERVAL_MS = 50;
@@ -27,32 +29,34 @@ const PAGE_LOAD_STRATEGY = Object.freeze({
 });
 
 /**
- * @this {RemoteDebugger}
- * @returns {void}
+ * Emits a frame detached event when a frame is detached from the page.
+ * This is typically called by the RPC client when receiving a Page.frameDetached event.
  */
-export function frameDetached () {
+export function frameDetached(this: RemoteDebugger): void {
   this.emit(events.EVENT_FRAMES_DETACHED);
 }
 
 /**
- * @this {RemoteDebugger}
- * @returns {void}
+ * Cancels the current page load operation by unregistering from page readiness
+ * notifications and canceling any pending page load delay.
  */
-export function cancelPageLoad () {
+export function cancelPageLoad(this: RemoteDebugger): void {
   this.log.debug('Unregistering from page readiness notifications');
   setPageLoading(this, false);
   getPageLoadDelay(this)?.cancel();
 }
 
 /**
- * Return if current readState can be handles as page load completes
- * for the given page load strategy.
+ * Determines if the current readyState indicates that page loading is completed
+ * based on the configured page load strategy.
  *
- * @this {RemoteDebugger}
- * @param {string} readyState
- * @returns {boolean}
+ * @param readyState - The document readyState value ('loading', 'interactive', or 'complete').
+ * @returns True if the page load is considered complete for the current strategy:
+ *          - 'eager': returns true when readyState is not 'loading'
+ *          - 'none': always returns true
+ *          - 'normal' (default): returns true only when readyState is 'complete'
  */
-export function isPageLoadingCompleted (readyState) {
+export function isPageLoadingCompleted(this: RemoteDebugger, readyState: string): boolean {
   const pageLoadStrategy = _.toLower(getPageLoadStartegy(this));
   switch (pageLoadStrategy) {
     case PAGE_LOAD_STRATEGY.EAGER:
@@ -67,11 +71,14 @@ export function isPageLoadingCompleted (readyState) {
 }
 
 /**
- * @this {RemoteDebugger}
- * @param {timing.Timer?} [startPageLoadTimer]
- * @returns {Promise<void>}
+ * Waits for the DOM to be ready by periodically checking the page readiness state.
+ * Uses exponential backoff for retry intervals and respects the configured page load
+ * strategy and timeout settings.
+ *
+ * @param startPageLoadTimer - Optional timer instance to use for tracking elapsed time.
+ *                             If not provided, a new timer will be created and started.
  */
-export async function waitForDom (startPageLoadTimer) {
+export async function waitForDom(this: RemoteDebugger, startPageLoadTimer?: timing.Timer): Promise<void> {
   const readinessTimeoutMs = this.pageLoadMs;
   this.log.debug(`Waiting up to ${readinessTimeoutMs}ms for the page to be ready`);
   const timer = startPageLoadTimer ?? new timing.Timer().start();
@@ -79,7 +86,6 @@ export async function waitForDom (startPageLoadTimer) {
   let isPageLoading = true;
   setPageLoading(this, true);
   setPageLoadDelay(this, util.cancellableDelay(readinessTimeoutMs));
-  /** @type {B<void>} */
   const pageReadinessPromise = B.resolve((async () => {
     let retry = 0;
     while (isPageLoading) {
@@ -118,7 +124,6 @@ export async function waitForDom (startPageLoadTimer) {
       retry++;
     }
   })());
-  /** @type {B<void>} */
   const cancellationPromise = B.resolve((async () => {
     try {
       await getPageLoadDelay(this);
@@ -135,11 +140,15 @@ export async function waitForDom (startPageLoadTimer) {
 }
 
 /**
- * @this {RemoteDebugger}
- * @param {number} [timeoutMs]
- * @returns {Promise<boolean>}
+ * Checks if the current page is ready by executing a JavaScript command to
+ * retrieve the document readyState and evaluating it against the page load strategy.
+ *
+ * @param timeoutMs - Optional timeout in milliseconds for the readyState check.
+ *                    If not provided, uses the configured page ready timeout.
+ * @returns A promise that resolves to true if the page is ready according to
+ *          the page load strategy, false otherwise or if the check times out.
  */
-export async function checkPageIsReady (timeoutMs) {
+export async function checkPageIsReady(this: RemoteDebugger, timeoutMs?: number): Promise<boolean> {
   const readyCmd = 'document.readyState;';
   const actualTimeoutMs = timeoutMs ?? getPageReadyTimeout(this);
   try {
@@ -152,7 +161,7 @@ export async function checkPageIsReady (timeoutMs) {
       })
     );
     return this.isPageLoadingCompleted(readyState);
-  } catch (err) {
+  } catch (err: any) {
     if (err instanceof BTimeoutError) {
       this.log.debug(`Page readiness check timed out after ${actualTimeoutMs}ms`);
     } else {
@@ -163,11 +172,14 @@ export async function checkPageIsReady (timeoutMs) {
 }
 
 /**
- * @this {RemoteDebugger}
- * @param {string} url
- * @returns {Promise<void>}
+ * Navigates to a new URL and waits for the page to be ready.
+ * Validates the URL format, waits for the page to be available, sends the navigation
+ * command, and monitors for the Page.loadEventFired event or timeout.
+ *
+ * @param url - The URL to navigate to. Must be a valid URL format.
+ * @throws TypeError if the provided URL is not a valid URL format.
  */
-export async function navToUrl (url) {
+export async function navToUrl(this: RemoteDebugger, url: string): Promise<void> {
   const {appIdKey, pageIdKey} = checkParams({
     appIdKey: getAppIdKey(this),
     pageIdKey: getPageIdKey(this),
@@ -183,22 +195,18 @@ export async function navToUrl (url) {
   this.log.debug(`Navigating to new URL: '${url}'`);
   setNavigatingToPage(this, true);
   await rpcClient.waitForPage(
-    /** @type {import('../types').AppIdKey} */ (appIdKey),
-    /** @type {import('../types').PageIdKey} */ (pageIdKey)
+    appIdKey as AppIdKey,
+    pageIdKey as PageIdKey
   );
   const readinessTimeoutMs = this.pageLoadMs;
-  /** @type {(() => void)|undefined} */
-  let onPageLoaded;
-  /** @type {NodeJS.Timeout|undefined|null} */
-  let onPageLoadedTimeout;
+  let onPageLoaded: (() => void) | undefined;
+  let onPageLoadedTimeout: NodeJS.Timeout | undefined | null;
   setPageLoadDelay(this, util.cancellableDelay(readinessTimeoutMs));
   setPageLoading(this, true);
   let isPageLoading = true;
-  // /** @type {Promise<void>|null} */
   const start = new timing.Timer().start();
 
-  /** @type {B<void>} */
-  const pageReadinessPromise = new B((resolve) => {
+  const pageReadinessPromise = new B<void>((resolve) => {
     onPageLoadedTimeout = setTimeout(() => {
       if (isPageLoading) {
         isPageLoading = false;
@@ -231,7 +239,6 @@ export async function navToUrl (url) {
       pageIdKey,
     });
   });
-  /** @type {B<void>} */
   const cancellationPromise = B.resolve((async () => {
     try {
       await getPageLoadDelay(this);
@@ -254,7 +261,3 @@ export async function navToUrl (url) {
     }
   }
 }
-
-/**
- * @typedef {import('../remote-debugger').RemoteDebugger} RemoteDebugger
- */

package/package.json

@@ -4,7 +4,7 @@
   "keywords": [
     "appium"
   ],
-  "version": "15.2.9",
+  "version": "15.2.10",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {

package/lib/mixins/message-handlers.js

@@ -1,224 +0,0 @@
-import { events } from './events';
-import {
-  pageArrayFromDict,
-  appInfoFromDict,
-} from '../utils';
-import _ from 'lodash';
-import {
-  setAppIdKey,
-  getAppDict,
-  getAppIdKey,
-  getBundleId,
-  getNavigatingToPage,
-  setCurrentState,
-  setConnectedDrivers,
-  getSkippedApps,
-} from './property-accessors';
-
-/*
- * Generic callbacks used throughout the lifecycle of the Remote Debugger.
- * These will be added to the prototype.
- */
-
-/**
- * @this {RemoteDebugger}
- * @param {Error?} err
- * @param {string} appIdKey
- * @param {Record<string, any>} pageDict
- * @returns {Promise<void>}
- */
-export async function onPageChange (err, appIdKey, pageDict) {
-  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,
-  });
-}
-
-/**
- * @this {RemoteDebugger}
- * @param {Error?} err
- * @param {Record<string, any>} dict
- * @returns {Promise<void>}
- */
-export async function onAppConnect (err, dict) {
-  const appIdKey = dict.WIRApplicationIdentifierKey;
-  this.log.debug(`Notified that new application '${appIdKey}' has connected`);
-  updateAppsWithDict.bind(this)(dict);
-}
-
-/**
- * @this {RemoteDebugger}
- * @param {Error?} err
- * @param {import('@appium/types').StringRecord} dict
- * @returns {void}
- */
-export function onAppDisconnect (err, dict) {
-  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)(/** @type {string} */ (getBundleId(this))));
-  }
-
-  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);
-  }
-}
-
-/**
- * @this {RemoteDebugger}
- * @param {Error?} err
- * @param {Record<string, any>} dict
- * @returns {Promise<void>}
- */
-export async function onAppUpdate (err, dict) {
-  this.log.debug(`Notified that an application has been updated`);
-  updateAppsWithDict.bind(this)(dict);
-}
-
-/**
- * @this {RemoteDebugger}
- * @param {Error?} err
- * @param {Record<string, any>} drivers
- * @returns {void}
- */
-export function onConnectedDriverList (err, drivers) {
-  setConnectedDrivers(this, drivers.WIRDriverDictionaryKey);
-  this.log.debug(`Received connected driver list: ${JSON.stringify(this.connectedDrivers)}`);
-}
-
-/**
- * @this {RemoteDebugger}
- * @param {Error?} err
- * @param {Record<string, any>} state
- * @returns {void}
- */
-export function onCurrentState (err, state) {
-  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)}`);
-}
-
-/**
- * @this {RemoteDebugger}
- * @param {Error?} err
- * @param {Record<string, any>} apps
- * @returns {Promise<void>}
- */
-export async function onConnectedApplicationList (err, apps) {
-  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
-  let newDict = {};
-  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);
-}
-
-/**
- *
- * @this {RemoteDebugger}
- * @param {import('@appium/types').StringRecord} dict
- * @returns {void}
- */
-function updateAppsWithDict (dict) {
-  // 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)(/** @type {string} */ (getBundleId(this))));
-  }
-}
-
-/**
- * Given a bundle id, finds the correct remote debugger app that is
- * connected.
- *
- * @this {RemoteDebugger}
- * @param {string} bundleId
- * @returns {string|undefined}
- */
-export function getDebuggerAppKey (bundleId) {
-  let appId;
-  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;
-    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;
-}
-
-/**
- * @typedef {import('../remote-debugger').RemoteDebugger} RemoteDebugger
- */