appium-webdriveragent 10.5.3 → 11.0.0

package/build/lib/webdriveragent.js

@@ -6,12 +6,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebDriverAgent = void 0;
 const asyncbox_1 = require("asyncbox");
 const lodash_1 = __importDefault(require("lodash"));
-const path_1 = __importDefault(require("path"));
-const url_1 = __importDefault(require("url"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = __importDefault(require("node:url"));
 const bluebird_1 = __importDefault(require("bluebird"));
 const base_driver_1 = require("@appium/base-driver");
 const support_1 = require("@appium/support");
-const logger_1 = __importDefault(require("./logger"));
+const logger_1 = require("./logger");
 const no_session_proxy_1 = require("./no-session-proxy");
 const utils_1 = require("./utils");
 const xcodebuild_1 = require("./xcodebuild");
@@ -27,29 +27,53 @@ const WDA_CF_BUNDLE_NAME = 'WebDriverAgentRunner-Runner';
 const SHARED_RESOURCES_GUARD = new async_lock_1.default();
 const RECENT_MODULE_VERSION_ITEM_NAME = 'recentWdaModuleVersion';
 class WebDriverAgent {
-    /** @type {string} */
     bootstrapPath;
-    /** @type {string} */
     agentPath;
-    /** @type {any} @deprecated for removal */
-    idb;
+    args;
+    log;
+    device;
+    platformVersion;
+    platformName;
+    iosSdkVersion;
+    host;
+    isRealDevice;
+    wdaBundlePath;
+    wdaLocalPort;
+    wdaRemotePort;
+    wdaBaseUrl;
+    wdaBindingIP;
+    prebuildWDA;
+    webDriverAgentUrl;
+    started;
+    wdaConnectionTimeout;
+    useXctestrunFile;
+    usePrebuiltWDA;
+    derivedDataPath;
+    mjpegServerPort;
+    updatedWDABundleId;
+    wdaLaunchTimeout;
+    usePreinstalledWDA;
+    xctestApiClient;
+    updatedWDABundleIdSuffix;
+    _xcodebuild;
+    noSessionProxy;
+    jwproxy;
+    proxyReqRes;
+    _url;
     /**
-     * @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, log = null) {
         this.args = lodash_1.default.clone(args);
-        this.log = log ?? logger_1.default;
+        this.log = log ?? logger_1.log;
         this.device = args.device;
         this.platformVersion = args.platformVersion;
         this.platformName = args.platformName;
         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);
         this.wdaLocalPort = args.wdaLocalPort;
@@ -73,9 +97,9 @@ class WebDriverAgent {
         this.usePreinstalledWDA = args.usePreinstalledWDA;
         this.xctestApiClient = null;
         this.updatedWDABundleIdSuffix = args.updatedWDABundleIdSuffix ?? constants_1.DEFAULT_TEST_BUNDLE_SUFFIX;
-        this.xcodebuild = this.canSkipXcodebuild
+        this._xcodebuild = this.canSkipXcodebuild
             ? null
-            : new xcodebuild_1.XcodeBuild(this.xcodeVersion, this.device, {
+            : new xcodebuild_1.XcodeBuild(this.device, {
                 platformVersion: this.platformVersion,
                 platformName: this.platformName,
                 iosSdkVersion: this.iosSdkVersion,
@@ -104,42 +128,41 @@ 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() {
         // 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() {
+        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() {
         return `${this.updatedWDABundleId ? this.updatedWDABundleId : constants_1.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 || utils_1.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_1.default.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 (0, utils_1.getPIDsListeningOnPort)(/** @type {string} */ (this.url.port), (cmdLine) => cmdLine.includes('/WebDriverAgentRunner') &&
+        const obsoletePids = await (0, utils_1.getPIDsListeningOnPort)(this.url.port, (cmdLine) => cmdLine.includes('/WebDriverAgentRunner') &&
             !cmdLine.toLowerCase().includes(this.device.udid.toLowerCase()));
         if (lodash_1.default.isEmpty(obsoletePids)) {
             this.log.debug(`No obsolete cached processes from previous WDA sessions ` +
@@ -157,15 +180,8 @@ class WebDriverAgent {
         }
     }
     /**
-     * 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
-     */
-    async isRunning() {
-        return !!(await this.getStatus());
-    }
-    /**
-     * @returns {string}
+     * Gets the base path for the WebDriverAgent URL.
+     * @returns The base path (empty string if root path)
      */
     get basePath() {
         if (this.url.path === '/') {
@@ -173,230 +189,6 @@ class WebDriverAgent {
         }
         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 no_session_proxy_1.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 (lodash_1.default.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 (0, asyncbox_1.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 (lodash_1.default.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 support_1.fs.readFile(path_1.default.join(utils_1.BOOTSTRAP_PATH, 'package.json'), 'utf8'));
-        const box = (0, strongbox_1.strongbox)(packageInfo.name);
-        let boxItem = box.getItem(RECENT_MODULE_VERSION_ITEM_NAME);
-        if (!boxItem) {
-            const timestampPath = path_1.default.resolve(process.env.HOME ?? '', constants_1.WDA_UPGRADE_TIMESTAMP_PATH);
-            if (await support_1.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 = support_1.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 (support_1.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 && support_1.util.compareVersions(this.platformVersion, '>=', '17.0')) {
-                await this._launchViaDevicectl({ env: xctestEnv });
-            }
-            else {
-                this.xctestApiClient = new appium_ios_device_1.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
      * {
@@ -416,9 +208,7 @@ 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) {
         if (this.webDriverAgentUrl) {
@@ -438,79 +228,48 @@ 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_1.default.normalize(this.bootstrapPath);
+            const synchronizationKey = node_path_1.default.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 (0, utils_1.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();
     }
     /**
-     * @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() {
+        const existsPromises = [
+            'Resources',
+            `Resources${node_path_1.default.sep}WebDriverAgent.bundle`,
+        ].map((subPath) => support_1.fs.exists(node_path_1.default.resolve(this.bootstrapPath, subPath)));
+        return (await bluebird_1.default.all(existsPromises)).some((v) => v === false);
     }
-    /**
-     *
-     * @param {string} wdaBundlePath
-     * @returns {Promise<string>}
-     */
     async parseBundleId(wdaBundlePath) {
-        const infoPlistPath = path_1.default.join(wdaBundlePath, 'Info.plist');
+        const infoPlistPath = node_path_1.default.join(wdaBundlePath, 'Info.plist');
         const infoPlist = await support_1.plist.parsePlist(await support_1.fs.readFile(infoPlistPath));
         if (!infoPlist.CFBundleIdentifier) {
             throw new Error(`Could not find bundle id in '${infoPlistPath}'`);
         }
         return infoPlist.CFBundleIdentifier;
     }
-    /**
-     * @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_1.default.join(wdaBundlePath, 'PlugIns', 'WebDriverAgentRunner.xctest'));
-        return { wdaBundleId, testBundleId, wdaBundlePath };
-    }
-    /**
-     * @returns {Promise<string>}
-     */
     async fetchWDABundle() {
         if (!this.derivedDataPath) {
-            return await (0, check_dependencies_1.bundleWDASim)(/** @type {XcodeBuild} */ (this.xcodebuild));
+            return await (0, check_dependencies_1.bundleWDASim)(this.xcodebuild);
         }
         const wdaBundlePaths = await support_1.fs.glob(`${this.derivedDataPath}/**/*${constants_1.WDA_RUNNER_APP}/`, {
             absolute: true,
@@ -520,20 +279,6 @@ class WebDriverAgent {
         }
         return wdaBundlePaths[0];
     }
-    /**
-     * @returns {Promise<boolean>}
-     */
-    async isSourceFresh() {
-        const existsPromises = [
-            'Resources',
-            `Resources${path_1.default.sep}WebDriverAgent.bundle`,
-        ].map((subPath) => support_1.fs.exists(path_1.default.resolve(/** @type {String} */ (this.bootstrapPath), subPath)));
-        return (await bluebird_1.default.all(existsPromises)).some((v) => v === false);
-    }
-    /**
-     * @param {string} sessionId
-     * @returns {void}
-     */
     setupProxies(sessionId) {
         const proxyOpts = {
             log: this.log,
@@ -553,7 +298,8 @@ class WebDriverAgent {
         this.noSessionProxy = new no_session_proxy_1.NoSessionProxy(proxyOpts);
     }
     /**
-     * @returns {Promise<void>}
+     * Stops the WebDriverAgent session and cleans up resources.
+     * Handles both preinstalled WDA and xcodebuild-based sessions.
      */
     async quit() {
         if (this.usePreinstalledWDA) {
@@ -573,8 +319,10 @@ class WebDriverAgent {
         }
         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 ' +
@@ -591,58 +339,62 @@ 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() {
         if (!this._url) {
             if (this.webDriverAgentUrl) {
-                this._url = url_1.default.parse(this.webDriverAgentUrl);
+                this._url = node_url_1.default.parse(this.webDriverAgentUrl);
             }
             else {
                 const port = this.wdaLocalPort || WDA_AGENT_PORT;
-                const { protocol, hostname } = url_1.default.parse(this.wdaBaseUrl || constants_1.WDA_BASE_URL);
-                this._url = url_1.default.parse(`${protocol}//${this.wdaBindingIP || hostname}:${port}`);
+                const { protocol, hostname } = node_url_1.default.parse(this.wdaBaseUrl || constants_1.WDA_BASE_URL);
+                this._url = node_url_1.default.parse(`${protocol}//${this.wdaBindingIP || hostname}:${port}`);
             }
         }
         return this._url;
     }
     /**
-     * @param {string} _url
-     * @returns {void}
+     * Sets the WebDriverAgent URL.
+     * @param _url - The URL string to parse and set
      */
     set url(_url) {
-        this._url = url_1.default.parse(_url);
+        this._url = node_url_1.default.parse(_url);
     }
     /**
-     * @returns {boolean}
+     * Gets whether WebDriverAgent has fully started.
+     * @returns `true` if WDA has started, `false` otherwise
      */
     get fullyStarted() {
         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) {
         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() {
         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();
+        const status = await this.getStatus(0);
         if (!status || !status.build) {
             this.log.debug('WDA is currently not running. There is nothing to cache');
             return;
@@ -674,13 +426,231 @@ class WebDriverAgent {
     }
     /**
      * Quit and uninstall running WDA.
-     * @returns {Promise<void>}
      */
     async quitAndUninstall() {
         await this.quit();
         await this.uninstall();
     }
+    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 || utils_1.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 || node_path_1.default.resolve(this.bootstrapPath, 'WebDriverAgent.xcodeproj');
+        this.log.info(`Using WDA agent: '${this.agentPath}'`);
+    }
+    async isRunning() {
+        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.
+     */
+    async getStatus(timeoutMs = 0) {
+        const noSessionProxy = new no_session_proxy_1.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');
+        if (lodash_1.default.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 (0, asyncbox_1.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.
+     */
+    async uninstall() {
+        try {
+            const bundleIds = await this.device.getUserInstalledBundleIdsByBundleName(WDA_CF_BUNDLE_NAME);
+            if (lodash_1.default.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 support_1.fs.readFile(node_path_1.default.join(utils_1.BOOTSTRAP_PATH, 'package.json'), 'utf8'));
+        const box = (0, strongbox_1.strongbox)(packageInfo.name);
+        let boxItem = box.getItem(RECENT_MODULE_VERSION_ITEM_NAME);
+        if (!boxItem) {
+            const timestampPath = node_path_1.default.resolve(process.env.HOME ?? '', constants_1.WDA_UPGRADE_TIMESTAMP_PATH);
+            if (await support_1.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 = support_1.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 (support_1.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) {
+            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.
+     */
+    async _launchViaDevicectl(opts = {}) {
+        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
+     */
+    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 && support_1.util.compareVersions(this.platformVersion, '>=', '17.0')) {
+                await this._launchViaDevicectl({ env: xctestEnv });
+            }
+            else {
+                this.xctestApiClient = new appium_ios_device_1.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;
+    }
 }
 exports.WebDriverAgent = WebDriverAgent;
-exports.default = WebDriverAgent;
 //# sourceMappingURL=webdriveragent.js.map