feat!: Migrate the package to ESM

lib/check-dependencies.ts

@@ -1,9 +1,9 @@
 import {fs} from '@appium/support';
 import {exec} from 'teen_process';
 import path from 'node:path';
-import {WDA_SCHEME, SDK_SIMULATOR, WDA_RUNNER_APP} from './constants';
-import {BOOTSTRAP_PATH} from './utils';
-import type {XcodeBuild} from './xcodebuild';
+import {WDA_SCHEME, SDK_SIMULATOR, WDA_RUNNER_APP} from './constants.js';
+import {BOOTSTRAP_PATH} from './utils/index.js';
+import type {XcodeBuild} from './xcodebuild.js';
 
 /**
  * Ensure simulator WDA is built and return the resulting app bundle path.

lib/index.ts

@@ -1,7 +1,7 @@
-export {bundleWDASim} from './check-dependencies';
-export {NoSessionProxy} from './no-session-proxy';
-export {WebDriverAgent} from './webdriveragent';
-export {WDA_BASE_URL, WDA_RUNNER_APP, WDA_RUNNER_BUNDLE_ID, PROJECT_FILE} from './constants';
-export {resetTestProcesses, BOOTSTRAP_PATH} from './utils';
+export {bundleWDASim} from './check-dependencies.js';
+export {NoSessionProxy} from './no-session-proxy.js';
+export {WebDriverAgent} from './webdriveragent.js';
+export {WDA_BASE_URL, WDA_RUNNER_APP, WDA_RUNNER_BUNDLE_ID, PROJECT_FILE} from './constants.js';
+export {resetTestProcesses, BOOTSTRAP_PATH} from './utils/index.js';
 
-export * from './types';
+export * from './types.js';

lib/utils/index.ts

@@ -1,16 +1,16 @@
-import {getWDAUpgradeTimestamp as getWDAUpgradeTimestampImpl} from './module';
+import {getWDAUpgradeTimestamp as getWDAUpgradeTimestampImpl} from './module.js';
 
-export {BOOTSTRAP_PATH} from './module';
-export {isTvOS} from './platform';
-export {getPIDsListeningOnPort, killAppUsingPattern, resetTestProcesses} from './processes';
-export {setRealDeviceSecurity} from './security';
+export {BOOTSTRAP_PATH} from './module.js';
+export {isTvOS} from './platform.js';
+export {getPIDsListeningOnPort, killAppUsingPattern, resetTestProcesses} from './processes.js';
+export {setRealDeviceSecurity} from './security.js';
 export {
   getAdditionalRunContent,
   getXctestrunFileName,
   getXctestrunFilePath,
   setXctestrunFile,
-} from './xctestrun';
-export type {XctestrunFileArgs} from './xctestrun';
+} from './xctestrun.js';
+export type {XctestrunFileArgs} from './xctestrun.js';
 
 /**
  * Retrieves WDA upgrade timestamp. The manifest only gets modified on package upgrade.

lib/utils/module.ts

@@ -2,13 +2,10 @@ import {fs, node as supportNode} from '@appium/support';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
 
-// Get current filename - works in both CommonJS and ESM
-const currentFilename =
-  typeof __filename !== 'undefined'
-    ? __filename
-    : fileURLToPath(new Function('return import.meta.url')());
-
-const moduleRoot = supportNode.getModuleRootSync('appium-webdriveragent', currentFilename);
+const moduleRoot = supportNode.getModuleRootSync(
+  'appium-webdriveragent',
+  fileURLToPath(import.meta.url),
+);
 
 if (!moduleRoot) {
   throw new Error('Cannot find the root folder of the appium-webdriveragent Node.js module');

lib/utils/platform.ts

@@ -1,4 +1,4 @@
-import {PLATFORM_NAME_TVOS} from '../constants';
+import {PLATFORM_NAME_TVOS} from '../constants.js';
 
 /**
  * Return true if the platformName is tvOS

lib/utils/processes.ts

@@ -1,6 +1,6 @@
 import {waitForCondition} from 'asyncbox';
 import {exec} from 'teen_process';
-import {log} from '../logger';
+import {log} from '../logger.js';
 
 /**
  * Find and terminate all processes matching the given pgrep pattern.

lib/utils/security.ts

@@ -1,5 +1,5 @@
 import {exec} from 'teen_process';
-import {log} from '../logger';
+import {log} from '../logger.js';
 
 /**
  * Configure keychain access required for real-device code signing.

lib/utils/xctestrun.ts

@@ -1,9 +1,9 @@
 import {fs, plist, util} from '@appium/support';
 import path from 'node:path';
 import {arch} from 'node:os';
-import {log} from '../logger';
-import type {DeviceInfo} from '../types';
-import {isTvOS} from './platform';
+import {log} from '../logger.js';
+import type {DeviceInfo} from '../types.js';
+import {isTvOS} from './platform.js';
 
 /**
  * Arguments for setting xctestrun file

lib/wda-strategies.ts

@@ -1,9 +1,9 @@
 import {exec} from 'teen_process';
 import {fs} from '@appium/support';
 import type {AppiumLogger, StringRecord} from '@appium/types';
-import {getPIDsListeningOnPort, resetTestProcesses} from './utils';
-import type {NoSessionProxy} from './no-session-proxy';
-import type {XcodeBuild} from './xcodebuild';
+import {getPIDsListeningOnPort, resetTestProcesses} from './utils/index.js';
+import type {NoSessionProxy} from './no-session-proxy.js';
+import type {XcodeBuild} from './xcodebuild.js';
 import type {
   AppleDevice,
   RealDevicePreinstalledHostOps,
@@ -12,7 +12,7 @@ import type {
   WdaHostOps,
   WdaLaunchEnvironment,
   WdaStartupStrategyName,
-} from './types';
+} from './types.js';
 
 const WDA_AGENT_PORT = 8100;
 const HOST_OPS_REQUIRED_MESSAGE =

lib/webdriveragent.ts

@@ -3,31 +3,31 @@ import path from 'node:path';
 import {JWProxy} from '@appium/base-driver';
 import {fs, util} from '@appium/support';
 import type {AppiumLogger, StringRecord} from '@appium/types';
-import {log as defaultLogger} from './logger';
-import {NoSessionProxy} from './no-session-proxy';
-import {BOOTSTRAP_PATH, getWDAUpgradeTimestamp} from './utils';
-import {XcodeBuild} from './xcodebuild';
+import {log as defaultLogger} from './logger.js';
+import {NoSessionProxy} from './no-session-proxy.js';
+import {BOOTSTRAP_PATH, getWDAUpgradeTimestamp} from './utils/index.js';
+import {XcodeBuild} from './xcodebuild.js';
 import AsyncLock from 'async-lock';
 import {
   WDA_RUNNER_BUNDLE_ID,
   WDA_BASE_URL,
   WDA_UPGRADE_TIMESTAMP_PATH,
   DEFAULT_TEST_BUNDLE_SUFFIX,
-} from './constants';
+} from './constants.js';
 import {strongbox} from '@appium/strongbox';
 import type {
   WebDriverAgentArgs,
   AppleDevice,
   XcodeBuildSettings,
   RetrieveBuildSettingsOptions,
   WdaHostOps,
-} from './types';
+} from './types.js';
 import {
   createDefaultWdaHostOps,
   createWdaStartupStrategy,
   type WdaStartupStrategy,
   type WdaStartupStrategyContext,
-} from './wda-strategies';
+} from './wda-strategies.js';
 
 const WDA_LAUNCH_TIMEOUT = 60 * 1000;
 const WDA_AGENT_PORT = 8100;
@@ -349,17 +349,6 @@ export class WebDriverAgent {
     return await this.xcodebuild.retrieveBuildSettings(options);
   }
 
-  /**
-   * @deprecated Use {@link retrieveBuildSettings} instead. Will be removed in a future release.
-   * @returns The derived data path, or `undefined` if xcodebuild is skipped
-   */
-  async retrieveDerivedDataPath(): Promise<string | undefined> {
-    if (this.canSkipXcodebuild) {
-      return;
-    }
-    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.

lib/xcodebuild.ts

@@ -2,18 +2,23 @@ import {retryInterval} from 'asyncbox';
 import {SubProcess, exec} from 'teen_process';
 import {logger, timing, util} from '@appium/support';
 import type {AppiumLogger, StringRecord} from '@appium/types';
-import {log as defaultLogger} from './logger';
-import {getWDAUpgradeTimestamp, isTvOS, setRealDeviceSecurity, setXctestrunFile} from './utils';
+import {log as defaultLogger} from './logger.js';
+import {
+  getWDAUpgradeTimestamp,
+  isTvOS,
+  setRealDeviceSecurity,
+  setXctestrunFile,
+} from './utils/index.js';
 import path from 'node:path';
-import {WDA_RUNNER_BUNDLE_ID} from './constants';
+import {WDA_RUNNER_BUNDLE_ID} from './constants.js';
 import type {
   AppleDevice,
   RetrieveBuildSettingsOptions,
   XcodeBuildArgs,
   XcodeBuildSettings,
   XcodeShowBuildSettingsEntry,
-} from './types';
-import type {NoSessionProxy} from './no-session-proxy';
+} from './types.js';
+import type {NoSessionProxy} from './no-session-proxy.js';
 
 const DEFAULT_SIGNING_ID = 'iPhone Developer';
 const PREBUILD_DELAY = 0;

package.json

@@ -3,7 +3,15 @@
   "version": "15.1.6",
   "description": "Package bundling WebDriverAgent",
   "main": "./build/lib/index.js",
+  "type": "module",
   "types": "./build/lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/lib/index.d.ts",
+      "import": "./build/lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "build": "tsc -b",
     "dev": "npm run build -- --watch",
@@ -14,8 +22,8 @@
     "format:check": "prettier --check ./lib ./test",
     "prepare": "npm run build",
     "version": "npm run sync-wda-version",
-    "test": "node --test --test-timeout=60000 \"./build/test/unit/**/*.spec.js\"",
-    "e2e-test": "node --test --test-force-exit --test-concurrency=1 --test-timeout=600000 \"./build/test/functional/**/*.spec.js\"",
+    "test": "node --enable-source-maps --test --test-timeout=60000 \"./build/test/unit/**/*.spec.js\"",
+    "e2e-test": "node --enable-source-maps --test --test-force-exit --test-concurrency=1 --test-timeout=600000 \"./build/test/functional/**/*.spec.js\"",
     "bundle": "npm run bundle:ios && npm run bundle:tv",
     "bundle:ios": "TARGET=runner SDK=sim node ./Scripts/build-webdriveragent.mjs",
     "bundle:tv": "TARGET=tv_runner SDK=tv_sim node ./Scripts/build-webdriveragent.mjs",
@@ -59,6 +67,7 @@
     "@types/sinon": "^22.0.0",
     "appium-xcode": "^6.0.0",
     "conventional-changelog-conventionalcommits": "^9.3.1",
+    "esmock": "^2.7.6",
     "node-simctl": "^8.0.0",
     "prettier": "^3.9.3",
     "semantic-release": "^25.0.2",

test/functional/helpers/simulator.ts

@@ -1,8 +1,8 @@
 import {Simctl} from 'node-simctl';
 import {retryInterval} from 'asyncbox';
 import {killAllSimulators as simKill} from 'appium-ios-simulator';
-import {resetTestProcesses} from '../../../lib/utils';
-import type {AppleDevice} from '../../../lib/types';
+import {resetTestProcesses} from '../../../lib/utils/index.js';
+import type {AppleDevice} from '../../../lib/types.js';
 
 type SimulatorTestDevice = AppleDevice & {simctl: Simctl};
 

test/functional/webdriveragent-e2e.spec.ts

@@ -1,12 +1,12 @@
 import {Simctl} from 'node-simctl';
 import {getSimulator} from 'appium-ios-simulator';
-import {killAllSimulators, shutdownSimulator} from './helpers/simulator';
+import {killAllSimulators, shutdownSimulator} from './helpers/simulator.js';
 import {SubProcess} from 'teen_process';
-import {PLATFORM_VERSION, DEVICE_NAME} from './desired';
+import {PLATFORM_VERSION, DEVICE_NAME} from './desired.js';
 import {retryInterval} from 'asyncbox';
-import {WebDriverAgent} from '../../lib/webdriveragent';
+import {WebDriverAgent} from '../../lib/webdriveragent.js';
 import axios from 'axios';
-import type {AppleDevice} from '../../lib/types';
+import type {AppleDevice} from '../../lib/types.js';
 import {describe, before, after, beforeEach, afterEach, it} from 'node:test';
 import assert from 'node:assert/strict';
 

test/unit/utils.spec.ts

@@ -1,12 +1,16 @@
 import assert from 'node:assert/strict';
-import {getXctestrunFilePath, getAdditionalRunContent, getXctestrunFileName} from '../../lib/utils';
-import {PLATFORM_NAME_IOS, PLATFORM_NAME_TVOS} from '../../lib/constants';
+import {
+  getXctestrunFilePath,
+  getAdditionalRunContent,
+  getXctestrunFileName,
+} from '../../lib/utils/index.js';
+import {PLATFORM_NAME_IOS, PLATFORM_NAME_TVOS} from '../../lib/constants.js';
 import {fs} from '@appium/support';
 import path from 'node:path';
 import {fail} from 'node:assert';
 import {arch} from 'node:os';
 import sinon from 'sinon';
-import type {DeviceInfo} from '../../lib/types';
+import type {DeviceInfo} from '../../lib/types.js';
 import {describe, beforeEach, afterEach, it} from 'node:test';
 
 function get_arch(): string {

test/unit/webdriveragent.spec.ts

@@ -1,13 +1,27 @@
-import {BOOTSTRAP_PATH} from '../../lib/utils';
-import {WebDriverAgent} from '../../lib/webdriveragent';
-import {selectWdaStartupStrategyName} from '../../lib/wda-strategies';
-import * as utils from '../../lib/utils';
+import {BOOTSTRAP_PATH} from '../../lib/utils/index.js';
+import {selectWdaStartupStrategyName} from '../../lib/wda-strategies.js';
+import * as utils from '../../lib/utils/index.js';
 import path from 'node:path';
 import sinon from 'sinon';
-import type {WebDriverAgentArgs} from '../../lib/types';
+import esmock from 'esmock';
+import type {WebDriverAgentArgs} from '../../lib/types.js';
+import type * as WebDriverAgentModule from '../../lib/webdriveragent.js';
 import {describe, beforeEach, afterEach, it} from 'node:test';
 import assert from 'node:assert/strict';
 
+let currentGetWDAUpgradeTimestamp: (...args: any[]) => any = utils.getWDAUpgradeTimestamp;
+
+const {WebDriverAgent} = await esmock<typeof WebDriverAgentModule>(
+  '../../lib/webdriveragent.js',
+  import.meta.url,
+  {},
+  {
+    '../../lib/utils/index.js': {
+      getWDAUpgradeTimestamp: (...args: any[]) => currentGetWDAUpgradeTimestamp(...args),
+    },
+  },
+);
+
 const fakeConstructorArgs: WebDriverAgentArgs = {
   device: {
     udid: 'some-sim-udid',
@@ -82,7 +96,7 @@ describe('WebDriverAgent', function () {
         derivedDataPath: customDerivedDataPath,
       });
       if (agent.xcodebuild) {
-        assert.strictEqual(await agent.retrieveDerivedDataPath(), customDerivedDataPath);
+        assert.strictEqual(await agent.xcodebuild.retrieveDerivedDataPath(), customDerivedDataPath);
       }
     });
 
@@ -265,9 +279,10 @@ describe('WebDriverAgent', function () {
   });
 
   describe('setupCaching()', function () {
-    let wda: WebDriverAgent;
+    let wda: InstanceType<typeof WebDriverAgent>;
     let wdaStub: sinon.SinonStub;
-    const getTimestampStub = sinon.stub(utils, 'getWDAUpgradeTimestamp');
+    const getTimestampStub = sinon.stub();
+    currentGetWDAUpgradeTimestamp = getTimestampStub;
 
     beforeEach(function () {
       wda = new WebDriverAgent(fakeConstructorArgs);

tsconfig.json

@@ -6,7 +6,9 @@
     "outDir": "build",
     "types": ["node"],
     "checkJs": true,
-    "strict": true
+    "strict": true,
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext"
   },
   "include": [
     "lib",