appium-remote-debugger 10.0.3 → 10.1.0

package/lib/remote-debugger.js

@@ -7,6 +7,7 @@ import _ from 'lodash';
 import B from 'bluebird';
 import path from 'path';
 import AsyncLock from 'async-lock';
+import RpcClient from './rpc/rpc-client';
 
 const REMOTE_DEBUGGER_PORT = 27753;
 const SAFARI_BUNDLE_ID = 'com.apple.mobilesafari';
@@ -20,6 +21,76 @@ const GARBAGE_COLLECT_TIMEOUT = 5000;
 
 
 class RemoteDebugger extends EventEmitter {
+  // properties
+  /** @type {any[]|undefined} */
+  _skippedApps;
+  /** @type {Record<string, any>} */
+  _clientEventListeners;
+  /** @type {Record<string, any>} */
+  appDict;
+  /** @type {Record<string, any>[]|undefined} */
+  connectedDrivers;
+  /** @type {Record<string, any>[]|undefined} */
+  currentState;
+  /** @type {boolean|undefined} */
+  connected;
+  /** @type {B<void>} */
+  pageLoadDelay;
+  /** @type {B<void>} */
+  navigationDelay;
+  /** @type {RpcClient?} */
+  rpcClient;
+
+  // events
+  /** @type {string} */
+  static EVENT_PAGE_CHANGE;
+  /** @type {string} */
+  static EVENT_DISCONNECT;
+
+  // 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 {() => Promise<void>} */
+  pageUnload;
+  /** @type {() => Promise<boolean>} */
+  checkPageIsReady;
+  /** @type {(dict: Record<string, any>) => void} */
+  updateAppsWithDict;
+  /** @type {(startPageLoadTimer?: import('@appium/support').timing.Timer, pageLoadVerifyHook?: import('./mixins/navigate').TPageLoadVerifyHook) => Promise<void>} */
+  waitForDom;
+  /** @type {(startPageLoadTimer?: import('@appium/support').timing.Timer?, pageLoadVerifyHook?: import('./mixins/navigate').TPageLoadVerifyHook) => Promise<void>} */
+  pageLoad;
+  /** @type {(command: string, override?: boolean) => Promise<any>} */
+  execute;
+  /** @type {() => Promise<any>} */
+  waitForFrameNavigated;
+  /** @type {(atom: string, args?: any[], frames?: string[]) => Promise<string>} */
+  executeAtom;
+
+  // 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;
+
   /*
    * The constructor takes an opts hash with the following properties:
    *   - bundleId - id of the app being connected to
@@ -39,6 +110,7 @@ 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}`);
 
     const {
@@ -141,12 +213,20 @@ class RemoteDebugger extends EventEmitter {
   }
 
   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', {
@@ -156,6 +236,10 @@ class RemoteDebugger extends EventEmitter {
   }
 
   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,
@@ -167,12 +251,20 @@ class RemoteDebugger extends EventEmitter {
    * Keep track of the client event listeners so they can be removed
    */
   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);
     }
@@ -211,6 +303,10 @@ class RemoteDebugger extends EventEmitter {
   // 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,
@@ -220,6 +316,10 @@ class RemoteDebugger extends EventEmitter {
 
   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
@@ -228,6 +328,10 @@ class RemoteDebugger extends EventEmitter {
 
   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,
@@ -237,6 +341,10 @@ class RemoteDebugger extends EventEmitter {
 
   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,
@@ -247,6 +355,10 @@ class RemoteDebugger extends EventEmitter {
 
   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) {

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

@@ -8,12 +8,6 @@ export default class RpcClientRealDevice extends RpcClient {
     super(Object.assign({
       shouldCheckForTarget: false,
     }, opts));
-
-    const {
-      udid,
-    } = opts;
-
-    this.udid = udid;
   }
 
   async connect () {
@@ -49,6 +43,7 @@ export default class RpcClientRealDevice extends RpcClient {
     if (!this.isConnected) {
       return;
     }
+    // @ts-ignore messageHandler must be defined here
     await this.messageHandler.handleMessage(data);
   }
 }

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

@@ -39,6 +39,7 @@ export default class RpcClientSimulator extends RpcClient {
         // Forward the actual socketPath to the proxy
         this.socket.once('connect', () => {
           log.debug(`Forwarding the actual web inspector socket to the proxy: '${this.socketPath}'`);
+          // @ts-ignore socket must be efined here
           this.socket.write(JSON.stringify({
             socketPath: this.socketPath
           }));
@@ -57,7 +58,7 @@ export default class RpcClientSimulator extends RpcClient {
 
       // tcp socket
       log.debug(`Connecting to remote debugger ${this.messageProxy ? 'via proxy ' : ''}through TCP: ${this.host}:${this.port}`);
-      this.socket = new net.Socket({type: 'tcp6'});
+      this.socket = new net.Socket();
       this.socket.connect(this.port, this.host);
     }
 
@@ -86,12 +87,14 @@ export default class RpcClientSimulator extends RpcClient {
     // connect the socket
     return await new B((resolve, reject) => {
       // only resolve this function when we are actually connected
+      // @ts-ignore socket must be defined here
       this.socket.on('connect', () => {
         log.debug(`Debugger socket connected`);
         this.isConnected = true;
 
         resolve();
       });
+      // @ts-ignore socket must be defined here
       this.socket.on('error', (err) => {
         if (this.isConnected) {
           log.error(`Socket error: ${err.message}`);
@@ -127,6 +130,7 @@ export default class RpcClientSimulator extends RpcClient {
         reject(err);
       };
 
+      // @ts-ignore socket must be defined
       this.socket.on('error', onSocketError);
       this.service.sendMessage(cmd);
       resolve();
@@ -134,6 +138,7 @@ export default class RpcClientSimulator extends RpcClient {
     .finally(() => {
       // remove this listener, so we don't exhaust the system
       try {
+        // @ts-ignore socket must be defined
         this.socket.removeListener('error', onSocketError);
       } catch (ign) {}
     });
@@ -153,6 +158,7 @@ export default class RpcClientSimulator extends RpcClient {
         data[key] = data[key].toString('utf8');
       }
     }
+    // @ts-ignore messageHandler must be defined
     await this.messageHandler.handleMessage(data);
   }
 }

package/lib/rpc/rpc-client.js

@@ -28,6 +28,15 @@ function isTargetBased (isSafari, platformVersion) {
 }
 
 export default class RpcClient {
+  /** @type {RpcMessageHandler|undefined} */
+  messageHandler;
+
+  /** @type {RemoteMessages|undefined} */
+  remoteMessages;
+
+  /** @type {boolean} */
+  connected;
+
   constructor (opts = {}) {
     this._targets = [];
     this._shouldCheckForTarget = !!opts.shouldCheckForTarget;
@@ -41,6 +50,7 @@ export default class RpcClient {
       webInspectorMaxFrameLength,
       socketChunkSize,
       fullPageInitialization = false,
+      udid,
     } = opts;
 
     this.isSafari = isSafari;
@@ -50,6 +60,8 @@ export default class RpcClient {
     this.senderId = util.uuidV4();
     this.msgId = 0;
 
+    this.udid = udid;
+
     this.logAllCommunication = logAllCommunication;
     this.logAllCommunicationHexDump = logAllCommunicationHexDump;
     this.socketChunkSize = socketChunkSize;
@@ -96,16 +108,19 @@ export default class RpcClient {
   }
 
   on (event, listener) {
+    // @ts-ignore messageHandler must be defined here
     this.messageHandler.on(event, listener);
     return this;
   }
 
   once (event, listener) {
+    // @ts-ignore messageHandler must be defined here
     this.messageHandler.once(event, listener);
     return this;
   }
 
   off (event, listener) {
+    // @ts-ignore messageHandler must be defined here
     this.messageHandler.off(event, listener);
     return this;
   }
@@ -138,6 +153,13 @@ export default class RpcClient {
     return this._isTargetBased;
   }
 
+  /**
+   *
+   * @param {string} appIdKey
+   * @param {string} pageIdKey
+   * @param {boolean} [force]
+   * @returns {Promise<void>}
+   */
   async waitForTarget (appIdKey, pageIdKey, force = false) {
     if (!force && !this.needsTarget) {
       return;
@@ -162,6 +184,13 @@ export default class RpcClient {
     }
   }
 
+  /**
+   *
+   * @param {string} command
+   * @param {Record<string, any>} [opts]
+   * @param {boolean} [waitForResponse]
+   * @returns {Promise<any>}
+   */
   async send (command, opts = {}, waitForResponse = true) {
     const timer = new timing.Timer().start();
     const {
@@ -194,6 +223,13 @@ export default class RpcClient {
     }
   }
 
+  /**
+   *
+   * @param {string} command
+   * @param {Record<string, any>} opts
+   * @param {boolean} [waitForResponse]
+   * @returns {Promise<any>}
+   */
   async sendToDevice (command, opts = {}, waitForResponse = true) {
     return await new B(async (resolve, reject) => {
       // promise to be resolved whenever remote debugger
@@ -206,6 +242,7 @@ export default class RpcClient {
         // for target-base communication, everything is wrapped up
         wrapperMsgId = this.msgId++;
         // acknowledge wrapper message
+        // @ts-ignore messageHandler must be defined
         this.messageHandler.on(wrapperMsgId.toString(), function (err) {
           if (err) {
             reject(err);
@@ -224,6 +261,7 @@ export default class RpcClient {
         targetId,
         id: msgId,
       }, opts);
+      // @ts-ignore remoteMessages must be defined
       const cmd = this.remoteMessages.getRemoteCommand(command, fullOpts);
 
       if (cmd?.__argument?.WIRSocketDataKey) {
@@ -240,6 +278,7 @@ export default class RpcClient {
         // the promise will be resolved as soon as the socket has been sent
         messageHandled = false;
         // do not log receipts
+        // @ts-ignore messageHandler must be defined
         this.messageHandler.once(msgId.toString(), function (err) {
           if (err) {
             // we are not waiting for this, and if it errors it is most likely
@@ -251,7 +290,9 @@ export default class RpcClient {
             reject(err);
           }
         });
+      // @ts-ignore messageHandler must be defined
       } else if (this.messageHandler.listeners(cmd.__selector).length) {
+        // @ts-ignore messageHandler must be defined
         this.messageHandler.prependOnceListener(cmd.__selector, function (err, ...args) {
           if (err) {
             return reject(err);
@@ -260,6 +301,7 @@ export default class RpcClient {
           resolve(args);
         });
       } else if (cmd?.__argument?.WIRSocketDataKey) {
+        // @ts-ignore messageHandler must be defined
         this.messageHandler.once(msgId.toString(), function (err, value) {
           if (err) {
             return reject(new Error(`Remote debugger error with code '${err.code}': ${err.message}`));
@@ -273,8 +315,8 @@ export default class RpcClient {
       }
 
       const msg = `Sending '${cmd.__selector}' message` +
-        (fullOpts.appIdKey ? ` to app '${fullOpts.appIdKey}'` : '') +
-        (fullOpts.pageIdKey ? `, page '${fullOpts.pageIdKey}'` : '') +
+        (appIdKey ? ` to app '${appIdKey}'` : '') +
+        (pageIdKey ? `, page '${pageIdKey}'` : '') +
         (this.needsTarget && targetId ? `, target '${targetId}'` : '') +
         ` (id: ${msgId}): '${command}'`;
       log.debug(msg);
@@ -296,10 +338,11 @@ export default class RpcClient {
   }
 
   async disconnect () { // eslint-disable-line require-await
-    this.messageHandler.removeAllListeners();
+    this.messageHandler?.removeAllListeners();
   }
 
-  async sendMessage (/* command */) { // eslint-disable-line require-await
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async sendMessage (command) { // eslint-disable-line require-await
     throw new Error(`Sub-classes need to implement a 'sendMessage' function`);
   }
 
@@ -307,6 +350,13 @@ export default class RpcClient {
     throw new Error(`Sub-classes need to implement a 'receive' function`);
   }
 
+  /**
+   *
+   * @param {Error?} err
+   * @param {string} app
+   * @param {Record<string, any>} targetInfo
+   * @returns {void}
+   */
   addTarget (err, app, targetInfo) {
     if (_.isNil(targetInfo?.targetId)) {
       log.warn(`Received 'Target.targetCreated' event for app '${app}' with no target. Skipping`);
@@ -322,6 +372,7 @@ export default class RpcClient {
       return;
     }
 
+    // @ts-ignore this.pendingTargetNotification must be defined here
     const [appIdKey, pageIdKey] = this.pendingTargetNotification;
 
     log.debug(`Target created for app '${appIdKey}' and page '${pageIdKey}': ${JSON.stringify(targetInfo)}`);
@@ -332,6 +383,14 @@ export default class RpcClient {
     this.targets[appIdKey][pageIdKey] = targetInfo.targetId;
   }
 
+  /**
+   *
+   * @param {Error?} err
+   * @param {string} app
+   * @param {string} oldTargetId
+   * @param {string} newTargetId
+   * @returns {void}
+   */
   updateTarget (err, app, oldTargetId, newTargetId) {
     log.debug(`Target updated for app '${app}'. Old target: '${oldTargetId}', new target: '${newTargetId}'`);
     if (!this.targets[app]) {
@@ -345,6 +404,13 @@ export default class RpcClient {
     };
   }
 
+  /**
+   *
+   * @param {Error?} err
+   * @param {string} app
+   * @param {Record<string, any>} targetInfo
+   * @returns {void}
+   */
   removeTarget (err, app, targetInfo) {
     if (_.isNil(targetInfo?.targetId)) {
       log.debug(`Received 'Target.targetDestroyed' event with no target. Skipping`);
@@ -382,11 +448,22 @@ export default class RpcClient {
     log.debug(`Target '${targetInfo.targetId}' deleted for app '${app}', but no such target exists`);
   }
 
+  /**
+   * @param {string} appIdKey
+   * @param {string} pageIdKey
+   * @returns {any}
+   */
   getTarget (appIdKey, pageIdKey) {
     return (this.targets[appIdKey] || {})[pageIdKey];
   }
 
+  /**
+   * @param {string} appIdKey
+   * @param {string} pageIdKey
+   * @returns {Promise<void>}
+   */
   async selectPage (appIdKey, pageIdKey) {
+    /** @type {[string, string]} */
     this.pendingTargetNotification = [appIdKey, pageIdKey];
     this.shouldCheckForTarget = false;
 
@@ -421,8 +498,11 @@ export default class RpcClient {
     }
   }
 
-  /*
+  /**
    * Perform the minimal initialization to get the Web Inspector working
+   * @param {string} appIdKey
+   * @param {string} pageIdKey
+   * @returns {Promise<void>}
    */
   async initializePage (appIdKey, pageIdKey) {
     const sendOpts = {
@@ -442,9 +522,13 @@ export default class RpcClient {
     await this.send('Inspector.initialized', sendOpts, false);
   }
 
-  /*
+  /**
    * Mimic every step that Desktop Safari Develop tools uses to initialize a
    * Web Inspector session
+   *
+   * @param {string} appIdKey
+   * @param {string} pageIdKey
+   * @returns {Promise<void>}
    */
   async initializePageFull (appIdKey, pageIdKey) {
     const sendOpts = {
@@ -509,6 +593,11 @@ export default class RpcClient {
     await this.send('Inspector.initialized', sendOpts, false);
   }
 
+  /**
+   *
+   * @param {string} appIdKey
+   * @returns {Promise<[string, Record<string, any>]>}
+   */
   async selectApp (appIdKey) {
     return await new B((resolve, reject) => {
       // local callback, temporarily added as callback to
@@ -531,6 +620,7 @@ export default class RpcClient {
 
         reject(new Error('New application has connected'));
       };
+      // @ts-ignore messageHandler must be defined
       this.messageHandler.prependOnceListener('_rpc_applicationConnected:', onAppChange);
 
       // do the actual connecting to the app
@@ -558,6 +648,11 @@ export default class RpcClient {
     });
   }
 
+  /**
+   *
+   * @param {Error?} err
+   * @param {Record<string, any>} context
+   */
   onExecutionContextCreated (err, context) {
     // { id: 2, isPageContext: true, name: '', frameId: '0.1' }
     // right now we have no way to map contexts to apps/pages
@@ -570,6 +665,11 @@ export default class RpcClient {
     log.debug(`Web Inspector garbage collected`);
   }
 
+  /**
+   *
+   * @param {Error?} err
+   * @param {Record<string, any>} scriptInfo
+   */
   onScriptParsed (err, scriptInfo) {
     // { scriptId: '13', url: '', startLine: 0, startColumn: 0, endLine: 82, endColumn: 3 }
     log.debug(`Script parsed: ${JSON.stringify(scriptInfo)}`);

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

@@ -190,7 +190,7 @@ export default class RpcMessageHandler extends EventEmitters {
         // if this happens then some aspect of the protocol is missing to us
         // so print the entire message to get visibiity into what is going on
         log.error(`Unexpected message format from Web Inspector:`);
-        this.warn(util.jsonStringify(plist));
+        log.warn(util.jsonStringify(plist, null));
         throw err;
       }
     } else {

package/lib/utils.js

@@ -23,9 +23,31 @@ const ACCEPTED_PAGE_TYPES = [
 
 const RESPONSE_LOG_LENGTH = 100;
 
-/*
+/**
+ * @typedef {Object} DeferredPromise
+ * @property {B<any>} promise
+ * @property {(...args: any[]) => void} resolve
+ * @property {(err?: Error) => void} reject
+ */
+
+/**
+ * @typedef {Object} AppInfo
+ * @property {string} id
+ * @property {boolean} isProxy
+ * @property {string} name
+ * @property {string} bundleId
+ * @property {string} hostId
+ * @property {boolean} isActive
+ * @property {boolean|string} isAutomationEnabled
+ * @property {any[]|undefined|DeferredPromise} [pageArray]
+ */
+
+/**
  * Takes a dictionary from the remote debugger and makes a more manageable
  * dictionary whose keys are understandable
+ *
+ * @param {Record<string, any>} dict
+ * @returns {[string, AppInfo]}
  */
 function appInfoFromDict (dict) {
   const id = dict.WIRApplicationIdentifierKey;
@@ -35,6 +57,7 @@ function appInfoFromDict (dict) {
   // automation enabled can be either from the keys
   //   - WIRRemoteAutomationEnabledKey (boolean)
   //   - WIRAutomationAvailabilityKey (string or boolean)
+  /** @type {boolean|string} */
   let isAutomationEnabled = !!dict.WIRRemoteAutomationEnabledKey;
   if (_.has(dict, 'WIRAutomationAvailabilityKey')) {
     if (_.isString(dict.WIRAutomationAvailabilityKey)) {
@@ -189,9 +212,14 @@ function simpleStringify (value, multiline = false) {
   return multiline ? JSON.stringify(cleanValue, null, 2) : JSON.stringify(cleanValue);
 }
 
+/**
+ * @returns {DeferredPromise}
+ */
 function deferredPromise () {
   // http://bluebirdjs.com/docs/api/deferred-migration.html
+  /** @type {(...args: any[]) => void}  */
   let resolve;
+  /** @type {(err?: Error) => void} */
   let reject;
   const promise = new B((res, rej) => { // eslint-disable-line promise/param-names
     resolve = res;
@@ -199,7 +227,9 @@ function deferredPromise () {
   });
   return {
     promise,
+    // @ts-ignore It will be assigned eventually
     resolve,
+    // @ts-ignore It will be assigned eventually
     reject
   };
 }