chore: Improve various type declarations (#397)

appium · Aug 1, 2024 · 93ed417 · 93ed417
1 parent e959dbb
commit 93ed417
Show file tree

Hide file tree

Showing 14 changed files with 373 additions and 277 deletions.
diff --git a/lib/mixins/connect.js b/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
  */
diff --git a/lib/mixins/cookies.js b/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
+ */
diff --git a/lib/mixins/events.js b/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
+ */
diff --git a/lib/mixins/execute.js b/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
+ */