@appium/support 2.55.3 → 2.56.1

package/lib/node.js

@@ -1,7 +1,15 @@
 import { isWindows } from './system';
 import log from './logger';
+import _ from 'lodash';
 import { exec } from 'teen_process';
 import path from 'path';
+import { v4 as uuidV4 } from 'uuid';
+
+const ECMA_SIZES = Object.freeze({
+  STRING: 2,
+  BOOLEAN: 4,
+  NUMBER: 8,
+});
 
 /**
  * Internal utility to link global package to local context
@@ -63,4 +71,99 @@ async function requirePackage (packageName) {
   }
 }
 
-export { requirePackage };
+function extractAllProperties (obj) {
+  const stringProperties = [];
+  for (const prop in obj) {
+    stringProperties.push(prop);
+  }
+  if (_.isFunction(Object.getOwnPropertySymbols)) {
+    stringProperties.push(...(Object.getOwnPropertySymbols(obj)));
+  }
+  return stringProperties;
+}
+
+function _getSizeOfObject (seen, object) {
+  if (_.isNil(object)) {
+    return 0;
+  }
+
+  let bytes = 0;
+  const properties = extractAllProperties(object);
+  for (const key of properties) {
+    // Do not recalculate circular references
+    if (typeof object[key] === 'object' && !_.isNil(object[key])) {
+      if (seen.has(object[key])) {
+        continue;
+      }
+      seen.add(object[key]);
+    }
+
+    bytes += getCalculator(seen)(key);
+    try {
+      bytes += getCalculator(seen)(object[key]);
+    } catch (ex) {
+      if (ex instanceof RangeError) {
+        // circular reference detected, final result might be incorrect
+        // let's be nice and not throw an exception
+        bytes = 0;
+      }
+    }
+  }
+
+  return bytes;
+}
+
+function getCalculator (seen) {
+  return function calculator (obj) {
+    if (_.isBuffer(obj)) {
+      return obj.length;
+    }
+
+    switch (typeof (obj)) {
+      case 'string':
+        return obj.length * ECMA_SIZES.STRING;
+      case 'boolean':
+        return ECMA_SIZES.BOOLEAN;
+      case 'number':
+        return ECMA_SIZES.NUMBER;
+      case 'symbol':
+        return _.isFunction(Symbol.keyFor) && Symbol.keyFor(obj)
+          ? Symbol.keyFor(obj).length * ECMA_SIZES.STRING
+          : (obj.toString().length - 8) * ECMA_SIZES.STRING;
+      case 'object':
+        return _.isArray(obj)
+          ? obj.map(getCalculator(seen)).reduce((acc, curr) => acc + curr, 0)
+          : _getSizeOfObject(seen, obj);
+      default:
+        return 0;
+    }
+  };
+}
+
+/**
+ * Calculate the in-depth size in memory of the provided object.
+ * The original implementation is borrowed from https://github.com/miktam/sizeof.
+ *
+ * @param {*} obj An object whose size should be calculated
+ * @returns {number} Object size in bytes.
+ */
+function getObjectSize (obj) {
+  return getCalculator(new WeakSet())(obj);
+}
+
+const OBJECTS_MAPPING = new WeakMap();
+
+/**
+ * Calculates a unique object identifier
+ *
+ * @param {object} object Any valid ECMA object
+ * @returns {string} A uuidV4 string that uniquely identifies given object
+ */
+function getObjectId (object) {
+  if (!OBJECTS_MAPPING.has(object)) {
+    OBJECTS_MAPPING.set(object, uuidV4());
+  }
+  return OBJECTS_MAPPING.get(object);
+}
+
+export { requirePackage, getObjectSize, getObjectId };

package/lib/npm.js

@@ -0,0 +1,335 @@
+// @ts-check
+
+import path from 'path';
+import semver from 'semver';
+import { exec } from 'teen_process';
+import { fs } from './fs';
+import * as util from './util';
+import * as system from './system';
+import resolveFrom from 'resolve-from';
+
+
+/**
+ * Relative path to directory containing any Appium internal files
+ * XXX: this is duplicated in `appium/lib/constants.js`.
+ */
+export const CACHE_DIR_RELATIVE_PATH = path.join(
+  'node_modules',
+  '.cache',
+  'appium',
+);
+
+/**
+ * Relative path to lockfile used when installing an extension via `appium`
+ */
+export const INSTALL_LOCKFILE_RELATIVE_PATH = path.join(
+  CACHE_DIR_RELATIVE_PATH,
+  '.install.lock',
+);
+
+/**
+ * Relative path to lockfile used when linking an extension via `appium`
+ */
+export const LINK_LOCKFILE_RELATIVE_PATH = path.join(
+  CACHE_DIR_RELATIVE_PATH,
+  '.link.lock',
+);
+
+/**
+ * XXX: This should probably be a singleton, but it isn't.  Maybe this module should just export functions?
+ */
+export class NPM {
+  /**
+   * Returns path to "install" lockfile
+   * @private
+   * @param {string} cwd
+   */
+  _getInstallLockfilePath (cwd) {
+    return path.join(cwd, INSTALL_LOCKFILE_RELATIVE_PATH);
+  }
+
+  /**
+   * Returns path to "link" lockfile
+   * @private
+   * @param {string} cwd
+   */
+  _getLinkLockfilePath (cwd) {
+    return path.join(cwd, LINK_LOCKFILE_RELATIVE_PATH);
+  }
+
+  /**
+   * Execute `npm` with given args.
+   *
+   * If the process exits with a nonzero code, the contents of `STDOUT` and `STDERR` will be in the
+   * `message` of the {@link TeenProcessExecError} rejected.
+   * @param {string} cmd
+   * @param {string[]} args
+   * @param {ExecOpts} opts
+   * @param {TeenProcessExecOpts} [execOpts]
+   */
+  async exec (cmd, args, opts, execOpts = {}) {
+    let { cwd, json, lockFile } = opts;
+
+    // make sure we perform the current operation in cwd
+    execOpts = {...execOpts, cwd};
+
+    args.unshift(cmd);
+    if (json) {
+      args.push('--json');
+    }
+    const npmCmd = system.isWindows() ? 'npm.cmd' : 'npm';
+    let runner = async () => await exec(npmCmd, args, execOpts);
+    if (lockFile) {
+      const acquireLock = util.getLockFileGuard(lockFile);
+      const _runner = runner;
+      runner = async () => await acquireLock(_runner);
+    }
+
+    let ret;
+    try {
+      const {stdout, stderr, code} = await runner();
+      ret = /** @type {TeenProcessExecResult} */({stdout, stderr, code});
+      // if possible, parse NPM's json output. During NPM install 3rd-party
+      // packages can write to stdout, so sometimes the json output can't be
+      // guaranteed to be parseable
+      try {
+        ret.json = JSON.parse(stdout);
+      } catch (ign) {}
+    } catch (e) {
+      const {stdout = '', stderr = '', code = null} = /** @type {TeenProcessExecError} */(e);
+      const err = new Error(`npm command '${args.join(' ')}' failed with code ${code}.\n\nSTDOUT:\n${stdout.trim()}\n\nSTDERR:\n${stderr.trim()}`);
+      throw err;
+    }
+    return ret;
+  }
+
+  /**
+   * @param {string} cwd
+   * @param {string} pkg
+   */
+  async getLatestVersion (cwd, pkg) {
+    return (await this.exec('view', [pkg, 'dist-tags'], {
+      json: true,
+      cwd
+    })).json?.latest;
+  }
+
+  /**
+   * @param {string} cwd
+   * @param {string} pkg
+   * @param {string} curVersion
+   */
+  async getLatestSafeUpgradeVersion (cwd, pkg, curVersion) {
+    const allVersions = (await this.exec('view', [pkg, 'versions'], {
+      json: true,
+      cwd
+    })).json;
+    return this.getLatestSafeUpgradeFromVersions(curVersion, allVersions);
+  }
+
+  /**
+   * Runs `npm ls`, optionally for a particular package.
+   * @param {string} cwd
+   * @param {string} [pkg]
+   */
+  async list (cwd, pkg) {
+    return (await this.exec('list', pkg ? [pkg] : [], {cwd, json: true})).json;
+  }
+
+  /**
+   * Given a current version and a list of all versions for a package, return the version which is
+   * the highest safely-upgradable version (meaning not crossing any major revision boundaries, and
+   * not including any alpha/beta/rc versions)
+   *
+   * @param {string} curVersion - the current version of a package
+   * @param {Array<string>} allVersions - a list of version strings
+   *
+   * @return {string|null} - the highest safely-upgradable version, or null if there isn't one
+   */
+  getLatestSafeUpgradeFromVersions (curVersion, allVersions) {
+    let safeUpgradeVer = null;
+    const curSemver = semver.parse(curVersion);
+    if (curSemver === null) {
+      throw new Error(`Could not parse current version '${curVersion}'`);
+    }
+    for (const testVer of allVersions) {
+      const testSemver = semver.parse(testVer);
+      if (testSemver === null) {
+        throw new Error(`Could not parse version to test against: '${testVer}'`);
+      }
+      // if the test version is a prerelease, ignore it
+      if (testSemver.prerelease.length > 0) {
+        continue;
+      }
+      // if the current version is later than the test version, skip this test version
+      if (curSemver.compare(testSemver) === 1) {
+        continue;
+      }
+      // if the test version is newer, but crosses a major revision boundary, also skip it
+      if (testSemver.major > curSemver.major) {
+        continue;
+      }
+      // otherwise this version is safe to upgrade to. But there might be multiple ones of this
+      // kind, so keep iterating and keeping the highest
+      if (safeUpgradeVer === null || testSemver.compare(safeUpgradeVer) === 1) {
+        safeUpgradeVer = testSemver;
+      }
+    }
+    if (safeUpgradeVer) {
+      safeUpgradeVer = safeUpgradeVer.format();
+    }
+    return safeUpgradeVer;
+  }
+
+  /**
+   * Installs a package w/ `npm`
+   * @param {string} cwd
+   * @param {string} pkgName
+   * @param {InstallPackageOpts} [opts]
+   * @returns {Promise<import('type-fest').PackageJson>}
+   */
+  async installPackage (cwd, pkgName, {pkgVer} = {}) {
+    // not only this, this directory needs a 'package.json' inside of it, otherwise, if any
+    // directory in the filesystem tree ABOVE cwd happens to have a package.json or a node_modules
+    // dir in it, NPM will install the module up there instead (silly NPM)
+    const dummyPkgJson = path.resolve(cwd, 'package.json');
+    if (!await fs.exists(dummyPkgJson)) {
+      await fs.writeFile(dummyPkgJson, '{}');
+    }
+
+    const res = await this.exec('install', [
+      '--no-save',
+      '--global-style',
+      '--no-package-lock',
+      pkgVer ? `${pkgName}@${pkgVer}` : pkgName
+    ], {
+      cwd,
+      json: true,
+      lockFile: this._getInstallLockfilePath(cwd)
+    });
+
+    if (res.json) {
+      // we parsed a valid json response, so if we got an error here, return that
+      // message straightaway
+      if (res.json.error) {
+        throw new Error(res.json.error);
+      }
+    }
+
+    // Now read package data from the installed package to return, and make sure
+    // everything got installed ok. Remember, pkgName might end up with a / in it due to an npm
+    // org, so if so, that will get correctly exploded into multiple directories, by path.resolve here
+    // (even on Windows!)
+    const pkgJsonPath = resolveFrom(cwd, `${pkgName}/package.json`);
+    try {
+      return require(pkgJsonPath);
+    } catch {
+      throw new Error('The package was not downloaded correctly; its package.json ' +
+                      'did not exist or was unreadable. We looked for it at ' +
+                      pkgJsonPath);
+    }
+  }
+
+  /**
+   * @todo: I think this can be an `install` instead of a `link`.
+   * @param {string} cwd
+   * @param {string} pkgPath
+   */
+  async linkPackage (cwd, pkgPath) {
+    // from the path alone we don't know the npm package name, so we need to
+    // look in package.json
+    let pkgName;
+    try {
+      pkgName = require(path.resolve(pkgPath, 'package.json')).name;
+    } catch {
+      throw new Error('Could not find package.json inside the package path ' +
+                      `provided: ${pkgPath}`);
+    }
+
+    // this is added to handle commands with relative paths
+    // ie: "node . driver install --source=local ../fake-driver"
+    pkgPath = path.resolve(process.cwd(), pkgPath);
+
+    // call link with --no-package-lock to ensure no corruption while installing local packages
+    const args = [
+      '--global-style',
+      '--no-package-lock',
+      pkgPath
+    ];
+    const res = await this.exec('link', args, {cwd, lockFile: this._getLinkLockfilePath(cwd)});
+    if (res.json && res.json.error) {
+      throw new Error(res.json.error);
+    }
+
+    // now ensure it was linked to the correct place
+    try {
+      return require(resolveFrom(cwd, `${pkgName}/package.json`));
+    } catch {
+      throw new Error('The package was not linked correctly; its package.json ' +
+                      'did not exist or was unreadable');
+    }
+  }
+
+  /**
+   * @param {string} cwd
+   * @param {string} pkg
+   */
+  async uninstallPackage (cwd, pkg) {
+    await this.exec('uninstall', [pkg], {
+      cwd,
+      lockFile: this._getInstallLockfilePath(cwd)
+    });
+  }
+}
+
+export const npm = new NPM();
+
+/**
+ * Options for {@link NPM.installPackage}
+ * @typedef InstallPackageOpts
+ * @property {string} [pkgVer] - the version of the package to install
+ */
+
+/**
+ * Options for {@link NPM.exec}
+ * @typedef ExecOpts
+ * @property {string} cwd - Current working directory
+ * @property {boolean} [json] - If `true`, supply `--json` flag to npm and resolve w/ parsed JSON
+ * @property {string} [lockFile] - Path to lockfile to use
+ */
+
+// THESE TYPES SHOULD BE IN TEEN PROCESS, NOT HERE
+
+/**
+ * Result from a non-zero-exit execution of `appium`
+ * @typedef TeenProcessExecResult
+ * @property {string} stdout - Stdout
+ * @property {string} stderr - Stderr
+ * @property {number?} code - Exit code
+ * @property {any} json - JSON parsed from stdout
+ */
+
+/**
+ * Extra props `teen_process.exec` adds to its error objects
+ * @typedef TeenProcessExecErrorProps
+ * @property {string} stdout - STDOUT
+ * @property {string} stderr - STDERR
+ * @property {number?} code - Exit code
+ */
+
+/**
+ * Options unique to `teen_process.exec`. I probably missed some
+ * @typedef TeenProcessExecExtraOpts
+ * @property {number} [maxStdoutBufferSize]
+ * @property {number} [maxStderrBufferSize]
+ */
+
+/**
+ * All options for `teen_process.exec`
+ * @typedef {import('child_process').SpawnOptions & TeenProcessExecExtraOpts} TeenProcessExecOpts
+ */
+
+/**
+ * Error thrown by `teen_process.exec`
+ * @typedef {Error & TeenProcessExecErrorProps} TeenProcessExecError
+ */

package/lib/tempdir.js

@@ -13,7 +13,7 @@ const RDWR_EXCL = cnst.O_CREAT | cnst.O_TRUNC | cnst.O_RDWR | cnst.O_EXCL;
  * - No `process.env.APPIUM_TMP_DIR`: `/var/folders/34/2222sh8n27d6rcp7jqlkw8km0000gn/T/xxxxxxxx.yyyy`
  * - With `process.env.APPIUM_TMP_DIR = '/path/to/root'`: `/path/to/root/xxxxxxxx.yyyy`
  *
- * @returns {string} A path to the temporary directory
+ * @returns {Promise<string>} A path to the temporary directory
  */
 async function tempDir () {
   const now = new Date();
@@ -33,7 +33,7 @@ async function tempDir () {
 }
 
 /**
- * @typedef {Object} Affixes
+ * @typedef Affixes
  * @property {string} prefix - prefix of the temp directory name
  * @property {string} suffix - suffix of the temp directory name
  */
@@ -44,7 +44,7 @@ async function tempDir () {
  *
  * @param {string|Affixes} rawAffixes
  * @param {?string} defaultPrefix
- * @returns {string}  A path to the temporary directory with rawAffixes and defaultPrefix
+ * @returns {Promise<string>}  A path to the temporary directory with rawAffixes and defaultPrefix
  */
 async function path (rawAffixes, defaultPrefix) {
   const affixes = parseAffixes(rawAffixes, defaultPrefix);
@@ -54,7 +54,7 @@ async function path (rawAffixes, defaultPrefix) {
 }
 
 /**
- * @typedef {Object} OpenedAffixes
+ * @typedef OpenedAffixes
  * @property {string} path - The path to file
  * @property {integer} fd - The file descriptor opened
  */
@@ -64,7 +64,7 @@ async function path (rawAffixes, defaultPrefix) {
  * with arbitrary prefix/suffix for the directory name and return it as open.
  *
  * @param {Affixes} affixes
- * @returns {OpenedAffixes}
+ * @returns {Promise<OpenedAffixes>}
  */
 async function open (affixes) {
   const filePath = await path(affixes, 'f-');
@@ -116,7 +116,7 @@ const openDir = tempDir;
 /**
  * Returns a path to a temporary directory whcih is defined as static in the same process
  *
- * @returns {string} A temp directory path whcih is defined as static in the same process
+ * @returns {Promise<string>} A temp directory path whcih is defined as static in the same process
  */
 async function staticDir () { // eslint-disable-line require-await
   return _static;

package/lib/util.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import B from 'bluebird';
 import _ from 'lodash';
 import os from 'os';
@@ -75,6 +77,7 @@ function localIp () {
   let ip = _.chain(os.networkInterfaces())
     .values()
     .flatten()
+    // @ts-ignore
     .filter(function (val) {
       return (val.family === 'IPv4' && val.internal === false);
     })
@@ -217,16 +220,16 @@ function filterObject (obj, predicate) {
  *                 if it is less than zero.
  */
 function toReadableSizeString (bytes) {
-  const intBytes = parseInt(bytes, 10);
+  const intBytes = parseInt(String(bytes), 10);
   if (isNaN(intBytes) || intBytes < 0) {
     throw new Error(`Cannot convert '${bytes}' to a readable size format`);
   }
   if (intBytes >= GiB) {
-    return `${parseFloat(intBytes / (GiB * 1.0)).toFixed(2)} GB`;
+    return `${(intBytes / (GiB * 1.0)).toFixed(2)} GB`;
   } else if (intBytes >= MiB) {
-    return `${parseFloat(intBytes / (MiB * 1.0)).toFixed(2)} MB`;
+    return `${(intBytes / (MiB * 1.0)).toFixed(2)} MB`;
   } else if (intBytes >= KiB) {
-    return `${parseFloat(intBytes / (KiB * 1.0)).toFixed(2)} KB`;
+    return `${(intBytes / (KiB * 1.0)).toFixed(2)} KB`;
   }
   return `${intBytes} B`;
 }
@@ -260,7 +263,7 @@ function isSubPath (originalPath, root, forcePosix = null) {
  * @param {string} path1 - Absolute or relative path to a file/folder
  * @param {string} path2 - Absolute or relative path to a file/folder
  * @param {...string} pathN - Zero or more absolute or relative paths to files/folders
- * @returns {boolean} true if all paths are pointing to the same file system item
+ * @returns {Promise<boolean>} true if all paths are pointing to the same file system item
  */
 async function isSameDestination (path1, path2, ...pathN) {
   const allPaths = [path1, path2, ...pathN];
@@ -288,19 +291,20 @@ async function isSameDestination (path1, path2, ...pathN) {
 /**
  * Coerces the given number/string to a valid version string
  *
- * @param {string|number} ver - Version string to coerce
- * @param {boolean} strict [true] - If true then an exception will be thrown
+ * @template {boolean} [Strict=true]
+ * @param {string} ver - Version string to coerce
+ * @param {Strict} [strict] - If `true` then an exception will be thrown
  * if `ver` cannot be coerced
- * @returns {string} Coerced version number or null if the string cannot be
+ * @returns {Strict extends true ? string : string|null} Coerced version number or null if the string cannot be
  * coerced and strict mode is disabled
  * @throws {Error} if strict mode is enabled and `ver` cannot be coerced
  */
-function coerceVersion (ver, strict = true) {
+function coerceVersion (ver, strict = /** @type {Strict} */(true)) {
   const result = semver.valid(semver.coerce(`${ver}`));
   if (strict && !result) {
     throw new Error(`'${ver}' cannot be coerced to a valid version number`);
   }
-  return result;
+  return /** @type {Strict extends true ? string : string|null} */(result);
 }
 
 const SUPPORTED_OPERATORS = ['==', '!=', '>', '<', '>=', '<=', '='];
@@ -308,9 +312,9 @@ const SUPPORTED_OPERATORS = ['==', '!=', '>', '<', '>=', '<=', '='];
 /**
  * Compares two version strings
  *
- * @param {string|number} ver1 - The first version number to compare. Should be a valid
+ * @param {string} ver1 - The first version number to compare. Should be a valid
  * version number supported by semver parser.
- * @param {string|number} ver2 - The second version number to compare. Should be a valid
+ * @param {string} ver2 - The second version number to compare. Should be a valid
  * version number supported by semver parser.
  * @param {string} operator - One of supported version number operators:
  * ==, !=, >, <, <=, >=, =
@@ -333,7 +337,7 @@ function compareVersions (ver1, operator, ver2) {
  * Add appropriate quotes to command arguments. See https://github.com/substack/node-shell-quote
  * for more details
  *
- * @param {string|Array<string>} - The arguments that will be parsed
+ * @param {string|string[]} args - The arguments that will be parsed
  * @returns {string} - The arguments, quoted
  */
 function quote (args) {
@@ -354,8 +358,8 @@ function unleakString (s) {
 
 
 /**
- * @typedef {Object} PluralizeOptions
- * @property {?boolean} inclusive [false] - Whether to prefix with the number (e.g., 3 ducks)
+ * @typedef PluralizeOptions
+ * @property {boolean} [inclusive=false] - Whether to prefix with the number (e.g., 3 ducks)
  */
 
 /**
@@ -363,7 +367,7 @@ function unleakString (s) {
  *
  * @param {string} word - The word to pluralize
  * @param {number} count - How many of the word exist
- * @param {?PluralizeOptions|boolean} options|inclusive - options for word pluralization,
+ * @param {PluralizeOptions|boolean} options - options for word pluralization,
  *   or a boolean indicating the options.inclusive property
  * @returns {string} The word pluralized according to the number
  */
@@ -380,8 +384,8 @@ function pluralize (word, count, options = {}) {
 }
 
 /**
- * @typedef {Object} EncodingOptions
- * @property {number} maxSize [1073741824] The maximum size of
+ * @typedef EncodingOptions
+ * @property {number} [maxSize=1073741824] The maximum size of
  * the resulting buffer in bytes. This is set to 1GB by default, because
  * Appium limits the maximum HTTP body size to 1GB. Also, the NodeJS heap
  * size must be enough to keep the resulting object (usually this size is
@@ -395,7 +399,7 @@ function pluralize (word, count, options = {}) {
  *
  * @param {string} srcPath The full path to the file being encoded
  * @param {EncodingOptions} opts
- * @returns {Buffer} base64-encoded content of the source file as memory buffer
+ * @returns {Promise<Buffer>} base64-encoded content of the source file as memory buffer
  * @throws {Error} if there was an error while reading the source file
  * or the source file is too
  */
@@ -445,9 +449,9 @@ async function toInMemoryBase64 (srcPath, opts = {}) {
 }
 
 /**
- * @typedef {Object} LockFileOptions
- * @property {number} timeout [120] The max time in seconds to wait for the lock
- * @property {boolean} tryRecovery [false] Whether to try lock recovery if
+ * @typedef LockFileOptions
+ * @property {number} [timeout=120] The max time in seconds to wait for the lock
+ * @property {boolean} [tryRecovery=false] Whether to try lock recovery if
  * the first attempt to acquire it timed out.
  */
 
@@ -458,7 +462,7 @@ async function toInMemoryBase64 (srcPath, opts = {}) {
  *
  * @param {string} lockFile The full path to the file used for the lock
  * @param {LockFileOptions} opts
- * @returns {AsyncFunction} async function that takes another async function defining the locked
+ * @returns {(behavior: () => Promise<void>) => Promise<void>} async function that takes another async function defining the locked
  * behavior
  */
 function getLockFileGuard (lockFile, opts = {}) {
@@ -467,7 +471,7 @@ function getLockFileGuard (lockFile, opts = {}) {
     tryRecovery = false,
   } = opts;
 
-  const lock = B.promisify(_lockfile.lock);
+  const lock = /** @type {(lockfile: string, opts: import('lockfile').Options)=>B<void>} */(B.promisify(_lockfile.lock));
   const check = B.promisify(_lockfile.check);
   const unlock = B.promisify(_lockfile.unlock);