@appium/support 7.0.5 → 7.0.6

package/lib/plist.ts

@@ -0,0 +1,187 @@
+import xmlplist from 'plist';
+import bplistCreate from 'bplist-creator';
+import {parseFile, parseBuffer} from 'bplist-parser';
+import {fs} from './fs';
+import log from './logger';
+import _ from 'lodash';
+
+const BPLIST_IDENTIFIER = {
+  BUFFER: Buffer.from('bplist00'),
+  TEXT: 'bplist00',
+};
+const PLIST_IDENTIFIER = {
+  BUFFER: Buffer.from('<'),
+  TEXT: '<',
+};
+
+/**
+ * Parses a file in xml or binary format of plist
+ *
+ * @param plist - The plist file path
+ * @param mustExist - If set to false, this method will return an empty object when the file doesn't exist
+ * @param quiet - If set to false, the plist path will be logged in debug level
+ * @returns Parsed plist as a JS object
+ */
+export async function parsePlistFile(
+  plist: string,
+  mustExist = true,
+  quiet = true
+): Promise<object> {
+  if (!(await fs.exists(plist))) {
+    if (mustExist) {
+      throw log.errorWithException(`Plist file doesn't exist: '${plist}'`);
+    }
+    if (!quiet) {
+      log.debug(`Plist file '${plist}' does not exist. Returning an empty plist.`);
+    }
+    return {};
+  }
+
+  let obj: object = {};
+  let type = 'binary';
+  try {
+    const parsed = await parseFile(plist);
+    if (parsed.length) {
+      obj = parsed[0];
+    } else {
+      throw new Error(`Binary file '${plist}' appears to be empty`);
+    }
+  } catch {
+    try {
+      obj = await parseXmlPlistFile(plist);
+      type = 'xml';
+    } catch (err) {
+      throw log.errorWithException(
+        `Could not parse plist file '${plist}' as XML: ${(err as Error).message}`
+      );
+    }
+  }
+
+  if (!quiet) {
+    log.debug(`Parsed plist file '${plist}' as ${type}`);
+  }
+  return obj;
+}
+
+/**
+ * Updates a plist file with the given fields
+ *
+ * @param plist - The plist file path
+ * @param updatedFields - The updated fields-value pairs
+ * @param binary - If set to false, the file will be created as a xml plist
+ * @param mustExist - If set to false, this method will update an empty plist
+ * @param quiet - If set to false, the plist path will be logged in debug level
+ */
+export async function updatePlistFile(
+  plist: string,
+  updatedFields: object,
+  binary = true,
+  mustExist = true,
+  quiet = true
+): Promise<void> {
+  let obj: object;
+  try {
+    obj = await parsePlistFile(plist, mustExist);
+  } catch (err) {
+    throw log.errorWithException(`Could not update plist: ${(err as Error).message}`);
+  }
+  _.extend(obj, updatedFields);
+  const newPlist = binary ? bplistCreate(obj) : xmlplist.build(obj);
+  try {
+    await fs.writeFile(plist, newPlist);
+  } catch (err) {
+    throw log.errorWithException(`Could not save plist: ${(err as Error).message}`);
+  }
+  if (!quiet) {
+    log.debug(`Wrote plist file '${plist}'`);
+  }
+}
+
+/**
+ * Creates a binary plist Buffer from an object
+ *
+ * @param data - The object to be turned into a binary plist
+ * @returns Plist in the form of a binary buffer
+ */
+export function createBinaryPlist(data: object): Buffer {
+  return bplistCreate(data);
+}
+
+/**
+ * Parses a Buffer into an Object
+ *
+ * @param data - The buffer of a binary plist
+ * @returns Array of parsed root objects (typically one element)
+ */
+export function parseBinaryPlist(data: Buffer): object[] {
+  return parseBuffer(data);
+}
+
+/**
+ * Creates a plist from an object
+ *
+ * @param object - The JS object to be turned into a plist
+ * @param binary - Set it to true for a binary plist
+ * @returns A buffer or a string depending on the binary parameter
+ */
+export function createPlist(object: object, binary = false): Buffer | string {
+  if (binary) {
+    return createBinaryPlist(object);
+  }
+  return xmlplist.build(object);
+}
+
+/**
+ * Parses a buffer or string into a JS object
+ *
+ * @param data - The plist as a string or Buffer
+ * @returns Parsed plist as a JS object
+ * @throws Will throw an error if the plist type is unknown
+ */
+export function parsePlist(data: string | Buffer): object {
+  const textPlist = getXmlPlist(data);
+  if (textPlist) {
+    return xmlplist.parse(textPlist);
+  }
+
+  const binaryPlist = getBinaryPlist(data);
+  if (binaryPlist) {
+    return parseBinaryPlist(binaryPlist)[0];
+  }
+
+  throw new Error(
+    `Unknown type of plist, data: ${_.truncate(data.toString(), {length: 200})}`
+  );
+}
+
+async function parseXmlPlistFile(plistFilename: string): Promise<object> {
+  const xmlContent = await fs.readFile(plistFilename, 'utf8');
+  return xmlplist.parse(xmlContent);
+}
+
+function getXmlPlist(data: string | Buffer): string | null {
+  if (_.isString(data) && data.startsWith(PLIST_IDENTIFIER.TEXT)) {
+    return data;
+  }
+  if (
+    Buffer.isBuffer(data) &&
+    PLIST_IDENTIFIER.BUFFER.compare(data, 0, PLIST_IDENTIFIER.BUFFER.length) === 0
+  ) {
+    return data.toString();
+  }
+  return null;
+}
+
+function getBinaryPlist(data: string | Buffer): Buffer | null {
+  if (_.isString(data) && data.startsWith(BPLIST_IDENTIFIER.TEXT)) {
+    return Buffer.from(data);
+  }
+
+  if (
+    Buffer.isBuffer(data) &&
+    BPLIST_IDENTIFIER.BUFFER.compare(data, 0, BPLIST_IDENTIFIER.BUFFER.length) === 0
+  ) {
+    return data;
+  }
+  return null;
+}

package/lib/process.ts

@@ -0,0 +1,62 @@
+import {exec} from 'teen_process';
+import type {ExecError} from 'teen_process';
+
+/*
+ * Exit Status for pgrep and pkill (`man pkill`)
+ *  0. One or more processes matched the criteria.
+ *  1. No processes matched.
+ *  2. Syntax error in the command line.
+ *  3. Fatal error: out of memory etc.
+ */
+
+/**
+ * Get PIDs of processes whose executable name matches the given name (exact match via pgrep -x).
+ *
+ * @param appName - Executable name to match (e.g. 'tail', 'node').
+ * @returns Promise resolving to an array of process IDs. Empty if no processes matched.
+ * @throws {Error} If pgrep fails for any reason other than "no processes matched" (exit 1).
+ * @deprecated Use a process-management API or package that fits your platform instead.
+ */
+export async function getProcessIds(appName: string): Promise<number[]> {
+  let pids: number[];
+  try {
+    const {stdout} = await exec('pgrep', ['-x', appName]);
+    pids = stdout
+      .trim()
+      .split('\n')
+      .map((pid) => parseInt(pid, 10));
+  } catch (err) {
+    const code = (err as ExecError).code;
+    if (code !== 1) {
+      throw new Error(`Error getting process ids for app '${appName}': ${(err as Error).message}`);
+    }
+    pids = [];
+  }
+  return pids;
+}
+
+/**
+ * Kill all processes whose executable name matches the given name (via pkill -x).
+ *
+ * @param appName - Executable name to match (e.g. 'tail', 'node').
+ * @param force - If true, use SIGKILL (-9); otherwise use default pkill signal.
+ * @returns Promise that resolves when done, or when no matching processes were running.
+ * @throws {Error} If pkill fails for any reason other than "no processes matched" (exit 1).
+ * @deprecated Use a process-management API or package that fits your platform instead.
+ */
+export async function killProcess(appName: string, force = false): Promise<void> {
+  const pids = await getProcessIds(appName);
+  if (pids.length === 0) {
+    return;
+  }
+
+  try {
+    const args = force ? ['-9', '-x', appName] : ['-x', appName];
+    await exec('pkill', args);
+  } catch (err) {
+    const code = (err as ExecError).code;
+    if (code !== 1) {
+      throw new Error(`Error killing app '${appName}' with pkill: ${(err as Error).message}`);
+    }
+  }
+}

package/lib/system.ts

@@ -0,0 +1,95 @@
+import {exec} from 'teen_process';
+import _ from 'lodash';
+import os from 'node:os';
+
+const VERSION_PATTERN = /^(\d+\.\d+)/m;
+
+/**
+ * Whether the current OS is Windows.
+ */
+export function isWindows(): boolean {
+  return os.type() === 'Windows_NT';
+}
+
+/**
+ * Whether the current OS is macOS (Darwin).
+ */
+export function isMac(): boolean {
+  return os.type() === 'Darwin';
+}
+
+/**
+ * Whether the current OS is Linux (i.e. not Windows and not macOS).
+ */
+export function isLinux(): boolean {
+  return !isWindows() && !isMac();
+}
+
+/**
+ * Whether the current Windows process is 64-bit (or WOW64).
+ */
+export function isOSWin64(): boolean {
+  return process.arch === 'x64' || _.has(process.env, 'PROCESSOR_ARCHITEW6432');
+}
+
+/**
+ * Detects the major.minor macOS version (e.g. "10.12") via `sw_vers -productVersion`.
+ *
+ * @returns The major.minor version string.
+ * @throws {Error} If `sw_vers` fails or output cannot be parsed.
+ */
+export async function macOsxVersion(): Promise<string> {
+  let stdout: string;
+  try {
+    stdout = (await exec('sw_vers', ['-productVersion'])).stdout.trim();
+  } catch (err) {
+    throw new Error(`Could not detect Mac OS X Version: ${err}`);
+  }
+
+  const versionMatch = VERSION_PATTERN.exec(stdout);
+  if (!versionMatch) {
+    throw new Error(`Could not detect Mac OS X Version from sw_vers output: '${stdout}'`);
+  }
+  return versionMatch[1];
+}
+
+/**
+ * System detection helpers (platform, architecture, macOS version).
+ * Use this object when you need `arch()` to call other helpers via `this` (e.g. for testing).
+ */
+export const system: System = {
+  isWindows,
+  isMac,
+  isLinux,
+  isOSWin64,
+  arch: archImpl,
+  macOsxVersion,
+};
+
+/**
+ * Resolves the process architecture as `'32'` or `'64'` (uname on Unix, process.arch/env on Windows).
+ */
+export const arch = system.arch;
+
+// #region Private
+
+interface System {
+  isWindows(): boolean;
+  isMac(): boolean;
+  isLinux(): boolean;
+  isOSWin64(): boolean;
+  arch(): Promise<string>;
+  macOsxVersion(): Promise<string>;
+}
+
+async function archImpl(this: System): Promise<string> {
+  if (this.isLinux() || this.isMac()) {
+    const {stdout} = await exec('uname', ['-m']);
+    return stdout.trim() === 'i686' ? '32' : '64';
+  } else if (this.isWindows()) {
+    return this.isOSWin64() ? '64' : '32';
+  }
+  return '64';
+}
+
+// #endregion

package/lib/tempdir.ts

@@ -0,0 +1,115 @@
+/* This library is originated from temp.js at http://github.com/bruce/node-temp */
+import {fs} from './fs';
+import os from 'node:os';
+import nodePath from 'node:path';
+import _ from 'lodash';
+import {constants} from 'node:fs';
+import log from './logger';
+
+const RDWR_EXCL = constants.O_CREAT | constants.O_TRUNC | constants.O_RDWR | constants.O_EXCL;
+
+/** Prefix/suffix for temp directory or file names */
+export interface Affixes {
+  prefix?: string;
+  suffix?: string;
+}
+
+/** Result of opening a temp file */
+export interface OpenedAffixes {
+  path: string;
+  fd: number;
+}
+
+/**
+ * Generate a temporary directory with arbitrary prefix/suffix for the directory name.
+ *
+ * @param rawAffixes - Prefix string, or object with prefix/suffix, or omitted.
+ * @param defaultPrefix - Default prefix when rawAffixes is omitted.
+ * @returns A path to the temporary directory.
+ */
+export async function path(
+  rawAffixes?: string | Affixes,
+  defaultPrefix?: string
+): Promise<string> {
+  const affixes = parseAffixes(rawAffixes, defaultPrefix);
+  const name = `${affixes.prefix ?? ''}${affixes.suffix ?? ''}`;
+  const tempDirectory = await tempDir();
+  return nodePath.join(tempDirectory, name);
+}
+
+/**
+ * Generate a temp file path with prefix/suffix, open the file, and return path and fd.
+ *
+ * @param affixes - Prefix/suffix for the file name.
+ * @returns The opened file path and descriptor.
+ */
+export async function open(affixes: Affixes): Promise<OpenedAffixes> {
+  const filePath = await path(affixes, 'f-');
+  try {
+    const fd = await fs.open(filePath, RDWR_EXCL, 0o600);
+    return {path: filePath, fd};
+  } catch (err) {
+    throw log.errorWithException(err as Error);
+  }
+}
+
+/** Returns a new path to a temporary directory (alias for the tempDir implementation). */
+export const openDir = tempDir;
+
+/**
+ * Returns a path to a temporary directory which is reused for the life of the process.
+ *
+ * @returns The same temp directory path on every call.
+ */
+export const staticDir = _.memoize(async function staticDir (): Promise<string> {
+  return tempDir();
+});
+
+// #region Private
+
+/**
+ * Generate a temporary directory in os.tmpdir() or process.env.APPIUM_TMP_DIR.
+ */
+async function tempDir(): Promise<string> {
+  const now = new Date();
+  const filePath = nodePath.join(
+    process.env.APPIUM_TMP_DIR || os.tmpdir(),
+    [
+      now.getFullYear(),
+      now.getMonth(),
+      now.getDate(),
+      '-',
+      process.pid,
+      '-',
+      (Math.random() * 0x100000000 + 1).toString(36),
+    ].join('')
+  );
+
+  await fs.mkdir(filePath, {recursive: true});
+
+  return filePath;
+}
+
+function parseAffixes(
+  rawAffixes?: string | Affixes,
+  defaultPrefix?: string
+): Affixes {
+  let affixes: Affixes = {};
+  if (rawAffixes !== undefined && rawAffixes !== null) {
+    switch (typeof rawAffixes) {
+      case 'string':
+        affixes = {prefix: rawAffixes};
+        break;
+      case 'object':
+        affixes = rawAffixes;
+        break;
+      default:
+        throw new Error(`Unknown affix declaration: ${String(rawAffixes)}`);
+    }
+  } else {
+    affixes.prefix = defaultPrefix;
+  }
+  return affixes;
+}
+
+// #endregion

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

@@ -3,15 +3,16 @@ import _ from 'lodash';
 const NS_PER_S = 1e9;
 const NS_PER_MS = 1e6;
 
+/** High-resolution start time: tuple from process.hrtime() or bigint from process.hrtime.bigint() */
+type HrTime = [number, number] | bigint;
+
 /**
  * Class representing a duration, encapsulating the number and units.
  */
-class Duration {
-  constructor(nanos) {
-    this._nanos = nanos;
-  }
+export class Duration {
+  constructor(private _nanos: number) {}
 
-  get nanos() {
+  get nanos(): number {
     return this._nanos;
   }
 
@@ -20,7 +21,7 @@ class Duration {
    *
    * @returns {number} The duration as nanoseconds
    */
-  get asNanoSeconds() {
+  get asNanoSeconds(): number {
     return this.nanos;
   }
 
@@ -29,7 +30,7 @@ class Duration {
    *
    * @returns {number} The duration as milliseconds
    */
-  get asMilliSeconds() {
+  get asMilliSeconds(): number {
     return this.nanos / NS_PER_MS;
   }
 
@@ -38,25 +39,23 @@ class Duration {
    *
    * @returns {number} The duration fas seconds
    */
-  get asSeconds() {
+  get asSeconds(): number {
     return this.nanos / NS_PER_S;
   }
 
-  toString() {
+  toString(): string {
     // default to milliseconds, rounded
     return this.asMilliSeconds.toFixed(0);
   }
 }
 
-class Timer {
+export class Timer {
   /**
    * Creates a timer
    */
-  constructor() {
-    this._startTime = null;
-  }
+  constructor(private _startTime: HrTime | null = null) {}
 
-  get startTime() {
+  get startTime(): HrTime | null {
     return this._startTime;
   }
 
@@ -65,14 +64,11 @@ class Timer {
    *
    * @return {Timer} The current instance, for chaining
    */
-  start() {
-    if (!_.isNull(this.startTime)) {
+  start(): this {
+    if (!_.isNull(this._startTime)) {
       throw new Error('Timer has already been started.');
     }
-    // once Node 10 is no longer supported, this check can be removed
-    this._startTime = _.isFunction(process.hrtime.bigint)
-      ? process.hrtime.bigint()
-      : process.hrtime();
+    this._startTime = process.hrtime.bigint();
     return this;
   }
 
@@ -81,36 +77,35 @@ class Timer {
    *
    * @return {Duration} the duration
    */
-  getDuration() {
-    if (_.isNull(this.startTime)) {
-      throw new Error(`Unable to get duration. Timer was not started`);
+  getDuration(): Duration {
+    if (_.isNull(this._startTime)) {
+      throw new Error('Unable to get duration. Timer was not started');
     }
 
-    let nanoDuration;
-    if (_.isArray(this.startTime)) {
+    let nanoDuration: number;
+    if (_.isArray(this._startTime)) {
       // startTime was created using process.hrtime()
-      const [seconds, nanos] = process.hrtime(this.startTime);
+      const [seconds, nanos] = process.hrtime(this._startTime as [number, number]);
       nanoDuration = seconds * NS_PER_S + nanos;
-    } else if (typeof this.startTime === 'bigint' && _.isFunction(process.hrtime.bigint)) {
+    } else if (typeof this._startTime === 'bigint') {
       // startTime was created using process.hrtime.bigint()
       const endTime = process.hrtime.bigint();
       // get the difference, and convert to number
-      nanoDuration = Number(endTime - this.startTime);
+      nanoDuration = Number(endTime - this._startTime);
     } else {
-      throw new Error(`Unable to get duration. Start time '${this.startTime}' cannot be parsed`);
+      throw new Error(`Unable to get duration. Start time '${this._startTime}' cannot be parsed`);
     }
 
     return new Duration(nanoDuration);
   }
 
-  toString() {
+  toString(): string {
     try {
       return this.getDuration().toString();
     } catch (err) {
-      return `<err: ${err.message}>`;
+      return `<err: ${(err as Error).message}>`;
     }
   }
 }
 
-export {Timer, Duration};
-export default Timer;
+export {Timer as default};