appium-remote-debugger 11.5.3 → 11.5.5

package/lib/rpc/rpc-client.js

@@ -8,17 +8,18 @@ import { util, timing } from '@appium/support';
 import { EventEmitter } from 'node:events';
 import { ON_TARGET_PROVISIONED_EVENT } from './constants';
 
-
 const DATA_LOG_LENGTH = {length: 200};
-
-const WAIT_FOR_TARGET_TIMEOUT = 10000;
-const WAIT_FOR_TARGET_INTERVAL = 1000;
-
+const WAIT_FOR_TARGET_TIMEOUT_MS = 10000;
+const WAIT_FOR_TARGET_INTERVAL_MS = 1000;
 const MIN_PLATFORM_FOR_TARGET_BASED = '12.2';
-
 // `Target.exists` protocol method was removed from WebKit in 13.4
 const MIN_PLATFORM_NO_TARGET_EXISTS = '13.4';
 
+/**
+ * @param {boolean} isSafari
+ * @param {string} platformVersion
+ * @returns {boolean}
+ */
 function isTargetBased (isSafari, platformVersion) {
   // On iOS 12.2 the messages get sent through the Target domain
   // On iOS 13.0+, WKWebView also needs to follow the Target domain,
@@ -39,13 +40,62 @@ export class RpcClient {
   /** @type {boolean} */
   connected;
 
-  constructor (opts = {}) {
-    this._targets = [];
-    this._shouldCheckForTarget = !!opts.shouldCheckForTarget;
+  /** @type {boolean} */
+  isSafari;
+
+  /** @type {string} */
+  connId;
+
+  /** @type {string} */
+  senderId;
+
+  /** @type {number} */
+  msgId;
+
+  /** @type {string|undefined} */
+  udid;
+
+  /** @type {boolean|undefined} */
+  logAllCommunication;
+
+  /** @type {boolean|undefined} */
+  logAllCommunicationHexDump;
+
+  /** @type {number|undefined} */
+  socketChunkSize;
+
+  /** @type {number|undefined} */
+  webInspectorMaxFrameLength;
+
+  /** @type {boolean|undefined} */
+  fullPageInitialization;
+
+  /** @type {string|undefined} */
+  bundleId;
+
+  /** @type {string} */
+  platformVersion;
 
+  /** @type {string[]} */
+  _contexts;
+
+  /** @type {import('@appium/types').StringRecord} */
+  _targets;
+
+  /** @type {EventEmitter} */
+  _targetSubscriptions;
+
+  /** @type {boolean} */
+  _shouldCheckForTarget;
+
+  /**
+   *
+   * @param {RpcClientOptions} [opts={}]
+   */
+  constructor (opts = {}) {
     const {
       bundleId,
-      platformVersion = {},
+      platformVersion = '',
       isSafari = true,
       logAllCommunication = false,
       logAllCommunicationHexDump = false,
@@ -79,21 +129,34 @@ export class RpcClient {
     this._targetSubscriptions = new EventEmitter();
 
     // start with a best guess for the protocol
-    this.isTargetBased = isTargetBased(isSafari, this.platformVersion);
+    this._shouldCheckForTarget = !!opts.shouldCheckForTarget;
+    this.isTargetBased = platformVersion ? isTargetBased(isSafari, platformVersion) : true;
   }
 
+  /**
+   * @returns {string[]}
+   */
   get contexts () {
     return this._contexts;
   }
 
+  /**
+   * @returns {boolean}
+   */
   get needsTarget () {
     return this.shouldCheckForTarget && this.isTargetBased;
   }
 
+  /**
+   * @returns {import('@appium/types').StringRecord}
+   */
   get targets () {
     return this._targets;
   }
 
+  /**
+   * @returns {boolean}
+   */
   get shouldCheckForTarget () {
     return this._shouldCheckForTarget;
   }
@@ -102,36 +165,65 @@ export class RpcClient {
     this._shouldCheckForTarget = !!shouldCheckForTarget;
   }
 
+  /**
+   * @returns {boolean}
+   */
   get isConnected () {
     return this.connected;
   }
 
+  /**
+   * @param {boolean} connected
+   */
   set isConnected (connected) {
     this.connected = !!connected;
   }
 
+  /**
+   * @returns {EventEmitter}
+   */
   get targetSubscriptions() {
     return this._targetSubscriptions;
   }
 
+  /**
+   *
+   * @param {string} event
+   * @param {Function} listener
+   * @returns {this}
+   */
   on (event, listener) {
     // @ts-ignore messageHandler must be defined here
     this.messageHandler.on(event, listener);
     return this;
   }
 
+  /**
+   *
+   * @param {string} event
+   * @param {Function} listener
+   * @returns {this}
+   */
   once (event, listener) {
     // @ts-ignore messageHandler must be defined here
     this.messageHandler.once(event, listener);
     return this;
   }
 
+  /**
+   * @param {string} event
+   * @param {Function} listener
+   * @returns {this}
+   */
   off (event, listener) {
     // @ts-ignore messageHandler must be defined here
     this.messageHandler.off(event, listener);
     return this;
   }
 
+  /**
+   * @param {boolean} isTargetBased
+   */
   set isTargetBased (isTargetBased) {
     log.warn(`Setting communication protocol: using ${isTargetBased ? 'Target-based' : 'full Web Inspector protocol'} communication`);
     this._isTargetBased = isTargetBased;
@@ -156,8 +248,11 @@ export class RpcClient {
     }
   }
 
+  /**
+   * @returns {boolean}
+   */
   get isTargetBased () {
-    return this._isTargetBased;
+    return !!this._isTargetBased;
   }
 
   /**
@@ -179,8 +274,8 @@ export class RpcClient {
     // otherwise waiting is necessary to see what the target is
     try {
       await waitForCondition(() => !_.isEmpty(this.getTarget(appIdKey, pageIdKey)), {
-        waitMs: WAIT_FOR_TARGET_TIMEOUT,
-        intervalMs: WAIT_FOR_TARGET_INTERVAL,
+        waitMs: WAIT_FOR_TARGET_TIMEOUT_MS,
+        intervalMs: WAIT_FOR_TARGET_INTERVAL_MS,
         error: 'No targets found, unable to communicate with device',
       });
     } catch (err) {
@@ -348,12 +443,21 @@ export class RpcClient {
     this.messageHandler?.removeAllListeners();
   }
 
+  /**
+   * @param {string} command
+   * @returns {Promise<void>}
+   */
   // 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`);
   }
 
-  async receive (/* data */) { // eslint-disable-line require-await
+  /**
+   * @param {any} data
+   * @returns {Promise<void>}
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async receive (data) { // eslint-disable-line require-await
     throw new Error(`Sub-classes need to implement a 'receive' function`);
   }
 
@@ -641,29 +745,24 @@ export class RpcClient {
 
         reject(new Error('New application has connected'));
       };
-      // @ts-ignore messageHandler must be defined
-      this.messageHandler.prependOnceListener('_rpc_applicationConnected:', onAppChange);
+      this.messageHandler?.prependOnceListener('_rpc_applicationConnected:', onAppChange);
 
       // do the actual connecting to the app
-      return (async () => {
-        let pageDict, connectedAppIdKey;
+      (async () => {
         try {
-          ([connectedAppIdKey, pageDict] = await this.send('connectToApp', {
-            appIdKey
-          }));
+          const [connectedAppIdKey, pageDict] = await this.send('connectToApp', {appIdKey});
+          // sometimes the connect logic happens, but with an empty dictionary
+          // which leads to the remote debugger getting disconnected, and into a loop
+          if (_.isEmpty(pageDict)) {
+            reject(new Error('Empty page dictionary received'));
+          } else {
+            resolve([connectedAppIdKey, pageDict]);
+          }
         } catch (err) {
-          log.warn(`Unable to connect to app: ${err.message}`);
+          log.warn(`Unable to connect to the app: ${err.message}`);
           reject(err);
-        }
-
-        // sometimes the connect logic happens, but with an empty dictionary
-        // which leads to the remote debugger getting disconnected, and into a loop
-        if (_.isEmpty(pageDict)) {
-          let msg = 'Empty page dictionary received';
-          log.debug(msg);
-          reject(new Error(msg));
-        } else {
-          resolve([connectedAppIdKey, pageDict]);
+        } finally {
+          this.messageHandler?.off('_rpc_applicationConnected:', onAppChange);
         }
       })();
     });
@@ -681,6 +780,9 @@ export class RpcClient {
     this.contexts.push(context.id);
   }
 
+  /**
+   * @returns {void}
+   */
   onGarbageCollected () {
     // just want to log that this is happening, as it can affect opertion
     log.debug(`Web Inspector garbage collected`);
@@ -698,3 +800,17 @@ export class RpcClient {
 }
 
 export default RpcClient;
+
+/**
+ * @typedef {Object} RpcClientOptions
+ * @property {string} [bundleId]
+ * @property {string} [platformVersion='']
+ * @property {boolean} [isSafari=true]
+ * @property {boolean} [logAllCommunication=false]
+ * @property {boolean} [logAllCommunicationHexDump=false]
+ * @property {number} [webInspectorMaxFrameLength]
+ * @property {number} [socketChunkSize]
+ * @property {boolean} [fullPageInitialization=false]
+ * @property {string} [udid]
+ * @property {boolean} [shouldCheckForTarget]
+ */

package/lib/utils.js

@@ -38,10 +38,10 @@ export const RESPONSE_LOG_LENGTH = 100;
  * @property {boolean} isProxy
  * @property {string} name
  * @property {string} bundleId
- * @property {string} hostId
+ * @property {string} [hostId]
  * @property {boolean} isActive
  * @property {boolean|string} isAutomationEnabled
- * @property {any[]|undefined|DeferredPromise} [pageArray]
+ * @property {import('./mixins/connect').Page[]} [pageArray]
  */
 
 /**
@@ -83,28 +83,23 @@ export function appInfoFromDict (dict) {
   return [id, entry];
 }
 
-/*
+/**
  * Take a dictionary from the remote debugger and makes a more manageable
  * dictionary of pages available.
+ *
+ * @param {import('@appium/types').StringRecord} pageDict
+ * @returns {import('./mixins/connect').Page[]}
  */
 export function pageArrayFromDict (pageDict) {
-  if (pageDict.id) {
-    // the page is already translated, so wrap in an array and pass back
-    return [pageDict];
-  }
-  let newPageArray = [];
-  for (const dict of _.values(pageDict)) {
+  return _.values(pageDict)
     // count only WIRTypeWeb pages and ignore all others (WIRTypeJavaScript etc)
-    if (_.isUndefined(dict.WIRTypeKey) || ACCEPTED_PAGE_TYPES.includes(dict.WIRTypeKey)) {
-      newPageArray.push({
-        id: dict.WIRPageIdentifierKey,
-        title: dict.WIRTitleKey,
-        url: dict.WIRURLKey,
-        isKey: !_.isUndefined(dict.WIRConnectionIdentifierKey),
-      });
-    }
-  }
-  return newPageArray;
+    .filter((dict) => _.isUndefined(dict.WIRTypeKey) || ACCEPTED_PAGE_TYPES.includes(dict.WIRTypeKey))
+    .map((dict) => ({
+      id: dict.WIRPageIdentifierKey,
+      title: dict.WIRTitleKey,
+      url: dict.WIRURLKey,
+      isKey: !_.isUndefined(dict.WIRConnectionIdentifierKey),
+    }));
 }
 
 /**
@@ -147,7 +142,7 @@ export function getDebuggerAppKey (bundleId, appDict) {
  * Find app keys based on assigned bundleIds from appDict
  * When bundleIds includes a wildcard ('*'), returns all appKeys in appDict.
  * @param {string[]} bundleIds
- * @param {Record<string, any>} appDict
+ * @param {Record<string, AppInfo>} appDict
  * @returns {string[]}
  */
 export function getPossibleDebuggerAppKeys(bundleIds, appDict) {

package/package.json

@@ -4,7 +4,7 @@
   "keywords": [
     "appium"
   ],
-  "version": "11.5.3",
+  "version": "11.5.5",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -36,7 +36,6 @@
     "@appium/base-driver": "^9.0.0",
     "@appium/support": "^5.0.3",
     "appium-ios-device": "^2.0.0",
-    "async-lock": "^1.2.2",
     "asyncbox": "^3.0.0",
     "bluebird": "^3.4.7",
     "fancy-log": "^2.0.0",