appium-remote-debugger 11.5.7 → 11.5.9

package/lib/mixins/connect.js

@@ -1,6 +1,7 @@
 import {
   pageArrayFromDict,
-  getPossibleDebuggerAppKeys,
+  WEB_CONTENT_BUNDLE_ID,
+  appIdsForBundle,
 } from '../utils';
 import events from './events';
 import { timing, util } from '@appium/support';
@@ -13,10 +14,14 @@ const SELECT_APP_RETRIES = 20;
 const SELECT_APP_RETRY_SLEEP_MS = 500;
 const SAFARI_BUNDLE_ID = 'com.apple.mobilesafari';
 const BLANK_PAGE_URL = 'about:blank';
+const WEB_CONTENT_PROCESS_BUNDLE_ID = 'process-com.apple.WebKit.WebContent';
+const SAFARI_VIEW_PROCESS_BUNDLE_ID = 'process-SafariViewService';
+const SAFARI_VIEW_BUNDLE_ID = 'com.apple.SafariViewService';
+const WILDCARD_BUNDLE_ID = '*';
 
 /**
  *
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @returns {Promise<void>}
  */
 export async function setConnectionKey () {
@@ -29,7 +34,7 @@ export async function setConnectionKey () {
 
 /**
  *
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {number} [timeout=APP_CONNECT_TIMEOUT_MS]
  * @returns {Promise<import('@appium/types').StringRecord>}
  */
@@ -83,7 +88,7 @@ export async function connect (timeout = APP_CONNECT_TIMEOUT_MS) {
 
 /**
  *
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @returns {Promise<void>}
  */
 export async function disconnect () {
@@ -96,11 +101,11 @@ export async function disconnect () {
 
 /**
  *
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {string?} [currentUrl=null]
  * @param {number} [maxTries=SELECT_APP_RETRIES]
  * @param {boolean} [ignoreAboutBlankUrl=false]
- * @returns {Promise<Page[]>}
+ * @returns {Promise<import('../types').Page[]>}
  */
 export async function selectApp (currentUrl = null, maxTries = SELECT_APP_RETRIES, ignoreAboutBlankUrl = false) {
   this.log.debug('Selecting application');
@@ -124,7 +129,7 @@ export async function selectApp (currentUrl = null, maxTries = SELECT_APP_RETRIE
     // translate the dictionary into a useful form, and return to sender
     this.log.debug(`Finally selecting app ${this.appIdKey}`);
 
-    /** @type {Page[]} */
+    /** @type {import('../types').Page[]} */
     const fullPageArray = [];
     for (const [app, info] of _.toPairs(this.appDict)) {
       if (!_.isArray(info.pageArray) || !info.isActive) {
@@ -150,20 +155,20 @@ export async function selectApp (currentUrl = null, maxTries = SELECT_APP_RETRIE
 
 /**
  *
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {string?} currentUrl
  * @param {number} maxTries
  * @param {boolean} ignoreAboutBlankUrl
- * @returns {Promise<AppPage>}
+ * @returns {Promise<import('../types').AppPage>}
  */
 export async function searchForApp (currentUrl, maxTries, ignoreAboutBlankUrl) {
   const bundleIds = this.includeSafari && !this.isSafari
     ? [this.bundleId, ...this.additionalBundleIds, SAFARI_BUNDLE_ID]
     : [this.bundleId, ...this.additionalBundleIds];
   let retryCount = 0;
-  return /** @type {AppPage} */ (await retryInterval(maxTries, SELECT_APP_RETRY_SLEEP_MS, async () => {
+  return /** @type {import('../types').AppPage} */ (await retryInterval(maxTries, SELECT_APP_RETRY_SLEEP_MS, async () => {
     logApplicationDictionary.bind(this)();
-    const possibleAppIds = getPossibleDebuggerAppKeys(/** @type {string[]} */ (bundleIds), this.appDict);
+    const possibleAppIds = getPossibleDebuggerAppKeys.bind(this)(/** @type {string[]} */ (bundleIds));
     this.log.debug(`Trying out the possible app ids: ${possibleAppIds.join(', ')} (try #${retryCount + 1} of ${maxTries})`);
     for (const attemptedAppIdKey of possibleAppIds) {
       try {
@@ -214,11 +219,11 @@ export async function searchForApp (currentUrl, maxTries, ignoreAboutBlankUrl) {
 
 /**
  *
- * @this {import('../remote-debugger').RemoteDebugger}
- * @param {Record<string, import('../utils').AppInfo>} appsDict
+ * @this {RemoteDebugger}
+ * @param {Record<string, import('../types').AppInfo>} appsDict
  * @param {string?} currentUrl
  * @param {boolean} [ignoreAboutBlankUrl]
- * @returns {AppPage?}
+ * @returns {import('../types').AppPage?}
  */
 export function searchForPage (appsDict, currentUrl = null, ignoreAboutBlankUrl = false) {
   for (const appDict of _.values(appsDict)) {
@@ -241,7 +246,7 @@ export function searchForPage (appsDict, currentUrl = null, ignoreAboutBlankUrl
 
 /**
  *
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {string|number} appIdKey
  * @param {string|number} pageIdKey
  * @param {boolean} [skipReadyCheck]
@@ -266,7 +271,7 @@ export async function selectPage (appIdKey, pageIdKey, skipReadyCheck = false) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @returns {void}
  */
 function logApplicationDictionary () {
@@ -292,22 +297,51 @@ function logApplicationDictionary () {
 }
 
 /**
- * @typedef {Object} AppPage
- * @property {string} appIdKey
- * @property {Page} pageDict
+ * Find app keys based on assigned bundleIds from appDict
+ * When bundleIds includes a wildcard ('*'), returns all appKeys in appDict.
+ *
+ * @this {RemoteDebugger}
+ * @param {string[]} bundleIds
+ * @returns {string[]}
  */
+export function getPossibleDebuggerAppKeys(bundleIds) {
+  if (bundleIds.includes(WILDCARD_BUNDLE_ID)) {
+    this.log.debug('Skip checking bundle identifiers because the bundleIds includes a wildcard');
+    return _.uniq(Object.keys(this.appDict));
+  }
 
-/**
- * @typedef {Object} App
- * @property {string} id
- * @property {string} bundleId
- */
+  // go through the possible bundle identifiers
+  const possibleBundleIds = _.uniq([
+    WEB_CONTENT_BUNDLE_ID,
+    WEB_CONTENT_PROCESS_BUNDLE_ID,
+    SAFARI_VIEW_PROCESS_BUNDLE_ID,
+    SAFARI_VIEW_BUNDLE_ID,
+    WILDCARD_BUNDLE_ID,
+    ...bundleIds,
+  ]);
+  this.log.debug(`Checking for bundle identifiers: ${possibleBundleIds.join(', ')}`);
+  /** @type {Set<string>} */
+  const proxiedAppIds = new Set();
+  for (const bundleId of possibleBundleIds) {
+    // now we need to determine if we should pick a proxy for this instead
+    for (const appId of appIdsForBundle(bundleId, this.appDict)) {
+      proxiedAppIds.add(appId);
+      this.log.debug(`Found app id key '${appId}' for bundle '${bundleId}'`);
+      for (const [key, data] of _.toPairs(this.appDict)) {
+        if (data.isProxy && data.hostId === appId) {
+          this.log.debug(
+            `Found separate bundleId '${data.bundleId}' ` +
+            `acting as proxy for '${bundleId}', with app id '${key}'`
+          );
+          proxiedAppIds.add(key);
+        }
+      }
+    }
+  }
+
+  return Array.from(proxiedAppIds);
+}
 
 /**
- * @typedef {Object} Page
- * @property {string} url
- * @property {string} title
- * @property {number} id
- * @property {boolean} isKey
- * @property {string} [bundleId]
+ * @typedef {import('../remote-debugger').RemoteDebugger} RemoteDebugger
  */

package/lib/mixins/cookies.js

@@ -1,7 +1,7 @@
 
 /**
  *
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @returns {Promise<import('@appium/types').StringRecord>}
  */
 export async function getCookies () {
@@ -14,7 +14,7 @@ export async function getCookies () {
 
 /**
  *
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {import('@appium/types').StringRecord} cookie
  * @returns {Promise<any>}
  */
@@ -29,7 +29,7 @@ export async function setCookie (cookie) {
 
 /**
  *
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {string} cookieName
  * @param {string} url
  * @returns {Promise<any>}
@@ -43,3 +43,7 @@ export async function deleteCookie (cookieName, url) {
     url,
   });
 }
+
+/**
+ * @typedef {import('../remote-debugger').RemoteDebugger} RemoteDebugger
+ */

package/lib/mixins/events.js

@@ -8,7 +8,7 @@ export const events = {
 /**
  * Keep track of the client event listeners so they can be removed
  *
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {string} eventName
  * @param {(event: import('@appium/types').StringRecord) => any} listener
  * @returns {void}
@@ -20,7 +20,7 @@ export function addClientEventListener (eventName, listener) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {string} eventName
  * @returns {void}
  */
@@ -31,3 +31,7 @@ export function removeClientEventListener (eventName) {
 }
 
 export default events;
+
+/**
+ * @typedef {import('../remote-debugger').RemoteDebugger} RemoteDebugger
+ */

package/lib/mixins/execute.js

@@ -11,6 +11,8 @@ const RPC_RESPONSE_TIMEOUT_MS = 5000;
 
 /**
  * Execute a Selenium atom in Safari
+ *
+ * @this {RemoteDebugger}
  * @param {string} atom Name of Selenium atom (see atoms/ directory)
  * @param {any[]} args Arguments passed to the atom
  * @param {string[]} frames
@@ -25,7 +27,7 @@ export async function executeAtom (atom, args = [], frames = []) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {string} atom
  * @param {any[]} [args]
  * @param {string[]} [frames]
@@ -116,7 +118,7 @@ export async function executeAtomAsync (atom, args = [], frames = []) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {string} command
  * @param {boolean} [override]
  * @returns {Promise<any>}
@@ -150,7 +152,7 @@ export async function execute (command, override) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {string} objectId
  * @param {any} fn
  * @param {any[]} [args]
@@ -174,3 +176,7 @@ export async function callFunction (objectId, fn, args) {
 
   return convertResult(res);
 }
+
+/**
+ * @typedef {import('../remote-debugger').RemoteDebugger} RemoteDebugger
+ */

package/lib/mixins/message-handlers.js

@@ -1,7 +1,6 @@
 import events from './events';
 import {
   pageArrayFromDict,
-  getDebuggerAppKey,
   appInfoFromDict,
 } from '../utils';
 import _ from 'lodash';
@@ -13,7 +12,7 @@ import _ from 'lodash';
  */
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {Error?} err
  * @param {string} appIdKey
  * @param {Record<string, any>} pageDict
@@ -56,7 +55,7 @@ export async function onPageChange (err, appIdKey, pageDict) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {Error?} err
  * @param {Record<string, any>} dict
  * @returns {Promise<void>}
@@ -69,7 +68,7 @@ export async function onAppConnect (err, dict) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {Error?} err
  * @param {import('@appium/types').StringRecord} dict
  * @returns {void}
@@ -86,7 +85,7 @@ export function onAppDisconnect (err, dict) {
   // if the disconnected app is the one we are connected to, try to find another
   if (this.appIdKey === appIdKey) {
     this.log.debug(`No longer have app id. Attempting to find new one.`);
-    this.appIdKey = getDebuggerAppKey(/** @type {string} */ (this.bundleId), this.appDict);
+    this.appIdKey = getDebuggerAppKey.bind(this)(/** @type {string} */ (this.bundleId));
   }
 
   if (!this.appDict) {
@@ -98,7 +97,7 @@ export function onAppDisconnect (err, dict) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {Error?} err
  * @param {Record<string, any>} dict
  * @returns {Promise<void>}
@@ -110,7 +109,7 @@ export async function onAppUpdate (err, dict) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {Error?} err
  * @param {Record<string, any>} drivers
  * @returns {void}
@@ -121,7 +120,7 @@ export function onConnectedDriverList (err, drivers) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {Error?} err
  * @param {Record<string, any>} state
  * @returns {void}
@@ -134,7 +133,7 @@ export function onCurrentState (err, state) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {Error?} err
  * @param {Record<string, any>} apps
  * @returns {Promise<void>}
@@ -159,7 +158,7 @@ export async function onConnectedApplicationList (err, apps) {
 
 /**
  *
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {import('@appium/types').StringRecord} dict
  * @returns {void}
  */
@@ -176,6 +175,47 @@ function updateAppsWithDict (dict) {
 
   // try to get the app id from our connected apps
   if (!this.appIdKey) {
-    this.appIdKey = getDebuggerAppKey(/** @type {string} */ (this.bundleId), this.appDict);
+    this.appIdKey = getDebuggerAppKey.bind(this)(/** @type {string} */ (this.bundleId));
   }
 }
+
+/**
+ * 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(this.appDict)) {
+    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(this.appDict)) {
+      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
+ */

package/lib/mixins/misc.js

@@ -5,7 +5,7 @@ const SAFARI_BUNDLE_ID = 'com.apple.mobilesafari';
 const GARBAGE_COLLECT_TIMEOUT_MS = 5000;
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @returns {Promise<void>}
  */
 export async function launchSafari () {
@@ -15,7 +15,7 @@ export async function launchSafari () {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {(event: import('@appium/types').StringRecord) => any} fn
  * @returns {Promise<any>}
  */
@@ -29,7 +29,7 @@ export async function startTimeline (fn) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @returns {Promise<any>}
  */
 export async function stopTimeline () {
@@ -41,7 +41,7 @@ export async function stopTimeline () {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {(event: import('@appium/types').StringRecord) => any} listener
  * @returns {void}
  */
@@ -52,7 +52,7 @@ export function startConsole (listener) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @returns {void}
  */
 export function stopConsole () {
@@ -62,7 +62,7 @@ export function stopConsole () {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {(event: import('@appium/types').StringRecord) => any} listener
  * @returns {void}
  */
@@ -72,7 +72,7 @@ export function startNetwork (listener) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @returns {void}
  */
 export function stopNetwork () {
@@ -82,7 +82,7 @@ export function stopNetwork () {
 
 // Potentially this does not work for mobile safari
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {string} value
  * @returns {Promise<any>}
  */
@@ -96,7 +96,7 @@ export async function overrideUserAgent (value) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {number} [timeoutMs=GARBAGE_COLLECT_TIMEOUT_MS]
  * @returns {Promise<void>}
  */
@@ -126,3 +126,7 @@ export async function garbageCollect (timeoutMs = GARBAGE_COLLECT_TIMEOUT_MS) {
     }
   }
 }
+
+/**
+ * @typedef {import('../remote-debugger').RemoteDebugger} RemoteDebugger
+ */

package/lib/mixins/navigate.js

@@ -21,7 +21,7 @@ const PAGE_LOAD_STRATEGY = {
 };
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @returns {void}
  */
 export function frameDetached () {
@@ -29,7 +29,7 @@ export function frameDetached () {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @returns {void}
  */
 export function cancelPageLoad () {
@@ -43,7 +43,8 @@ export function cancelPageLoad () {
 /**
  * Return if current readState can be handles as page load completes
  * for the given page load strategy.
- * @this {import('../remote-debugger').RemoteDebugger}
+ *
+ * @this {RemoteDebugger}
  * @param {string} readyState
  * @returns {boolean}
  */
@@ -63,7 +64,7 @@ export function isPageLoadingCompleted (readyState) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {timing.Timer?} [startPageLoadTimer]
  * @returns {Promise<void>}
  */
@@ -132,7 +133,7 @@ export async function waitForDom (startPageLoadTimer) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {number} [timeoutMs]
  * @returns {Promise<boolean>}
  */
@@ -156,7 +157,7 @@ export async function checkPageIsReady (timeoutMs) {
 }
 
 /**
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {string} url
  * @returns {Promise<void>}
  */
@@ -280,3 +281,7 @@ export async function navToUrl (url) {
     throw err;
   }
 }
+
+/**
+ * @typedef {import('../remote-debugger').RemoteDebugger} RemoteDebugger
+ */

package/lib/mixins/screenshot.js

@@ -1,6 +1,6 @@
 /**
  * Capture a rect of the page or by default the viewport
- * @this {import('../remote-debugger').RemoteDebugger}
+ * @this {RemoteDebugger}
  * @param {ScreenshotCaptureOptions} [opts={}]  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
@@ -32,3 +32,7 @@ export async function captureScreenshot(opts = {}) {
  * @property {import('@appium/types').Rect | null} [rect=null]
  * @property {"Viewport" | "Page"} [coordinateSystem="Viewport"]
  */
+
+/**
+ * @typedef {import('../remote-debugger').RemoteDebugger} RemoteDebugger
+ */

package/lib/remote-debugger.js

@@ -24,9 +24,9 @@ export class RemoteDebugger extends EventEmitter {
   // properties
   /** @type {string[]|undefined} */
   _skippedApps;
-  /** @type {Record<string, any>} */
+  /** @type {import('@appium/types').StringRecord<Function[]>} */
   _clientEventListeners;
-  /** @type {Record<string, any>} */
+  /** @type {import('./types').AppDict} */
   appDict;
   /** @type {string|null|undefined} */
   appIdKey;

package/lib/types.ts

@@ -0,0 +1,39 @@
+import type { StringRecord } from '@appium/types';
+import type B from 'bluebird';
+
+export interface DeferredPromise {
+  promise: B<any>;
+  resolve: (...args: any[]) => void;
+  reject: (err?: Error) => void;
+}
+
+export interface AppInfo {
+  id: string;
+  isProxy: boolean;
+  name: string;
+  bundleId: string;
+  hostId?: string;
+  isActive: boolean;
+  isAutomationEnabled: boolean | string;
+  pageArray?: Page[];
+}
+
+export interface AppPage {
+  appIdKey: string;
+  pageDict: Page;
+}
+
+export interface App {
+  id: string;
+  bundleId: string;
+}
+
+export interface Page {
+  url: string;
+  title: string;
+  id: number | string;
+  isKey: boolean;
+  bundleId?: string;
+}
+
+export type AppDict = StringRecord<AppInfo>;