@appium/support 2.57.3 → 2.59.0

package/lib/net.js

@@ -1,7 +1,7 @@
 import _ from 'lodash';
 import fs from './fs';
 import B from 'bluebird';
-import { toReadableSizeString } from './util';
+import {toReadableSizeString} from './util';
 import log from './logger';
 import Ftp from 'jsftp';
 import Timer from './timing';
@@ -12,10 +12,10 @@ const DEFAULT_TIMEOUT_MS = 4 * 60 * 1000;
 
 /**
  * Converts {@linkcode AuthCredentials} to credentials understood by {@linkcode axios}.
- * @param {AuthCredentials | import('axios').AxiosBasicCredentials} auth
+ * @param {AuthCredentials | import('axios').AxiosBasicCredentials} [auth]
  * @returns {import('axios').AxiosBasicCredentials?}
  */
-function toAxiosAuth (auth) {
+function toAxiosAuth(auth) {
   if (!_.isPlainObject(auth)) {
     return null;
   }
@@ -24,7 +24,7 @@ function toAxiosAuth (auth) {
     username: _.get(auth, 'username', _.get(auth, 'user')),
     password: _.get(auth, 'password', _.get(auth, 'pass')),
   };
-  return (axiosAuth.username && axiosAuth.password) ? axiosAuth : null;
+  return axiosAuth.username && axiosAuth.password ? axiosAuth : null;
 }
 
 /**
@@ -32,7 +32,11 @@ function toAxiosAuth (auth) {
  * @param {URL} parsedUri
  * @param {HttpUploadOptions & NetOptions} [uploadOptions]
  */
-async function uploadFileToHttp (localFileStream, parsedUri, uploadOptions = /** @type {HttpUploadOptions & NetOptions} */({})) {
+async function uploadFileToHttp(
+  localFileStream,
+  parsedUri,
+  uploadOptions = /** @type {HttpUploadOptions & NetOptions} */ ({})
+) {
   const {
     method = 'POST',
     timeout = DEFAULT_TIMEOUT_MS,
@@ -41,7 +45,7 @@ async function uploadFileToHttp (localFileStream, parsedUri, uploadOptions = /**
     fileFieldName = 'file',
     formFields,
   } = uploadOptions;
-  const { href } = parsedUri;
+  const {href} = parsedUri;
 
   /** @type {import('axios').AxiosRequestConfig} */
   const requestOpts = {
@@ -73,7 +77,7 @@ async function uploadFileToHttp (localFileStream, parsedUri, uploadOptions = /**
     }
     requestOpts.headers = {
       ...(_.isPlainObject(headers) ? headers : {}),
-      ...form.getHeaders()
+      ...form.getHeaders(),
     };
     requestOpts.data = form;
   } else {
@@ -82,8 +86,10 @@ async function uploadFileToHttp (localFileStream, parsedUri, uploadOptions = /**
     }
     requestOpts.data = localFileStream;
   }
-  log.debug(`Performing ${method} to ${href} with options (excluding data): ` +
-    JSON.stringify(_.omit(requestOpts, ['data'])));
+  log.debug(
+    `Performing ${method} to ${href} with options (excluding data): ` +
+      JSON.stringify(_.omit(requestOpts, ['data']))
+  );
 
   const {status, statusText} = await axios(requestOpts);
   log.info(`Server response: ${status} ${statusText}`);
@@ -94,16 +100,13 @@ async function uploadFileToHttp (localFileStream, parsedUri, uploadOptions = /**
  * @param {URL} parsedUri
  * @param {NotHttpUploadOptions & NetOptions} [uploadOptions]
  */
-async function uploadFileToFtp (localFileStream, parsedUri, uploadOptions = /** @type {NotHttpUploadOptions & NetOptions} */({})) {
-  const {
-    auth,
-  } = uploadOptions;
-  const {
-    hostname,
-    port,
-    protocol,
-    pathname,
-  } = parsedUri;
+async function uploadFileToFtp(
+  localFileStream,
+  parsedUri,
+  uploadOptions = /** @type {NotHttpUploadOptions & NetOptions} */ ({})
+) {
+  const {auth} = uploadOptions;
+  const {hostname, port, protocol, pathname} = parsedUri;
 
   const ftpOpts = {
     host: hostname,
@@ -131,7 +134,7 @@ async function uploadFileToFtp (localFileStream, parsedUri, uploadOptions = /**
  * @param {URL} url
  * @returns {opts is HttpUploadOptions & NetOptions}
  */
-function isHttpUploadOptions (opts, url) {
+function isHttpUploadOptions(opts, url) {
   try {
     const {protocol} = new URL(url);
     return protocol === 'http:' || protocol === 'https:';
@@ -146,7 +149,7 @@ function isHttpUploadOptions (opts, url) {
  * @param {URL} url
  * @returns {opts is NotHttpUploadOptions & NetOptions}
  */
-function isNotHttpUploadOptions (opts, url) {
+function isNotHttpUploadOptions(opts, url) {
   try {
     const {protocol} = new URL(url);
     return protocol === 'ftp:';
@@ -163,14 +166,16 @@ function isNotHttpUploadOptions (opts, url) {
  * @param {(HttpUploadOptions|NotHttpUploadOptions) & NetOptions} [uploadOptions]
  * @returns {Promise<void>}
  */
-async function uploadFile (localPath, remoteUri, uploadOptions = /** @type {(HttpUploadOptions|NotHttpUploadOptions) & NetOptions} */({})) {
-  if (!await fs.exists(localPath)) {
-    throw new Error (`'${localPath}' does not exists or is not accessible`);
+async function uploadFile(
+  localPath,
+  remoteUri,
+  uploadOptions = /** @type {(HttpUploadOptions|NotHttpUploadOptions) & NetOptions} */ ({})
+) {
+  if (!(await fs.exists(localPath))) {
+    throw new Error(`'${localPath}' does not exists or is not accessible`);
   }
 
-  const {
-    isMetered = true,
-  } = uploadOptions;
+  const {isMetered = true} = uploadOptions;
   const url = new URL(remoteUri);
   const {size} = await fs.stat(localPath);
   if (isMetered) {
@@ -181,20 +186,24 @@ async function uploadFile (localPath, remoteUri, uploadOptions = /** @type {(Htt
     if (!uploadOptions.fileFieldName) {
       uploadOptions.headers = {
         ...(_.isPlainObject(uploadOptions.headers) ? uploadOptions.headers : {}),
-        'Content-Length': size
+        'Content-Length': size,
       };
     }
     await uploadFileToHttp(fs.createReadStream(localPath), url, uploadOptions);
   } else if (isNotHttpUploadOptions(uploadOptions, url)) {
     await uploadFileToFtp(fs.createReadStream(localPath), url, uploadOptions);
   } else {
-    throw new Error(`Cannot upload the file at '${localPath}' to '${remoteUri}'. ` +
-      `Unsupported remote protocol '${url.protocol}'. ` +
-      `Only http/https and ftp/ftps protocols are supported.`);
+    throw new Error(
+      `Cannot upload the file at '${localPath}' to '${remoteUri}'. ` +
+        `Unsupported remote protocol '${url.protocol}'. ` +
+        `Only http/https and ftp/ftps protocols are supported.`
+    );
   }
   if (isMetered) {
-    log.info(`Uploaded '${localPath}' of ${toReadableSizeString(size)} size in ` +
-      `${timer.getDuration().asSeconds.toFixed(3)}s`);
+    log.info(
+      `Uploaded '${localPath}' of ${toReadableSizeString(size)} size in ` +
+        `${timer.getDuration().asSeconds.toFixed(3)}s`
+    );
   }
 }
 
@@ -206,13 +215,12 @@ async function uploadFile (localPath, remoteUri, uploadOptions = /** @type {(Htt
  * @param {DownloadOptions & NetOptions} [downloadOptions]
  * @throws {Error} If download operation fails
  */
-async function downloadFile (remoteUrl, dstPath, downloadOptions = /** @type {DownloadOptions & NetOptions} */({})) {
-  const {
-    isMetered = true,
-    auth,
-    timeout = DEFAULT_TIMEOUT_MS,
-    headers,
-  } = downloadOptions;
+async function downloadFile(
+  remoteUrl,
+  dstPath,
+  downloadOptions = /** @type {DownloadOptions & NetOptions} */ ({})
+) {
+  const {isMetered = true, auth, timeout = DEFAULT_TIMEOUT_MS, headers} = downloadOptions;
 
   /**
    * @type {import('axios').AxiosRequestConfig}
@@ -234,10 +242,7 @@ async function downloadFile (remoteUrl, dstPath, downloadOptions = /** @type {Do
   let responseLength;
   try {
     const writer = fs.createWriteStream(dstPath);
-    const {
-      data: responseStream,
-      headers: responseHeaders,
-    } = await axios(requestOpts);
+    const {data: responseStream, headers: responseHeaders} = await axios(requestOpts);
     responseLength = parseInt(responseHeaders['content-length'], 10);
     responseStream.pipe(writer);
 
@@ -256,13 +261,17 @@ async function downloadFile (remoteUrl, dstPath, downloadOptions = /** @type {Do
   const {size} = await fs.stat(dstPath);
   if (responseLength && size !== responseLength) {
     await fs.rimraf(dstPath);
-    throw new Error(`The size of the file downloaded from ${remoteUrl} (${size} bytes) ` +
-      `differs from the one in Content-Length response header (${responseLength} bytes)`);
+    throw new Error(
+      `The size of the file downloaded from ${remoteUrl} (${size} bytes) ` +
+        `differs from the one in Content-Length response header (${responseLength} bytes)`
+    );
   }
   if (isMetered) {
     const secondsElapsed = timer.getDuration().asSeconds;
-    log.debug(`${remoteUrl} (${toReadableSizeString(size)}) ` +
-      `has been downloaded to '${dstPath}' in ${secondsElapsed.toFixed(3)}s`);
+    log.debug(
+      `${remoteUrl} (${toReadableSizeString(size)}) ` +
+        `has been downloaded to '${dstPath}' in ${secondsElapsed.toFixed(3)}s`
+    );
     if (secondsElapsed >= 2) {
       const bytesPerSec = Math.floor(size / secondsElapsed);
       log.debug(`Approximate download speed: ${toReadableSizeString(bytesPerSec)}/s`);
@@ -270,21 +279,21 @@ async function downloadFile (remoteUrl, dstPath, downloadOptions = /** @type {Do
   }
 }
 
-export { uploadFile, downloadFile };
+export {uploadFile, downloadFile};
 
 /**
  * Common options for {@linkcode uploadFile} and {@linkcode downloadFile}.
  * @typedef NetOptions
  * @property {boolean} [isMetered=true] - Whether to log the actual download performance
  * (e.g. timings and speed)
- * @property {AuthCredentials} auth
+ * @property {AuthCredentials} [auth] - Authentication credentials
  */
 
 /**
  * Specific options for {@linkcode downloadFile}.
  * @typedef DownloadOptions
  * @property {number} [timeout] - The actual request timeout in milliseconds; defaults to {@linkcode DEFAULT_TIMEOUT_MS}
- * @property {Record<string,any>} headers - Request headers mapping
+ * @property {Record<string,any>} [headers] - Request headers mapping
  */
 
 /**
@@ -316,4 +325,3 @@ export { uploadFile, downloadFile };
  * to be included into the upload request. This property is only considered if
  * `fileFieldName` is set
  */
-

package/lib/node.js

@@ -1,9 +1,9 @@
-import { isWindows } from './system';
+import {isWindows} from './system';
 import log from './logger';
 import _ from 'lodash';
-import { exec } from 'teen_process';
+import {exec} from 'teen_process';
 import path from 'path';
-import { v4 as uuidV4 } from 'uuid';
+import {v4 as uuidV4} from 'uuid';
 
 const ECMA_SIZES = Object.freeze({
   STRING: 2,
@@ -17,7 +17,7 @@ const ECMA_SIZES = Object.freeze({
  * @param {string} packageName - name of the package to link
  * @throws {Error} If the command fails
  */
-async function linkGlobalPackage (packageName) {
+async function linkGlobalPackage(packageName) {
   try {
     log.debug(`Linking package '${packageName}'`);
     const cmd = isWindows() ? 'npm.cmd' : 'npm';
@@ -43,7 +43,7 @@ async function linkGlobalPackage (packageName) {
  * @returns {Promise<unknown>} - the package object
  * @throws {Error} If the package is not found locally or globally
  */
-async function requirePackage (packageName) {
+async function requirePackage(packageName) {
   // first, get it in the normal way (see https://nodejs.org/api/modules.html#modules_all_together)
   try {
     log.debug(`Loading local package '${packageName}'`);
@@ -54,7 +54,12 @@ async function requirePackage (packageName) {
 
   // second, get it from where it ought to be in the global node_modules
   try {
-    const globalPackageName = path.resolve(process.env.npm_config_prefix ?? '', 'lib', 'node_modules', packageName);
+    const globalPackageName = path.resolve(
+      process.env.npm_config_prefix ?? '',
+      'lib',
+      'node_modules',
+      packageName
+    );
     log.debug(`Loading global package '${globalPackageName}'`);
     return require(globalPackageName);
   } catch (err) {
@@ -71,18 +76,18 @@ async function requirePackage (packageName) {
   }
 }
 
-function extractAllProperties (obj) {
+function extractAllProperties(obj) {
   const stringProperties = [];
   for (const prop in obj) {
     stringProperties.push(prop);
   }
   if (_.isFunction(Object.getOwnPropertySymbols)) {
-    stringProperties.push(...(Object.getOwnPropertySymbols(obj)));
+    stringProperties.push(...Object.getOwnPropertySymbols(obj));
   }
   return stringProperties;
 }
 
-function _getSizeOfObject (seen, object) {
+function _getSizeOfObject(seen, object) {
   if (_.isNil(object)) {
     return 0;
   }
@@ -113,13 +118,13 @@ function _getSizeOfObject (seen, object) {
   return bytes;
 }
 
-function getCalculator (seen) {
-  return function calculator (obj) {
+function getCalculator(seen) {
+  return function calculator(obj) {
     if (_.isBuffer(obj)) {
       return obj.length;
     }
 
-    switch (typeof (obj)) {
+    switch (typeof obj) {
       case 'string':
         return obj.length * ECMA_SIZES.STRING;
       case 'boolean':
@@ -128,7 +133,7 @@ function getCalculator (seen) {
         return ECMA_SIZES.NUMBER;
       case 'symbol':
         return _.isFunction(Symbol.keyFor) && Symbol.keyFor(obj)
-          ? /** @type {string} */(Symbol.keyFor(obj)).length * ECMA_SIZES.STRING
+          ? /** @type {string} */ (Symbol.keyFor(obj)).length * ECMA_SIZES.STRING
           : (obj.toString().length - 8) * ECMA_SIZES.STRING;
       case 'object':
         return _.isArray(obj)
@@ -147,7 +152,7 @@ function getCalculator (seen) {
  * @param {*} obj An object whose size should be calculated
  * @returns {number} Object size in bytes.
  */
-function getObjectSize (obj) {
+function getObjectSize(obj) {
   return getCalculator(new WeakSet())(obj);
 }
 
@@ -159,11 +164,40 @@ const OBJECTS_MAPPING = new WeakMap();
  * @param {object} object Any valid ECMA object
  * @returns {string} A uuidV4 string that uniquely identifies given object
  */
-function getObjectId (object) {
+function getObjectId(object) {
   if (!OBJECTS_MAPPING.has(object)) {
     OBJECTS_MAPPING.set(object, uuidV4());
   }
   return OBJECTS_MAPPING.get(object);
 }
 
-export { requirePackage, getObjectSize, getObjectId };
+/**
+ * Perform deep freeze of the given object (e. g.
+ * all nested objects also become immutable).
+ * If the passed object is of a plain type
+ * then no change is done and the same object
+ * is returned.
+ * ! This function changes the given object,
+ * so it becomes immutable.
+ *
+ * @param {*} object Any valid ECMA object
+ * @returns {*} The same object that was passed to the
+ * function after it was made immutable.
+ */
+function deepFreeze(object) {
+  let propNames;
+  try {
+    propNames = Object.getOwnPropertyNames(object);
+  } catch (ign) {
+    return object;
+  }
+  for (const name of propNames) {
+    const value = object[name];
+    if (value && typeof value === 'object') {
+      deepFreeze(value);
+    }
+  }
+  return Object.freeze(object);
+}
+
+export {requirePackage, getObjectSize, getObjectId, deepFreeze};

package/lib/npm.js

@@ -2,31 +2,23 @@
 
 import path from 'path';
 import semver from 'semver';
-import { hasAppiumDependency } from './env';
-import { exec } from 'teen_process';
-import { fs } from './fs';
+import {hasAppiumDependency} from './env';
+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',
-);
+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',
-);
+export const INSTALL_LOCKFILE_RELATIVE_PATH = path.join(CACHE_DIR_RELATIVE_PATH, '.install.lock');
 
 /**
  * XXX: This should probably be a singleton, but it isn't.  Maybe this module should just export functions?
@@ -37,7 +29,7 @@ export class NPM {
    * @private
    * @param {string} cwd
    */
-  _getInstallLockfilePath (cwd) {
+  _getInstallLockfilePath(cwd) {
     return path.join(cwd, INSTALL_LOCKFILE_RELATIVE_PATH);
   }
 
@@ -51,8 +43,8 @@ export class NPM {
    * @param {ExecOpts} opts
    * @param {ExecOpts} [execOpts]
    */
-  async exec (cmd, args, opts, execOpts = /** @type {ExecOpts} */({})) {
-    let { cwd, json, lockFile } = opts;
+  async exec(cmd, args, opts, execOpts = /** @type {ExecOpts} */ ({})) {
+    let {cwd, json, lockFile} = opts;
 
     // make sure we perform the current operation in cwd
     execOpts = {...execOpts, cwd};
@@ -81,8 +73,12 @@ export class NPM {
         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()}`);
+      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;
@@ -92,11 +88,13 @@ export class NPM {
    * @param {string} cwd
    * @param {string} pkg
    */
-  async getLatestVersion (cwd, pkg) {
-    return (await this.exec('view', [pkg, 'dist-tags'], {
-      json: true,
-      cwd
-    })).json?.latest;
+  async getLatestVersion(cwd, pkg) {
+    return (
+      await this.exec('view', [pkg, 'dist-tags'], {
+        json: true,
+        cwd,
+      })
+    ).json?.latest;
   }
 
   /**
@@ -104,11 +102,13 @@ export class NPM {
    * @param {string} pkg
    * @param {string} curVersion
    */
-  async getLatestSafeUpgradeVersion (cwd, pkg, curVersion) {
-    const allVersions = (await this.exec('view', [pkg, 'versions'], {
-      json: true,
-      cwd
-    })).json;
+  async getLatestSafeUpgradeVersion(cwd, pkg, curVersion) {
+    const allVersions = (
+      await this.exec('view', [pkg, 'versions'], {
+        json: true,
+        cwd,
+      })
+    ).json;
     return this.getLatestSafeUpgradeFromVersions(curVersion, allVersions);
   }
 
@@ -117,7 +117,7 @@ export class NPM {
    * @param {string} cwd
    * @param {string} [pkg]
    */
-  async list (cwd, pkg) {
+  async list(cwd, pkg) {
     return (await this.exec('list', pkg ? [pkg] : [], {cwd, json: true})).json;
   }
 
@@ -131,7 +131,7 @@ export class NPM {
    *
    * @return {string|null} - the highest safely-upgradable version, or null if there isn't one
    */
-  getLatestSafeUpgradeFromVersions (curVersion, allVersions) {
+  getLatestSafeUpgradeFromVersions(curVersion, allVersions) {
     let safeUpgradeVer = null;
     const curSemver = semver.parse(curVersion);
     if (curSemver === null) {
@@ -173,7 +173,7 @@ export class NPM {
    * @param {InstallPackageOpts} [opts]
    * @returns {Promise<import('type-fest').PackageJson>}
    */
-  async installPackage (cwd, pkgName, {pkgVer} = {}) {
+  async installPackage(cwd, pkgName, {pkgVer} = {}) {
     /** @type {any} */
     let dummyPkgJson;
     const dummyPkgPath = path.join(cwd, 'package.json');
@@ -199,18 +199,19 @@ export class NPM {
      * "dummy" and is controlled by the user.  So we'll just add it as a dev
      * dep; whatever else it does is up to the user's npm config.
      */
-    const installOpts = await hasAppiumDependency(cwd) ?
-      ['--save-dev'] :
-      ['--save-dev', '--save-exact', '--global-style', '--no-package-lock'];
+    const installOpts = (await hasAppiumDependency(cwd))
+      ? ['--save-dev']
+      : ['--save-dev', '--save-exact', '--global-style', '--no-package-lock'];
 
-    const res = await this.exec('install', [
-      ...installOpts,
-      pkgVer ? `${pkgName}@${pkgVer}` : pkgName
-    ], {
-      cwd,
-      json: true,
-      lockFile: this._getInstallLockfilePath(cwd)
-    });
+    const res = await this.exec(
+      'install',
+      [...installOpts, 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
@@ -228,9 +229,11 @@ export class NPM {
     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);
+      throw new Error(
+        'The package was not downloaded correctly; its package.json ' +
+          'did not exist or was unreadable. We looked for it at ' +
+          pkgJsonPath
+      );
     }
   }
 
@@ -238,10 +241,10 @@ export class NPM {
    * @param {string} cwd
    * @param {string} pkg
    */
-  async uninstallPackage (cwd, pkg) {
+  async uninstallPackage(cwd, pkg) {
     await this.exec('uninstall', [pkg], {
       cwd,
-      lockFile: this._getInstallLockfilePath(cwd)
+      lockFile: this._getInstallLockfilePath(cwd),
     });
   }
 }