appium-xcuitest-driver 11.2.4 → 11.3.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [11.3.0](https://github.com/appium/appium-xcuitest-driver/compare/v11.2.4...v11.3.0) (2026-05-09)
+
+### Features
+
+* add download-wda command ([#2835](https://github.com/appium/appium-xcuitest-driver/issues/2835)) ([1f568b4](https://github.com/appium/appium-xcuitest-driver/commit/1f568b4823a75ede182afdc7c82b73193f554765))
+
 ## [11.2.4](https://github.com/appium/appium-xcuitest-driver/compare/v11.2.3...v11.2.4) (2026-05-08)
 
 ### Bug Fixes

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-xcuitest-driver",
-  "version": "11.2.4",
+  "version": "11.3.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-xcuitest-driver",
-      "version": "11.2.4",
+      "version": "11.3.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/strongbox": "^1.0.0-rc.1",
@@ -240,6 +240,18 @@
         "sharp": "0.34.5"
       }
     },
+    "node_modules/@appium/support/node_modules/semver": {
+      "version": "7.7.4",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
+      "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/@appium/tsconfig": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/@appium/tsconfig/-/tsconfig-1.1.2.tgz",
@@ -551,9 +563,9 @@
       }
     },
     "node_modules/appium-ios-device": {
-      "version": "3.1.12",
-      "resolved": "https://registry.npmjs.org/appium-ios-device/-/appium-ios-device-3.1.12.tgz",
-      "integrity": "sha512-2EEeGzWz2uDmUJftxuZ4b5DCptGqvQuND+FDMQ6p4qOpxbQX6E5HmAs0LyeepB/xAxkUP9wXZdBRl1OnrLKqvg==",
+      "version": "3.1.13",
+      "resolved": "https://registry.npmjs.org/appium-ios-device/-/appium-ios-device-3.1.13.tgz",
+      "integrity": "sha512-W10U63ISs2z/OwrkvRkSpGJeLc3qeBfIBhKd33jLaaDZE3VNR3yD7vLVLBfXxVaaM6UFOqx3yL5BtoeYltsmYQ==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/support": "^7.2.2",
@@ -655,9 +667,9 @@
       }
     },
     "node_modules/appium-webdriveragent": {
-      "version": "12.2.1",
-      "resolved": "https://registry.npmjs.org/appium-webdriveragent/-/appium-webdriveragent-12.2.1.tgz",
-      "integrity": "sha512-iSY3s4EUiNqY7SZg36ufI3Jt84dBDcFxIUxmusAUJzjxkHPYy+VNTOyIdtuP5RkhFNoSh4VHg8JjusGKqdKWwg==",
+      "version": "12.2.2",
+      "resolved": "https://registry.npmjs.org/appium-webdriveragent/-/appium-webdriveragent-12.2.2.tgz",
+      "integrity": "sha512-/GbzAjEHaaNgBUK8eVnmtf8s2fudjyCi55IBoEzv0sFg/188Bo+wsJfQhECjrk9CdhkpiwjsHAlJGLUy+iEpIQ==",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/base-driver": "^10.3.0",
@@ -667,7 +679,7 @@
         "appium-ios-simulator": "^8.0.0",
         "async-lock": "^1.0.0",
         "asyncbox": "^6.1.0",
-        "axios": "^1.4.0",
+        "axios": "^1.16.0",
         "teen_process": "^4.0.7"
       },
       "engines": {
@@ -3450,9 +3462,9 @@
       "optional": true
     },
     "node_modules/semver": {
-      "version": "7.7.4",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
-      "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
+      "version": "7.8.0",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.0.tgz",
+      "integrity": "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA==",
       "license": "ISC",
       "bin": {
         "semver": "bin/semver.js"

package/package.json

@@ -8,7 +8,7 @@
     "xcuitest",
     "xctest"
   ],
-  "version": "11.2.4",
+  "version": "11.3.0",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -34,6 +34,7 @@
       "build-wda": "./scripts/build-wda.mjs",
       "open-wda": "./scripts/open-wda.mjs",
       "tunnel-creation": "./scripts/tunnel-creation.mjs",
+      "download-wda": "./scripts/download-wda.mjs",
       "download-wda-sim": "./scripts/download-wda-sim.mjs",
       "image-mounter": "./scripts/image-mounter.mjs",
       "list-real-devices": "./scripts/list-real-devices.mjs",

package/scripts/download-wda-sim.mjs

@@ -1,80 +1,25 @@
-import {fs, logger, zip, net, node} from 'appium/support.js';
-import _ from 'lodash';
-import os from 'node:os';
-import path from 'node:path';
+import {getWDAPrebuiltPackage} from './download-wda.mjs';
 import {Command} from 'commander';
+import { deprecate } from 'node:util';
 
-const log = logger.getLogger('download-wda-sim');
-const wdaUrl = (/** @type {string} */ version, /** @type {string} */ zipFileName) =>
-  `https://github.com/appium/WebDriverAgent/releases/download/v${version}/${zipFileName}`;
-const destZip = (/** @type {string} */ platform) => {
-  const scheme = `WebDriverAgentRunner${_.toLower(platform) === 'tvos' ? '_tvOS' : ''}`;
-  return `${scheme}-Build-Sim-${os.arch() === 'arm64' ? 'arm64' : 'x86_64'}.zip`;
-};
-
-/**
- * Return installed appium-webdriveragent package version
- * @returns {Promise<string>}
- */
-async function webdriveragentPkgVersion() {
-  const moduleRoot = node.getModuleRootSync('appium-xcuitest-driver', import.meta.url);
-  if (!moduleRoot) {
-    throw new Error('Cannot resolve module root for appium-xcuitest-driver');
-  }
-  const pkgPath = path.join(
-    moduleRoot,
-    'node_modules',
-    'appium-webdriveragent',
-    'package.json'
-  );
-  const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
-  return String(pkg.version);
-};
-
-/**
- * Prepare the working root directory.
- * @param {string} outdir
- * @returns {Promise<string>} Root directory to download and unzip.
- */
-async function prepareRootDir(outdir) {
-  const destDir = path.resolve(process.cwd(), outdir);
-  if (await fs.exists(destDir)) {
-    throw new Error(`${destDir} already exists`);
-  }
-  await fs.mkdir(destDir, {recursive: true});
-  return destDir;
-}
-
-/**
- * @param {DownloadOptions} options
- */
-async function getWDAPrebuiltPackage(options) {
-  const destDir = await prepareRootDir(options.outdir);
-  const zipFileName = destZip(options.platform);
-  const wdaVersion = await webdriveragentPkgVersion();
-  const urlToDownload = wdaUrl(wdaVersion, zipFileName);
-  const downloadedZipFile = path.join(destDir, zipFileName);
-  try {
-    log.info(`Downloading ${urlToDownload}`);
-    await net.downloadFile(urlToDownload, downloadedZipFile);
-
-    log.info(`Unpacking ${downloadedZipFile} into ${destDir}`);
-    await zip.extractAllTo(downloadedZipFile, destDir);
-
-    log.info(`Deleting ${downloadedZipFile}`);
-  } finally {
-    if (await fs.exists(downloadedZipFile)) {
-      await fs.unlink(downloadedZipFile);
-    }
-  }
-}
+const DEPRECATION_MESSAGE =
+  "[DEPRECATED] 'download-wda-sim' is deprecated. " +
+  "Use 'appium driver run xcuitest download-wda -- --kind=sim --platform=<platform> --outdir=<outdir>' instead.";
 
 async function main() {
   const program = new Command();
 
+  const oldHandler = deprecate(
+    async (options) => {
+      await getWDAPrebuiltPackage({...options, kind: 'sim'});
+    },
+    DEPRECATION_MESSAGE
+  );
+
   program
     .name('appium driver run xcuitest download-wda-sim')
     .description('Download a prebuilt WebDriverAgentRunner for iOS/tvOS simulator')
+    .addHelpText('beforeAll', `${DEPRECATION_MESSAGE}\n\n`)
     .requiredOption('--outdir <path>', 'Destination directory to download and unpack into')
     .requiredOption(
       '--platform <platform>',
@@ -86,14 +31,12 @@ async function main() {
       `
 EXAMPLES:
   # Download WDA for iOS simulator
-  appium driver run xcuitest download-wda-sim --outdir ./wda-sim --platform iOS
+  appium driver run xcuitest download-wda-sim -- --outdir ./wda-sim --platform iOS
 
   # Download WDA for tvOS simulator
-  appium driver run xcuitest download-wda-sim --outdir ./wda-sim-tvos --platform tvOS`,
+  appium driver run xcuitest download-wda-sim -- --outdir ./wda-sim-tvos --platform tvOS`,
     )
-    .action(async (options) => {
-      await getWDAPrebuiltPackage(options);
-    });
+    .action(oldHandler);
 
   await program.parseAsync(process.argv);
 }

package/scripts/download-wda.mjs

@@ -0,0 +1,167 @@
+import {fs, logger, zip, net, node} from 'appium/support.js';
+import {constants as fsConstants, promises as fsPromises} from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {Command} from 'commander';
+
+const log = logger.getLogger('download-wda');
+const WDA_KIND_REAL = 'real';
+const WDA_KIND_SIM = 'sim';
+
+const wdaUrl = (/** @type {string} */ version, /** @type {string} */ zipFileName) =>
+  `https://github.com/appium/WebDriverAgent/releases/download/v${version}/${zipFileName}`;
+
+/**
+ * Download and unpack a prebuilt WDA package for the given platform and kind.
+ * @param {DownloadOptions} options
+ * @returns {Promise<void>}
+ */
+export async function getWDAPrebuiltPackage(options) {
+  const kind = normalizeKind(options.kind);
+  const destDir = await prepareRootDir(options.outdir);
+  const zipFileName = destZip(options.platform, kind);
+  const wdaVersion = await getWebdriveragentPkgVersion();
+  const urlToDownload = wdaUrl(wdaVersion, zipFileName);
+  const downloadedZipFile = path.join(destDir, zipFileName);
+  try {
+    log.info(`Downloading ${urlToDownload}`);
+    await net.downloadFile(urlToDownload, downloadedZipFile);
+
+    log.info(`Unpacking ${downloadedZipFile} into ${destDir}`);
+    await zip.extractAllTo(downloadedZipFile, destDir);
+
+    log.info(`Deleting ${downloadedZipFile}`);
+  } finally {
+    if (await fs.exists(downloadedZipFile)) {
+      await fs.unlink(downloadedZipFile);
+    }
+  }
+}
+
+const destZip = (/** @type {string} */ platform, /** @type {WDAKind} */ kind) => {
+  const scheme = `WebDriverAgentRunner${String(platform).toLowerCase() === 'tvos' ? '_tvOS' : ''}`;
+  if (kind === WDA_KIND_SIM) {
+    return `${scheme}-Build-Sim-${os.arch() === 'arm64' ? 'arm64' : 'x86_64'}.zip`;
+  }
+  return `${scheme}-Runner.zip`;
+};
+
+/**
+ * Normalize the kind value, ensuring it is either 'real' or 'sim'. Default to 'real' if undefined.
+ * @param {string | undefined} kind
+ * @returns {WDAKind}
+ */
+function normalizeKind(kind) {
+  const normalized = String(kind || WDA_KIND_REAL).toLowerCase();
+  if (![WDA_KIND_REAL, WDA_KIND_SIM].includes(normalized)) {
+    throw new Error(`Unsupported kind '${kind}'. Supported values are '${WDA_KIND_REAL}' and '${WDA_KIND_SIM}'`);
+  }
+  return /** @type {WDAKind} */ (normalized);
+}
+
+/**
+ * Return installed appium-webdriveragent package version
+ * @returns {Promise<string>}
+ */
+async function getWebdriveragentPkgVersion() {
+  const moduleRoot = node.getModuleRootSync('appium-xcuitest-driver', import.meta.url);
+  if (!moduleRoot) {
+    throw new Error('Cannot resolve module root for appium-xcuitest-driver');
+  }
+  const pkgPath = path.join(
+    moduleRoot,
+    'node_modules',
+    'appium-webdriveragent',
+    'package.json'
+  );
+  const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+  if (!pkg.version || typeof pkg.version !== 'string') {
+    throw new Error(`Cannot find version in ${pkgPath}`);
+  }
+  return pkg.version;
+};
+
+/**
+ * Prepare the working root directory.
+ * @param {string} outdir
+ * @returns {Promise<string>} Root directory to download and unzip.
+ */
+async function prepareRootDir(outdir) {
+  const destDir = path.resolve(process.cwd(), outdir);
+  if (await fs.exists(destDir)) {
+    throw new Error(`${destDir} already exists`);
+  }
+
+  const parentDir = path.dirname(destDir);
+  try {
+    await fsPromises.access(parentDir, fsConstants.W_OK);
+  } catch (err) {
+    throw new Error(`Parent directory '${parentDir}' is not writable`, {
+      cause: err,
+    });
+  }
+
+  try {
+    await fs.mkdir(destDir, {recursive: true});
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Cannot create directory '${destDir}': ${message}`, {
+      cause: err,
+    });
+  }
+  return destDir;
+}
+
+async function main() {
+  const program = new Command();
+
+  program
+    .name('appium driver run xcuitest download-wda')
+    .description('Download a prebuilt WebDriverAgentRunner for iOS/tvOS real devices or simulators')
+    .requiredOption('--outdir <path>', 'Destination directory to download and unpack into')
+    .requiredOption(
+      '--platform <platform>',
+      'Target platform (e.g. iOS or tvOS)',
+      (value) => value,
+    )
+    .option(
+      '--kind <kind>',
+      `Target package type: ${WDA_KIND_REAL} (real devices) or ${WDA_KIND_SIM} (simulators). Default: ${WDA_KIND_REAL}`,
+    )
+    .addHelpText(
+      'after',
+      `
+EXAMPLES:
+  # Download WDA for iOS real device (default)
+  appium driver run xcuitest download-wda -- --outdir ./wda-real --platform iOS
+
+  # Download WDA for tvOS simulator
+  appium driver run xcuitest download-wda -- --outdir ./wda-sim-tvos --platform tvOS --kind sim`,
+    )
+    .action(async (options) => {
+      await getWDAPrebuiltPackage({
+        ...options,
+        kind: options.kind ?? WDA_KIND_REAL,
+      });
+    });
+
+  await program.parseAsync(process.argv);
+}
+
+const isMainModule =
+  Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+  await main();
+}
+
+/**
+ * @typedef {'real' | 'sim'} WDAKind
+ */
+
+/**
+ * @typedef {Object} DownloadOptions
+ * @property {string} outdir
+ * @property {string} platform
+ * @property {WDAKind | undefined} [kind]
+ */