chore: Add more type declarations (#886)

Author: mykola-mokhnach

lib/check-dependencies.js

@@ -3,6 +3,7 @@ import _ from 'lodash';
 import { exec } from 'teen_process';
 import path from 'path';
 import XcodeBuild from './xcodebuild';
+import xcode from 'appium-xcode';
 import {
   WDA_SCHEME, SDK_SIMULATOR, WDA_RUNNER_APP
 } from './constants';
@@ -22,23 +23,29 @@ async function buildWDASim () {
 }
 
 // eslint-disable-next-line require-await
-async function checkForDependencies () {
+export async function checkForDependencies () {
   log.debug('Dependencies are up to date');
   return false;
 }
 
-async function bundleWDASim (xcodebuild) {
+/**
+ *
+ * @param {XcodeBuild} xcodebuild
+ * @returns {Promise<string>}
+ */
+export async function bundleWDASim (xcodebuild) {
   if (xcodebuild && !_.isFunction(xcodebuild.retrieveDerivedDataPath)) {
-    xcodebuild = new XcodeBuild('', {});
+    xcodebuild = new XcodeBuild(/** @type {import('appium-xcode').XcodeVersion} */ (await xcode.getVersion(true)), {});
   }
 
   const derivedDataPath = await xcodebuild.retrieveDerivedDataPath();
+  if (!derivedDataPath) {
+    throw new Error('Cannot retrieve the path to the Xcode derived data folder');
+  }
   const wdaBundlePath = path.join(derivedDataPath, 'Build', 'Products', 'Debug-iphonesimulator', WDA_RUNNER_APP);
   if (await fs.exists(wdaBundlePath)) {
     return wdaBundlePath;
   }
   await buildWDASim();
   return wdaBundlePath;
 }
-
-export { checkForDependencies, bundleWDASim };

lib/webdriveragent.js

@@ -27,7 +27,19 @@ const WDA_CF_BUNDLE_NAME = 'WebDriverAgentRunner-Runner';
 const SHARED_RESOURCES_GUARD = new AsyncLock();
 const RECENT_MODULE_VERSION_ITEM_NAME = 'recentWdaModuleVersion';
 
-class WebDriverAgent {
+export class WebDriverAgent {
+  /** @type {string} */
+  bootstrapPath;
+
+  /** @type {string} */
+  agentPath;
+
+  /**
+   * @param {import('appium-xcode').XcodeVersion} xcodeVersion
+   * // TODO: make args typed
+   * @param {import('@appium/types').StringRecord} [args={}]
+   * @param {import('@appium/types').AppiumLogger?} [log=null]
+   */
   constructor (xcodeVersion, args = {}, log = null) {
     this.xcodeVersion = xcodeVersion;
 
@@ -123,6 +135,10 @@ class WebDriverAgent {
     return `${this.updatedWDABundleId ? this.updatedWDABundleId : WDA_RUNNER_BUNDLE_ID}${this.updatedWDABundleIdSuffix}`;
   }
 
+  /**
+   * @param {string} [bootstrapPath]
+   * @param {string} [agentPath]
+   */
   setWDAPaths (bootstrapPath, agentPath) {
     // allow the user to specify a place for WDA. This is undocumented and
     // only here for the purposes of testing development of WDA
@@ -134,8 +150,11 @@ class WebDriverAgent {
     this.log.info(`Using WDA agent: '${this.agentPath}'`);
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async cleanupObsoleteProcesses () {
-    const obsoletePids = await getPIDsListeningOnPort(this.url.port,
+    const obsoletePids = await getPIDsListeningOnPort(/** @type {string} */ (this.url.port),
       (cmdLine) => cmdLine.includes('/WebDriverAgentRunner') &&
         !cmdLine.toLowerCase().includes(this.device.udid.toLowerCase()));
 
@@ -164,6 +183,9 @@ class WebDriverAgent {
     return !!(await this.getStatus());
   }
 
+  /**
+   * @returns {string}
+   */
   get basePath () {
     if (this.url.path === '/') {
       return '';
@@ -243,6 +265,8 @@ class WebDriverAgent {
    * Uninstall WDAs from the test device.
    * Over Xcode 11, multiple WDA can be in the device since Xcode 11 generates different WDA.
    * Appium does not expect multiple WDAs are running on a device.
+   *
+   * @returns {Promise<void>}
    */
   async uninstall () {
     try {
@@ -476,6 +500,9 @@ class WebDriverAgent {
     return await this.xcodebuild.start();
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async startWithIDB () {
     this.log.info('Will launch WDA with idb instead of xcodebuild since the corresponding flag is enabled');
     const {wdaBundleId, testBundleId} = await this.prepareWDA();
@@ -490,6 +517,11 @@ class WebDriverAgent {
     return await this.idb.runXCUITest(wdaBundleId, wdaBundleId, testBundleId, {env});
   }
 
+  /**
+   *
+   * @param {string} wdaBundlePath
+   * @returns {Promise<string>}
+   */
   async parseBundleId (wdaBundlePath) {
     const infoPlistPath = path.join(wdaBundlePath, 'Info.plist');
     const infoPlist = await plist.parsePlist(await fs.readFile(infoPlistPath));
@@ -499,6 +531,9 @@ class WebDriverAgent {
     return infoPlist.CFBundleIdentifier;
   }
 
+  /**
+   * @returns {Promise<{wdaBundleId: string, testBundleId: string, wdaBundlePath: string}>}
+   */
   async prepareWDA () {
     const wdaBundlePath = this.wdaBundlePath || await this.fetchWDABundle();
     const wdaBundleId = await this.parseBundleId(wdaBundlePath);
@@ -509,9 +544,12 @@ class WebDriverAgent {
     return {wdaBundleId, testBundleId, wdaBundlePath};
   }
 
+  /**
+   * @returns {Promise<string>}
+   */
   async fetchWDABundle () {
     if (!this.derivedDataPath) {
-      return await bundleWDASim(this.xcodebuild);
+      return await bundleWDASim(/** @type {XcodeBuild} */ (this.xcodebuild));
     }
     const wdaBundlePaths = await fs.glob(`${this.derivedDataPath}/**/*${WDA_RUNNER_APP}/`, {
       absolute: true,
@@ -522,14 +560,21 @@ class WebDriverAgent {
     return wdaBundlePaths[0];
   }
 
+  /**
+   * @returns {Promise<boolean>}
+   */
   async isSourceFresh () {
     const existsPromises = [
       'Resources',
       `Resources${path.sep}WebDriverAgent.bundle`,
-    ].map((subPath) => fs.exists(path.resolve(this.bootstrapPath, subPath)));
+    ].map((subPath) => fs.exists(path.resolve(/** @type {String} */ (this.bootstrapPath), subPath)));
     return (await B.all(existsPromises)).some((v) => v === false);
   }
 
+  /**
+   * @param {string} sessionId
+   * @returns {void}
+   */
   setupProxies (sessionId) {
     const proxyOpts = {
       log: this.log,
@@ -547,6 +592,9 @@ class WebDriverAgent {
     this.noSessionProxy = new NoSessionProxy(proxyOpts);
   }
 
+  /**
+   * @returns {Promise<void>}
+   */
   async quit () {
     if (this.usePreinstalledWDA) {
       this.log.info('Stopping the XCTest session');
@@ -582,6 +630,9 @@ class WebDriverAgent {
     }
   }
 
+  /**
+   * @returns {import('url').UrlWithStringQuery}
+   */
   get url () {
     if (!this._url) {
       if (this.webDriverAgentUrl) {
@@ -595,30 +646,44 @@ class WebDriverAgent {
     return this._url;
   }
 
+  /**
+   * @param {string} _url
+   * @returns {void}
+   */
   set url (_url) {
     this._url = url.parse(_url);
   }
 
+  /**
+   * @returns {boolean}
+   */
   get fullyStarted () {
     return this.started;
   }
 
+  /**
+   * @param {boolean} started
+   * @returns {void}s
+   */
   set fullyStarted (started) {
     this.started = started ?? false;
   }
 
+  /**
+   * @returns {Promise<string|undefined>}
+   */
   async retrieveDerivedDataPath () {
     if (this.canSkipXcodebuild) {
       return;
     }
-    // @ts-ignore xcodebuild should be set
-    return await this.xcodebuild.retrieveDerivedDataPath();
+    return await /** @type {XcodeBuild} */ (this.xcodebuild).retrieveDerivedDataPath();
   }
 
   /**
    * Reuse running WDA if it has the same bundle id with updatedWDABundleId.
    * Or reuse it if it has the default id without updatedWDABundleId.
    * Uninstall it if the method faces an exception for the above situation.
+   * @returns {Promise<void>}
    */
   async setupCaching () {
     const status = await this.getStatus();
@@ -660,6 +725,7 @@ class WebDriverAgent {
 
   /**
    * Quit and uninstall running WDA.
+   * @returns {Promise<void>}
    */
   async quitAndUninstall () {
     await this.quit();
@@ -668,4 +734,3 @@ class WebDriverAgent {
 }
 
 export default WebDriverAgent;
-export { WebDriverAgent };