appium-remote-debugger 11.4.1 → 11.5.0

package/lib/remote-debugger.js

@@ -1,27 +1,28 @@
 import { EventEmitter } from 'events';
-import log from './logger';
+import defaultLog from './logger';
 import { RpcClientSimulator } from './rpc';
-import { checkParams, getModuleRoot } from './utils';
-import { mixins, events } from './mixins';
+import { getModuleProperties } from './utils';
+import * as connectMixins from './mixins/connect';
+import * as executeMixins from './mixins/execute';
+import * as messageHandlerMixins from './mixins/message-handlers';
+import * as navigationMixins from './mixins/navigate';
+import * as cookieMixins from './mixins/cookies';
+import * as screenshotMixins from './mixins/screenshot';
+import * as eventMixins from './mixins/events';
+import * as miscellaneousMixins from './mixins/misc';
 import _ from 'lodash';
-import B from 'bluebird';
-import path from 'path';
 import AsyncLock from 'async-lock';
 
-const REMOTE_DEBUGGER_PORT = 27753;
-const SAFARI_BUNDLE_ID = 'com.apple.mobilesafari';
-
+export const REMOTE_DEBUGGER_PORT = 27753;
 /* How many milliseconds to wait for webkit to return a response before timing out */
-const RPC_RESPONSE_TIMEOUT_MS = 5000;
-
-const PAGE_READY_TIMEOUT = 5000;
+export const RPC_RESPONSE_TIMEOUT_MS = 5000;
+const PAGE_READY_TIMEOUT_MS = 5000;
+const { version: MODULE_VERSION } = getModuleProperties();
 
-const GARBAGE_COLLECT_TIMEOUT = 5000;
 
-
-class RemoteDebugger extends EventEmitter {
+export class RemoteDebugger extends EventEmitter {
   // properties
-  /** @type {any[]|undefined} */
+  /** @type {string[]|undefined} */
   _skippedApps;
   /** @type {Record<string, any>} */
   _clientEventListeners;
@@ -29,20 +30,24 @@ class RemoteDebugger extends EventEmitter {
   appDict;
   /** @type {string|null|undefined} */
   appIdKey;
+  /** @type {string|number|null|undefined} */
+  pageIdKey;
   /** @type {Record<string, any>[]|undefined} */
   connectedDrivers;
   /** @type {Record<string, any>[]|undefined} */
   currentState;
   /** @type {boolean|undefined} */
   connected;
-  /** @type {B<void>} */
+  /** @type {import('bluebird')<void>} */
   pageLoadDelay;
-  /** @type {B<void>} */
+  /** @type {import('bluebird')<void>} */
   navigationDelay;
-  /** @type {import('./rpc/rpc-client').default?} */
+  /** @type {import('./rpc/rpc-client').RpcClient?} */
   rpcClient;
   /** @type {string|undefined} */
   pageLoadStrategy;
+  /** @type {import('@appium/types').AppiumLogger} */
+  _log;
 
   // events
   /** @type {string} */
@@ -53,83 +58,46 @@ class RemoteDebugger extends EventEmitter {
   static EVENT_FRAMES_DETACHED;
 
   // methods
-  /** @type {() => Promise<void>} */
-  setConnectionKey;
-  /** @type {() => Promise<void>} */
-  disconnect;
-  /** @type {(currentUrl: string?, maxTries: number, ignoreAboutBlankUrl: boolean) => Promise<Record<string, any>>} */
-  searchForApp;
-  /** @type {(appsDict:Record<string, any>, currentUrl: string?, ignoreAboutBlankUrl: boolean) => import('./mixins/connect').AppPages?} */
-  searchForPage;
-  /** @type {(timeoutMs?: number) => Promise<boolean>} */
-  checkPageIsReady;
-  /** @type {() => void} */
-  cancelPageLoad;
-  /** @type {(dict: Record<string, any>) => void} */
-  updateAppsWithDict;
-  /** @type {(startPageLoadTimer?: import('@appium/support').timing.Timer) => Promise<void>} */
-  waitForDom;
-  /** @type {(command: string, override?: boolean) => Promise<any>} */
-  execute;
-  /** @type {(command: string, args?: any[], frames?: string[]) => Promise<any>} */
-  executeAtom;
-  /** @type {(atom: string, args?: any[], frames?: string[]) => Promise<any>} */
-  executeAtomAsync;
-  /** @type {(readyState: string) => boolean} */
-  isPageLoadingCompleted;
-  /** @type {(currentUrl?: string, maxTries?: number, ignoreAboutBlankUrl?: boolean) => Promise<import('./mixins/connect').AppPages[]>} */
-  selectApp;
-  /** @type {() => Promise<void>} */
-  connect;
-  /** @type {(appIdKey: string, pageIdKey: string, skipReadyCheck?: boolean) => Promise<void>} */
-  selectPage;
-  /** @type {(url: string) => Promise<void>} */
-  navToUrl;
+  setConnectionKey = connectMixins.setConnectionKey;
+  disconnect = connectMixins.disconnect;
+  searchForApp = connectMixins.searchForApp;
+  searchForPage = connectMixins.searchForPage;
+  checkPageIsReady = navigationMixins.checkPageIsReady;
+  cancelPageLoad = navigationMixins.cancelPageLoad;
+  waitForDom = navigationMixins.waitForDom;
+  execute = executeMixins.execute;
+  executeAtom = executeMixins.executeAtom;
+  executeAtomAsync = executeMixins.executeAtomAsync;
+  isPageLoadingCompleted = navigationMixins.isPageLoadingCompleted;
+  selectApp = connectMixins.selectApp;
+  connect = connectMixins.connect;
+  selectPage = connectMixins.selectPage;
+  navToUrl = navigationMixins.navToUrl;
+  getCookies = cookieMixins.getCookies;
+  setCookie = cookieMixins.setCookie;
+  deleteCookie = cookieMixins.deleteCookie;
+  captureScreenshot = screenshotMixins.captureScreenshot;
+  addClientEventListener = eventMixins.addClientEventListener;
+  removeClientEventListener = eventMixins.removeClientEventListener;
+  launchSafari = miscellaneousMixins.launchSafari;
+  startTimeline = miscellaneousMixins.startTimeline;
+  stopTimeline = miscellaneousMixins.stopTimeline;
+  startConsole = miscellaneousMixins.startConsole;
+  stopConsole = miscellaneousMixins.stopConsole;
+  startNetwork = miscellaneousMixins.startNetwork;
+  stopNetwork = miscellaneousMixins.stopNetwork;
+  overrideUserAgent = miscellaneousMixins.overrideUserAgent;
+  garbageCollect = miscellaneousMixins.garbageCollect;
 
   // Callbacks
-  /** @type {(err: Error?, appIdKey: string, pageDict: Record<string, any>) => Promise<void>} */
-  onPageChange;
-  /** @type {(err: Error?, apps: Record<string, any>) => Promise<void>} */
-  onConnectedApplicationList;
-  /** @type {(err: Error?, dict: Record<string, any>) => Promise<void>} */
-  onAppConnect;
-  /** @type {(err: Error?, dict: Record<string, any>) => void} */
-  onAppDisconnect;
-  /** @type {(err: Error?, dict: Record<string, any>) => Promise<void>} */
-  onAppUpdate;
-  /** @type {(err: Error?, drivers: Record<string, any>) => void} */
-  onConnectedDriverList;
-  /** @type {(err: Error?, state: Record<string, any>) => void} */
-  onCurrentState;
-  /** @type {(err: Error?, state: Record<string, any>) => void} */
-  frameDetached;
-
-  /**
-   * @typedef {Object} RemoteDebuggerOptions
-   * @property {string} [bundleId] id of the app being connected to
-   * @property {string[]} [additionalBundleIds=[]] array of possible bundle
-   *                      ids that the inspector could return
-   * @property {string} [platformVersion] version of iOS
-   * @property {boolean} [isSafari=true]
-   * @property {boolean} [includeSafari=false]
-   * @property {boolean} [useNewSafari=false] for web inspector, whether this is a new Safari instance
-   * @property {number} [pageLoadMs] the time, in ms, that should be waited for page loading
-   * @property {string} [host] the remote debugger's host address
-   * @property {number} [port=REMOTE_DEBUGGER_PORT] the remote debugger port through which to communicate
-   * @property {string} [socketPath]
-   * @property {number} [pageReadyTimeout=PAGE_READY_TIMEOUT]
-   * @property {string} [remoteDebugProxy]
-   * @property {boolean} [garbageCollectOnExecute=false]
-   * @property {boolean} [logFullResponse=false]
-   * @property {boolean} [logAllCommunication=false] log plists sent and received from Web Inspector
-   * @property {boolean} [logAllCommunicationHexDump=false] log communication from Web Inspector as hex dump
-   * @property {number} [webInspectorMaxFrameLength] The maximum size in bytes of a single data
-   *                    frame in the device communication protocol
-   * @property {number} [socketChunkSize] size, in bytes, of chunks of data sent to
-   *                    Web Inspector (real device only)
-   * @property {boolean} [fullPageInitialization]
-   * @property {string} [pageLoadStrategy]
-   */
+  onPageChange = messageHandlerMixins.onPageChange;
+  onConnectedApplicationList = messageHandlerMixins.onConnectedApplicationList;
+  onAppConnect = messageHandlerMixins.onAppConnect;
+  onAppDisconnect = messageHandlerMixins.onAppDisconnect;
+  onAppUpdate = messageHandlerMixins.onAppUpdate;
+  onConnectedDriverList = messageHandlerMixins.onConnectedDriverList;
+  onCurrentState = messageHandlerMixins.onCurrentState;
+  frameDetached = navigationMixins.frameDetached;
 
   /**
    * @param {RemoteDebuggerOptions} opts
@@ -137,8 +105,9 @@ class RemoteDebugger extends EventEmitter {
   constructor (opts = {}) {
     super();
 
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    log.info(`Remote Debugger version ${require(path.resolve(getModuleRoot(), 'package.json')).version}`);
+    // @ts-ignore This is OK
+    this._log = opts.log ?? defaultLog;
+    this.log.info(`Remote Debugger version ${MODULE_VERSION}`);
 
     const {
       bundleId,
@@ -151,7 +120,7 @@ class RemoteDebugger extends EventEmitter {
       host,
       port = REMOTE_DEBUGGER_PORT,
       socketPath,
-      pageReadyTimeout = PAGE_READY_TIMEOUT,
+      pageReadyTimeout = PAGE_READY_TIMEOUT_MS,
       remoteDebugProxy,
       garbageCollectOnExecute = false,
       logFullResponse = false,
@@ -160,7 +129,7 @@ class RemoteDebugger extends EventEmitter {
       webInspectorMaxFrameLength,
       socketChunkSize,
       fullPageInitialization,
-      pageLoadStrategy
+      pageLoadStrategy,
     } = opts;
 
     this.bundleId = bundleId;
@@ -170,7 +139,7 @@ class RemoteDebugger extends EventEmitter {
     this.includeSafari = includeSafari;
     this.useNewSafari = useNewSafari;
     this.pageLoadMs = pageLoadMs;
-    log.debug(`useNewSafari --> ${this.useNewSafari}`);
+    this.log.debug(`useNewSafari --> ${this.useNewSafari}`);
 
     this.garbageCollectOnExecute = garbageCollectOnExecute;
 
@@ -195,6 +164,30 @@ class RemoteDebugger extends EventEmitter {
     this._lock = new AsyncLock();
   }
 
+  /**
+   * @returns {import('@appium/types').AppiumLogger}
+   */
+  get log() {
+    return this._log;
+  }
+
+  /**
+   * @param {boolean} [checkConnected=false]
+   * @returns {import('./rpc/rpc-client').RpcClient}
+   */
+  requireRpcClient(checkConnected = false) {
+    if (!this.rpcClient) {
+      throw new Error(`rpcClient is undefined. Has 'initRpcClient' been called before?`);
+    }
+    if (checkConnected && !this.rpcClient.isConnected) {
+      throw new Error('Remote debugger is not connected');
+    }
+    return this.rpcClient;
+  }
+
+  /**
+   * @returns {void}
+   */
   setup () {
     // app handling configuration
     this.appDict = {};
@@ -208,8 +201,11 @@ class RemoteDebugger extends EventEmitter {
     this._clientEventListeners = {};
   }
 
+  /**
+   * @returns {void}
+   */
   teardown () {
-    log.debug('Cleaning up listeners');
+    this.log.debug('Cleaning up listeners');
 
     this.appDict = {};
     this.appIdKey = null;
@@ -222,6 +218,9 @@ class RemoteDebugger extends EventEmitter {
     this.removeAllListeners(RemoteDebugger.EVENT_DISCONNECT);
   }
 
+  /**
+   * @returns {void}
+   */
   initRpcClient () {
     this.rpcClient = new RpcClientSimulator({
       bundleId: this.bundleId,
@@ -238,228 +237,65 @@ class RemoteDebugger extends EventEmitter {
     });
   }
 
+  /**
+   * @returns {boolean}
+   */
   get isConnected () {
     return !!this.rpcClient?.isConnected;
   }
 
-  async launchSafari () {
-    if (!this.rpcClient) {
-      throw new Error(`rpcClient is undefined. Has 'initRpcClient' been called before?`);
-    }
-
-    await this.rpcClient.send('launchApplication', {
-      bundleId: SAFARI_BUNDLE_ID
-    });
-  }
-
-  async startTimeline (fn) {
-    if (!this.rpcClient) {
-      throw new Error(`rpcClient is undefined. Has 'initRpcClient' been called before?`);
-    }
-
-    log.debug('Starting to record the timeline');
-    this.rpcClient.on('Timeline.eventRecorded', fn);
-    return await this.rpcClient.send('Timeline.start', {
-      appIdKey: this.appIdKey,
-      pageIdKey: this.pageIdKey,
-    });
-  }
-
-  async stopTimeline () {
-    if (!this.rpcClient) {
-      throw new Error(`rpcClient is undefined. Has 'initRpcClient' been called before?`);
-    }
-
-    log.debug('Stopping to record the timeline');
-    await this.rpcClient.send('Timeline.stop', {
-      appIdKey: this.appIdKey,
-      pageIdKey: this.pageIdKey,
-    });
-  }
-
-  /*
-   * Keep track of the client event listeners so they can be removed
+  /**
+   * @param {boolean} allow
    */
-  addClientEventListener (eventName, listener) {
-    if (!this.rpcClient) {
-      throw new Error(`rpcClient is undefined. Has 'initRpcClient' been called before?`);
-    }
-
-    this._clientEventListeners[eventName] = this._clientEventListeners[eventName] || [];
-    this._clientEventListeners[eventName].push(listener);
-    this.rpcClient.on(eventName, listener);
-  }
-
-  removeClientEventListener (eventName) {
-    if (!this.rpcClient) {
-      throw new Error(`rpcClient is undefined. Has 'initRpcClient' been called before?`);
-    }
-
-    for (const listener of (this._clientEventListeners[eventName] || [])) {
-      this.rpcClient.off(eventName, listener);
-    }
-  }
-
-  startConsole (listener) {
-    log.debug('Starting to listen for JavaScript console');
-    this.addClientEventListener('Console.messageAdded', listener);
-    this.addClientEventListener('Console.messageRepeatCountUpdated', listener);
-  }
-
-  stopConsole () {
-    log.debug('Stopping to listen for JavaScript console');
-    this.removeClientEventListener('Console.messageAdded');
-    this.removeClientEventListener('Console.messageRepeatCountUpdated');
-  }
-
-  startNetwork (listener) {
-    log.debug('Starting to listen for network events');
-    this.addClientEventListener('NetworkEvent', listener);
-  }
-
-  stopNetwork () {
-    log.debug('Stopping to listen for network events');
-    this.removeClientEventListener('NetworkEvent');
-  }
-
   set allowNavigationWithoutReload (allow) {
     this._allowNavigationWithoutReload = allow;
   }
 
+  /**
+   * @returns {boolean}
+   */
   get allowNavigationWithoutReload () {
-    return this._allowNavigationWithoutReload;
-  }
-
-  // Potentially this does not work for mobile safari
-  async overrideUserAgent (value) {
-    log.debug('Setting overrideUserAgent');
-    if (!this.rpcClient) {
-      throw new Error(`rpcClient is undefined. Has 'initRpcClient' been called before?`);
-    }
-
-    return await this.rpcClient.send('Page.overrideUserAgent', {
-      appIdKey: this.appIdKey,
-      pageIdKey: this.pageIdKey,
-      value
-    });
+    return !!this._allowNavigationWithoutReload;
   }
 
   /**
-   * Capture a rect of the page or by default the viewport
-   * @param {{rect?: import('@appium/types').Rect|null, coordinateSystem?: "Viewport"|"Page"}} [opts={rect: null, coordinateSystem: 'Viewport'}]
-   * if rect is null capture the whole coordinate system else capture the rect in the given coordinateSystem
-   * @returns {Promise<string>} a base64 encoded string of the screenshot
+   * @returns {string[]}
    */
-  async captureScreenshot(opts) {
-    const {rect = null, coordinateSystem = 'Viewport'} = opts ?? {};
-    log.debug('Capturing screenshot');
-    if (!this.rpcClient) {
-      throw new Error(`rpcClient is undefined. Has 'initRpcClient' been called before?`);
-    }
-
-    const arect = rect ?? /** @type {import('@appium/types').Rect} */ (await this.executeAtom(
-      'execute_script',
-      ['return {x: 0, y: 0, width: window.innerWidth, height: window.innerHeight}', []]
-    ));
-    const response = await this.rpcClient.send('Page.snapshotRect', {
-      ...arect,
-      appIdKey: this.appIdKey,
-      pageIdKey: this.pageIdKey,
-      coordinateSystem,
-    });
-
-    if (response.error) {
-      throw new Error(response.error);
-    }
-
-    return response.dataURL.replace(/^data:image\/png;base64,/, '');
-  }
-
-  async getCookies () {
-    log.debug('Getting cookies');
-    if (!this.rpcClient) {
-      throw new Error(`rpcClient is undefined. Has 'initRpcClient' been called before?`);
-    }
-
-    return await this.rpcClient.send('Page.getCookies', {
-      appIdKey: this.appIdKey,
-      pageIdKey: this.pageIdKey
-    });
-  }
-
-  async setCookie (cookie) {
-    log.debug('Setting cookie');
-    if (!this.rpcClient) {
-      throw new Error(`rpcClient is undefined. Has 'initRpcClient' been called before?`);
-    }
-
-    return await this.rpcClient.send('Page.setCookie', {
-      appIdKey: this.appIdKey,
-      pageIdKey: this.pageIdKey,
-      cookie
-    });
-  }
-
-  async deleteCookie (cookieName, url) {
-    log.debug(`Deleting cookie '${cookieName}' on '${url}'`);
-    if (!this.rpcClient) {
-      throw new Error(`rpcClient is undefined. Has 'initRpcClient' been called before?`);
-    }
-
-    return await this.rpcClient.send('Page.deleteCookie', {
-      appIdKey: this.appIdKey,
-      pageIdKey: this.pageIdKey,
-      cookieName,
-      url,
-    });
-  }
-
-  async garbageCollect (timeoutMs = GARBAGE_COLLECT_TIMEOUT) {
-    log.debug(`Garbage collecting with ${timeoutMs}ms timeout`);
-    if (!this.rpcClient) {
-      throw new Error(`rpcClient is undefined. Has 'initRpcClient' been called before?`);
-    }
-
-    try {
-      checkParams({appIdKey: this.appIdKey, pageIdKey: this.pageIdKey});
-    } catch (err) {
-      log.debug(`Unable to collect garbage at this time`);
-      return;
-    }
-
-    await B.resolve(this.rpcClient.send('Heap.gc', {
-      appIdKey: this.appIdKey,
-      pageIdKey: this.pageIdKey,
-    })).timeout(timeoutMs)
-    .then(function gcSuccess () { // eslint-disable-line promise/prefer-await-to-then
-      log.debug(`Garbage collection successful`);
-    }).catch(function gcError (err) { // eslint-disable-line promise/prefer-await-to-callbacks
-      if (err instanceof B.TimeoutError) {
-        log.debug(`Garbage collection timed out after ${timeoutMs}ms`);
-      } else {
-        log.debug(`Unable to collect garbage: ${err.message}`);
-      }
-    });
-  }
-
-  async useAppDictLock (fn) {
-    return await this._lock.acquire('appDict', fn);
-  }
-
   get skippedApps () {
-    return this._skippedApps || [];
+    return this._skippedApps ?? [];
   }
 }
 
-for (const [name, fn] of _.toPairs(mixins)) {
-  RemoteDebugger.prototype[name] = fn;
-}
-
-for (const [name, event] of _.toPairs(events)) {
+for (const [name, event] of _.toPairs(eventMixins.events)) {
   RemoteDebugger[name] = event;
 }
 
 export default RemoteDebugger;
-export {
-  RemoteDebugger, REMOTE_DEBUGGER_PORT, RPC_RESPONSE_TIMEOUT_MS,
-};
+
+/**
+ * @typedef {Object} RemoteDebuggerOptions
+ * @property {string} [bundleId] id of the app being connected to
+ * @property {string[]} [additionalBundleIds=[]] array of possible bundle
+ *                      ids that the inspector could return
+ * @property {string} [platformVersion] version of iOS
+ * @property {boolean} [isSafari=true]
+ * @property {boolean} [includeSafari=false]
+ * @property {boolean} [useNewSafari=false] for web inspector, whether this is a new Safari instance
+ * @property {number} [pageLoadMs] the time, in ms, that should be waited for page loading
+ * @property {string} [host] the remote debugger's host address
+ * @property {number} [port=REMOTE_DEBUGGER_PORT] the remote debugger port through which to communicate
+ * @property {string} [socketPath]
+ * @property {number} [pageReadyTimeout=PAGE_READY_TIMEOUT]
+ * @property {string} [remoteDebugProxy]
+ * @property {boolean} [garbageCollectOnExecute=false]
+ * @property {boolean} [logFullResponse=false]
+ * @property {boolean} [logAllCommunication=false] log plists sent and received from Web Inspector
+ * @property {boolean} [logAllCommunicationHexDump=false] log communication from Web Inspector as hex dump
+ * @property {number} [webInspectorMaxFrameLength] The maximum size in bytes of a single data
+ *                    frame in the device communication protocol
+ * @property {number} [socketChunkSize] size, in bytes, of chunks of data sent to
+ *                    Web Inspector (real device only)
+ * @property {boolean} [fullPageInitialization]
+ * @property {string} [pageLoadStrategy]
+ * @property {import('@appium/types').AppiumLogger} [log]
+ */

package/lib/rpc/rpc-client.js

@@ -29,7 +29,7 @@ function isTargetBased (isSafari, platformVersion) {
   return isHighVersion;
 }
 
-export default class RpcClient {
+export class RpcClient {
   /** @type {RpcMessageHandler|undefined} */
   messageHandler;
 
@@ -163,7 +163,7 @@ export default class RpcClient {
   /**
    *
    * @param {string} appIdKey
-   * @param {string} pageIdKey
+   * @param {string|number} pageIdKey
    * @param {boolean} [force]
    * @returns {Promise<void>}
    */
@@ -471,7 +471,7 @@ export default class RpcClient {
 
   /**
    * @param {string} appIdKey
-   * @param {string} pageIdKey
+   * @param {string|number} pageIdKey
    * @returns {any}
    */
   getTarget (appIdKey, pageIdKey) {
@@ -480,11 +480,11 @@ export default class RpcClient {
 
   /**
    * @param {string} appIdKey
-   * @param {string} pageIdKey
+   * @param {string|number} pageIdKey
    * @returns {Promise<void>}
    */
   async selectPage (appIdKey, pageIdKey) {
-    /** @type {[string, string]} */
+    /** @type {[string, string|number]} */
     this.pendingTargetNotification = [appIdKey, pageIdKey];
     this.shouldCheckForTarget = false;
 
@@ -522,7 +522,7 @@ export default class RpcClient {
   /**
    * Perform the minimal initialization to get the Web Inspector working
    * @param {string} appIdKey
-   * @param {string} pageIdKey
+   * @param {string|number} pageIdKey
    * @returns {Promise<void>}
    */
   async initializePage (appIdKey, pageIdKey) {
@@ -548,7 +548,7 @@ export default class RpcClient {
    * Web Inspector session
    *
    * @param {string} appIdKey
-   * @param {string} pageIdKey
+   * @param {string|number} pageIdKey
    * @returns {Promise<void>}
    */
   async initializePageFull (appIdKey, pageIdKey) {
@@ -696,3 +696,5 @@ export default class RpcClient {
     log.debug(`Script parsed: ${JSON.stringify(scriptInfo)}`);
   }
 }
+
+export default RpcClient;