@limrun/appium-xcuitest-driver 10.4.3-lim.1

package/package.json

@@ -0,0 +1,175 @@
+{
+  "name": "@limrun/appium-xcuitest-driver",
+  "description": "Appium driver for iOS using XCUITest for backend",
+  "keywords": [
+    "appium",
+    "ios",
+    "webdriveragent",
+    "xcuitest",
+    "xctest"
+  ],
+  "version": "10.4.3-lim.1",
+  "author": "Appium Contributors",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/appium/appium-xcuitest-driver.git"
+  },
+  "bugs": {
+    "url": "https://github.com/appium/appium-xcuitest-driver/issues"
+  },
+  "engines": {
+    "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
+    "npm": ">=10"
+  },
+  "appium": {
+    "driverName": "xcuitest",
+    "automationName": "XCUITest",
+    "platformNames": [
+      "iOS",
+      "tvOS"
+    ],
+    "mainClass": "XCUITestDriver",
+    "scripts": {
+      "build-wda": "./scripts/build-wda.js",
+      "open-wda": "./scripts/open-wda.mjs",
+      "tunnel-creation": "./scripts/tunnel-creation.mjs",
+      "download-wda-sim": "./scripts/download-wda-sim.mjs",
+      "image-mounter": "./scripts/image-mounter.mjs"
+    },
+    "schema": {
+      "$schema": "http://json-schema.org/draft-07/schema",
+      "type": "object",
+      "properties": {
+        "webdriveragent-port": {
+          "appiumCliDest": "wdaLocalPort",
+          "default": 8100,
+          "description": "Local port used for communication with WebDriverAgent",
+          "maximum": 65535,
+          "minimum": 1,
+          "type": "integer"
+        }
+      },
+      "additionalProperties": false,
+      "title": "XCUITest Driver Configuration",
+      "description": "Appium configuration schema for the XCUITest driver."
+    },
+    "doctor": {
+      "checks": [
+        "./build/lib/doctor/required-checks.js",
+        "./build/lib/doctor/optional-checks.js"
+      ]
+    }
+  },
+  "main": "./build/index.js",
+  "bin": {},
+  "directories": {
+    "lib": "lib"
+  },
+  "files": [
+    "index.js",
+    "lib",
+    "scripts",
+    "build/index.js",
+    "build/index.d.ts",
+    "build/lib",
+    "!.DS_Store",
+    "CHANGELOG.md",
+    "LICENSE",
+    "npm-shrinkwrap.json"
+  ],
+  "types": "./build/index.d.ts",
+  "dependencies": {
+    "@appium/strongbox": "^1.0.0-rc.1",
+    "@colors/colors": "^1.6.0",
+    "appium-idb": "^2.0.0",
+    "appium-ios-device": "^3.0.0",
+    "@limrun/appium-ios-simulator": "7.0.2-lim.1",
+    "appium-remote-debugger": "^15.0.3",
+    "appium-webdriveragent": "^10.2.1",
+    "@limrun/appium-xcode": "6.1.2-lim.1",
+    "async-lock": "^1.4.0",
+    "asyncbox": "^3.0.0",
+    "bluebird": "^3.7.2",
+    "commander": "^14.0.1",
+    "css-selector-parser": "^3.0.0",
+    "js2xmlparser2": "^0.x",
+    "lodash": "^4.17.21",
+    "lru-cache": "^11.1.0",
+    "moment": "^2.29.4",
+    "moment-timezone": "^0.x",
+    "node-devicectl": "^1.1.0",
+    "@limrun/node-simctl": "^8.0.5-lim.1",
+    "portscanner": "^2.2.0",
+    "semver": "^7.5.4",
+    "source-map-support": "^0.x",
+    "teen_process": "^3.0.0",
+    "winston": "^3.17.0",
+    "ws": "^8.13.0"
+  },
+  "optionalDependencies": {
+    "appium-ios-remotexpc": "^0.x"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "npm run build -- --clean",
+    "dev": "npm run build -- --watch",
+    "build:docs": "appium-docs build",
+    "dev:docs": "appium-docs build --serve",
+    "publish:docs": "appium-docs build --deploy --push -b docs-site -m 'docs: auto-build docs for appium-xcuitest-driver@%s' --alias latest",
+    "lint": "eslint .",
+    "lint:commit": "commitlint",
+    "lint:fix": "npm run lint -- --fix",
+    "format": "prettier -w ./lib",
+    "install-docs-deps": "appium-docs init --no-mkdocs",
+    "prepare": "npm run rebuild",
+    "rebuild": "npm run clean; npm run build",
+    "test": "mocha --exit --timeout 1m \"./test/unit/**/*-specs.js\"",
+    "e2e-test": "mocha --exit --timeout 10m \"./test/functional/**/*-specs.js\"",
+    "e2e-test:basic": "mocha \"./test/functional/basic\" --exit --timeout 10m",
+    "e2e-test:device": "mocha \"./test/functional/device\" --exit --timeout 10m",
+    "e2e-test:driver": "mocha \"./test/functional/driver\" --exit --timeout 10m",
+    "e2e-test:long": "mocha \"./test/functional/long\" --exit --timeout 10m",
+    "e2e-test:parallel": "mocha \"./test/functional/parallel\" --exit --timeout 10m",
+    "e2e-test:web": "mocha \"./test/functional/web\" --exit --timeout 10m",
+    "e2e-test:native-web-tap": "mocha \"./test/functional/web/safari-nativewebtap-e2e-specs.js\" --exit --timeout 10m",
+    "start": "appium --relaxed-security --port 4567 --keep-alive-timeout 1200"
+  },
+  "prettier": {
+    "bracketSpacing": false,
+    "printWidth": 100,
+    "singleQuote": true
+  },
+  "peerDependencies": {
+    "appium": "^3.0.0-rc.2"
+  },
+  "devDependencies": {
+    "@appium/docutils": "^2.0.0-rc.1",
+    "@appium/eslint-config-appium-ts": "^2.0.0-rc.1",
+    "@appium/test-support": "^4.0.0-rc.1",
+    "@appium/tsconfig": "^1.0.0-rc.1",
+    "@appium/types": "^1.0.0-rc.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/bluebird": "^3.5.38",
+    "@types/lodash": "^4.14.196",
+    "@types/mocha": "^10.0.1",
+    "@types/node": "^24.0.1",
+    "@types/portscanner": "^2.1.1",
+    "axios": "^1.4.0",
+    "chai": "^6.0.0",
+    "chai-as-promised": "^8.0.0",
+    "conventional-changelog-conventionalcommits": "^9.0.0",
+    "mocha": "^11.0.1",
+    "mocha-junit-reporter": "^2.2.1",
+    "mocha-multi-reporters": "^1.5.1",
+    "pem": "^1.14.8",
+    "prettier": "^3.0.0",
+    "semantic-release": "^25.0.0",
+    "sharp": "^0.x",
+    "sinon": "^21.0.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.4.2",
+    "webdriverio": "^9.4.1"
+  }
+}

package/scripts/build-docs.js

@@ -0,0 +1,56 @@
+// for simplicity this file is not transpiled and is run directly via an npm script
+/* eslint-disable promise/prefer-await-to-callbacks */
+/* eslint-disable promise/prefer-await-to-then */
+
+const {deploy} = require('@appium/docutils');
+const {logger} = require('appium/support');
+const path = require('path');
+const semver = require('semver');
+const {version} = require('../package.json');
+
+const log = logger.getLogger('Docs');
+
+const DOCS_REMOTE = 'origin';
+const DOCS_BRANCH = 'docs-site';
+const DOCS_PREFIX = false;
+const REPO_DIR = path.resolve(__dirname, '..');
+const LATEST_ALIAS = 'latest';
+
+const packageJson = require.resolve('../package.json');
+
+const branch = process.env.APPIUM_DOCS_BRANCH ?? DOCS_BRANCH;
+const deployPrefix = process.env.APPIUM_DOCS_PREFIX ?? DOCS_PREFIX;
+const remote = process.env.APPIUM_DOCS_REMOTE ?? DOCS_REMOTE;
+
+const push = Boolean(process.env.APPIUM_DOCS_PUBLISH);
+
+async function main() {
+  log.info(`Building XCUI docs and committing to ${DOCS_BRANCH}`);
+  const {major, minor} = semver.parse(version);
+  const deployVersion = `${major}.${minor}`;
+
+  const mkdocsYml = path.join(REPO_DIR, 'mkdocs.yml');
+
+  log.info(`Building docs for version ${deployVersion}`);
+  await deploy({
+    mkDocsYml: mkdocsYml,
+    push,
+    branch,
+    deployPrefix,
+    remote,
+    packageJson,
+    deployVersion,
+    message: `docs: auto-build docs for appium-xcuitest-driver@${deployVersion}`,
+    alias: LATEST_ALIAS,
+  });
+  log.info(`Docs built`);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err); // eslint-disable-line no-console
+    process.exitCode = 1;
+  });
+}
+
+module.exports = main;

package/scripts/build-wda.js

@@ -0,0 +1,42 @@
+const {WebDriverAgent} = require('appium-webdriveragent');
+const xcode = require('@limrun/appium-xcode');
+const {Simctl} = require('@limrun/node-simctl');
+const {getSimulator} = require('@limrun/appium-ios-simulator');
+const {logger} = require('appium/support');
+const {parseArgValue} = require('./utils');
+
+const log = logger.getLogger('WDA');
+
+async function build() {
+  const customDevice = parseArgValue('name');
+  const xcodeVersion = await xcode.getVersion(true);
+  const platformVersion = parseArgValue('sdk') || (await xcode.getMaxIOSSDK());
+  const iosDevices = await new Simctl().getDevices(platformVersion, 'iOS');
+  const verifyDevicePresence = (info) => {
+    if (!info) {
+      throw new Error(
+        `Cannot find any available iOS ${platformVersion} ${customDevice ? `${customDevice} ` : ''}simulator on your system. Only the following simulators are available:\n${iosDevices.map((e) => e.name).join('\n')}`,
+      );
+    }
+    return info;
+  };
+  const deviceInfo = verifyDevicePresence(
+    iosDevices.find(({name}) => name.includes(customDevice || 'iPhone')),
+  );
+  const device = await getSimulator(deviceInfo.udid, {
+    platform: deviceInfo.platform,
+    checkExistence: false,
+  });
+  const wda = new WebDriverAgent(xcodeVersion, {
+    iosSdkVersion: platformVersion,
+    platformVersion,
+    showXcodeLog: true,
+    device,
+  });
+  log.info(
+    `Building WDA for ${deviceInfo.name} ${platformVersion} with udid '${deviceInfo.udid}' Simulator...`,
+  );
+  await wda.xcodebuild.start(true);
+}
+
+(async () => await build())();

package/scripts/download-wda-sim.mjs

@@ -0,0 +1,68 @@
+import {fs, logger, zip, net, node} from 'appium/support.js';
+import _ from 'lodash';
+import os from 'os';
+import path from 'path';
+import {parseArgValue} from './utils.js';
+
+const log = logger.getLogger('download-wda-sim');
+const wdaUrl = (version, zipFileName) =>
+  `https://github.com/appium/WebDriverAgent/releases/download/v${version}/${zipFileName}`;
+const destZip = (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 {number}
+ */
+async function webdriveragentPkgVersion() {
+  const pkgPath = path.join(
+    node.getModuleRootSync('appium-xcuitest-driver', import.meta.url),
+    'node_modules',
+    'appium-webdriveragent',
+    'package.json'
+  );
+  return JSON.parse(await fs.readFile(pkgPath, 'utf8')).version;
+};
+
+/**
+ * Prepare the working root directory.
+ * @returns {string} Root directory to download and unzip.
+ */
+async function prepareRootDir() {
+  const destDirRoot = parseArgValue('outdir');
+  if (!destDirRoot) {
+    throw new Error(`--outdir is required`);
+  }
+  const destDir = path.resolve(process.cwd(), destDirRoot);
+  if (await fs.exists(destDir)) {
+    throw new Error(`${destDir} already exists`);
+  }
+  await fs.mkdir(destDir, {recursive: true});
+  return destDir;
+}
+
+async function getWDAPrebuiltPackage() {
+  const destDir = await prepareRootDir();
+  const platform = parseArgValue('platform');
+  const zipFileName = destZip(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);
+    }
+  }
+}
+
+(async () => await getWDAPrebuiltPackage())();

package/scripts/image-mounter.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * Image mounter script for mounting and unmounting Personalized Developer Disk Image on iOS devices
+ * This script provides a CLI interface to mount/unmount DDI via remote XPC services
+ */
+
+import {logger} from 'appium/support.js';
+import {promises as fs} from 'fs';
+import path from 'path';
+import {Command} from 'commander';
+
+const log = logger.getLogger('ImageMounter');
+
+/**
+ * ImageMounter class for managing image mounting and unmounting operations
+ */
+class ImageMounter {
+  constructor() {
+    this.remoteXPCModule = null;
+  }
+
+  async initializeRemoteXPC() {
+    if (this.remoteXPCModule) {
+      return this.remoteXPCModule;
+    }
+
+    try {
+      this.remoteXPCModule = await import('appium-ios-remotexpc');
+      return this.remoteXPCModule;
+    } catch {
+      throw new Error(
+        'appium-ios-remotexpc is not installed. Please install it using:\n' +
+        'npm install appium-ios-remotexpc\n\n' +
+        'Note: This is an optional dependency required for image mounting functionality.'
+      );
+    }
+  }
+
+  async validateFile(filePath, fileType) {
+    const absolutePath = path.resolve(filePath);
+
+    try {
+      const stat = await fs.stat(absolutePath);
+
+      if (!stat.isFile()) {
+        throw new Error(`${fileType} path is not a file: ${absolutePath}`);
+      }
+
+      return absolutePath;
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new Error(`${fileType} file not found: ${absolutePath}`);
+      }
+      throw error;
+    }
+  }
+
+  async getTargetDevice(udid) {
+    const {createUsbmux} = await this.initializeRemoteXPC();
+
+    log.info('Connecting to usbmuxd...');
+    const usbmux = await createUsbmux();
+
+    const devices = await usbmux.listDevices();
+    if (devices.length === 0) {
+      await usbmux.close();
+      throw new Error(
+        'No iOS devices found. Ensure a device is connected, unlocked, and trusted. ' +
+        'See https://appium.github.io/appium-xcuitest-driver/latest/preparation/real-device-config/ for details.'
+      );
+    }
+
+    let targetDevice;
+    if (udid) {
+      targetDevice = devices.find((device) => device.Properties.SerialNumber === udid);
+      if (!targetDevice) {
+        await usbmux.close();
+        throw new Error(
+          `Device with UDID ${udid} not found. Available devices:\n` +
+          devices.map((d) => `  - ${d.Properties.SerialNumber}`).join('\n')
+        );
+      }
+    } else {
+      if (devices.length > 1) {
+        log.warn(`Multiple devices found. Using first device: ${devices[0].Properties.SerialNumber}`);
+        log.warn('Available devices:');
+        devices.forEach((device) =>
+          log.warn(`  - ${device.Properties.SerialNumber}`
+        ));
+        log.warn('Use --udid flag to specify a particular device.');
+      }
+      targetDevice = devices[0];
+    }
+
+    return {usbmux, targetDevice};
+  }
+
+  async withImageMounterService(udid, fn) {
+    const {usbmux, targetDevice} = await this.getTargetDevice(udid);
+    const deviceUdid = targetDevice.Properties.SerialNumber;
+
+    try {
+      const remoteXPCModule = await this.initializeRemoteXPC();
+      const {
+        Services
+      } = remoteXPCModule;
+
+      log.info('Starting mobile image mounter service...');
+      const {
+        mobileImageMounterService: imageMounterService,
+        remoteXPC
+      } = await Services.startMobileImageMounterService(deviceUdid);
+
+      try {
+        return await fn(imageMounterService, deviceUdid);
+      } finally {
+        await imageMounterService.cleanup();
+        if (remoteXPC) {
+          log.info(`Closing remoteXPC connection for device ${deviceUdid}`);
+          await remoteXPC.close();
+        }
+      }
+    } finally {
+      await usbmux.close();
+    }
+  }
+
+  /**
+   * Mount Personalized Developer Disk Image on device
+   * @param {string} imagePath - Path to the .dmg file
+   * @param {string} manifestPath - Path to the BuildManifest.plist file
+   * @param {string} trustCachePath - Path to the .trustcache file
+   * @param {string} [udid] - Device UDID
+   */
+  async mount(imagePath, manifestPath, trustCachePath, udid) {
+    const [validatedImagePath, validatedManifestPath, validatedTrustCachePath] = await Promise.all([
+      this.validateFile(imagePath, 'Image (.dmg)'),
+      this.validateFile(manifestPath, 'Build Manifest (.plist)'),
+      this.validateFile(trustCachePath, 'Trust Cache (.trustcache)')
+    ]);
+
+    await this.withImageMounterService(udid, async (imageMounterService, deviceUdid) => {
+      log.info(`Mounting image on device: ${deviceUdid}`);
+
+      if (await imageMounterService.isPersonalizedImageMounted()) {
+        log.info('✅ Personalized image is already mounted on the device');
+        return;
+      }
+
+      await imageMounterService.mount(
+        validatedImagePath,
+        validatedManifestPath,
+        validatedTrustCachePath
+      );
+
+      log.info('✅ Image mounted successfully!');
+    });
+  }
+
+  /**
+   * Unmount image from device
+   * @param {string} [udid] - Device UDID
+   * @param {string} [mountPath='/System/Developer'] - Mount path to unmount
+   */
+  async unmount(udid, mountPath = '/System/Developer') {
+    await this.withImageMounterService(udid, async (imageMounterService, deviceUdid) => {
+      log.info(`Unmounting image from device: ${deviceUdid}`);
+      log.info(`Mount path: ${mountPath}`);
+
+      await imageMounterService.unmountImage(mountPath);
+      log.info('✅ Image unmounted successfully!');
+    });
+  }
+}
+
+/**
+ * CLI with Commander.js
+ */
+async function main() {
+  const program = new Command();
+  const imageMounter = new ImageMounter();
+
+  program
+    .name('appium driver run xcuitest image-mounter')
+    .description('Mount and unmount Developer Disk Images on iOS devices')
+    .version('1.0.0')
+    .addHelpText('after', `
+NOTE:
+  This script requires the 'appium-ios-remotexpc' package to be installed.
+  Install it using: npm install appium-ios-remotexpc`);
+
+  // Mount command
+  program
+    .command('mount')
+    .description('Mount a Developer Disk Image on iOS device')
+    .requiredOption('-i, --image <path>', 'Path to the .dmg image file')
+    .requiredOption('-m, --manifest <path>', 'Path to the BuildManifest.plist file')
+    .requiredOption('-t, --trustcache <path>', 'Path to the .trustcache file')
+    .option('-u, --udid <udid>', 'Target device UDID (optional, uses first device if not specified)')
+    .addHelpText('after', `
+EXAMPLES:
+  # Mount Developer Disk Image
+  appium driver run xcuitest image-mounter mount --image DeveloperDiskImage.dmg --manifest BuildManifest.plist --trustcache DeveloperDiskImage.trustcache
+
+  # Mount on specific device
+  appium driver run xcuitest image-mounter mount --image DeveloperDiskImage.dmg --manifest BuildManifest.plist --trustcache DeveloperDiskImage.trustcache --udid <udid>`)
+    .action(async (options) => {
+      await imageMounter.mount(
+        options.image,
+        options.manifest,
+        options.trustcache,
+        options.udid
+      );
+    });
+
+  // Unmount command
+  program
+    .command('unmount')
+    .description('Unmount a Developer Disk Image from iOS device')
+    .option('-u, --udid <udid>', 'Target device UDID (optional, uses first device if not specified)')
+    .option('-p, --mount-path <path>', 'Mount path to unmount', '/System/Developer')
+    .addHelpText('after', `
+EXAMPLES:
+  # Unmount from default path
+  appium driver run xcuitest image-mounter unmount
+
+  # Unmount from specific device
+  appium driver run xcuitest image-mounter unmount --udid <udid>`)
+    .action(async (options) => {
+      await imageMounter.unmount(
+        options.udid,
+        options.mountPath
+      );
+    });
+
+  await program.parseAsync(process.argv);
+}
+
+(async () => await main())();

package/scripts/open-wda.mjs

@@ -0,0 +1,15 @@
+import path from 'node:path';
+import { exec } from 'teen_process';
+import { logger } from 'appium/support.js';
+import { BOOTSTRAP_PATH } from 'appium-webdriveragent';
+
+const log = logger.getLogger('WDA');
+const XCODEPROJ_NAME = 'WebDriverAgent.xcodeproj';
+
+async function openWda() {
+  const dstPath = path.resolve(BOOTSTRAP_PATH, XCODEPROJ_NAME);
+  log.info(`Opening '${dstPath}'`);
+  await exec('open', [dstPath]);
+}
+
+(async () => await openWda())();