appium-webdriveragent 10.5.4 → 11.0.0

package/lib/{webdriveragent.js → webdriveragent.ts}

@@ -1,11 +1,12 @@
 import { waitForCondition } from 'asyncbox';
 import _ from 'lodash';
-import path from 'path';
-import url from 'url';
+import path from 'node:path';
+import url from 'node:url';
 import B from 'bluebird';
 import { JWProxy } from '@appium/base-driver';
 import { fs, util, plist } from '@appium/support';
-import defaultLogger from './logger';
+import type { AppiumLogger, StringRecord } from '@appium/types';
+import { log as defaultLogger } from './logger';
 import { NoSessionProxy } from './no-session-proxy';
 import {
   getWDAUpgradeTimestamp, resetTestProcesses, getPIDsListeningOnPort, BOOTSTRAP_PATH
@@ -20,6 +21,7 @@ import {
 } from './constants';
 import {Xctest} from 'appium-ios-device';
 import {strongbox} from '@appium/strongbox';
+import type { WebDriverAgentArgs, AppleDevice } from './types';
 
 const WDA_LAUNCH_TIMEOUT = 60 * 1000;
 const WDA_AGENT_PORT = 8100;
@@ -28,23 +30,46 @@ const SHARED_RESOURCES_GUARD = new AsyncLock();
 const RECENT_MODULE_VERSION_ITEM_NAME = 'recentWdaModuleVersion';
 
 export class WebDriverAgent {
-  /** @type {string} */
-  bootstrapPath;
-
-  /** @type {string} */
-  agentPath;
-
-  /** @type {any} @deprecated for removal */
-  idb;
+  bootstrapPath: string;
+  agentPath: string;
+  readonly args: WebDriverAgentArgs;
+  private readonly log: AppiumLogger;
+  readonly device: AppleDevice;
+  readonly platformVersion?: string;
+  readonly platformName?: string;
+  readonly iosSdkVersion?: string;
+  readonly host?: string;
+  readonly isRealDevice: boolean;
+  private readonly wdaBundlePath?: string;
+  private readonly wdaLocalPort?: number;
+  readonly wdaRemotePort: number;
+  readonly wdaBaseUrl: string;
+  readonly wdaBindingIP?: string;
+  private readonly prebuildWDA?: boolean;
+  webDriverAgentUrl?: string;
+  started: boolean;
+  private readonly wdaConnectionTimeout?: number;
+  private readonly useXctestrunFile?: boolean;
+  private readonly usePrebuiltWDA?: boolean;
+  private readonly derivedDataPath?: string;
+  private readonly mjpegServerPort?: number;
+  updatedWDABundleId?: string;
+  private readonly wdaLaunchTimeout: number;
+  private readonly usePreinstalledWDA?: boolean;
+  private xctestApiClient?: Xctest | null;
+  private readonly updatedWDABundleIdSuffix: string;
+  private _xcodebuild?: XcodeBuild | null;
+  noSessionProxy?: NoSessionProxy;
+  jwproxy?: JWProxy;
+  proxyReqRes?: any;
+  private _url?: url.UrlWithStringQuery;
 
   /**
-   * @param {import('appium-xcode').XcodeVersion | undefined} xcodeVersion @deprecated Will be removed as no actual usage.
-   * @param {import('./types').WebDriverAgentArgs} args
-   * @param {import('@appium/types').AppiumLogger?} [log=null]
+   * Creates a new WebDriverAgent instance.
+   * @param args - Configuration arguments for WebDriverAgent
+   * @param log - Optional logger instance
    */
-  constructor (xcodeVersion, args, log = null) {
-    this.xcodeVersion = xcodeVersion;
-
+  constructor (args: WebDriverAgentArgs, log: AppiumLogger | null = null) {
     this.args = _.clone(args);
     this.log = log ?? defaultLogger;
 
@@ -54,8 +79,6 @@ export class WebDriverAgent {
     this.iosSdkVersion = args.iosSdkVersion;
     this.host = args.host;
     this.isRealDevice = !!args.realDevice;
-    /** @deprecated We'll stop supporting idb */
-    this.idb = args.device.idb;
     this.wdaBundlePath = args.wdaBundlePath;
 
     this.setWDAPaths(args.bootstrapPath, args.agentPath);
@@ -88,9 +111,9 @@ export class WebDriverAgent {
     this.xctestApiClient = null;
     this.updatedWDABundleIdSuffix = args.updatedWDABundleIdSuffix ?? DEFAULT_TEST_BUNDLE_SUFFIX;
 
-    this.xcodebuild = this.canSkipXcodebuild
+    this._xcodebuild = this.canSkipXcodebuild
     ? null
-    : new XcodeBuild(this.xcodeVersion, this.device, {
+    : new XcodeBuild(this.device, {
         platformVersion: this.platformVersion,
         platformName: this.platformName,
         iosSdkVersion: this.iosSdkVersion,
@@ -120,46 +143,44 @@ export class WebDriverAgent {
 
   /**
    * Return true if the session does not need xcodebuild.
-   * @returns {boolean} Whether the session needs/has xcodebuild.
+   * @returns Whether the session needs/has xcodebuild.
    */
-  get canSkipXcodebuild () {
+  get canSkipXcodebuild (): boolean {
     // Use this.args.webDriverAgentUrl to guarantee
     // the capabilities set gave the `appium:webDriverAgentUrl`.
     return this.usePreinstalledWDA || !!this.args.webDriverAgentUrl;
   }
 
+  /**
+   * Get the xcodebuild instance. Throws if not initialized.
+   * @returns The XcodeBuild instance
+   * @throws Error if xcodebuild is not available
+   */
+  get xcodebuild (): XcodeBuild {
+    if (!this._xcodebuild) {
+      throw new Error('xcodebuild is not available');
+    }
+    return this._xcodebuild;
+  }
+
   /**
    * Return bundle id for WebDriverAgent to launch the WDA.
    * The primary usage is with 'this.usePreinstalledWDA'.
    * It adds `.xctrunner` as suffix by default but 'this.updatedWDABundleIdSuffix'
    * lets skip it.
    *
-   * @returns {string} Bundle ID for Xctest.
+   * @returns Bundle ID for Xctest.
    */
-  get bundleIdForXctest () {
+  get bundleIdForXctest (): string {
     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
-    this.bootstrapPath = bootstrapPath || BOOTSTRAP_PATH;
-    this.log.info(`Using WDA path: '${this.bootstrapPath}'`);
-
-    // for backward compatibility we need to be able to specify agentPath too
-    this.agentPath = agentPath || path.resolve(this.bootstrapPath, 'WebDriverAgent.xcodeproj');
-    this.log.info(`Using WDA agent: '${this.agentPath}'`);
-  }
-
-  /**
-   * @returns {Promise<void>}
+   * Cleans up obsolete cached processes from previous WDA sessions
+   * that are listening on the same port but belong to different devices.
    */
-  async cleanupObsoleteProcesses () {
-    const obsoletePids = await getPIDsListeningOnPort(/** @type {string} */ (this.url.port),
+  async cleanupObsoleteProcesses (): Promise<void> {
+    const obsoletePids = await getPIDsListeningOnPort(this.url.port as string,
       (cmdLine) => cmdLine.includes('/WebDriverAgentRunner') &&
         !cmdLine.toLowerCase().includes(this.device.udid.toLowerCase()));
 
@@ -173,268 +194,23 @@ export class WebDriverAgent {
       `from previous WDA sessions. Cleaning them up`);
     try {
       await exec('kill', obsoletePids);
-    } catch (e) {
+    } catch (e: any) {
       this.log.warn(`Failed to kill obsolete cached process${obsoletePids.length === 1 ? '' : 'es'} '${obsoletePids}'. ` +
         `Original error: ${e.message}`);
     }
   }
 
   /**
-   * Return boolean if WDA is running or not
-   * @return {Promise<boolean>} True if WDA is running
-   * @throws {Error} If there was invalid response code or body
+   * Gets the base path for the WebDriverAgent URL.
+   * @returns The base path (empty string if root path)
    */
-  async isRunning () {
-    return !!(await this.getStatus());
-  }
-
-  /**
-   * @returns {string}
-   */
-  get basePath () {
+  get basePath (): string {
     if (this.url.path === '/') {
       return '';
     }
     return this.url.path || '';
   }
 
-  /**
-   * Return current running WDA's status like below
-   * {
-   *   "state": "success",
-   *   "os": {
-   *     "name": "iOS",
-   *     "version": "11.4",
-   *     "sdkVersion": "11.3"
-   *   },
-   *   "ios": {
-   *     "simulatorVersion": "11.4",
-   *     "ip": "172.254.99.34"
-   *   },
-   *   "build": {
-   *     "time": "Jun 24 2018 17:08:21",
-   *     "productBundleIdentifier": "com.facebook.WebDriverAgentRunner"
-   *   }
-   * }
-   *
-   * @param {number} [timeoutMs=0] If the given timeoutMs is zero or negative number,
-   *                               this function will return the response of `/status` immediately. If the given timeoutMs,
-   *                               this function will try to get the response of `/status` up to the timeoutMs.
-   * @return {Promise<import('@appium/types').StringRecord|null>} State Object
-   * @throws {Error} If there was an error within timeoutMs timeout.
-   *                 No error is raised if zero or negative number for the timeoutMs.
-   */
-  async getStatus (timeoutMs = 0) {
-    const noSessionProxy = new NoSessionProxy({
-      server: this.url.hostname,
-      port: this.url.port,
-      base: this.basePath,
-      timeout: 3000,
-    });
-
-    const sendGetStatus = async () => await /** @type import('@appium/types').StringRecord */ (noSessionProxy.command('/status', 'GET'));
-
-    if (_.isNil(timeoutMs) || timeoutMs <= 0) {
-      try {
-        return await sendGetStatus();
-      } catch (err) {
-        this.log.debug(`WDA is not listening at '${this.url.href}'. Original error:: ${err.message}`);
-        return null;
-      }
-    }
-
-    let lastError = null;
-    let status = null;
-    try {
-      await waitForCondition(async () => {
-        try {
-          status = await sendGetStatus();
-          return true;
-        } catch (err) {
-          lastError = err;
-        }
-        return false;
-      }, {
-        waitMs: timeoutMs,
-        intervalMs: 300,
-      });
-    } catch (err) {
-      this.log.debug(`Failed to get the status endpoint in ${timeoutMs} ms. ` +
-        `The last error while accessing ${this.url.href}: ${lastError}. Original error:: ${err.message}.`);
-      throw new Error(`WDA was not ready in ${timeoutMs} ms.`);
-    }
-    return status;
-  }
-
-  /**
-   * 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 {
-      const bundleIds = await this.device.getUserInstalledBundleIdsByBundleName(WDA_CF_BUNDLE_NAME);
-      if (_.isEmpty(bundleIds)) {
-        this.log.debug('No WDAs on the device.');
-        return;
-      }
-
-      this.log.debug(`Uninstalling WDAs: '${bundleIds}'`);
-      for (const bundleId of bundleIds) {
-        await this.device.removeApp(bundleId);
-      }
-    } catch (e) {
-      this.log.debug(e);
-      this.log.warn(`WebDriverAgent uninstall failed. Perhaps, it is already uninstalled? ` +
-        `Original error: ${e.message}`);
-    }
-  }
-
-  async _cleanupProjectIfFresh () {
-    if (this.canSkipXcodebuild) {
-      return;
-    }
-
-    const packageInfo = JSON.parse(await fs.readFile(path.join(BOOTSTRAP_PATH, 'package.json'), 'utf8'));
-    const box = strongbox(packageInfo.name);
-    let boxItem = box.getItem(RECENT_MODULE_VERSION_ITEM_NAME);
-    if (!boxItem) {
-      const timestampPath = path.resolve(process.env.HOME ?? '', WDA_UPGRADE_TIMESTAMP_PATH);
-      if (await fs.exists(timestampPath)) {
-        // TODO: It is probably a bit ugly to hardcode the recent version string,
-        // TODO: hovewer it should do the job as a temporary transition trick
-        // TODO: to switch from a hardcoded file path to the strongbox usage.
-        try {
-          boxItem = await box.createItemWithValue(RECENT_MODULE_VERSION_ITEM_NAME, '5.0.0');
-        } catch (e) {
-          this.log.warn(`The actual module version cannot be persisted: ${e.message}`);
-          return;
-        }
-      } else {
-        this.log.info('There is no need to perform the project cleanup. A fresh install has been detected');
-        try {
-          await box.createItemWithValue(RECENT_MODULE_VERSION_ITEM_NAME, packageInfo.version);
-        } catch (e) {
-          this.log.warn(`The actual module version cannot be persisted: ${e.message}`);
-        }
-        return;
-      }
-    }
-
-    let recentModuleVersion = await boxItem.read();
-    try {
-      recentModuleVersion = util.coerceVersion(recentModuleVersion, true);
-    } catch (e) {
-      this.log.warn(`The persisted module version string has been damaged: ${e.message}`);
-      this.log.info(`Updating it to '${packageInfo.version}' assuming the project clenup is not needed`);
-      await boxItem.write(packageInfo.version);
-      return;
-    }
-
-    if (util.compareVersions(recentModuleVersion, '>=', packageInfo.version)) {
-      this.log.info(
-        `WebDriverAgent does not need a cleanup. The project sources are up to date ` +
-        `(${recentModuleVersion} >= ${packageInfo.version})`
-      );
-      return;
-    }
-
-    this.log.info(
-      `Cleaning up the WebDriverAgent project after the module upgrade has happened ` +
-      `(${recentModuleVersion} < ${packageInfo.version})`
-    );
-    try {
-      // @ts-ignore xcodebuild should be set
-      await this.xcodebuild.cleanProject();
-      await boxItem.write(packageInfo.version);
-    } catch (e) {
-      this.log.warn(`Cannot perform WebDriverAgent project cleanup. Original error: ${e.message}`);
-    }
-  }
-
-
-  /**
-   * @typedef {Object} LaunchWdaViaDeviceCtlOptions
-   * @property {Record<string, string|number>} [env] environment variables for the launching WDA process
-   */
-
-  /**
-   * Launch WDA with preinstalled package with 'xcrun devicectl device process launch'.
-   * The WDA package must be prepared properly like published via
-   * https://github.com/appium/WebDriverAgent/releases
-   * with proper sign for this case.
-   *
-   * When we implement launching XCTest service via appium-ios-device,
-   * this implementation can be replaced with it.
-   *
-   * @param {LaunchWdaViaDeviceCtlOptions} [opts={}] launching WDA with devicectl command options.
-   * @return {Promise<void>}
-   */
-  async _launchViaDevicectl(opts = {}) {
-    const {env} = opts;
-
-    await this.device.devicectl.launchApp(
-      this.bundleIdForXctest, { env, terminateExisting: true }
-    );
-  }
-
-  /**
-   * Launch WDA with preinstalled package without xcodebuild.
-   * @param {string} sessionId Launch WDA and establish the session with this sessionId
-   * @return {Promise<import('@appium/types').StringRecord|null>} State Object
-   * @throws {Error} If there was an error within timeoutMs timeout.
-   *                 No error is raised if zero or negative number for the timeoutMs.
-   */
-  async launchWithPreinstalledWDA(sessionId) {
-    const xctestEnv = {
-      USE_PORT: this.wdaLocalPort || WDA_AGENT_PORT,
-      WDA_PRODUCT_BUNDLE_IDENTIFIER: this.bundleIdForXctest
-    };
-    if (this.mjpegServerPort) {
-      xctestEnv.MJPEG_SERVER_PORT = this.mjpegServerPort;
-    }
-    if (this.wdaBindingIP) {
-      xctestEnv.USE_IP = this.wdaBindingIP;
-    }
-    this.log.info('Launching WebDriverAgent on the device without xcodebuild');
-    if (this.isRealDevice) {
-      // Current method to launch WDA process can be done via 'xcrun devicectl',
-      // but it has limitation about the WDA preinstalled package.
-      // https://github.com/appium/appium/issues/19206#issuecomment-2014182674
-      if (this.platformVersion && util.compareVersions(this.platformVersion, '>=', '17.0')) {
-        await this._launchViaDevicectl({env: xctestEnv});
-      } else {
-        this.xctestApiClient = new Xctest(this.device.udid, this.bundleIdForXctest, null, {env: xctestEnv});
-        await this.xctestApiClient.start();
-      }
-    } else {
-      await this.device.simctl.exec('launch', {
-        args: [
-          '--terminate-running-process',
-          this.device.udid,
-          this.bundleIdForXctest,
-        ],
-        env: xctestEnv,
-      });
-    }
-
-    this.setupProxies(sessionId);
-    let status;
-    try {
-      status = await this.getStatus(this.wdaLaunchTimeout);
-    } catch {
-      throw new Error(
-        `Failed to start the preinstalled WebDriverAgent in ${this.wdaLaunchTimeout} ms. ` +
-        `The WebDriverAgent might not be properly built or the device might be locked. ` +
-        `The 'appium:wdaLaunchTimeout' capability modifies the timeout.`
-      );
-    }
-    this.started = true;
-    return status;
-  }
-
   /**
    * Return current running WDA's status like below after launching WDA
    * {
@@ -454,11 +230,9 @@ export class WebDriverAgent {
    *   }
    * }
    *
-   * @param {string} sessionId Launch WDA and establish the session with this sessionId
-   * @return {Promise<any?>} State Object
-   * @throws {Error} If there was invalid response code or body
+   * @param sessionId Launch WDA and establish the session with this sessionId
    */
-  async launch (sessionId) {
+  async launch (sessionId: string): Promise<StringRecord | null> {
     if (this.webDriverAgentUrl) {
       this.log.info(`Using provided WebdriverAgent at '${this.webDriverAgentUrl}'`);
       this.url = this.webDriverAgentUrl;
@@ -481,7 +255,7 @@ export class WebDriverAgent {
 
     // useXctestrunFile and usePrebuiltWDA use existing dependencies
     // It depends on user side
-    if (this.idb || this.useXctestrunFile || this.usePrebuiltWDA) {
+    if (this.useXctestrunFile || this.usePrebuiltWDA) {
       this.log.info('Skipped WDA project cleanup according to the provided capabilities');
     } else {
       const synchronizationKey = path.normalize(this.bootstrapPath);
@@ -492,77 +266,43 @@ export class WebDriverAgent {
     // We need to provide WDA local port, because it might be occupied
     await resetTestProcesses(this.device.udid, !this.isRealDevice);
 
-    if (this.idb) {
-      return await this.startWithIDB();
+    if (!this.noSessionProxy) {
+      throw new Error('noSessionProxy is not available');
     }
-
-    // @ts-ignore xcodebuild should be set
     await this.xcodebuild.init(this.noSessionProxy);
 
     // Start the xcodebuild process
     if (this.prebuildWDA) {
-      // @ts-ignore xcodebuild should be set
       await this.xcodebuild.prebuild();
     }
-    // @ts-ignore xcodebuild should be set
-    return await this.xcodebuild.start();
+    return await this.xcodebuild.start() as StringRecord | null;
   }
 
   /**
-   * @deprecated We'll stop supporting idb. Deprecated for removal.
-   * @returns {Promise<void>}
+   * Checks if the WebDriverAgent source is fresh by verifying
+   * that required resource files exist.
+   * @returns `true` if source is fresh (all required files exist), `false` otherwise
    */
-  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();
-    const env = {
-      USE_PORT: this.wdaRemotePort,
-      WDA_PRODUCT_BUNDLE_IDENTIFIER: this.bundleIdForXctest,
-    };
-    if (this.mjpegServerPort) {
-      env.MJPEG_SERVER_PORT = this.mjpegServerPort;
-    }
-    if (this.wdaBindingIP) {
-      env.USE_IP = this.wdaBindingIP;
-    }
-
-    return await this.idb.runXCUITest(wdaBundleId, wdaBundleId, testBundleId, {env});
+  async isSourceFresh (): Promise<boolean> {
+    const existsPromises = [
+      'Resources',
+      `Resources${path.sep}WebDriverAgent.bundle`,
+    ].map((subPath) => fs.exists(path.resolve(this.bootstrapPath, subPath)));
+    return (await B.all(existsPromises)).some((v) => v === false);
   }
 
-  /**
-   *
-   * @param {string} wdaBundlePath
-   * @returns {Promise<string>}
-   */
-  async parseBundleId (wdaBundlePath) {
+  private async parseBundleId (wdaBundlePath: string): Promise<string> {
     const infoPlistPath = path.join(wdaBundlePath, 'Info.plist');
     const infoPlist = await plist.parsePlist(await fs.readFile(infoPlistPath));
     if (!infoPlist.CFBundleIdentifier) {
       throw new Error(`Could not find bundle id in '${infoPlistPath}'`);
     }
-    return infoPlist.CFBundleIdentifier;
+    return infoPlist.CFBundleIdentifier as string;
   }
 
-  /**
-   * @deprecated We'll stop using idb
-   * @returns {Promise<{wdaBundleId: string, testBundleId: string, wdaBundlePath: string}>}
-   */
-  async prepareWDA () {
-    const wdaBundlePath = this.wdaBundlePath || await this.fetchWDABundle();
-    const wdaBundleId = await this.parseBundleId(wdaBundlePath);
-    if (!await this.device.isAppInstalled(wdaBundleId)) {
-      await this.device.installApp(wdaBundlePath);
-    }
-    const testBundleId = await this.idb.installXCTestBundle(path.join(wdaBundlePath, 'PlugIns', 'WebDriverAgentRunner.xctest'));
-    return {wdaBundleId, testBundleId, wdaBundlePath};
-  }
-
-  /**
-   * @returns {Promise<string>}
-   */
-  async fetchWDABundle () {
+  private async fetchWDABundle (): Promise<string> {
     if (!this.derivedDataPath) {
-      return await bundleWDASim(/** @type {XcodeBuild} */ (this.xcodebuild));
+      return await bundleWDASim(this.xcodebuild);
     }
     const wdaBundlePaths = await fs.glob(`${this.derivedDataPath}/**/*${WDA_RUNNER_APP}/`, {
       absolute: true,
@@ -573,23 +313,8 @@ export class WebDriverAgent {
     return wdaBundlePaths[0];
   }
 
-  /**
-   * @returns {Promise<boolean>}
-   */
-  async isSourceFresh () {
-    const existsPromises = [
-      'Resources',
-      `Resources${path.sep}WebDriverAgent.bundle`,
-    ].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 = {
+  private setupProxies (sessionId: string): void {
+    const proxyOpts: any = {
       log: this.log,
       server: this.url.hostname ?? undefined,
       port: parseInt(this.url.port ?? '', 10) || undefined,
@@ -610,9 +335,10 @@ export class WebDriverAgent {
   }
 
   /**
-   * @returns {Promise<void>}
+   * Stops the WebDriverAgent session and cleans up resources.
+   * Handles both preinstalled WDA and xcodebuild-based sessions.
    */
-  async quit () {
+  async quit (): Promise<void> {
     if (this.usePreinstalledWDA) {
       this.log.info('Stopping the XCTest session');
       if (this.xctestApiClient) {
@@ -621,14 +347,16 @@ export class WebDriverAgent {
       } else {
         try {
           await this.device.simctl.terminateApp(this.bundleIdForXctest);
-        } catch (e) {
+        } catch (e: any) {
           this.log.warn(e.message);
         }
       }
     } else if (!this.args.webDriverAgentUrl) {
       this.log.info('Shutting down sub-processes');
-      await this.xcodebuild?.quit();
-      await this.xcodebuild?.reset();
+      if (this._xcodebuild) {
+        await this.xcodebuild.quit();
+        await this.xcodebuild.reset();
+      }
     } else {
       this.log.debug('Do not stop xcodebuild nor XCTest session ' +
         'since the WDA session is managed by outside this driver.');
@@ -648,9 +376,12 @@ export class WebDriverAgent {
   }
 
   /**
-   * @returns {import('url').UrlWithStringQuery}
+   * Gets the WebDriverAgent URL.
+   * Constructs the URL from webDriverAgentUrl if provided, otherwise
+   * builds it from wdaBaseUrl, wdaBindingIP, and wdaLocalPort.
+   * @returns The parsed URL object
    */
-  get url () {
+  get url (): url.UrlWithStringQuery {
     if (!this._url) {
       if (this.webDriverAgentUrl) {
         this._url = url.parse(this.webDriverAgentUrl);
@@ -664,46 +395,47 @@ export class WebDriverAgent {
   }
 
   /**
-   * @param {string} _url
-   * @returns {void}
+   * Sets the WebDriverAgent URL.
+   * @param _url - The URL string to parse and set
    */
-  set url (_url) {
+  set url (_url: string) {
     this._url = url.parse(_url);
   }
 
   /**
-   * @returns {boolean}
+   * Gets whether WebDriverAgent has fully started.
+   * @returns `true` if WDA has started, `false` otherwise
    */
-  get fullyStarted () {
+  get fullyStarted (): boolean {
     return this.started;
   }
 
   /**
-   * @param {boolean} started
-   * @returns {void}s
+   * Sets whether WebDriverAgent has fully started.
+   * @param started - `true` if WDA has started, `false` otherwise
    */
-  set fullyStarted (started) {
+  set fullyStarted (started: boolean) {
     this.started = started ?? false;
   }
 
   /**
-   * @returns {Promise<string|undefined>}
+   * Retrieves the Xcode derived data path for WebDriverAgent.
+   * @returns The derived data path, or `undefined` if xcodebuild is skipped
    */
-  async retrieveDerivedDataPath () {
+  async retrieveDerivedDataPath (): Promise<string | undefined> {
     if (this.canSkipXcodebuild) {
       return;
     }
-    return await /** @type {XcodeBuild} */ (this.xcodebuild).retrieveDerivedDataPath();
+    return await 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();
+  async setupCaching (): Promise<void> {
+    const status = await this.getStatus(0);
     if (!status || !status.build) {
       this.log.debug('WDA is currently not running. There is nothing to cache');
       return;
@@ -712,7 +444,7 @@ export class WebDriverAgent {
     const {
       productBundleIdentifier,
       upgradedAt,
-    } = status.build;
+    } = status.build as any;
     // for real device
     if (util.hasValue(productBundleIdentifier) && util.hasValue(this.updatedWDABundleId) && this.updatedWDABundleId !== productBundleIdentifier) {
       this.log.info(`Will uninstall running WDA since it has different bundle id. The actual value is '${productBundleIdentifier}'.`);
@@ -742,12 +474,243 @@ export class WebDriverAgent {
 
   /**
    * Quit and uninstall running WDA.
-   * @returns {Promise<void>}
    */
-  async quitAndUninstall () {
+  async quitAndUninstall (): Promise<void> {
     await this.quit();
     await this.uninstall();
   }
-}
 
-export default WebDriverAgent;
+  private setWDAPaths (bootstrapPath?: string, agentPath?: string): void {
+    // allow the user to specify a place for WDA. This is undocumented and
+    // only here for the purposes of testing development of WDA
+    this.bootstrapPath = bootstrapPath || BOOTSTRAP_PATH;
+    this.log.info(`Using WDA path: '${this.bootstrapPath}'`);
+
+    // for backward compatibility we need to be able to specify agentPath too
+    this.agentPath = agentPath || path.resolve(this.bootstrapPath, 'WebDriverAgent.xcodeproj');
+    this.log.info(`Using WDA agent: '${this.agentPath}'`);
+  }
+
+  private async isRunning (): Promise<boolean> {
+    return !!(await this.getStatus());
+  }
+
+  /**
+   * Return current running WDA's status like below
+   * {
+   *   "state": "success",
+   *   "os": {
+   *     "name": "iOS",
+   *     "version": "11.4",
+   *     "sdkVersion": "11.3"
+   *   },
+   *   "ios": {
+   *     "simulatorVersion": "11.4",
+   *     "ip": "172.254.99.34"
+   *   },
+   *   "build": {
+   *     "time": "Jun 24 2018 17:08:21",
+   *     "productBundleIdentifier": "com.facebook.WebDriverAgentRunner"
+   *   }
+   * }
+   *
+   * @param timeoutMs If zero or negative, returns immediately. Otherwise, waits up to timeoutMs.
+   */
+  private async getStatus (timeoutMs: number = 0): Promise<StringRecord | null> {
+    const noSessionProxy = new NoSessionProxy({
+      server: this.url.hostname ?? undefined,
+      port: parseInt(this.url.port ?? '', 10) || undefined,
+      base: this.basePath,
+      timeout: 3000,
+    });
+
+    const sendGetStatus = async () => await noSessionProxy.command('/status', 'GET') as StringRecord;
+
+    if (_.isNil(timeoutMs) || timeoutMs <= 0) {
+      try {
+        return await sendGetStatus();
+      } catch (err: any) {
+        this.log.debug(`WDA is not listening at '${this.url.href}'. Original error:: ${err.message}`);
+        return null;
+      }
+    }
+
+    let lastError: any = null;
+    let status: StringRecord | null = null;
+    try {
+      await waitForCondition(async () => {
+        try {
+          status = await sendGetStatus();
+          return true;
+        } catch (err) {
+          lastError = err;
+        }
+        return false;
+      }, {
+        waitMs: timeoutMs,
+        intervalMs: 300,
+      });
+    } catch (err: any) {
+      this.log.debug(`Failed to get the status endpoint in ${timeoutMs} ms. ` +
+        `The last error while accessing ${this.url.href}: ${lastError}. Original error:: ${err.message}.`);
+      throw new Error(`WDA was not ready in ${timeoutMs} ms.`);
+    }
+    return status;
+  }
+
+  /**
+   * 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.
+   */
+  private async uninstall (): Promise<void> {
+    try {
+      const bundleIds = await this.device.getUserInstalledBundleIdsByBundleName(WDA_CF_BUNDLE_NAME);
+      if (_.isEmpty(bundleIds)) {
+        this.log.debug('No WDAs on the device.');
+        return;
+      }
+
+      this.log.debug(`Uninstalling WDAs: '${bundleIds}'`);
+      for (const bundleId of bundleIds) {
+        await this.device.removeApp(bundleId);
+      }
+    } catch (e: any) {
+      this.log.debug(e);
+      this.log.warn(`WebDriverAgent uninstall failed. Perhaps, it is already uninstalled? ` +
+        `Original error: ${e.message}`);
+    }
+  }
+
+  private async _cleanupProjectIfFresh (): Promise<void> {
+    if (this.canSkipXcodebuild) {
+      return;
+    }
+
+    const packageInfo = JSON.parse(await fs.readFile(path.join(BOOTSTRAP_PATH, 'package.json'), 'utf8'));
+    const box = strongbox(packageInfo.name);
+    let boxItem = box.getItem(RECENT_MODULE_VERSION_ITEM_NAME);
+    if (!boxItem) {
+      const timestampPath = path.resolve(process.env.HOME ?? '', WDA_UPGRADE_TIMESTAMP_PATH);
+      if (await fs.exists(timestampPath)) {
+        // TODO: It is probably a bit ugly to hardcode the recent version string,
+        // TODO: hovewer it should do the job as a temporary transition trick
+        // TODO: to switch from a hardcoded file path to the strongbox usage.
+        try {
+          boxItem = await box.createItemWithValue(RECENT_MODULE_VERSION_ITEM_NAME, '5.0.0');
+        } catch (e: any) {
+          this.log.warn(`The actual module version cannot be persisted: ${e.message}`);
+          return;
+        }
+      } else {
+        this.log.info('There is no need to perform the project cleanup. A fresh install has been detected');
+        try {
+          await box.createItemWithValue(RECENT_MODULE_VERSION_ITEM_NAME, packageInfo.version);
+        } catch (e: any) {
+          this.log.warn(`The actual module version cannot be persisted: ${e.message}`);
+        }
+        return;
+      }
+    }
+
+    let recentModuleVersion = await boxItem.read();
+    try {
+      recentModuleVersion = util.coerceVersion(recentModuleVersion, true);
+    } catch (e: any) {
+      this.log.warn(`The persisted module version string has been damaged: ${e.message}`);
+      this.log.info(`Updating it to '${packageInfo.version}' assuming the project clenup is not needed`);
+      await boxItem.write(packageInfo.version);
+      return;
+    }
+
+    if (util.compareVersions(recentModuleVersion, '>=', packageInfo.version)) {
+      this.log.info(
+        `WebDriverAgent does not need a cleanup. The project sources are up to date ` +
+        `(${recentModuleVersion} >= ${packageInfo.version})`
+      );
+      return;
+    }
+
+    this.log.info(
+      `Cleaning up the WebDriverAgent project after the module upgrade has happened ` +
+      `(${recentModuleVersion} < ${packageInfo.version})`
+    );
+    try {
+      await this.xcodebuild.cleanProject();
+      await boxItem.write(packageInfo.version);
+    } catch (e: any) {
+      this.log.warn(`Cannot perform WebDriverAgent project cleanup. Original error: ${e.message}`);
+    }
+  }
+
+  /**
+   * Launch WDA with preinstalled package with 'xcrun devicectl device process launch'.
+   * The WDA package must be prepared properly like published via
+   * https://github.com/appium/WebDriverAgent/releases
+   * with proper sign for this case.
+   *
+   * When we implement launching XCTest service via appium-ios-device,
+   * this implementation can be replaced with it.
+   *
+   * @param opts launching WDA with devicectl command options.
+   */
+  private async _launchViaDevicectl(opts: {env?: Record<string, string | number>} = {}): Promise<void> {
+    const {env} = opts;
+
+    await this.device.devicectl.launchApp(
+      this.bundleIdForXctest, { env, terminateExisting: true }
+    );
+  }
+
+  /**
+   * Launch WDA with preinstalled package without xcodebuild.
+   * @param sessionId Launch WDA and establish the session with this sessionId
+   */
+  private async launchWithPreinstalledWDA(sessionId: string): Promise<StringRecord | null> {
+    const xctestEnv: Record<string, string | number> = {
+      USE_PORT: this.wdaLocalPort || WDA_AGENT_PORT,
+      WDA_PRODUCT_BUNDLE_IDENTIFIER: this.bundleIdForXctest
+    };
+    if (this.mjpegServerPort) {
+      xctestEnv.MJPEG_SERVER_PORT = this.mjpegServerPort;
+    }
+    if (this.wdaBindingIP) {
+      xctestEnv.USE_IP = this.wdaBindingIP;
+    }
+    this.log.info('Launching WebDriverAgent on the device without xcodebuild');
+    if (this.isRealDevice) {
+      // Current method to launch WDA process can be done via 'xcrun devicectl',
+      // but it has limitation about the WDA preinstalled package.
+      // https://github.com/appium/appium/issues/19206#issuecomment-2014182674
+      if (this.platformVersion && util.compareVersions(this.platformVersion, '>=', '17.0')) {
+        await this._launchViaDevicectl({env: xctestEnv});
+      } else {
+        this.xctestApiClient = new Xctest(this.device.udid, this.bundleIdForXctest, null, {env: xctestEnv});
+        await this.xctestApiClient.start();
+      }
+    } else {
+      await this.device.simctl.exec('launch', {
+        args: [
+          '--terminate-running-process',
+          this.device.udid,
+          this.bundleIdForXctest,
+        ],
+        env: xctestEnv,
+      });
+    }
+
+    this.setupProxies(sessionId);
+    let status: StringRecord | null;
+    try {
+      status = await this.getStatus(this.wdaLaunchTimeout);
+    } catch {
+      throw new Error(
+        `Failed to start the preinstalled WebDriverAgent in ${this.wdaLaunchTimeout} ms. ` +
+        `The WebDriverAgent might not be properly built or the device might be locked. ` +
+        `The 'appium:wdaLaunchTimeout' capability modifies the timeout.`
+      );
+    }
+    this.started = true;
+    return status;
+  }
+}