appium-remote-debugger 10.0.3 → 10.1.1

package/lib/atoms.js

@@ -6,6 +6,10 @@ import { getModuleRoot } from './utils';
 
 const ATOMS_CACHE = {};
 
+/**
+ * @param {any} obj
+ * @returns {string}
+ */
 function atomsStringify(obj) {
   if (typeof obj === 'undefined') {
     return 'undefined';
@@ -13,7 +17,11 @@ function atomsStringify(obj) {
   return JSON.stringify(obj);
 }
 
-
+/**
+ *
+ * @param {string} atomName
+ * @returns {Promise<Buffer>}
+ */
 async function getAtom (atomName) {
   // check if we have already loaded and cached this atom
   if (!_.has(ATOMS_CACHE, atomName)) {
@@ -28,15 +36,28 @@ async function getAtom (atomName) {
   return ATOMS_CACHE[atomName];
 }
 
+/**
+ * @param {string} script
+ * @param {string} frame
+ * @returns {Promise<string>}
+ */
 async function wrapScriptForFrame (script, frame) {
   log.debug(`Wrapping script for frame '${frame}'`);
   const elFromCache = await getAtom('get_element_from_cache');
   return `(function (window) { var document = window.document; ` +
-         `return (${script}); })((${elFromCache.toString('utf8')})(${atomsStringify(frame)}))`;
+    `return (${script}); })((${elFromCache.toString('utf8')})(${atomsStringify(frame)}))`;
 }
 
-async function getScriptForAtom (atom, args, frames = [], asyncCallBack = null) {
-  const atomSrc = await getAtom(atom);
+/**
+ *
+ * @param {string} atom
+ * @param {any[]} [args]
+ * @param {string[]} [frames]
+ * @param {string?} [asyncCallBack]
+ * @returns {Promise<string>}
+ */
+async function getScriptForAtom (atom, args = [], frames = [], asyncCallBack = null) {
+  const atomSrc = (await getAtom(atom)).toString('utf8');
   let script;
   if (frames.length > 0) {
     script = atomSrc;

package/lib/mixins/connect.js

@@ -1,6 +1,8 @@
 import log from '../logger';
-import { appInfoFromDict, pageArrayFromDict, getDebuggerAppKey,
-         getPossibleDebuggerAppKeys, simpleStringify, deferredPromise } from '../utils';
+import {
+  appInfoFromDict, pageArrayFromDict, getDebuggerAppKey,
+  getPossibleDebuggerAppKeys, simpleStringify, deferredPromise
+} from '../utils';
 import events from './events';
 import { timing } from '@appium/support';
 import { retryInterval, waitForCondition } from 'asyncbox';
@@ -14,20 +16,48 @@ const SELECT_APP_RETRY_SLEEP_MS = 500;
 const SAFARI_BUNDLE_ID = 'com.apple.mobilesafari';
 const BLANK_PAGE_URL = 'about:blank';
 
+/**
+ * @typedef {Object} AppPages
+ * @property {string} appIdKey
+ * @property {Record<string, any>} pageDict
+ */
 
+/**
+ * @typedef {Object} App
+ * @property {string} id
+ * @property {string} bundleId
+ */
+
+
+/**
+ *
+ * @this {import('../remote-debugger').RemoteDebugger}
+ */
 async function setConnectionKey () {
   log.debug('Sending connection key request');
+  if (!this.rpcClient) {
+    throw new Error('rpcClient is undefined. Is the debugger connected?');
+  }
+
   // send but only wait to make sure the socket worked
   // as response from Web Inspector can take a long time
   await this.rpcClient.send('setConnectionKey', {}, false);
 }
 
+/**
+ *
+ * @this {import('../remote-debugger').RemoteDebugger}
+ */
 async function connect (timeout = APP_CONNECT_TIMEOUT_MS) {
   this.setup();
 
   // initialize the rpc client
   this.initRpcClient();
 
+  if (!this.rpcClient) {
+    throw new Error('rpcClient is undefined. Is the debugger connected?');
+  }
+
   // listen for basic debugger-level events
   this.rpcClient.on('_rpc_reportSetup:', _.noop);
   this.rpcClient.on('_rpc_forwardGetListing:', this.onPageChange.bind(this));
@@ -43,13 +73,13 @@ async function connect (timeout = APP_CONNECT_TIMEOUT_MS) {
 
   // get the connection information about the app
   try {
-    await this.setConnectionKey();
+    this.setConnectionKey();
     if (timeout) {
       log.debug(`Waiting up to ${timeout}ms for applications to be reported`);
       try {
         await waitForCondition(() => !_.isEmpty(this.appDict), {
           waitMs: timeout,
-          interval: APP_CONNECT_INTERVAL_MS,
+          intervalMs: APP_CONNECT_INTERVAL_MS,
         });
       } catch (err) {
         log.debug(`Timed out waiting for applications to be reported`);
@@ -63,6 +93,11 @@ async function connect (timeout = APP_CONNECT_TIMEOUT_MS) {
   }
 }
 
+/**
+ *
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @returns {Promise<void>}
+ */
 async function disconnect () {
   if (this.rpcClient) {
     await this.rpcClient.disconnect();
@@ -71,12 +106,24 @@ async function disconnect () {
   this.teardown();
 }
 
+/**
+ *
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {string?} currentUrl
+ * @param {number} [maxTries]
+ * @param {boolean} [ignoreAboutBlankUrl]
+ * @returns {Promise<AppPages[]>}
+ */
 async function selectApp (currentUrl = null, maxTries = SELECT_APP_RETRIES, ignoreAboutBlankUrl = false) {
+  log.debug('Selecting application');
+  if (!this.rpcClient) {
+    throw new Error('rpcClient is undefined. Is the debugger connected?');
+  }
+
   const shouldCheckForTarget = this.rpcClient.shouldCheckForTarget;
   this.rpcClient.shouldCheckForTarget = false;
   try {
     const timer = new timing.Timer().start();
-    log.debug('Selecting application');
     if (!this.appDict || _.isEmpty(this.appDict)) {
       log.debug('No applications currently connected.');
       return [];
@@ -125,12 +172,24 @@ async function selectApp (currentUrl = null, maxTries = SELECT_APP_RETRIES, igno
   }
 }
 
+/**
+ *
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {string?} currentUrl
+ * @param {number} maxTries
+ * @param {boolean} ignoreAboutBlankUrl
+ * @returns {Promise<AppPages?>}
+ */
 async function searchForApp (currentUrl, maxTries, ignoreAboutBlankUrl) {
   const bundleIds = this.includeSafari && !this.isSafari
     ? [this.bundleId, ...this.additionalBundleIds, SAFARI_BUNDLE_ID]
     : [this.bundleId, ...this.additionalBundleIds];
   try {
     return await retryInterval(maxTries, SELECT_APP_RETRY_SLEEP_MS, async (retryCount) => {
+      if (!this.rpcClient) {
+        throw new Error('rpcClient is undefined. Is the debugger connected?');
+      }
+
       logApplicationDictionary(this.appDict);
       const possibleAppIds = getPossibleDebuggerAppKeys(bundleIds, this.appDict);
       log.debug(`Trying out the possible app ids: ${possibleAppIds.join(', ')} (try #${retryCount + 1} of ${maxTries})`);
@@ -141,7 +200,7 @@ async function searchForApp (currentUrl, maxTries, ignoreAboutBlankUrl) {
             continue;
           }
           log.debug(`Attempting app '${attemptedAppIdKey}'`);
-          const [appIdKey, pageDict] = await this.rpcClient.selectApp(attemptedAppIdKey, this.onAppConnect.bind(this));
+          const [appIdKey, pageDict] = await this.rpcClient.selectApp(attemptedAppIdKey);
           // in iOS 8.2 the connect logic happens, but with an empty dictionary
           // which leads to the remote debugger getting disconnected, and into a loop
           if (_.isEmpty(pageDict)) {
@@ -175,8 +234,17 @@ async function searchForApp (currentUrl, maxTries, ignoreAboutBlankUrl) {
   } catch (ign) {
     log.errorAndThrow(`Could not connect to a valid app after ${maxTries} tries.`);
   }
+  return null;
 }
 
+/**
+ *
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {Record<string, any>} appsDict
+ * @param {string?} currentUrl
+ * @param {boolean} [ignoreAboutBlankUrl]
+ * @returns {AppPages?}
+ */
 function searchForPage (appsDict, currentUrl = null, ignoreAboutBlankUrl = false) {
   for (const appDict of _.values(appsDict)) {
     if (!appDict || !appDict.isActive || !appDict.pageArray || appDict.pageArray.promise) {
@@ -193,11 +261,22 @@ function searchForPage (appsDict, currentUrl = null, ignoreAboutBlankUrl = false
   return null;
 }
 
+/**
+ *
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {string} appIdKey
+ * @param {string} pageIdKey
+ * @param {boolean} [skipReadyCheck]
+ * @returns {Promise<void>}
+ */
 async function selectPage (appIdKey, pageIdKey, skipReadyCheck = false) {
   this.appIdKey = `PID:${appIdKey}`;
   this.pageIdKey = pageIdKey;
 
   log.debug(`Selecting page '${pageIdKey}' on app '${this.appIdKey}' and forwarding socket setup`);
+  if (!this.rpcClient) {
+    throw new Error('rpcClient is undefined. Is the debugger connected?');
+  }
 
   const timer = new timing.Timer().start();
 
@@ -211,7 +290,13 @@ async function selectPage (appIdKey, pageIdKey, skipReadyCheck = false) {
   log.debug(`Selected page after ${timer.getDuration().asMilliSeconds.toFixed(0)}ms`);
 }
 
+/**
+ *
+ * @param {Record<string, any>} apps
+ * @returns {void}
+ */
 function logApplicationDictionary (apps) {
+
   function getValueString (key, value) {
     if (_.isFunction(value)) {
       return '[Function]';
@@ -221,6 +306,7 @@ function logApplicationDictionary (apps) {
     }
     return JSON.stringify(value);
   }
+
   log.debug('Current applications available:');
   for (const [app, info] of _.toPairs(apps)) {
     log.debug(`    Application: "${app}"`);
@@ -242,6 +328,12 @@ function logApplicationDictionary (apps) {
   }
 }
 
+/**
+ *
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {Record<string, any>} dict
+ * @returns {void}
+ */
 function updateAppsWithDict (dict) {
   // get the dictionary entry into a nice form, and add it to the
   // application dictionary
@@ -264,4 +356,7 @@ function updateAppsWithDict (dict) {
   }
 }
 
-export default { setConnectionKey, connect, disconnect, selectApp, searchForApp, searchForPage, selectPage, updateAppsWithDict };
+export default {
+  setConnectionKey, connect, disconnect, selectApp,
+  searchForApp, searchForPage, selectPage, updateAppsWithDict
+};

package/lib/mixins/execute.js

@@ -13,12 +13,12 @@ const RPC_RESPONSE_TIMEOUT_MS = 5000;
 /**
  * Execute a Selenium atom in Safari
  * @param {string} atom Name of Selenium atom (see atoms/ directory)
- * @param {Array<*>} args Arguments passed to the atom
- * @param {Array<string>} frames
- * @returns {string} The result received from the atom
+ * @param {any[]} args Arguments passed to the atom
+ * @param {string[]} frames
+ * @returns {Promise<string>} The result received from the atom
  */
-async function executeAtom (atom, args, frames) {
-  if (!this.rpcClient.isConnected) {
+async function executeAtom (atom, args = [], frames = []) {
+  if (!this.rpcClient?.isConnected) {
     throw new Error('Remote debugger is not connected');
   }
 
@@ -29,13 +29,25 @@ async function executeAtom (atom, args, frames) {
   return value;
 }
 
-async function executeAtomAsync (atom, args, frames) {
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {string} atom
+ * @param {any[]} [args]
+ * @param {string[]} [frames]
+ * @returns {Promise<any>}
+ */
+async function executeAtomAsync (atom, args = [], frames = []) {
   // helper to send directly to the web inspector
-  const evaluate = async (method, opts) => await this.rpcClient.send(method, Object.assign({
-    appIdKey: this.appIdKey,
-    pageIdKey: this.pageIdKey,
-    returnByValue: false,
-  }, opts));
+  const evaluate = async (method, opts) => {
+    if (!this.rpcClient?.isConnected) {
+      throw new Error('Remote debugger is not connected');
+    }
+    return await this.rpcClient.send(method, Object.assign({
+      appIdKey: this.appIdKey,
+      pageIdKey: this.pageIdKey,
+      returnByValue: false,
+    }, opts));
+  };
 
   // first create a Promise on the page, saving the resolve/reject functions
   // as properties
@@ -80,7 +92,7 @@ async function executeAtomAsync (atom, args, frames) {
     const retryWait = 100;
     const timeout = (args.length >= 3) ? args[2] : RPC_RESPONSE_TIMEOUT_MS;
     // if the timeout math turns up 0 retries, make sure it happens once
-    const retries = parseInt(timeout / retryWait, 10) || 1;
+    const retries = parseInt(`${timeout / retryWait}`, 10) || 1;
     const timer = new timing.Timer().start();
     log.debug(`Waiting up to ${timeout}ms for async execute to finish`);
     res = await retryInterval(retries, retryWait, async () => {
@@ -105,12 +117,20 @@ async function executeAtomAsync (atom, args, frames) {
   } finally {
     try {
       // try to get rid of the promise
-      await this.executeAtom('execute_script', [`delete window.${promiseName};`, [null, null], subcommandTimeout], frames);
+      await this.executeAtom(
+        'execute_script', [`delete window.${promiseName};`, [null, null], subcommandTimeout], frames
+      );
     } catch (ign) {}
   }
   return convertResult(res);
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {string} command
+ * @param {boolean} [override]
+ * @returns {Promise<any>}
+ */
 async function execute (command, override) {
   // if the page is not loaded yet, wait for it
   if (this.pageLoading && !override) {
@@ -130,6 +150,9 @@ async function execute (command, override) {
   }
 
   log.debug(`Sending javascript command: '${_.truncate(command, {length: 50})}'`);
+  if (!this.rpcClient?.isConnected) {
+    throw new Error('Remote debugger is not connected');
+  }
   const res = await this.rpcClient.send('Runtime.evaluate', {
     expression: command,
     returnByValue: true,
@@ -140,7 +163,17 @@ async function execute (command, override) {
   return convertResult(res);
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {string} objectId
+ * @param {any} fn
+ * @param {any[]} [args]
+ */
 async function callFunction (objectId, fn, args) {
+  if (!this.rpcClient?.isConnected) {
+    throw new Error('Remote debugger is not connected');
+  }
+
   checkParams({appIdKey: this.appIdKey, pageIdKey: this.pageIdKey});
 
   if (this.garbageCollectOnExecute) {

package/lib/mixins/message-handlers.js

@@ -9,6 +9,13 @@ import _ from 'lodash';
  * These will be added to the prototype.
  */
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {Error?} err
+ * @param {string} appIdKey
+ * @param {Record<string, any>} pageDict
+ * @returns {Promise<void>}
+ */
 async function onPageChange (err, appIdKey, pageDict) {
   if (_.isEmpty(pageDict)) {
     return;
@@ -54,10 +61,16 @@ async function onPageChange (err, appIdKey, pageDict) {
   });
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {Error?} err
+ * @param {Record<string, any>} dict
+ * @returns {Promise<void>}
+ */
 async function onAppConnect (err, dict) {
   const appIdKey = dict.WIRApplicationIdentifierKey;
   log.debug(`Notified that new application '${appIdKey}' has connected`);
-  await this.useAppDictLock((done) => {
+  await this.useAppDictLock((/** @type {() => Void} */done) => {
     try {
       this.updateAppsWithDict(dict);
     } finally {
@@ -66,6 +79,12 @@ async function onAppConnect (err, dict) {
   });
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {Error?} err
+ * @param {Record<string, any>} dict
+ * @returns {void}
+ */
 function onAppDisconnect (err, dict) {
   const appIdKey = dict.WIRApplicationIdentifierKey;
   log.debug(`Application '${appIdKey}' disconnected. Removing from app dictionary.`);
@@ -89,6 +108,12 @@ function onAppDisconnect (err, dict) {
   }
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {Error?} err
+ * @param {Record<string, any>} dict
+ * @returns {Promise<void>}
+ */
 async function onAppUpdate (err, dict) {
   await this.useAppDictLock((done) => {
     try {
@@ -99,11 +124,23 @@ async function onAppUpdate (err, dict) {
   });
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {Error?} err
+ * @param {Record<string, any>} drivers
+ * @returns {void}
+ */
 function onConnectedDriverList (err, drivers) {
   this.connectedDrivers = drivers.WIRDriverDictionaryKey;
   log.debug(`Received connected driver list: ${JSON.stringify(this.connectedDrivers)}`);
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {Error?} err
+ * @param {Record<string, any>} state
+ * @returns {void}
+ */
 function onCurrentState (err, state) {
   this.currentState = state.WIRAutomationAvailabilityKey;
   // This state changes when 'Remote Automation' in 'Settings app' > 'Safari' > 'Advanced' > 'Remote Automation' changes
@@ -111,6 +148,12 @@ function onCurrentState (err, state) {
   log.debug(`Received connected automation availability state: ${JSON.stringify(this.currentState)}`);
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {Error?} err
+ * @param {Record<string, any>} apps
+ * @returns {Promise<void>}
+ */
 async function onConnectedApplicationList (err, apps) {
   log.debug(`Received connected applications list: ${_.keys(apps).join(', ')}`);
 

package/lib/mixins/navigate.js

@@ -6,10 +6,24 @@ import _ from 'lodash';
 import B from 'bluebird';
 
 
+/**
+ * @typedef {(() => Promise<any>|void)|undefined} TPageLoadVerifyHook
+ */
+
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @returns {void}
+ */
 function frameDetached () {
   this.emit(events.EVENT_FRAMES_DETACHED);
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {timing.Timer?} startPageLoadTimer
+ * @param {TPageLoadVerifyHook} [pageLoadVerifyHook]
+ * @returns {Promise<void>}
+ */
 async function pageLoad (startPageLoadTimer, pageLoadVerifyHook = _.noop) {
   const timeoutMs = 500;
   if (!_.isFunction(startPageLoadTimer?.getDuration)) {
@@ -43,6 +57,7 @@ async function pageLoad (startPageLoadTimer, pageLoadVerifyHook = _.noop) {
     }
 
     // if we are ready, or we've spend too much time on this
+    // @ts-ignore startPageLoadTimer is defined here
     const elapsedMs = startPageLoadTimer.getDuration().asMilliSeconds;
     if (await this.checkPageIsReady() || (this.pageLoadMs > 0 && elapsedMs > this.pageLoadMs)) {
       log.debug('Page is ready');
@@ -55,11 +70,15 @@ async function pageLoad (startPageLoadTimer, pageLoadVerifyHook = _.noop) {
   try {
     await verify();
   } finally {
+    // @ts-ignore startPageLoadTimer is defined here
     log.debug(`Page load completed in ${startPageLoadTimer.getDuration().asMilliSeconds.toFixed(0)}ms`);
     this.pageLoading = false;
   }
 }
-
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @returns {void}
+ */
 function cancelPageLoad () {
   log.debug('Unregistering from page readiness notifications');
   this.pageLoading = false;
@@ -68,16 +87,30 @@ function cancelPageLoad () {
   }
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @returns {Promise<void>}
+ */
 async function pageUnload () {
   log.debug('Page unloading');
   await this.waitForDom();
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {timing.Timer|null|undefined} startPageLoadTimer
+ * @param {TPageLoadVerifyHook} [pageLoadVerifyHook]
+ * @returns {Promise<void>}
+ */
 async function waitForDom (startPageLoadTimer, pageLoadVerifyHook) {
   log.debug('Waiting for dom...');
   await this.pageLoad(startPageLoadTimer, pageLoadVerifyHook);
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @returns {Promise<boolean>}
+ */
 async function checkPageIsReady () {
   checkParams({appIdKey: this.appIdKey});
 
@@ -98,9 +131,19 @@ async function checkPageIsReady () {
   return readyState === 'complete';
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @param {string} url
+ * @param {TPageLoadVerifyHook} [pageLoadVerifyHook]
+ * @returns {Promise<void>}
+ */
 async function navToUrl (url, pageLoadVerifyHook) {
   checkParams({appIdKey: this.appIdKey, pageIdKey: this.pageIdKey});
 
+  if (!this.rpcClient) {
+    throw new Error('rpcClient is undefined. Is the debugger connected?');
+  }
+
   this._navigatingToPage = true;
 
   try {
@@ -136,10 +179,17 @@ async function navToUrl (url, pageLoadVerifyHook) {
   }
 }
 
+/**
+ * @this {import('../remote-debugger').RemoteDebugger}
+ * @returns {Promise<any>}
+ */
 async function waitForFrameNavigated () {
   let navEventListener;
   return await new B(async (resolve) => {
     log.debug('Waiting for frame navigated message...');
+    if (!this.rpcClient) {
+      throw new Error('rpcClient is undefined. Is the debugger connected?');
+    }
     const start = new timing.Timer().start();
 
     // add a handler for the `Page.frameNavigated` message
@@ -177,10 +227,12 @@ async function waitForFrameNavigated () {
     }
   }).finally(() => {
     if (navEventListener) {
-      this.rpcClient.off('Page.frameNavigated', navEventListener);
+      this.rpcClient?.off('Page.frameNavigated', navEventListener);
     }
   });
 }
 
 
-export default { frameDetached, pageLoad, cancelPageLoad, pageUnload, waitForDom, checkPageIsReady, navToUrl, waitForFrameNavigated };
+export default {
+  frameDetached, pageLoad, cancelPageLoad, pageUnload, waitForDom, checkPageIsReady, navToUrl, waitForFrameNavigated
+};