appium-webdriveragent 10.5.4 → 11.0.0

package/lib/{utils.js → utils.ts}

@@ -1,24 +1,34 @@
 import { fs, plist } from '@appium/support';
-import { exec } from 'teen_process';
-import path from 'path';
-import log from './logger';
+import { exec, SubProcess } from 'teen_process';
+import path, { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { log } from './logger';
 import _ from 'lodash';
 import { WDA_RUNNER_BUNDLE_ID, PLATFORM_NAME_TVOS } from './constants';
 import B from 'bluebird';
-import _fs from 'fs';
+import _fs from 'node:fs';
 import { waitForCondition } from 'asyncbox';
-import { arch } from 'os';
+import { arch } from 'node:os';
+import type { DeviceInfo } from './types';
 
 const PROJECT_FILE = 'project.pbxproj';
 
+// Get current filename - works in both CommonJS and ESM
+const currentFilename =
+  typeof __filename !== 'undefined'
+    ? __filename
+    : fileURLToPath(new Function('return import.meta.url')());
+
+const currentDirname = dirname(currentFilename);
+
 /**
  * Calculates the path to the current module's root folder
  *
  * @returns {string} The full path to module root
  * @throws {Error} If the current module root folder cannot be determined
  */
-const getModuleRoot = _.memoize(function getModuleRoot () {
-  let currentDir = path.dirname(path.resolve(__filename));
+const getModuleRoot = _.memoize(function getModuleRoot (): string {
+  let currentDir = currentDirname;
   let isAtFsRoot = false;
   while (!isAtFsRoot) {
     const manifestPath = path.join(currentDir, 'package.json');
@@ -36,24 +46,7 @@ const getModuleRoot = _.memoize(function getModuleRoot () {
 
 export const BOOTSTRAP_PATH = getModuleRoot();
 
-async function getPIDsUsingPattern (pattern) {
-  const args = [
-    '-if', // case insensitive, full cmdline match
-    pattern,
-  ];
-  try {
-    const {stdout} = await exec('pgrep', args);
-    return stdout.split(/\s+/)
-      .map((x) => parseInt(x, 10))
-      .filter(_.isInteger)
-      .map((x) => `${x}`);
-  } catch (err) {
-    log.debug(`'pgrep ${args.join(' ')}' didn't detect any matching processes. Return code: ${err.code}`);
-    return [];
-  }
-}
-
-async function killAppUsingPattern (pgrepPattern) {
+export async function killAppUsingPattern (pgrepPattern: string): Promise<void> {
   const signals = [2, 15, 9];
   for (const signal of signals) {
     const matchedPids = await getPIDsUsingPattern(pgrepPattern);
@@ -63,7 +56,7 @@ async function killAppUsingPattern (pgrepPattern) {
     const args = [`-${signal}`, ...matchedPids];
     try {
       await exec('kill', args);
-    } catch (err) {
+    } catch (err: any) {
       log.debug(`kill ${args.join(' ')} -> ${err.message}`);
     }
     if (signal === _.last(signals)) {
@@ -94,36 +87,27 @@ async function killAppUsingPattern (pgrepPattern) {
 
 /**
  * Return true if the platformName is tvOS
- * @param {string} platformName The name of the platorm
- * @returns {boolean} Return true if the platformName is tvOS
+ * @param platformName The name of the platorm
+ * @returns Return true if the platformName is tvOS
  */
-function isTvOS (platformName) {
+export function isTvOS (platformName: string): boolean {
   return _.toLower(platformName) === _.toLower(PLATFORM_NAME_TVOS);
 }
 
-async function replaceInFile (file, find, replace) {
-  let contents = await fs.readFile(file, 'utf8');
-
-  let newContents = contents.replace(find, replace);
-  if (newContents !== contents) {
-    await fs.writeFile(file, newContents, 'utf8');
-  }
-}
-
 /**
  * Update WebDriverAgentRunner project bundle ID with newBundleId.
  * This method assumes project file is in the correct state.
- * @param {string} agentPath - Path to the .xcodeproj directory.
- * @param {string} newBundleId the new bundle ID used to update.
+ * @param agentPath - Path to the .xcodeproj directory.
+ * @param newBundleId the new bundle ID used to update.
  */
-async function updateProjectFile (agentPath, newBundleId) {
-  let projectFilePath = path.resolve(agentPath, PROJECT_FILE);
+export async function updateProjectFile (agentPath: string, newBundleId: string): Promise<void> {
+  const projectFilePath = path.resolve(agentPath, PROJECT_FILE);
   try {
     // Assuming projectFilePath is in the correct state, create .old from projectFilePath
     await fs.copyFile(projectFilePath, `${projectFilePath}.old`);
     await replaceInFile(projectFilePath, new RegExp(_.escapeRegExp(WDA_RUNNER_BUNDLE_ID), 'g'), newBundleId);
     log.debug(`Successfully updated '${projectFilePath}' with bundle id '${newBundleId}'`);
-  } catch (err) {
+  } catch (err: any) {
     log.debug(`Error updating project file: ${err.message}`);
     log.warn(`Unable to update project file '${projectFilePath}' with ` +
       `bundle id '${newBundleId}'. WebDriverAgent may not start`);
@@ -132,9 +116,9 @@ async function updateProjectFile (agentPath, newBundleId) {
 
 /**
  * Reset WebDriverAgentRunner project bundle ID to correct state.
- * @param {string} agentPath - Path to the .xcodeproj directory.
+ * @param agentPath - Path to the .xcodeproj directory.
  */
-async function resetProjectFile (agentPath) {
+export async function resetProjectFile (agentPath: string): Promise<void> {
   const projectFilePath = path.join(agentPath, PROJECT_FILE);
   try {
     // restore projectFilePath from .old file
@@ -143,7 +127,7 @@ async function resetProjectFile (agentPath) {
     }
     await fs.mv(`${projectFilePath}.old`, projectFilePath);
     log.debug(`Successfully reset '${projectFilePath}' with bundle id '${WDA_RUNNER_BUNDLE_ID}'`);
-  } catch (err) {
+  } catch (err: any) {
     log.debug(`Error resetting project file: ${err.message}`);
     log.warn(`Unable to reset project file '${projectFilePath}' with ` +
       `bundle id '${WDA_RUNNER_BUNDLE_ID}'. WebDriverAgent has been ` +
@@ -151,27 +135,24 @@ async function resetProjectFile (agentPath) {
   }
 }
 
-async function setRealDeviceSecurity (keychainPath, keychainPassword) {
+export async function setRealDeviceSecurity (keychainPath: string, keychainPassword: string): Promise<void> {
   log.debug('Setting security for iOS device');
   await exec('security', ['-v', 'list-keychains', '-s', keychainPath]);
   await exec('security', ['-v', 'unlock-keychain', '-p', keychainPassword, keychainPath]);
   await exec('security', ['set-keychain-settings', '-t', '3600', '-l', keychainPath]);
 }
 
-/**
- * Information of the device under test
- * @typedef {import('./types').DeviceInfo} DeviceInfo
- */
-
 /**
  * Arguments for setting xctestrun file
- * @typedef {Object} XctestrunFileArgs
- * @property {DeviceInfo} deviceInfo - Information of the device under test
- * @property {string} sdkVersion - The Xcode SDK version of OS.
- * @property {string} bootstrapPath - The folder path containing xctestrun file.
- * @property {number|string} wdaRemotePort - The remote port WDA is listening on.
- * @property {string} [wdaBindingIP] - The IP address to bind to. If not given, it binds to all interfaces.
  */
+export interface XctestrunFileArgs {
+  deviceInfo: DeviceInfo;
+  sdkVersion: string;
+  bootstrapPath: string;
+  wdaRemotePort: number | string;
+  wdaBindingIP?: string;
+}
+
 /**
  * Creates xctestrun file per device & platform version.
  * We expects to have WebDriverAgentRunner_iphoneos${sdkVersion|platformVersion}-arm64.xctestrun for real device
@@ -180,13 +161,13 @@ async function setRealDeviceSecurity (keychainPath, keychainPassword) {
  * e.g. Xcode which has iOS SDK Version 12.2 on an intel Mac host machine generates WebDriverAgentRunner_iphonesimulator.2-x86_64.xctestrun
  *      even if the cap has platform version 11.4
  *
- * @param {XctestrunFileArgs} args
- * @return {Promise<string>} returns xctestrunFilePath for given device
+ * @param args
+ * @return returns xctestrunFilePath for given device
  * @throws if WebDriverAgentRunner_iphoneos${sdkVersion|platformVersion}-arm64.xctestrun for real device
  * or WebDriverAgentRunner_iphonesimulator${sdkVersion|platformVersion}-x86_64.xctestrun for simulator is not found @bootstrapPath,
  * then it will throw a file not found exception
  */
-async function setXctestrunFile (args) {
+export async function setXctestrunFile (args: XctestrunFileArgs): Promise<string> {
   const {deviceInfo, sdkVersion, bootstrapPath, wdaRemotePort, wdaBindingIP} = args;
   const xctestrunFilePath = await getXctestrunFilePath(deviceInfo, sdkVersion, bootstrapPath);
   const xctestRunContent = await plist.parsePlistFile(xctestrunFilePath);
@@ -199,12 +180,12 @@ async function setXctestrunFile (args) {
 
 /**
  * Return the WDA object which appends existing xctest runner content
- * @param {string} platformName - The name of the platform
- * @param {number|string} wdaRemotePort - The remote port number
- * @param {string} [wdaBindingIP] - The IP address to bind to. If not given, it binds to all interfaces.
- * @return {object} returns a runner object which has USE_PORT and optionally USE_IP
+ * @param platformName - The name of the platform
+ * @param wdaRemotePort - The remote port number
+ * @param wdaBindingIP - The IP address to bind to. If not given, it binds to all interfaces.
+ * @return returns a runner object which has USE_PORT and optionally USE_IP
  */
-function getAdditionalRunContent (platformName, wdaRemotePort, wdaBindingIP) {
+export function getAdditionalRunContent (platformName: string, wdaRemotePort: number | string, wdaBindingIP?: string): Record<string, any> {
   const runner = `WebDriverAgentRunner${isTvOS(platformName) ? '_tvOS' : ''}`;
   return {
     [runner]: {
@@ -219,19 +200,18 @@ function getAdditionalRunContent (platformName, wdaRemotePort, wdaBindingIP) {
 
 /**
  * Return the path of xctestrun if it exists
- * @param {DeviceInfo} deviceInfo
- * @param {string} sdkVersion - The Xcode SDK version of OS.
- * @param {string} bootstrapPath - The folder path containing xctestrun file.
- * @returns {Promise<string>}
+ * @param deviceInfo
+ * @param sdkVersion - The Xcode SDK version of OS.
+ * @param bootstrapPath - The folder path containing xctestrun file.
  */
-async function getXctestrunFilePath (deviceInfo, sdkVersion, bootstrapPath) {
+export async function getXctestrunFilePath (deviceInfo: DeviceInfo, sdkVersion: string, bootstrapPath: string): Promise<string> {
   // First try the SDK path, for Xcode 10 (at least)
-  const sdkBased = [
+  const sdkBased: [string, string] = [
     path.resolve(bootstrapPath, `${deviceInfo.udid}_${sdkVersion}.xctestrun`),
     sdkVersion,
   ];
   // Next try Platform path, for earlier Xcode versions
-  const platformBased = [
+  const platformBased: [string, string] = [
     path.resolve(bootstrapPath, `${deviceInfo.udid}_${deviceInfo.platformVersion}.xctestrun`),
     deviceInfo.platformVersion,
   ];
@@ -261,11 +241,11 @@ async function getXctestrunFilePath (deviceInfo, sdkVersion, bootstrapPath) {
 
 /**
  * Return the name of xctestrun file
- * @param {DeviceInfo} deviceInfo
- * @param {string} version - The Xcode SDK version of OS.
- * @return {string} returns xctestrunFilePath for given device
+ * @param deviceInfo
+ * @param version - The Xcode SDK version of OS.
+ * @return returns xctestrunFilePath for given device
  */
-function getXctestrunFileName (deviceInfo, version) {
+export function getXctestrunFileName (deviceInfo: DeviceInfo, version: string): string {
   const archSuffix = deviceInfo.isRealDevice
     ? `os${version}-arm64`
     : `simulator${version}-${arch() === 'arm64' ? 'arm64' : 'x86_64'}`;
@@ -274,12 +254,8 @@ function getXctestrunFileName (deviceInfo, version) {
 
 /**
  * Ensures the process is killed after the timeout
- *
- * @param {string} name
- * @param {import('teen_process').SubProcess} proc
- * @returns {Promise<void>}
  */
-async function killProcess (name, proc) {
+export async function killProcess (name: string, proc: SubProcess | null | undefined): Promise<void> {
   if (!proc || !proc.isRunning) {
     return;
   }
@@ -290,7 +266,7 @@ async function killProcess (name, proc) {
   try {
     await proc.stop('SIGTERM', 1000);
     return;
-  } catch (err) {
+  } catch (err: any) {
     if (!err.message.includes(`Process didn't end after`)) {
       throw err;
     }
@@ -300,7 +276,7 @@ async function killProcess (name, proc) {
   log.info(`Sending 'SIGKILL'...`);
   try {
     await proc.stop('SIGKILL');
-  } catch (err) {
+  } catch (err: any) {
     if (err.message.includes('not currently running')) {
       // the process ended but for some reason we were not informed
       return;
@@ -310,21 +286,16 @@ async function killProcess (name, proc) {
 }
 
 /**
- * Generate a random integer.
- *
- * @return {number} A random integer number in range [low, hight). `low`` is inclusive and `high` is exclusive.
+ * Generate a random integer in range [low, high). `low` is inclusive and `high` is exclusive.
  */
-function randomInt (low, high) {
+export function randomInt (low: number, high: number): number {
   return Math.floor(Math.random() * (high - low) + low);
 }
 
 /**
- * Retrieves WDA upgrade timestamp
- *
- * @return {Promise<number?>} The UNIX timestamp of the package manifest. The manifest only gets modified on
- * package upgrade.
+ * Retrieves WDA upgrade timestamp. The manifest only gets modified on package upgrade.
  */
-async function getWDAUpgradeTimestamp () {
+export async function getWDAUpgradeTimestamp (): Promise<number | null> {
   const packageManifest = path.resolve(getModuleRoot(), 'package.json');
   if (!await fs.exists(packageManifest)) {
     return null;
@@ -335,11 +306,8 @@ async function getWDAUpgradeTimestamp () {
 
 /**
  * Kills running XCTest processes for the particular device.
- *
- * @param {string} udid - The device UDID.
- * @param {boolean} isSimulator - Equals to true if the current device is a Simulator
  */
-async function resetTestProcesses (udid, isSimulator) {
+export async function resetTestProcesses (udid: string, isSimulator: boolean): Promise<void> {
   const processPatterns = [`xcodebuild.*${udid}`];
   if (isSimulator) {
     processPatterns.push(`${udid}.*XCTRunner`);
@@ -355,21 +323,21 @@ async function resetTestProcesses (udid, isSimulator) {
  * It is also possible to apply additional filtering based on the
  * process command line.
  *
- * @param {string|number} port - The port number.
- * @param {?Function} filteringFunc - Optional lambda function, which
+ * @param port - The port number.
+ * @param filteringFunc - Optional lambda function, which
  *                                    receives command line string of the particular process
  *                                    listening on given port, and is expected to return
  *                                    either true or false to include/exclude the corresponding PID
  *                                    from the resulting array.
- * @returns {Promise<string[]>} - the list of matched process ids.
+ * @returns - the list of matched process ids.
  */
-async function getPIDsListeningOnPort (port, filteringFunc = null) {
-  const result = [];
+export async function getPIDsListeningOnPort (port: string | number, filteringFunc: ((cmdline: string) => boolean | Promise<boolean>) | null = null): Promise<string[]> {
+  const result: string[] = [];
   try {
     // This only works since Mac OS X El Capitan
     const {stdout} = await exec('lsof', ['-ti', `tcp:${port}`]);
     result.push(...(stdout.trim().split(/\n+/)));
-  } catch (e) {
+  } catch (e: any) {
     if (e.code !== 1) {
       // code 1 means no processes. Other errors need reporting
       log.debug(`Error getting processes listening on port '${port}': ${e.stderr || e.message}`);
@@ -381,10 +349,10 @@ async function getPIDsListeningOnPort (port, filteringFunc = null) {
     return result;
   }
   return await B.filter(result, async (pid) => {
-    let stdout;
+    let stdout: string;
     try {
       ({stdout} = await exec('ps', ['-p', pid, '-o', 'command']));
-    } catch (e) {
+    } catch (e: any) {
       if (e.code === 1) {
         // The process does not exist anymore, there's nothing to filter
         return false;
@@ -395,9 +363,31 @@ async function getPIDsListeningOnPort (port, filteringFunc = null) {
   });
 }
 
-export { updateProjectFile, resetProjectFile, setRealDeviceSecurity,
-  getAdditionalRunContent, getXctestrunFileName,
-  setXctestrunFile, getXctestrunFilePath, killProcess, randomInt,
-  getWDAUpgradeTimestamp, resetTestProcesses,
-  getPIDsListeningOnPort, killAppUsingPattern, isTvOS
-};
+// Private functions
+
+async function getPIDsUsingPattern (pattern: string): Promise<string[]> {
+  const args = [
+    '-if', // case insensitive, full cmdline match
+    pattern,
+  ];
+  try {
+    const {stdout} = await exec('pgrep', args);
+    return stdout.split(/\s+/)
+      .map((x) => parseInt(x, 10))
+      .filter(_.isInteger)
+      .map((x) => `${x}`);
+  } catch (err: any) {
+    log.debug(`'pgrep ${args.join(' ')}' didn't detect any matching processes. Return code: ${err.code}`);
+    return [];
+  }
+}
+
+async function replaceInFile (file: string, find: string | RegExp, replace: string): Promise<void> {
+  const contents = await fs.readFile(file, 'utf8');
+
+  const newContents = contents.replace(find, replace);
+  if (newContents !== contents) {
+    await fs.writeFile(file, newContents, 'utf8');
+  }
+}
+