@devicelab/maestro-runner-darwin-arm64 1.1.27 → 1.1.28

package/drivers/ios/WebDriverAgent/lib/webdriveragent.ts

@@ -1,76 +1,79 @@
-import { waitForCondition } from 'asyncbox';
-import _ from 'lodash';
 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 type { AppiumLogger, StringRecord } from '@appium/types';
-import { log as defaultLogger } from './logger';
-import { NoSessionProxy } from './no-session-proxy';
-import {
-  getWDAUpgradeTimestamp, resetTestProcesses, getPIDsListeningOnPort, BOOTSTRAP_PATH
-} from './utils';
-import {XcodeBuild} from './xcodebuild';
+
+import {WebDriverProxy} from '@appium/base-driver';
+import {strongbox} from '@appium/strongbox';
+import {fs, util} from '@appium/support';
+import type {AppiumLogger, StringRecord} from '@appium/types';
 import AsyncLock from 'async-lock';
-import { exec } from 'teen_process';
-import { bundleWDASim } from './check-dependencies';
+import {waitForCondition} from 'asyncbox';
+
+import {WDA_RUNNER_BUNDLE_ID, WDA_BASE_URL, DEFAULT_TEST_BUNDLE_SUFFIX} from './constants.js';
+import {log as defaultLogger} from './logger.js';
+import {NoSessionProxy} from './no-session-proxy.js';
+import type {
+  WebDriverAgentArgs,
+  AppleDevice,
+  XcodeBuildSettings,
+  RetrieveBuildSettingsOptions,
+  WdaHostOps,
+} from './types.js';
+import {BOOTSTRAP_PATH, getWDAUpgradeTimestamp, isWatchOS} from './utils/index.js';
 import {
-  WDA_RUNNER_BUNDLE_ID, WDA_RUNNER_APP,
-  WDA_BASE_URL, WDA_UPGRADE_TIMESTAMP_PATH, DEFAULT_TEST_BUNDLE_SUFFIX
-} from './constants';
-import {Xctest} from 'appium-ios-device';
-import {strongbox} from '@appium/strongbox';
-import type { WebDriverAgentArgs, AppleDevice } from './types';
+  createDefaultWdaHostOps,
+  createWdaStartupStrategy,
+  type WdaStartupStrategy,
+  type WdaStartupStrategyContext,
+} from './wda-strategies.js';
+import {XcodeBuild} from './xcodebuild.js';
 
 const WDA_LAUNCH_TIMEOUT = 60 * 1000;
 const WDA_AGENT_PORT = 8100;
-const WDA_CF_BUNDLE_NAME = 'WebDriverAgentRunner-Runner';
 const SHARED_RESOURCES_GUARD = new AsyncLock();
 const RECENT_MODULE_VERSION_ITEM_NAME = 'recentWdaModuleVersion';
+const URL_PROTOCOL_SEPARATOR = '://';
 
 export class WebDriverAgent {
-  bootstrapPath: string;
-  agentPath: string;
+  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;
+  updatedWDABundleId?: string;
+  noSessionProxy?: NoSessionProxy;
+  jwproxy?: WebDriverProxy;
+  proxyReqRes?: any;
+  private readonly log: AppiumLogger;
+  private readonly wdaLocalPort?: number;
+  private readonly prebuildWDA?: 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 maxHttpRequestBodySize?: number;
   private readonly wdaLaunchTimeout: number;
   private readonly usePreinstalledWDA?: boolean;
-  private xctestApiClient?: Xctest | null;
   private readonly updatedWDABundleIdSuffix: string;
+  private readonly hostOps: Required<WdaHostOps>;
+  private activeStartupStrategy?: WdaStartupStrategy;
   private _xcodebuild?: XcodeBuild | null;
-  noSessionProxy?: NoSessionProxy;
-  jwproxy?: JWProxy;
-  proxyReqRes?: any;
-  private _url?: url.UrlWithStringQuery;
+  private _url?: URL;
 
   /**
    * Creates a new WebDriverAgent instance.
    * @param args - Configuration arguments for WebDriverAgent
    * @param log - Optional logger instance
    */
-  constructor (args: WebDriverAgentArgs, log: AppiumLogger | null = null) {
-    this.args = _.clone(args);
+  constructor(args: WebDriverAgentArgs, log: AppiumLogger | null = null) {
+    this.args = {...args};
     this.log = log ?? defaultLogger;
 
     this.device = args.device;
@@ -79,13 +82,15 @@ export class WebDriverAgent {
     this.iosSdkVersion = args.iosSdkVersion;
     this.host = args.host;
     this.isRealDevice = !!args.realDevice;
-    this.wdaBundlePath = args.wdaBundlePath;
+
+    if (isWatchOS(this.platformName || '') && this.isRealDevice) {
+      throw new Error('Real watchOS device testing is not supported; watchOS is only available via the Simulator.');
+    }
 
     this.setWDAPaths(args.bootstrapPath, args.agentPath);
 
     this.wdaLocalPort = args.wdaLocalPort;
-    this.wdaRemotePort = ((this.isRealDevice ? args.wdaRemotePort : null) ?? args.wdaLocalPort)
-      || WDA_AGENT_PORT;
+    this.wdaRemotePort = ((this.isRealDevice ? args.wdaRemotePort : null) ?? args.wdaLocalPort) || WDA_AGENT_PORT;
     this.wdaBaseUrl = args.wdaBaseUrl || WDA_BASE_URL;
     this.wdaBindingIP = args.wdaBindingIP;
     this.prebuildWDA = args.prebuildWDA;
@@ -101,51 +106,70 @@ export class WebDriverAgent {
 
     this.useXctestrunFile = args.useXctestrunFile;
     this.usePrebuiltWDA = args.usePrebuiltWDA;
-    this.derivedDataPath = args.derivedDataPath;
     this.mjpegServerPort = args.mjpegServerPort;
+    this.maxHttpRequestBodySize = args.maxHttpRequestBodySize;
 
     this.updatedWDABundleId = args.updatedWDABundleId;
 
     this.wdaLaunchTimeout = args.wdaLaunchTimeout || WDA_LAUNCH_TIMEOUT;
     this.usePreinstalledWDA = args.usePreinstalledWDA;
-    this.xctestApiClient = null;
     this.updatedWDABundleIdSuffix = args.updatedWDABundleIdSuffix ?? DEFAULT_TEST_BUNDLE_SUFFIX;
+    const defaultHostOps = createDefaultWdaHostOps();
+    this.hostOps = {
+      simulator: {
+        ...defaultHostOps.simulator,
+        ...args.hostOps?.simulator,
+      },
+      realDevicePreinstalled: {
+        ...defaultHostOps.realDevicePreinstalled,
+        ...args.hostOps?.realDevicePreinstalled,
+      },
+      realDeviceXcodebuild: {
+        ...defaultHostOps.realDeviceXcodebuild,
+        ...args.hostOps?.realDeviceXcodebuild,
+      },
+    };
 
     this._xcodebuild = this.canSkipXcodebuild
-    ? null
-    : new XcodeBuild(this.device, {
-        platformVersion: this.platformVersion,
-        platformName: this.platformName,
-        iosSdkVersion: this.iosSdkVersion,
-        agentPath: this.agentPath,
-        bootstrapPath: this.bootstrapPath,
-        realDevice: this.isRealDevice,
-        showXcodeLog: args.showXcodeLog,
-        xcodeConfigFile: args.xcodeConfigFile,
-        xcodeOrgId: args.xcodeOrgId,
-        xcodeSigningId: args.xcodeSigningId,
-        keychainPath: args.keychainPath,
-        keychainPassword: args.keychainPassword,
-        useSimpleBuildTest: args.useSimpleBuildTest,
-        usePrebuiltWDA: args.usePrebuiltWDA,
-        updatedWDABundleId: this.updatedWDABundleId,
-        launchTimeout: this.wdaLaunchTimeout,
-        wdaRemotePort: this.wdaRemotePort,
-        wdaBindingIP: this.wdaBindingIP,
-        useXctestrunFile: this.useXctestrunFile,
-        derivedDataPath: args.derivedDataPath,
-        mjpegServerPort: this.mjpegServerPort,
-        allowProvisioningDeviceRegistration: args.allowProvisioningDeviceRegistration,
-        resultBundlePath: args.resultBundlePath,
-        resultBundleVersion: args.resultBundleVersion,
-      }, this.log);
+      ? null
+      : new XcodeBuild(
+          this.device,
+          {
+            platformVersion: this.platformVersion,
+            platformName: this.platformName,
+            iosSdkVersion: this.iosSdkVersion,
+            agentPath: this.agentPath,
+            bootstrapPath: this.bootstrapPath,
+            realDevice: this.isRealDevice,
+            showXcodeLog: args.showXcodeLog,
+            xcodeConfigFile: args.xcodeConfigFile,
+            xcodeOrgId: args.xcodeOrgId,
+            xcodeSigningId: args.xcodeSigningId,
+            keychainPath: args.keychainPath,
+            keychainPassword: args.keychainPassword,
+            useSimpleBuildTest: args.useSimpleBuildTest,
+            usePrebuiltWDA: args.usePrebuiltWDA,
+            updatedWDABundleId: this.updatedWDABundleId,
+            launchTimeout: this.wdaLaunchTimeout,
+            wdaRemotePort: this.wdaRemotePort,
+            wdaBindingIP: this.wdaBindingIP,
+            useXctestrunFile: this.useXctestrunFile,
+            derivedDataPath: args.derivedDataPath,
+            mjpegServerPort: this.mjpegServerPort,
+            maxHttpRequestBodySize: this.maxHttpRequestBodySize,
+            allowProvisioningDeviceRegistration: args.allowProvisioningDeviceRegistration,
+            resultBundlePath: args.resultBundlePath,
+            resultBundleVersion: args.resultBundleVersion,
+          },
+          this.log,
+        );
   }
 
   /**
    * Return true if the session does not need xcodebuild.
    * @returns Whether the session needs/has xcodebuild.
    */
-  get canSkipXcodebuild (): boolean {
+  get canSkipXcodebuild(): boolean {
     // Use this.args.webDriverAgentUrl to guarantee
     // the capabilities set gave the `appium:webDriverAgentUrl`.
     return this.usePreinstalledWDA || !!this.args.webDriverAgentUrl;
@@ -156,7 +180,7 @@ export class WebDriverAgent {
    * @returns The XcodeBuild instance
    * @throws Error if xcodebuild is not available
    */
-  get xcodebuild (): XcodeBuild {
+  get xcodebuild(): XcodeBuild {
     if (!this._xcodebuild) {
       throw new Error('xcodebuild is not available');
     }
@@ -171,44 +195,81 @@ export class WebDriverAgent {
    *
    * @returns Bundle ID for Xctest.
    */
-  get bundleIdForXctest (): string {
+  get bundleIdForXctest(): string {
     return `${this.updatedWDABundleId ? this.updatedWDABundleId : WDA_RUNNER_BUNDLE_ID}${this.updatedWDABundleIdSuffix}`;
   }
 
   /**
-   * Cleans up obsolete cached processes from previous WDA sessions
-   * that are listening on the same port but belong to different devices.
+   * Gets the base path for the WebDriverAgent URL.
+   * @returns The base path (empty string if root path)
    */
-  async cleanupObsoleteProcesses (): Promise<void> {
-    const obsoletePids = await getPIDsListeningOnPort(this.url.port as string,
-      (cmdLine) => cmdLine.includes('/WebDriverAgentRunner') &&
-        !cmdLine.toLowerCase().includes(this.device.udid.toLowerCase()));
-
-    if (_.isEmpty(obsoletePids)) {
-      this.log.debug(`No obsolete cached processes from previous WDA sessions ` +
-        `listening on port ${this.url.port} have been found`);
-      return;
+  get basePath(): string {
+    if (this.url.pathname === '/') {
+      return '';
     }
+    return this.url.pathname || '';
+  }
 
-    this.log.info(`Detected ${obsoletePids.length} obsolete cached process${obsoletePids.length === 1 ? '' : 'es'} ` +
-      `from previous WDA sessions. Cleaning them up`);
-    try {
-      await exec('kill', obsoletePids);
-    } catch (e: any) {
-      this.log.warn(`Failed to kill obsolete cached process${obsoletePids.length === 1 ? '' : 'es'} '${obsoletePids}'. ` +
-        `Original error: ${e.message}`);
+  /**
+   * 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(): URL {
+    if (!this._url) {
+      if (this.webDriverAgentUrl) {
+        this._url = this.toUrl(this.webDriverAgentUrl);
+      } else {
+        const port = this.wdaLocalPort || WDA_AGENT_PORT;
+        const parsedBaseUrl = this.toUrl(this.wdaBaseUrl || WDA_BASE_URL);
+        this._url = new URL(`${parsedBaseUrl.protocol}//${this.wdaBindingIP || parsedBaseUrl.hostname}:${port}`);
+      }
     }
+    return this._url;
   }
 
   /**
-   * Gets the base path for the WebDriverAgent URL.
-   * @returns The base path (empty string if root path)
+   * Gets whether WebDriverAgent has fully started.
+   * @returns `true` if WDA has started, `false` otherwise
    */
-  get basePath (): string {
-    if (this.url.path === '/') {
-      return '';
+  get fullyStarted(): boolean {
+    return this.started;
+  }
+
+  /**
+   * Sets whether WebDriverAgent has fully started.
+   * @param started - `true` if WDA has started, `false` otherwise
+   */
+  set fullyStarted(started: boolean) {
+    this.started = started ?? false;
+  }
+
+  /**
+   * Sets the WebDriverAgent URL.
+   * @param _url - The URL string to parse and set
+   */
+  set url(_url: string) {
+    this._url = this.toUrl(_url);
+  }
+
+  /**
+   * Cleans up obsolete cached processes from previous WDA sessions
+   * that are listening on the same port but belong to different devices.
+   */
+  async cleanupObsoleteProcesses(): Promise<void> {
+    try {
+      await this.hostOps.realDeviceXcodebuild.cleanupObsoleteProcesses?.({
+        udid: this.device.udid,
+        port: this.url.port as string,
+        commandLineIncludes: '/WebDriverAgentRunner',
+      });
+    } catch (e: any) {
+      this.log.warn(`Failed to clean obsolete cached processes. Original error: ${e.message}`);
     }
-    return this.url.path || '';
+  }
+
+  /**
   }
 
   /**
@@ -232,50 +293,11 @@ export class WebDriverAgent {
    *
    * @param sessionId Launch WDA and establish the session with this sessionId
    */
-  async launch (sessionId: string): Promise<StringRecord | null> {
-    if (this.webDriverAgentUrl) {
-      this.log.info(`Using provided WebdriverAgent at '${this.webDriverAgentUrl}'`);
-      this.url = this.webDriverAgentUrl;
-      this.setupProxies(sessionId);
-      return await this.getStatus();
-    }
-
-    if (this.usePreinstalledWDA) {
-      return await this.launchWithPreinstalledWDA(sessionId);
-    }
-
-    this.log.info('Launching WebDriverAgent on the device');
-
-    this.setupProxies(sessionId);
-
-    if (!this.useXctestrunFile && !await fs.exists(this.agentPath)) {
-      throw new Error(`Trying to use WebDriverAgent project at '${this.agentPath}' but the ` +
-                      'file does not exist');
-    }
-
-    // useXctestrunFile and usePrebuiltWDA use existing dependencies
-    // It depends on user side
-    if (this.useXctestrunFile || this.usePrebuiltWDA) {
-      this.log.info('Skipped WDA project cleanup according to the provided capabilities');
-    } else {
-      const synchronizationKey = path.normalize(this.bootstrapPath);
-      await SHARED_RESOURCES_GUARD.acquire(synchronizationKey,
-        async () => await this._cleanupProjectIfFresh());
-    }
-
-    // We need to provide WDA local port, because it might be occupied
-    await resetTestProcesses(this.device.udid, !this.isRealDevice);
-
-    if (!this.noSessionProxy) {
-      throw new Error('noSessionProxy is not available');
-    }
-    await this.xcodebuild.init(this.noSessionProxy);
-
-    // Start the xcodebuild process
-    if (this.prebuildWDA) {
-      await this.xcodebuild.prebuild();
-    }
-    return await this.xcodebuild.start() as StringRecord | null;
+  async launch(sessionId: string): Promise<StringRecord | null> {
+    const startupStrategy = this.createStartupStrategy();
+    this.log.info(`Selected '${startupStrategy.name}' WebDriverAgent startup strategy`);
+    this.activeStartupStrategy = startupStrategy;
+    return await startupStrategy.launch(sessionId);
   }
 
   /**
@@ -283,83 +305,19 @@ export class WebDriverAgent {
    * that required resource files exist.
    * @returns `true` if source is fresh (all required files exist), `false` otherwise
    */
-  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);
-  }
-
-  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 as string;
-  }
-
-  private async fetchWDABundle (): Promise<string> {
-    if (!this.derivedDataPath) {
-      return await bundleWDASim(this.xcodebuild);
-    }
-    const wdaBundlePaths = await fs.glob(`${this.derivedDataPath}/**/*${WDA_RUNNER_APP}/`, {
-      absolute: true,
-    });
-    if (_.isEmpty(wdaBundlePaths)) {
-      throw new Error(`Could not find the WDA bundle in '${this.derivedDataPath}'`);
-    }
-    return wdaBundlePaths[0];
-  }
-
-  private setupProxies (sessionId: string): void {
-    const proxyOpts: any = {
-      log: this.log,
-      server: this.url.hostname ?? undefined,
-      port: parseInt(this.url.port ?? '', 10) || undefined,
-      base: this.basePath,
-      timeout: this.wdaConnectionTimeout,
-      keepAlive: true,
-      scheme: this.url.protocol ? this.url.protocol.replace(':', '') : 'http',
-    };
-    if (this.args.reqBasePath) {
-      proxyOpts.reqBasePath = this.args.reqBasePath;
-    }
-
-    this.jwproxy = new JWProxy(proxyOpts);
-    this.jwproxy.sessionId = sessionId;
-    this.proxyReqRes = this.jwproxy.proxyReqRes.bind(this.jwproxy);
-
-    this.noSessionProxy = new NoSessionProxy(proxyOpts);
+  async isSourceFresh(): Promise<boolean> {
+    const existsPromises = ['Resources', path.join('Resources', 'WebDriverAgent.bundle')].map((subPath) =>
+      fs.exists(path.resolve(this.bootstrapPath, subPath)),
+    );
+    return (await Promise.all(existsPromises)).every((v) => v === true);
   }
 
   /**
    * Stops the WebDriverAgent session and cleans up resources.
    * Handles both preinstalled WDA and xcodebuild-based sessions.
    */
-  async quit (): Promise<void> {
-    if (this.usePreinstalledWDA) {
-      this.log.info('Stopping the XCTest session');
-      if (this.xctestApiClient) {
-        this.xctestApiClient.stop();
-        this.xctestApiClient = null;
-      } else {
-        try {
-          await this.device.simctl.terminateApp(this.bundleIdForXctest);
-        } catch (e: any) {
-          this.log.warn(e.message);
-        }
-      }
-    } else if (!this.args.webDriverAgentUrl) {
-      this.log.info('Shutting down sub-processes');
-      if (this._xcodebuild) {
-        await this.xcodebuild.quit();
-      }
-    } else {
-      this.log.debug('Do not stop xcodebuild nor XCTest session ' +
-        'since the WDA session is managed by outside this driver.');
-    }
+  async quit(): Promise<void> {
+    await (this.activeStartupStrategy ?? this.createStartupStrategy()).quit();
 
     if (this.jwproxy) {
       this.jwproxy.sessionId = null;
@@ -372,114 +330,168 @@ export class WebDriverAgent {
       // then clean that up. If the url was supplied, we want to keep it
       this.webDriverAgentUrl = undefined;
     }
+    this.activeStartupStrategy = undefined;
   }
 
   /**
-   * 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 (): url.UrlWithStringQuery {
-    if (!this._url) {
-      if (this.webDriverAgentUrl) {
-        this._url = url.parse(this.webDriverAgentUrl);
-      } else {
-        const port = this.wdaLocalPort || WDA_AGENT_PORT;
-        const {protocol, hostname} = url.parse(this.wdaBaseUrl || WDA_BASE_URL);
-        this._url = url.parse(`${protocol}//${this.wdaBindingIP || hostname}:${port}`);
-      }
-    }
-    return this._url;
-  }
-
-  /**
-   * Sets the WebDriverAgent URL.
-   * @param _url - The URL string to parse and set
-   */
-  set url (_url: string) {
-    this._url = url.parse(_url);
-  }
-
-  /**
-   * Gets whether WebDriverAgent has fully started.
-   * @returns `true` if WDA has started, `false` otherwise
-   */
-  get fullyStarted (): boolean {
-    return this.started;
-  }
-
-  /**
-   * Sets whether WebDriverAgent has fully started.
-   * @param started - `true` if WDA has started, `false` otherwise
-   */
-  set fullyStarted (started: boolean) {
-    this.started = started ?? false;
-  }
-
-  /**
-   * Retrieves the Xcode derived data path for WebDriverAgent.
-   * @returns The derived data path, or `undefined` if xcodebuild is skipped
+   * Retrieves Xcode build settings.
+   * @param options - Optional scheme, SDK, configuration, or destination
+   * @returns Build settings, or `undefined` if xcodebuild is skipped or settings cannot be determined
    */
-  async retrieveDerivedDataPath (): Promise<string | undefined> {
+  async retrieveBuildSettings(options?: RetrieveBuildSettingsOptions): Promise<XcodeBuildSettings | undefined> {
     if (this.canSkipXcodebuild) {
       return;
     }
-    return await this.xcodebuild.retrieveDerivedDataPath();
+    return await this.xcodebuild.retrieveBuildSettings(options);
   }
 
   /**
    * 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 The WDA URL used for caching on success, or `undefined` if caching was skipped.
    */
-  async setupCaching (): Promise<void> {
+  async setupCaching(): Promise<string | undefined> {
     const status = await this.getStatus(0);
     if (!status || !status.build) {
       this.log.debug('WDA is currently not running. There is nothing to cache');
-      return;
+      return undefined;
     }
 
-    const {
-      productBundleIdentifier,
-      upgradedAt,
-    } = status.build as any;
+    const {productBundleIdentifier, upgradedAt} = 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}'.`);
-      return await this.uninstall();
+    if (
+      util.hasValue(productBundleIdentifier) &&
+      util.hasValue(this.updatedWDABundleId) &&
+      this.updatedWDABundleId !== productBundleIdentifier
+    ) {
+      this.log.info(
+        `Will not reuse running WDA since it has different bundle id. The actual value is '${productBundleIdentifier}'.`,
+      );
+      return undefined;
     }
     // for simulator
-    if (util.hasValue(productBundleIdentifier) && !util.hasValue(this.updatedWDABundleId) && WDA_RUNNER_BUNDLE_ID !== productBundleIdentifier) {
-      this.log.info(`Will uninstall running WDA since its bundle id is not equal to the default value ${WDA_RUNNER_BUNDLE_ID}`);
-      return await this.uninstall();
+    if (
+      util.hasValue(productBundleIdentifier) &&
+      !util.hasValue(this.updatedWDABundleId) &&
+      WDA_RUNNER_BUNDLE_ID !== productBundleIdentifier
+    ) {
+      this.log.info(
+        `Will not reuse running WDA since its bundle id is not equal to the default value ${WDA_RUNNER_BUNDLE_ID}`,
+      );
+      return undefined;
     }
 
     const actualUpgradeTimestamp = await getWDAUpgradeTimestamp();
     this.log.debug(`Upgrade timestamp of the currently bundled WDA: ${actualUpgradeTimestamp}`);
     this.log.debug(`Upgrade timestamp of the WDA on the device: ${upgradedAt}`);
-    if (actualUpgradeTimestamp && upgradedAt && _.toLower(`${actualUpgradeTimestamp}`) !== _.toLower(`${upgradedAt}`)) {
-      this.log.info('Will uninstall running WDA since it has different version in comparison to the one ' +
-        `which is bundled with appium-xcuitest-driver module (${actualUpgradeTimestamp} != ${upgradedAt})`);
-      return await this.uninstall();
+    if (
+      actualUpgradeTimestamp &&
+      upgradedAt &&
+      `${actualUpgradeTimestamp}`.toLowerCase() !== `${upgradedAt}`.toLowerCase()
+    ) {
+      this.log.info(
+        'Will not reuse running WDA since it has different version in comparison to the one ' +
+          `which is bundled with appium-xcuitest-driver module (${actualUpgradeTimestamp} != ${upgradedAt})`,
+      );
+      return undefined;
     }
 
+    const cachedUrl = this.url.href;
     const message = util.hasValue(productBundleIdentifier)
-      ? `Will reuse previously cached WDA instance at '${this.url.href}' with '${productBundleIdentifier}'`
-      : `Will reuse previously cached WDA instance at '${this.url.href}'`;
-    this.log.info(`${message}. Set the wdaLocalPort capability to a value different from ${this.url.port} if this is an undesired behavior.`);
-    this.webDriverAgentUrl = this.url.href;
+      ? `Will reuse previously cached WDA instance at '${cachedUrl}' with '${productBundleIdentifier}'`
+      : `Will reuse previously cached WDA instance at '${cachedUrl}'`;
+    this.log.info(
+      `${message}. Set the wdaLocalPort capability to a value different from ${this.url.port} if this is an undesired behavior.`,
+    );
+    this.webDriverAgentUrl = cachedUrl;
+    return cachedUrl;
   }
 
-  /**
-   * Quit and uninstall running WDA.
-   */
-  async quitAndUninstall (): Promise<void> {
-    await this.quit();
-    await this.uninstall();
+  private createStartupStrategy(): WdaStartupStrategy {
+    const context: WdaStartupStrategyContext = {
+      argsWebDriverAgentUrl: this.args.webDriverAgentUrl,
+      webDriverAgentUrl: this.webDriverAgentUrl,
+      usePreinstalledWDA: this.usePreinstalledWDA,
+      useXctestrunFile: this.useXctestrunFile,
+      usePrebuiltWDA: this.usePrebuiltWDA,
+      prebuildWDA: this.prebuildWDA,
+      isRealDevice: this.isRealDevice,
+      device: this.device,
+      agentPath: this.agentPath,
+      bootstrapPath: this.bootstrapPath,
+      bundleIdForXctest: this.bundleIdForXctest,
+      wdaLocalPort: this.wdaLocalPort,
+      wdaRemotePort: this.wdaRemotePort,
+      wdaBindingIP: this.wdaBindingIP,
+      wdaLaunchTimeout: this.wdaLaunchTimeout,
+      mjpegServerPort: this.mjpegServerPort,
+      maxHttpRequestBodySize: this.maxHttpRequestBodySize,
+      platformName: this.platformName,
+      platformVersion: this.platformVersion,
+      log: this.log,
+      hostOps: this.hostOps,
+      setWebDriverAgentUrl: (value) => {
+        this.webDriverAgentUrl = value;
+      },
+      setUrl: (value) => {
+        this.url = value;
+      },
+      setupProxies: (sessionId) => this.setupProxies(sessionId),
+      getStatus: async (timeoutMs) => await this.getStatus(timeoutMs),
+      cleanupProjectIfFresh: async () => {
+        const synchronizationKey = path.normalize(this.bootstrapPath);
+        await SHARED_RESOURCES_GUARD.acquire(synchronizationKey, async () => await this._cleanupProjectIfFresh());
+      },
+      xcodebuild: () => this.xcodebuild,
+      noSessionProxy: () => {
+        if (!this.noSessionProxy) {
+          throw new Error('noSessionProxy is not available');
+        }
+        return this.noSessionProxy;
+      },
+      setStarted: (started) => {
+        this.started = started;
+      },
+    };
+    return createWdaStartupStrategy(context);
+  }
+
+  private setupProxies(sessionId: string): void {
+    const proxyOpts: any = {
+      log: this.log,
+      server: this.url.hostname ?? undefined,
+      port: parseInt(this.url.port ?? '', 10) || undefined,
+      base: this.basePath,
+      timeout: this.wdaConnectionTimeout,
+      keepAlive: true,
+      scheme: this.url.protocol ? this.url.protocol.replace(':', '') : 'http',
+      headers: this.args.extraRequestHeaders,
+    };
+    if (this.args.reqBasePath) {
+      proxyOpts.reqBasePath = this.args.reqBasePath;
+    }
+
+    this.jwproxy = new WebDriverProxy(proxyOpts);
+    this.jwproxy.sessionId = sessionId;
+    this.proxyReqRes = this.jwproxy.proxyReqRes.bind(this.jwproxy);
+
+    this.noSessionProxy = new NoSessionProxy(proxyOpts);
   }
 
-  private setWDAPaths (bootstrapPath?: string, agentPath?: string): void {
+  private toUrl(value: string): URL {
+    // Treat values without `://` as host/path inputs and normalize to http.
+    if (!value.includes(URL_PROTOCOL_SEPARATOR)) {
+      return new URL(`http://${value}`);
+    }
+    try {
+      return new URL(value);
+    } catch {
+      throw new Error(`Invalid URL: ${value}`);
+    }
+  }
+
+  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;
@@ -490,10 +502,6 @@ export class WebDriverAgent {
     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
    * {
@@ -515,17 +523,19 @@ export class WebDriverAgent {
    *
    * @param timeoutMs If zero or negative, returns immediately. Otherwise, waits up to timeoutMs.
    */
-  private async getStatus (timeoutMs: number = 0): Promise<StringRecord | null> {
+  private async getStatus(timeoutMs: number = 0): Promise<StringRecord | null> {
     const noSessionProxy = new NoSessionProxy({
+      scheme: this.url.protocol ? this.url.protocol.replace(':', '') : 'http',
       server: this.url.hostname ?? undefined,
       port: parseInt(this.url.port ?? '', 10) || undefined,
       base: this.basePath,
       timeout: 3000,
+      headers: this.args.extraRequestHeaders,
     });
 
-    const sendGetStatus = async () => await noSessionProxy.command('/status', 'GET') as StringRecord;
+    const sendGetStatus = async () => (await noSessionProxy.command('/status', 'GET')) as StringRecord;
 
-    if (_.isNil(timeoutMs) || timeoutMs <= 0) {
+    if (timeoutMs == null || timeoutMs <= 0) {
       try {
         return await sendGetStatus();
       } catch (err: any) {
@@ -537,82 +547,51 @@ export class WebDriverAgent {
     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,
-      });
+      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.`);
+      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.`, {cause: err});
     }
     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> {
+  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;
+    // Each Strongbox instance starts with an empty item map. Load the persisted value from disk.
+    const boxItem = await box.createItem<string>(RECENT_MODULE_VERSION_ITEM_NAME);
+    let recentModuleVersion = boxItem.value;
+    if (recentModuleVersion === undefined) {
+      this.log.info('There is no need to perform the project cleanup. A fresh install has been detected');
+      try {
+        await boxItem.write(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) {
@@ -625,14 +604,14 @@ export class WebDriverAgent {
     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})`
+          `(${recentModuleVersion} >= ${packageInfo.version})`,
       );
       return;
     }
 
     this.log.info(
       `Cleaning up the WebDriverAgent project after the module upgrade has happened ` +
-      `(${recentModuleVersion} < ${packageInfo.version})`
+        `(${recentModuleVersion} < ${packageInfo.version})`,
     );
     try {
       await this.xcodebuild.cleanProject();
@@ -641,75 +620,4 @@ export class WebDriverAgent {
       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;
-  }
 }