appium 2.0.0-beta.8 → 2.0.0-rc.1

package/lib/utils.js

@@ -1,65 +1,80 @@
 import _ from 'lodash';
 import logger from './logger';
-import { processCapabilities, PROTOCOLS } from 'appium-base-driver';
-import findRoot from 'find-root';
+import {processCapabilities, PROTOCOLS, STANDARD_CAPS} from '@appium/base-driver';
+import {inspect as dump} from 'util';
+import {node} from '@appium/support';
+import path from 'path';
+import {SERVER_SUBCOMMAND, DRIVER_TYPE, PLUGIN_TYPE} from './constants';
+import os from 'node:os';
 
 const W3C_APPIUM_PREFIX = 'appium';
+const STANDARD_CAPS_LOWERCASE = new Set([...STANDARD_CAPS].map((cap) => cap.toLowerCase()));
+export const V4_BROADCAST_IP = '0.0.0.0';
+export const V6_BROADCAST_IP = '::';
 
-function inspectObject (args) {
-  function getValueArray (obj, indent = '  ') {
-    if (!_.isObject(obj)) {
-      return [obj];
-    }
 
-    let strArr = ['{'];
-    for (let [arg, value] of _.toPairs(obj)) {
-      if (!_.isObject(value)) {
-        strArr.push(`${indent}  ${arg}: ${value}`);
-      } else {
-        value = getValueArray(value, `${indent}  `);
-        strArr.push(`${indent}  ${arg}: ${value.shift()}`);
-        strArr.push(...value);
-      }
-    }
-    strArr.push(`${indent}}`);
-    return strArr;
-  }
-  for (let [arg, value] of _.toPairs(args)) {
-    value = getValueArray(value);
-    logger.info(`  ${arg}: ${value.shift()}`);
-    for (let val of value) {
-      logger.info(val);
-    }
+/**
+ *
+ * If `stdout` is a TTY, this is `true`.
+ *
+ * Used for tighter control over log output.
+ * @type {boolean}
+ */
+const isStdoutTTY = process.stdout.isTTY;
+
+/**
+ * Dumps to value to the console using `info` logger.
+ *
+ * @todo May want to force color to be `false` if {@link isStdoutTTY} is `false`.
+ */
+const inspect = _.flow(
+  _.partialRight(
+    /** @type {(object: any, options: import('util').InspectOptions) => string} */ (dump),
+    {colors: true, depth: null, compact: !isStdoutTTY}
+  ),
+  (...args) => {
+    logger.info(...args);
   }
-}
+);
 
 /**
  * Takes the caps that were provided in the request and translates them
  * into caps that can be used by the inner drivers.
  *
- * @param {Object} jsonwpCapabilities
- * @param {Object} w3cCapabilities
- * @param {Object} constraints
- * @param {Object} defaultCapabilities
+ * @template {Constraints} C
+ * @template [J=any]
+ * @param {J} jsonwpCapabilities
+ * @param {W3CCapabilities<C>} w3cCapabilities
+ * @param {C} constraints
+ * @param {NSCapabilities<C>} [defaultCapabilities]
+ * @returns {ParsedDriverCaps<C,J>|InvalidCaps<C,J>}
  */
-function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constraints = {}, defaultCapabilities = {}) {
+function parseCapsForInnerDriver(
+  jsonwpCapabilities,
+  w3cCapabilities,
+  constraints = /** @type {C} */ ({}),
+  defaultCapabilities = {}
+) {
   // Check if the caller sent JSONWP caps, W3C caps, or both
-  const hasW3CCaps = _.isPlainObject(w3cCapabilities) &&
+  const hasW3CCaps =
+    _.isPlainObject(w3cCapabilities) &&
     (_.has(w3cCapabilities, 'alwaysMatch') || _.has(w3cCapabilities, 'firstMatch'));
   const hasJSONWPCaps = _.isPlainObject(jsonwpCapabilities);
-  let protocol = null;
-  let desiredCaps = {};
-  let processedW3CCapabilities = null;
-  let processedJsonwpCapabilities = null;
+  let desiredCaps = /** @type {ParsedDriverCaps<C>['desiredCaps']} */ ({});
+  /** @type {ParsedDriverCaps<C>['processedW3CCapabilities']} */
+  let processedW3CCapabilities;
+  /** @type {ParsedDriverCaps<C>['processedJsonwpCapabilities']} */
+  let processedJsonwpCapabilities;
 
-  if (!hasJSONWPCaps && !hasW3CCaps) {
-    return {
+  if (!hasW3CCaps) {
+    return /** @type {InvalidCaps<C>} */ ({
       protocol: PROTOCOLS.W3C,
-      error: new Error('Either JSONWP or W3C capabilities should be provided'),
-    };
+      error: new Error('W3C capabilities should be provided'),
+    });
   }
 
-  const {W3C, MJSONWP} = PROTOCOLS;
+  const {W3C} = PROTOCOLS;
+  const protocol = W3C;
 
   // Make sure we don't mutate the original arguments
   jsonwpCapabilities = _.cloneDeep(jsonwpCapabilities);
@@ -71,16 +86,23 @@ function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constrain
       for (const [defaultCapKey, defaultCapValue] of _.toPairs(defaultCapabilities)) {
         let isCapAlreadySet = false;
         // Check if the key is already present in firstMatch entries
-        for (const firstMatchEntry of (w3cCapabilities.firstMatch || [])) {
-          if (_.isPlainObject(firstMatchEntry)
-              && _.has(removeAppiumPrefixes(firstMatchEntry), removeAppiumPrefix(defaultCapKey))) {
+        for (const firstMatchEntry of w3cCapabilities.firstMatch ?? []) {
+          if (
+            _.isPlainObject(firstMatchEntry) &&
+            _.has(removeAppiumPrefixes(firstMatchEntry), removeAppiumPrefix(defaultCapKey))
+          ) {
             isCapAlreadySet = true;
             break;
           }
         }
         // Check if the key is already present in alwaysMatch entries
-        isCapAlreadySet = isCapAlreadySet || (_.isPlainObject(w3cCapabilities.alwaysMatch)
-          && _.has(removeAppiumPrefixes(w3cCapabilities.alwaysMatch), removeAppiumPrefix(defaultCapKey)));
+        isCapAlreadySet =
+          isCapAlreadySet ||
+          (_.isPlainObject(w3cCapabilities.alwaysMatch) &&
+            _.has(
+              removeAppiumPrefixes(w3cCapabilities.alwaysMatch),
+              removeAppiumPrefix(defaultCapKey)
+            ));
         if (isCapAlreadySet) {
           // Skip if the key is already present in the provided caps
           continue;
@@ -88,69 +110,42 @@ function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constrain
 
         // Only add the default capability if it is not overridden
         if (_.isEmpty(w3cCapabilities.firstMatch)) {
-          w3cCapabilities.firstMatch = [{[defaultCapKey]: defaultCapValue}];
+          w3cCapabilities.firstMatch = /** @type {W3CCapabilities<C>['firstMatch']} */ ([
+            {[defaultCapKey]: defaultCapValue},
+          ]);
         } else {
           w3cCapabilities.firstMatch[0][defaultCapKey] = defaultCapValue;
         }
       }
     }
     if (hasJSONWPCaps) {
-      jsonwpCapabilities = Object.assign({}, removeAppiumPrefixes(defaultCapabilities), jsonwpCapabilities);
+      jsonwpCapabilities = {
+        ...removeAppiumPrefixes(defaultCapabilities),
+        ...jsonwpCapabilities,
+      };
     }
   }
 
   // Get MJSONWP caps
   if (hasJSONWPCaps) {
-    protocol = MJSONWP;
-    desiredCaps = jsonwpCapabilities;
     processedJsonwpCapabilities = {...jsonwpCapabilities};
   }
 
   // Get W3C caps
   if (hasW3CCaps) {
-    protocol = W3C;
     // Call the process capabilities algorithm to find matching caps on the W3C
     // (see: https://github.com/jlipps/simple-wd-spec#processing-capabilities)
-    let isFixingNeededForW3cCaps = false;
     try {
       desiredCaps = processCapabilities(w3cCapabilities, constraints, true);
     } catch (error) {
-      if (!hasJSONWPCaps) {
-        return {
-          desiredCaps,
-          processedJsonwpCapabilities,
-          processedW3CCapabilities,
-          protocol,
-          error,
-        };
-      }
       logger.info(`Could not parse W3C capabilities: ${error.message}`);
-      isFixingNeededForW3cCaps = true;
-    }
-
-    if (hasJSONWPCaps && !isFixingNeededForW3cCaps) {
-      const differingKeys = _.difference(_.keys(removeAppiumPrefixes(processedJsonwpCapabilities)), _.keys(removeAppiumPrefixes(desiredCaps)));
-      if (!_.isEmpty(differingKeys)) {
-        logger.info(`The following capabilities were provided in the JSONWP desired capabilities that are missing ` +
-          `in W3C capabilities: ${JSON.stringify(differingKeys)}`);
-        isFixingNeededForW3cCaps = true;
-      }
-    }
-
-    if (isFixingNeededForW3cCaps && hasJSONWPCaps) {
-      logger.info('Trying to fix W3C capabilities by merging them with JSONWP caps');
-      w3cCapabilities = fixW3cCapabilities(w3cCapabilities, jsonwpCapabilities);
-      try {
-        desiredCaps = processCapabilities(w3cCapabilities, constraints, true);
-      } catch (error) {
-        logger.warn(`Could not parse fixed W3C capabilities: ${error.message}. Falling back to JSONWP protocol`);
-        return {
-          desiredCaps: processedJsonwpCapabilities,
-          processedJsonwpCapabilities,
-          processedW3CCapabilities: null,
-          protocol: MJSONWP,
-        };
-      }
+      return /** @type {InvalidCaps<C,J>} */ ({
+        desiredCaps,
+        processedJsonwpCapabilities,
+        processedW3CCapabilities,
+        protocol,
+        error,
+      });
     }
 
     // Create a new w3c capabilities payload that contains only the matching caps in `alwaysMatch`
@@ -160,99 +155,110 @@ function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constrain
     };
   }
 
-  return {desiredCaps, processedJsonwpCapabilities, processedW3CCapabilities, protocol};
+  return /** @type {ParsedDriverCaps<C,J>} */ ({
+    desiredCaps,
+    processedJsonwpCapabilities,
+    processedW3CCapabilities,
+    protocol,
+  });
 }
 
 /**
- * This helper method tries to fix corrupted W3C capabilities by
- * merging them to existing JSONWP capabilities.
- *
- * @param {Object} w3cCaps W3C capabilities
- * @param {Object} jsonwpCaps JSONWP capabilities
- * @return {Object} Fixed W3C capabilities
+ * Takes a capabilities objects and prefixes capabilities with `appium:`
+ * @template {Constraints} [C={}]
+ * @param {Capabilities<C>} caps - Desired capabilities object
+ * @returns {NSCapabilities<C>}
  */
-function fixW3cCapabilities (w3cCaps, jsonwpCaps) {
-  const result = {
-    firstMatch: w3cCaps.firstMatch || [],
-    alwaysMatch: w3cCaps.alwaysMatch || {},
-  };
-  const keysToInsert = _.keys(jsonwpCaps);
-  const removeMatchingKeys = (match) => {
-    _.pull(keysToInsert, match);
-    const colonIndex = match.indexOf(':');
-    if (colonIndex >= 0 && match.length > colonIndex) {
-      _.pull(keysToInsert, match.substring(colonIndex + 1));
-    }
-    if (keysToInsert.includes(`${W3C_APPIUM_PREFIX}:${match}`)) {
-      _.pull(keysToInsert, `${W3C_APPIUM_PREFIX}:${match}`);
-    }
-  };
+function insertAppiumPrefixes(caps) {
+  return /** @type {NSCapabilities<C>} */ (
+    _.mapKeys(caps, (_, key) =>
+      STANDARD_CAPS_LOWERCASE.has(key.toLowerCase()) || key.includes(':')
+        ? key
+        : `${W3C_APPIUM_PREFIX}:${key}`
+    )
+  );
+}
 
-  for (const firstMatchEntry of result.firstMatch) {
-    for (const pair of _.toPairs(firstMatchEntry)) {
-      removeMatchingKeys(pair[0]);
-    }
-  }
+/**
+ * @template {Constraints} [C={}]
+ * @param {NSCapabilities<C>} caps
+ * @returns {Capabilities<C>}
+ */
+function removeAppiumPrefixes(caps) {
+  return /** @type {Capabilities<C>} */ (_.mapKeys(caps, (_, key) => removeAppiumPrefix(key)));
+}
 
-  for (const pair of _.toPairs(result.alwaysMatch)) {
-    removeMatchingKeys(pair[0]);
-  }
+/**
+ * @param {string} key
+ * @returns {string}
+ */
+function removeAppiumPrefix(key) {
+  const prefix = `${W3C_APPIUM_PREFIX}:`;
+  return _.startsWith(key, prefix) ? key.substring(prefix.length) : key;
+}
 
-  for (const key of keysToInsert) {
-    result.alwaysMatch[key] = jsonwpCaps[key];
-  }
-  return result;
+/**
+ *
+ * @param {string} pkgName
+ * @returns {string|undefined}
+ */
+function getPackageVersion(pkgName) {
+  const pkgInfo = require(`${pkgName}/package.json`) || {};
+  return pkgInfo.version;
 }
 
 /**
- * Takes a capabilities objects and prefixes capabilities with `appium:`
- * @param {Object} caps Desired capabilities object
+ * Adjusts NODE_PATH environment variable,
+ * so drivers and plugins could load their peer dependencies.
+ * Read https://nodejs.org/api/modules.html#loading-from-the-global-folders
+ * for more details.
+ * @returns {void}
  */
-function insertAppiumPrefixes (caps) {
-  // Standard, non-prefixed capabilities (see https://www.w3.org/TR/webdriver/#dfn-table-of-standard-capabilities)
-  const STANDARD_CAPS = [
-    'browserName',
-    'browserVersion',
-    'platformName',
-    'acceptInsecureCerts',
-    'pageLoadStrategy',
-    'proxy',
-    'setWindowRect',
-    'timeouts',
-    'unhandledPromptBehavior'
-  ];
-
-  let prefixedCaps = {};
-  for (let [name, value] of _.toPairs(caps)) {
-    if (STANDARD_CAPS.includes(name) || name.includes(':')) {
-      prefixedCaps[name] = value;
+function adjustNodePath() {
+  const selfRoot = node.getModuleRootSync('appium', __filename);
+  if (!selfRoot || path.dirname(selfRoot).length >= selfRoot.length) {
+    return;
+  }
+  const nodeModulesRoot = path.dirname(selfRoot);
+
+  const refreshRequirePaths = () => {
+    try {
+      // ! This hack allows us to avoid modification of import
+      // ! statements in client modules. It uses a private API though,
+      // ! so it could break (maybe, eventually).
+      // See https://gist.github.com/branneman/8048520#7-the-hack
+      // @ts-ignore see above comment
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      require('module').Module._initPaths();
+      return true;
+    } catch (e) {
+      return false;
+    }
+  };
+
+  if (!process.env.NODE_PATH) {
+    process.env.NODE_PATH = nodeModulesRoot;
+    if (refreshRequirePaths()) {
+      process.env.APPIUM_OMIT_PEER_DEPS = '1';
     } else {
-      prefixedCaps[`${W3C_APPIUM_PREFIX}:${name}`] = value;
+      delete process.env.NODE_PATH;
     }
+    return;
   }
-  return prefixedCaps;
-}
 
-function removeAppiumPrefixes (caps) {
-  if (!_.isPlainObject(caps)) {
-    return caps;
+  const nodePathParts = process.env.NODE_PATH.split(path.delimiter);
+  if (nodePathParts.includes(nodeModulesRoot)) {
+    process.env.APPIUM_OMIT_PEER_DEPS = '1';
+    return;
   }
 
-  const fixedCaps = {};
-  for (let [name, value] of _.toPairs(caps)) {
-    fixedCaps[removeAppiumPrefix(name)] = value;
+  nodePathParts.push(nodeModulesRoot);
+  process.env.NODE_PATH = nodePathParts.join(path.delimiter);
+  if (refreshRequirePaths()) {
+    process.env.APPIUM_OMIT_PEER_DEPS = '1';
+  } else {
+    process.env.NODE_PATH = _.without(nodePathParts, nodeModulesRoot).join(path.delimiter);
   }
-  return fixedCaps;
-}
-
-function removeAppiumPrefix (key) {
-  const prefix = `${W3C_APPIUM_PREFIX}:`;
-  return _.startsWith(key, prefix) ? key.substring(prefix.length) : key;
-}
-
-function getPackageVersion (pkgName) {
-  const pkgInfo = require(`${pkgName}/package.json`) || {};
-  return pkgInfo.version;
 }
 
 /**
@@ -271,7 +277,7 @@ function getPackageVersion (pkgName) {
  * setting items or a dictionary containing parsed Appium setting names along with
  * their values.
  */
-function pullSettings (caps) {
+function pullSettings(caps) {
   if (!_.isPlainObject(caps) || _.isEmpty(caps)) {
     return {};
   }
@@ -289,9 +295,151 @@ function pullSettings (caps) {
   return result;
 }
 
-const rootDir = findRoot(__dirname);
+/**
+ * @template {CliCommand} [Cmd=ServerCommand]
+ * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @param {Args<Cmd, SubCmd>} args
+ * @returns {args is Args<ServerCommand>}
+ */
+export function isServerCommandArgs(args) {
+  return args.subcommand === SERVER_SUBCOMMAND;
+}
+
+/**
+ * @template {CliCommand} [Cmd=ServerCommand]
+ * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @param {Args<Cmd, SubCmd>} args
+ * @returns {args is Args<CliExtensionCommand, SubCmd>}
+ */
+export function isExtensionCommandArgs(args) {
+  return args.subcommand === DRIVER_TYPE || args.subcommand === PLUGIN_TYPE;
+}
+
+/**
+ * @template {CliCommand} Cmd
+ * @template {CliExtensionSubcommand} SubCmd
+ * @param {Args<Cmd, SubCmd>} args
+ * @returns {args is Args<DriverCommand, SubCmd>}
+ */
+export function isDriverCommandArgs(args) {
+  return args.subcommand === DRIVER_TYPE;
+}
+
+/**
+ * @template {CliCommand} Cmd
+ * @template {CliExtensionSubcommand} SubCmd
+ * @param {Args<Cmd, SubCmd>} args
+ * @returns {args is Args<PluginCommand, SubCmd>}
+ */
+export function isPluginCommandArgs(args) {
+  return args.subcommand === PLUGIN_TYPE;
+}
+
+/**
+ * Fetches the list of IP addresses of the current host.
+ *
+ * @param {4|6|null} family Either 4 to include ipv4 addresses only,
+ * 6 to include ipv6 addresses only, or null to include all of them
+ * @returns {string[]} The list of matched IP addresses
+ */
+export function fetchIpAddresses (family = null) {
+  let familyValue = null;
+  // 'IPv4' is in Node <= 17, from 18 it's a number 4 or 6
+  if (family === 4) {
+    familyValue = [4, 'IPv4'];
+  } else if (family === 6) {
+    familyValue = [6, 'IPv6'];
+  }
+  return _.flatMap(_.values(os.networkInterfaces()).filter(Boolean))
+    // @ts-ignore The linter does not understand the above filter
+    .filter(({family}) => !familyValue || familyValue && familyValue.includes(family))
+    // @ts-ignore The linter does not understand the above filter
+    .map(({address}) => address);
+}
 
 export {
-  inspectObject, parseCapsForInnerDriver, insertAppiumPrefixes, rootDir,
-  getPackageVersion, pullSettings, removeAppiumPrefixes,
+  inspect,
+  parseCapsForInnerDriver,
+  insertAppiumPrefixes,
+  getPackageVersion,
+  pullSettings,
+  removeAppiumPrefixes,
+  adjustNodePath,
 };
+
+/**
+ * @typedef {import('@appium/types').StringRecord} StringRecord
+ * @typedef {import('@appium/types').BaseDriverCapConstraints} BaseDriverCapConstraints
+ */
+
+/**
+ * @template {Constraints} [C=BaseDriverCapConstraints]
+ * @template [J=any]
+ * @typedef ParsedDriverCaps
+ * @property {Capabilities<C>} desiredCaps
+ * @property {string} protocol
+ * @property {J} [processedJsonwpCapabilities]
+ * @property {W3CCapabilities<C>} [processedW3CCapabilities]
+ */
+
+/**
+ * @todo protocol is more specific
+ * @template {Constraints} [C=BaseDriverCapConstraints]
+ * @template [J=any]
+ * @typedef InvalidCaps
+ * @property {Error} error
+ * @property {string} protocol
+ * @property {Capabilities<C>} [desiredCaps]
+ * @property {J} [processedJsonwpCapabilities]
+ * @property {W3CCapabilities<C>} [processedW3CCapabilities]
+ */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').Capabilities<C>} Capabilities
+ */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').W3CCapabilities<C>} W3CCapabilities
+ */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').NSCapabilities<C>} NSCapabilities
+ */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').ConstraintsToCaps<C>} ConstraintsToCaps
+ */
+
+/**
+ * @template T
+ * @typedef {import('type-fest').StringKeyOf<T>} StringKeyOf
+ */
+
+/**
+ * @typedef {import('@appium/types').Constraints} Constraints
+ */
+
+/**
+ * @typedef {import('appium/types').CliCommand} CliCommand
+ * @typedef {import('appium/types').CliExtensionSubcommand} CliExtensionSubcommand
+ * @typedef {import('appium/types').CliExtensionCommand} CliExtensionCommand
+ * @typedef {import('appium/types').CliCommandServer} ServerCommand
+ * @typedef {import('appium/types').CliCommandDriver} DriverCommand
+ * @typedef {import('appium/types').CliCommandPlugin} PluginCommand
+ */
+
+/**
+ * @template {CliCommand} [Cmd=ServerCommand]
+ * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @typedef {import('appium/types').Args<Cmd, SubCmd>} Args
+ */
+
+/**
+ * @template {CliCommand} [Cmd=ServerCommand]
+ * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @typedef {import('appium/types').ParsedArgs<Cmd, SubCmd>} ParsedArgs
+ */