@appium/support 2.55.4 → 2.57.0

package/lib/logging.js

@@ -22,10 +22,14 @@ function patchLogger (logger) {
   }
 }
 
+/**
+ *
+ * @returns {[npmlog.Logger, boolean]}
+ */
 function _getLogger () {
   // check if the user set the `_TESTING` or `_FORCE_LOGS` flag
-  const testingMode = parseInt(process.env._TESTING, 10) === 1;
-  const forceLogMode = parseInt(process.env._FORCE_LOGS, 10) === 1;
+  const testingMode = process.env._TESTING === '1';
+  const forceLogMode = process.env._FORCE_LOGS === '1';
 
   // if is possible that there is a logger instance that is already around,
   // in which case we want t o use that
@@ -44,19 +48,32 @@ function _getLogger () {
   return [logger, usingGlobalLog];
 }
 
+/**
+ * @param {Prefix?} prefix
+ * @param {boolean} logTimestamp whether to include timestamps into log prefixes
+ * @returns {string}
+ */
 function getActualPrefix (prefix, logTimestamp = false) {
-  let actualPrefix = _.isFunction(prefix) ? prefix() : prefix;
-  if (logTimestamp) {
-    actualPrefix = `[${moment().format(PREFIX_TIMESTAMP_FORMAT)}] ${actualPrefix}`;
-  }
-  return actualPrefix;
+  const result = (_.isFunction(prefix) ? prefix() : prefix) ?? '';
+  return logTimestamp
+    ? `[${moment().format(PREFIX_TIMESTAMP_FORMAT)}] ${result}`
+    : result;
 }
 
+/**
+ *
+ * @param {Prefix?} prefix
+ * @returns {AppiumLogger}
+ */
 function getLogger (prefix = null) {
   let [logger, usingGlobalLog] = _getLogger();
 
   // wrap the logger so that we can catch and modify any logging
-  let wrappedLogger = {unwrap: () => logger};
+  let wrappedLogger = {
+    unwrap: () => logger,
+    levels: NPM_LEVELS,
+    prefix,
+  };
 
   // allow access to the level of the underlying logger
   Object.defineProperty(wrappedLogger, 'level', {
@@ -70,12 +87,12 @@ function getLogger (prefix = null) {
     configurable: true
   });
 
-  const logTimestamp = parseInt(process.env._LOG_TIMESTAMP, 10) === 1;
+  const logTimestamp = process.env._LOG_TIMESTAMP === '1';
 
   // add all the levels from `npmlog`, and map to the underlying logger
   for (const level of NPM_LEVELS) {
     wrappedLogger[level] = function (...args) {
-      const actualPrefix = getActualPrefix(prefix, logTimestamp);
+      const actualPrefix = getActualPrefix(this.prefix, logTimestamp);
       for (const arg of args) {
         const out = (_.isError(arg) && arg.stack) ? arg.stack : `${arg}`;
         for (const line of out.split('\n')) {
@@ -99,15 +116,14 @@ function getLogger (prefix = null) {
     // package set the log level
     wrappedLogger.level = 'verbose';
   }
-  wrappedLogger.levels = NPM_LEVELS;
-  return wrappedLogger;
+  return /** @type {AppiumLogger} */(wrappedLogger);
 }
 
 /**
- * @typedef {Object} LoadResult
- * @property {List<string>} issues The list of rule parsing issues (one item per rule).
+ * @typedef LoadResult
+ * @property {string[]} issues The list of rule parsing issues (one item per rule).
  * Rules with issues are skipped. An empty list is returned if no parsing issues exist.
- * @property {List<SecureValuePreprocessingRule>} rules The list of successfully loaded
+ * @property {import('./log-internal').SecureValuePreprocessingRule[]} rules The list of successfully loaded
  * replacement rules. The list could be empty if no rules were loaded.
  */
 
@@ -117,12 +133,12 @@ function getLogger (prefix = null) {
  * appear in Appium logs.
  * Each call to this method replaces the previously loaded rules if any existed.
  *
- * @param {string|string[]|Rule[]} rulesJsonPath The full path to the JSON file containing
+ * @param {string|string[]|import('./log-internal').Rule[]} rulesJsonPath The full path to the JSON file containing
  * the replacement rules. Each rule could either be a string to be replaced
  * or an object with predefined properties. See the `Rule` type definition in
  * `log-internals.js` to get more details on its format.
  * @throws {Error} If the given file cannot be loaded
- * @returns {LoadResult}
+ * @returns {Promise<LoadResult>}
  */
 async function loadSecureValuesPreprocessingRules (rulesJsonPath) {
   const issues = await SECURE_VALUES_PREPROCESSOR.loadRules(rulesJsonPath);
@@ -137,3 +153,11 @@ const log = getLogger();
 
 export { log, patchLogger, getLogger, loadSecureValuesPreprocessingRules };
 export default log;
+
+/**
+ * @typedef {import('@appium/types').Prefix} Prefix
+ */
+
+/**
+ * @typedef {import('@appium/types').AppiumLogger} AppiumLogger
+ */

package/lib/mjpeg.js

@@ -30,6 +30,11 @@ const MJPEG_SERVER_TIMEOUT_MS = 10000;
 /** Class which stores the last bit of data streamed into it */
 class MJpegStream extends Writable {
 
+  /**
+   * @type {number}
+   */
+  updateCount = 0;
+
   /**
    * Create an MJpegStream
    * @param {string} mJpegUrl - URL of MJPEG-over-HTTP stream
@@ -52,24 +57,26 @@ class MJpegStream extends Writable {
    * or `null` if no image can be parsed
    */
   get lastChunkBase64 () {
+    const lastChunk = /** @type {Buffer} */(this.lastChunk);
     return !_.isEmpty(this.lastChunk) && _.isBuffer(this.lastChunk)
-      ? this.lastChunk.toString('base64')
+      ? lastChunk.toString('base64')
       : null;
   }
 
   /**
    * Get the PNG version of the JPEG buffer
    *
-   * @returns {?Buffer} PNG image data or `null` if no PNG
+   * @returns {Promise<Buffer?>} PNG image data or `null` if no PNG
    * image can be parsed
    */
   async lastChunkPNG () {
-    if (_.isEmpty(this.lastChunk) || !_.isBuffer(this.lastChunk)) {
+    const lastChunk = /** @type {Buffer} */(this.lastChunk);
+    if (_.isEmpty(lastChunk) || !_.isBuffer(lastChunk)) {
       return null;
     }
 
     try {
-      const jpg = await getJimpImage(this.lastChunk);
+      const jpg = await getJimpImage(lastChunk);
       return await jpg.getBuffer(MIME_PNG);
     } catch (e) {
       return null;
@@ -79,7 +86,7 @@ class MJpegStream extends Writable {
   /**
    * Get the base64-encoded version of the PNG
    *
-   * @returns {?string} base64-encoded PNG image data
+   * @returns {Promise<string?>} base64-encoded PNG image data
    * or `null` if no image can be parsed
    */
   async lastChunkPNGBase64 () {
@@ -185,6 +192,8 @@ class MJpegStream extends Writable {
       this.registerStartSuccess();
       this.registerStartSuccess = null;
     }
+
+    return true;
   }
 }
 

package/lib/mkdirp.js

@@ -1,9 +1,6 @@
-import mkdirp from 'mkdirp';
-
+import { fs } from './fs';
 /**
- * TODO: once we drop support for Node 10, this should be removed in favor
- * of fs.mkdir(dir, {recursive: true});
+ * @deprecated Use `fs.mkdirp` instead.
  */
-
-
+const { mkdirp } = fs;
 export { mkdirp };

package/lib/net.js

@@ -1,6 +1,5 @@
 import _ from 'lodash';
 import fs from './fs';
-import url from 'url';
 import B from 'bluebird';
 import { toReadableSizeString } from './util';
 import log from './logger';
@@ -11,19 +10,29 @@ import FormData from 'form-data';
 
 const DEFAULT_TIMEOUT_MS = 4 * 60 * 1000;
 
+/**
+ * Converts {@linkcode AuthCredentials} to credentials understood by {@linkcode axios}.
+ * @param {AuthCredentials | import('axios').AxiosBasicCredentials} auth
+ * @returns {import('axios').AxiosBasicCredentials?}
+ */
 function toAxiosAuth (auth) {
   if (!_.isPlainObject(auth)) {
     return null;
   }
 
   const axiosAuth = {
-    username: auth.username || auth.user,
-    password: auth.password || auth.pass,
+    username: _.get(auth, 'username', _.get(auth, 'user')),
+    password: _.get(auth, 'password', _.get(auth, 'pass')),
   };
   return (axiosAuth.username && axiosAuth.password) ? axiosAuth : null;
 }
 
-async function uploadFileToHttp (localFileStream, parsedUri, uploadOptions = {}) {
+/**
+ * @param {NodeJS.ReadableStream} localFileStream
+ * @param {URL} parsedUri
+ * @param {HttpUploadOptions & NetOptions} [uploadOptions]
+ */
+async function uploadFileToHttp (localFileStream, parsedUri, uploadOptions = /** @type {HttpUploadOptions & NetOptions} */({})) {
   const {
     method = 'POST',
     timeout = DEFAULT_TIMEOUT_MS,
@@ -34,6 +43,7 @@ async function uploadFileToHttp (localFileStream, parsedUri, uploadOptions = {})
   } = uploadOptions;
   const { href } = parsedUri;
 
+  /** @type {import('axios').AxiosRequestConfig} */
   const requestOpts = {
     url: href,
     method,
@@ -61,8 +71,10 @@ async function uploadFileToHttp (localFileStream, parsedUri, uploadOptions = {})
         }
       }
     }
-    requestOpts.headers = Object.assign({}, _.isPlainObject(headers) ? headers : {},
-      form.getHeaders());
+    requestOpts.headers = {
+      ...(_.isPlainObject(headers) ? headers : {}),
+      ...form.getHeaders()
+    };
     requestOpts.data = form;
   } else {
     if (_.isPlainObject(headers)) {
@@ -77,11 +89,14 @@ async function uploadFileToHttp (localFileStream, parsedUri, uploadOptions = {})
   log.info(`Server response: ${status} ${statusText}`);
 }
 
-async function uploadFileToFtp (localFileStream, parsedUri, uploadOptions = {}) {
+/**
+ * @param {string | Buffer | NodeJS.ReadableStream} localFileStream
+ * @param {URL} parsedUri
+ * @param {NotHttpUploadOptions & NetOptions} [uploadOptions]
+ */
+async function uploadFileToFtp (localFileStream, parsedUri, uploadOptions = /** @type {NotHttpUploadOptions & NetOptions} */({})) {
   const {
     auth,
-    user,
-    pass,
   } = uploadOptions;
   const {
     hostname,
@@ -92,11 +107,11 @@ async function uploadFileToFtp (localFileStream, parsedUri, uploadOptions = {})
 
   const ftpOpts = {
     host: hostname,
-    port: port || 21,
+    port: !_.isUndefined(port) ? _.parseInt(port) : 21,
   };
-  if ((auth?.user && auth?.pass) || (user && pass)) {
-    ftpOpts.user = auth?.user || user;
-    ftpOpts.pass = auth?.pass || pass;
+  if (auth?.user && auth?.pass) {
+    ftpOpts.user = auth.user;
+    ftpOpts.pass = auth.pass;
   }
   log.debug(`${protocol} upload options: ${JSON.stringify(ftpOpts)}`);
   return await new B((resolve, reject) => {
@@ -111,42 +126,44 @@ async function uploadFileToFtp (localFileStream, parsedUri, uploadOptions = {})
 }
 
 /**
- * @typedef {Object} AuthCredentials
- * @property {string} user - Non-empty user name
- * @property {string} pass - Non-empty password
- */
-
-/**
- * @typedef {Object} FtpUploadOptions
- * @property {boolean} isMetered [true] - Whether to log the actual upload performance
- * (e.g. timings and speed)
- * @property {AuthCredentials} auth
+ * Returns `true` if params are valid for {@linkcode uploadFileToHttp}.
+ * @param {any} opts
+ * @param {URL} url
+ * @returns {opts is HttpUploadOptions & NetOptions}
  */
+function isHttpUploadOptions (opts, url) {
+  try {
+    const {protocol} = new URL(url);
+    return protocol === 'http:' || protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
 
 /**
- * @typedef {Object} HttpUploadOptions
- * @property {boolean} isMetered [true] - Whether to log the actual upload performance
- * (e.g. timings and speed)
- * @property {string} method [POST] - The HTTP method used for file upload
- * @property {AuthCredentials} auth
- * @property {number} timeout [240000] - The actual request timeout in milliseconds
- * @property {Object} headers - Additional request headers mapping
- * @property {?string} fileFieldName [file] - The name of the form field containing the file
- * content to be uploaded. Any falsy value make the request to use non-multipart upload
- * @property {Array<Pair>|Object} formFields - The additional form fields
- * to be included into the upload request. This property is only considered if
- * `fileFieldName` is set
+ * Returns `true` if params are valid for {@linkcode uploadFileToFtp}.
+ * @param {any} opts
+ * @param {URL} url
+ * @returns {opts is NotHttpUploadOptions & NetOptions}
  */
-
+function isNotHttpUploadOptions (opts, url) {
+  try {
+    const {protocol} = new URL(url);
+    return protocol === 'ftp:';
+  } catch {
+    return false;
+  }
+}
 /**
  * Uploads the given file to a remote location. HTTP(S) and FTP
  * protocols are supported.
  *
  * @param {string} localPath - The path to a file on the local storage.
  * @param {string} remoteUri - The remote URI to upload the file to.
- * @param {?FtpUploadOptions|HttpUploadOptions} uploadOptions
+ * @param {(HttpUploadOptions|NotHttpUploadOptions) & NetOptions} [uploadOptions]
+ * @returns {Promise<void>}
  */
-async function uploadFile (localPath, remoteUri, uploadOptions = {}) {
+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`);
   }
@@ -154,26 +171,25 @@ async function uploadFile (localPath, remoteUri, uploadOptions = {}) {
   const {
     isMetered = true,
   } = uploadOptions;
-
-  const parsedUri = url.parse(remoteUri);
+  const url = new URL(remoteUri);
   const {size} = await fs.stat(localPath);
   if (isMetered) {
     log.info(`Uploading '${localPath}' of ${toReadableSizeString(size)} size to '${remoteUri}'`);
   }
   const timer = new Timer().start();
-  if (['http:', 'https:'].includes(parsedUri.protocol)) {
+  if (isHttpUploadOptions(uploadOptions, url)) {
     if (!uploadOptions.fileFieldName) {
-      uploadOptions.headers = Object.assign({},
-        _.isPlainObject(uploadOptions.headers) ? uploadOptions.headers : {},
-        {'Content-Length': size}
-      );
+      uploadOptions.headers = {
+        ...(_.isPlainObject(uploadOptions.headers) ? uploadOptions.headers : {}),
+        'Content-Length': size
+      };
     }
-    await uploadFileToHttp(fs.createReadStream(localPath), parsedUri, uploadOptions);
-  } else if (parsedUri.protocol === 'ftp:') {
-    await uploadFileToFtp(fs.createReadStream(localPath), parsedUri, uploadOptions);
+    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 '${parsedUri.protocol}'. ` +
+      `Unsupported remote protocol '${url.protocol}'. ` +
       `Only http/https and ftp/ftps protocols are supported.`);
   }
   if (isMetered) {
@@ -182,24 +198,15 @@ async function uploadFile (localPath, remoteUri, uploadOptions = {}) {
   }
 }
 
-/**
- * @typedef {Object} DownloadOptions
- * @property {boolean} isMetered [true] - Whether to log the actual download performance
- * (e.g. timings and speed)
- * @property {AuthCredentials} auth
- * @property {number} timeout [240000] - The actual request timeout in milliseconds
- * @property {Object} headers - Request headers mapping
- */
-
 /**
  * Downloads the given file via HTTP(S)
  *
  * @param {string} remoteUrl - The remote url
  * @param {string} dstPath - The local path to download the file to
- * @param {?DownloadOptions} downloadOptions
+ * @param {DownloadOptions & NetOptions} [downloadOptions]
  * @throws {Error} If download operation fails
  */
-async function downloadFile (remoteUrl, dstPath, downloadOptions = {}) {
+async function downloadFile (remoteUrl, dstPath, downloadOptions = /** @type {DownloadOptions & NetOptions} */({})) {
   const {
     isMetered = true,
     auth,
@@ -207,6 +214,9 @@ async function downloadFile (remoteUrl, dstPath, downloadOptions = {}) {
     headers,
   } = downloadOptions;
 
+  /**
+   * @type {import('axios').AxiosRequestConfig}
+   */
   const requestOpts = {
     url: remoteUrl,
     responseType: 'stream',
@@ -261,3 +271,49 @@ async function downloadFile (remoteUrl, dstPath, downloadOptions = {}) {
 }
 
 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
+ */
+
+/**
+ * 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
+ */
+
+/**
+ * Basic auth credentials; used by {@linkcode NetOptions}.
+ * @typedef AuthCredentials
+ * @property {string} user - Non-empty user name
+ * @property {string} pass - Non-empty password
+ */
+
+/**
+ * This type is used in {@linkcode uploadFile} if the remote location uses the `ftp` protocol, and distinguishes the type from {@linkcode HttpUploadOptions}.
+ * @typedef NotHttpUploadOptions
+ * @property {never} headers
+ * @property {never} method
+ * @property {never} timeout
+ * @property {never} fileFieldName
+ * @property {never} formFields
+ */
+
+/**
+ * Specific options for {@linkcode uploadFile} if the remote location uses the `http(s)` protocol
+ * @typedef HttpUploadOptions
+ * @property {Record<string,any>} headers - Additional request headers mapping
+ * @property {import('axios').Method} [method='POST'] - The HTTP method used for file upload
+ * @property {number} [timeout] - The actual request timeout in milliseconds; defaults to {@linkcode DEFAULT_TIMEOUT_MS}
+ * @property {string} [fileFieldName='file'] - The name of the form field containing the file
+ * content to be uploaded. Any falsy value make the request to use non-multipart upload
+ * @property {Record<string,any>} [formFields] - The additional form fields
+ * to be included into the upload request. This property is only considered if
+ * `fileFieldName` is set
+ */
+

package/lib/node.js

@@ -1,12 +1,20 @@
 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
  *
- * @returns {string} - name of the package to link
+ * @param {string} packageName - name of the package to link
  * @throws {Error} If the command fails
  */
 async function linkGlobalPackage (packageName) {
@@ -32,7 +40,7 @@ async function linkGlobalPackage (packageName) {
  * this will attempt to link the package and then re-require it
  *
  * @param {string} packageName - the name of the package to be required
- * @returns {object} - the package object
+ * @returns {Promise<unknown>} - the package object
  * @throws {Error} If the package is not found locally or globally
  */
 async function requirePackage (packageName) {
@@ -46,7 +54,7 @@ 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) {
@@ -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)
+          ? /** @type {string} */(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 };