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

package/lib/config.js

@@ -1,54 +1,79 @@
+/* eslint-disable no-console */
 import _ from 'lodash';
-import path from 'path';
-import { mkdirp, fs, system } from 'appium-support';
+import {system, fs} from '@appium/support';
 import axios from 'axios';
-import { exec } from 'teen_process';
-import { rootDir } from './utils';
-import logger from './logger';
+import {exec} from 'teen_process';
 import semver from 'semver';
-import {
-  StoreDeprecatedDefaultCapabilityAction, DEFAULT_CAPS_ARG,
-} from './cli/argparse-actions';
+import findUp from 'find-up';
+import {getDefaultsForSchema, getAllArgSpecs} from './schema/schema';
 
+const npmPackage = fs.readPackageJsonFrom(__dirname);
 
-const npmPackage = require(path.resolve(rootDir, 'package.json'));
 const APPIUM_VER = npmPackage.version;
-const MIN_NODE_VERSION = npmPackage.engines.node;
+const ENGINES = /** @type {Record<string,string>} */ (npmPackage.engines);
+const MIN_NODE_VERSION = ENGINES.node;
+const MIN_NPM_VERSION = ENGINES.npm;
 
 const GIT_META_ROOT = '.git';
 const GIT_BINARY = `git${system.isWindows() ? '.exe' : ''}`;
 const GITHUB_API = 'https://api.github.com/repos/appium/appium';
 
+/**
+ * @type {import('appium/types').BuildInfo}
+ */
 const BUILD_INFO = {
   version: APPIUM_VER,
 };
 
-function getNodeVersion () {
-  return semver.coerce(process.version);
+function getNodeVersion() {
+  return /** @type {import('semver').SemVer} */ (semver.coerce(process.version));
 }
 
-function isSubClass (candidateClass, superClass) {
-  return _.isFunction(superClass) && _.isFunction(candidateClass)
-    && (candidateClass.prototype instanceof superClass || candidateClass === superClass);
+/**
+ * Returns version of `npm`
+ * @returns {Promise<string>}
+ */
+async function getNpmVersion() {
+  const {stdout} = await exec(system.isWindows() ? 'npm.cmd' : 'npm', ['--version']);
+  return stdout.trim();
 }
 
-async function updateBuildInfo (useGithubApiFallback = false) {
+/**
+ * @param {boolean} [useGithubApiFallback]
+ */
+async function updateBuildInfo(useGithubApiFallback = false) {
   const sha = await getGitRev(useGithubApiFallback);
   if (!sha) {
     return;
   }
   BUILD_INFO['git-sha'] = sha;
-  const built = await getGitTimestamp(sha, useGithubApiFallback);
-  if (!_.isEmpty(built)) {
-    BUILD_INFO.built = built;
+  const buildTimestamp = await getGitTimestamp(sha, useGithubApiFallback);
+  if (buildTimestamp) {
+    BUILD_INFO.built = buildTimestamp;
   }
 }
 
-async function getGitRev (useGithubApiFallback = false) {
-  if (await fs.exists(path.resolve(rootDir, GIT_META_ROOT))) {
+/**
+ * Finds the Git metadata dir (see `GIT_META_ROOT`)
+ *
+ * This is needed because Appium cannot assume `package.json` and `.git` are in the same
+ * directory.  Monorepos, see?
+ * @returns {Promise<string|undefined>} Path to dir or `undefined` if not found
+ */
+async function findGitRoot() {
+  return await findUp(GIT_META_ROOT, {cwd: rootDir, type: 'directory'});
+}
+
+/**
+ * @param {boolean} [useGithubApiFallback]
+ * @returns {Promise<string?>}
+ */
+async function getGitRev(useGithubApiFallback = false) {
+  const gitRoot = await findGitRoot();
+  if (gitRoot) {
     try {
       const {stdout} = await exec(GIT_BINARY, ['rev-parse', 'HEAD'], {
-        cwd: rootDir
+        cwd: gitRoot,
       });
       return stdout.trim();
     } catch (ign) {}
@@ -58,28 +83,31 @@ async function getGitRev (useGithubApiFallback = false) {
     return null;
   }
 
+  // If the package folder is not a valid git repository
+  // then fetch the corresponding tag info from GitHub
   try {
-    const resBodyObj = (await axios.get(`${GITHUB_API}/tags`, {
-      headers: {
-        'User-Agent': `Appium ${APPIUM_VER}`
-      }
-    })).data;
-    if (_.isArray(resBodyObj)) {
-      for (const {name, commit} of resBodyObj) {
-        if (name === `v${APPIUM_VER}` && commit && commit.sha) {
-          return commit.sha;
-        }
-      }
-    }
+    return (
+      await axios.get(`${GITHUB_API}/git/refs/tags/appium@${APPIUM_VER}`, {
+        headers: {
+          'User-Agent': `Appium ${APPIUM_VER}`,
+        },
+      })
+    ).data?.object?.sha;
   } catch (ign) {}
   return null;
 }
 
-async function getGitTimestamp (commitSha, useGithubApiFallback = false) {
-  if (await fs.exists(path.resolve(rootDir, GIT_META_ROOT))) {
+/**
+ * @param {string} commitSha
+ * @param {boolean} [useGithubApiFallback]
+ * @returns {Promise<string?>}
+ */
+async function getGitTimestamp(commitSha, useGithubApiFallback = false) {
+  const gitRoot = await findGitRoot();
+  if (gitRoot) {
     try {
       const {stdout} = await exec(GIT_BINARY, ['show', '-s', '--format=%ci', commitSha], {
-        cwd: rootDir
+        cwd: gitRoot,
       });
       return stdout.trim();
     } catch (ign) {}
@@ -90,46 +118,51 @@ async function getGitTimestamp (commitSha, useGithubApiFallback = false) {
   }
 
   try {
-    const resBodyObj = (await axios.get(`${GITHUB_API}/commits/${commitSha}`, {
-      headers: {
-        'User-Agent': `Appium ${APPIUM_VER}`
-      }
-    })).data;
-    if (resBodyObj && resBodyObj.commit) {
-      if (resBodyObj.commit.committer && resBodyObj.commit.committer.date) {
-        return resBodyObj.commit.committer.date;
-      }
-      if (resBodyObj.commit.author && resBodyObj.commit.author.date) {
-        return resBodyObj.commit.author.date;
-      }
-    }
+    return (
+      await axios.get(`${GITHUB_API}/git/tags/${commitSha}`, {
+        headers: {
+          'User-Agent': `Appium ${APPIUM_VER}`,
+        },
+      })
+    ).data?.tagger?.date;
   } catch (ign) {}
   return null;
 }
 
 /**
- * @return Mutable object containing Appium build information. By default it
+ * Mutable object containing Appium build information. By default it
  * only contains the Appium version, but is updated with the build timestamp
  * and git commit hash asynchronously as soon as `updateBuildInfo` is called
  * and succeeds.
+ * @returns {import('appium/types').BuildInfo}
  */
-function getBuildInfo () {
+function getBuildInfo() {
   return BUILD_INFO;
 }
 
-function checkNodeOk () {
+function checkNodeOk() {
   const version = getNodeVersion();
   if (!semver.satisfies(version, MIN_NODE_VERSION)) {
-    logger.errorAndThrow(`Node version must be ${MIN_NODE_VERSION}. Currently ${version.version}`);
+    throw new Error(
+      `Node version must be at least ${MIN_NODE_VERSION}; current is ${version.version}`
+    );
   }
 }
 
-function warnNodeDeprecations () {
+export async function checkNpmOk() {
+  const npmVersion = await getNpmVersion();
+  if (!semver.satisfies(npmVersion, MIN_NPM_VERSION)) {
+    throw new Error(
+      `npm version must be at least ${MIN_NPM_VERSION}; current is ${npmVersion}. Run "npm install -g npm" to upgrade.`
+    );
+  }
+}
+
+function warnNodeDeprecations() {
   /**
    * Uncomment this section to get node version deprecation warnings
    * Also add test cases to config-specs.js to cover the cases added
    **/
-
   // const version = getNodeVersion();
   // if (version.major < 8) {
   //   logger.warn(`Appium support for versions of node < ${version.major} has been ` +
@@ -138,99 +171,177 @@ function warnNodeDeprecations () {
   // }
 }
 
-async function showConfig () {
+async function showBuildInfo() {
   await updateBuildInfo(true);
   console.log(JSON.stringify(getBuildInfo())); // eslint-disable-line no-console
 }
 
-function getNonDefaultArgs (parser, args) {
-  return parser.rawArgs.reduce((acc, [, {dest, default: defaultValue}]) => {
-    if (args[dest] && args[dest] !== defaultValue) {
-      acc[dest] = args[dest];
-    }
-    return acc;
-  }, {});
-}
+/**
+ * Returns k/v pairs of server arguments which are _not_ the defaults.
+ * @param {Args} parsedArgs
+ * @returns {Args}
+ */
+function getNonDefaultServerArgs(parsedArgs) {
+  /**
+   * Flattens parsed args into a single level object for comparison with
+   * flattened defaults across server args and extension args.
+   * @param {Args} args
+   * @returns {Record<string, { value: any, argSpec: ArgSpec }>}
+   */
+  const flatten = (args) => {
+    const argSpecs = getAllArgSpecs();
+    const flattened = _.reduce(
+      [...argSpecs.values()],
+      (acc, argSpec) => {
+        if (_.has(args, argSpec.dest)) {
+          acc[argSpec.dest] = {value: _.get(args, argSpec.dest), argSpec};
+        }
+        return acc;
+      },
+      /** @type {Record<string, { value: any, argSpec: ArgSpec }>} */ ({})
+    );
 
-function getDeprecatedArgs (parser, args) {
-  // go through the server command line arguments and figure
-  // out which of the ones used are deprecated
-  return parser.rawArgs.reduce((acc, [[name], {dest, default: defaultValue, action}]) => {
-    if (!args[dest] || args[dest] === defaultValue) {
-      return acc;
-    }
-
-    if (action?.deprecated_for) {
-      acc[name] = action.deprecated_for;
-    } else if (isSubClass(action, StoreDeprecatedDefaultCapabilityAction)) {
-      acc[name] = DEFAULT_CAPS_ARG;
-    }
-    return acc;
-  }, {});
-}
+    return flattened;
+  };
 
-function checkValidPort (port, portName) {
-  if (port > 0 && port < 65536) return true; // eslint-disable-line curly
-  logger.error(`Port '${portName}' must be greater than 0 and less than 65536. Currently ${port}`);
-  return false;
-}
+  const args = flatten(parsedArgs);
 
-function validateServerArgs (parser, args) {
-  // arguments that cannot both be set
-  let exclusives = [
-    ['noReset', 'fullReset'],
-    ['ipa', 'safari'],
-    ['app', 'safari'],
-    ['forceIphone', 'forceIpad'],
-    ['deviceName', 'defaultDevice']
-  ];
-
-  for (let exSet of exclusives) {
-    let numFoundInArgs = 0;
-    for (let opt of exSet) {
-      if (_.has(args, opt) && args[opt]) {
-        numFoundInArgs++;
-      }
-    }
-    if (numFoundInArgs > 1) {
-      throw new Error(`You can't pass in more than one argument from the ` +
-                      `set ${JSON.stringify(exSet)}, since they are ` +
-                      `mutually exclusive`);
-    }
-  }
+  // hopefully these function names are descriptive enough
+  const typesDiffer = /** @param {string} dest */ (dest) =>
+    typeof args[dest].value !== typeof defaultsFromSchema[dest];
 
-  const validations = {
-    port: checkValidPort,
-    callbackPort: checkValidPort,
-    bootstrapPort: checkValidPort,
-    chromedriverPort: checkValidPort,
-    robotPort: checkValidPort,
-    backendRetries: (r) => r >= 0,
-  };
+  const defaultValueIsArray = /** @param {string} dest */ (dest) =>
+    _.isArray(defaultsFromSchema[dest]);
+
+  const argsValueIsArray = /** @param {string} dest */ (dest) => _.isArray(args[dest].value);
+
+  const arraysDiffer = /** @param {string} dest */ (dest) =>
+    _.gt(_.size(_.difference(args[dest].value, defaultsFromSchema[dest])), 0);
+
+  const valuesDiffer = /** @param {string} dest */ (dest) =>
+    args[dest].value !== defaultsFromSchema[dest];
+
+  const defaultIsDefined = /** @param {string} dest */ (dest) =>
+    !_.isUndefined(defaultsFromSchema[dest]);
+
+  // note that `_.overEvery` is like an "AND", and `_.overSome` is like an "OR"
+
+  const argValueNotArrayOrArraysDiffer = _.overSome([_.negate(argsValueIsArray), arraysDiffer]);
+
+  const defaultValueNotArrayAndValuesDiffer = _.overEvery([
+    _.negate(defaultValueIsArray),
+    valuesDiffer,
+  ]);
+
+  /**
+   * This used to be a hideous conditional, but it's broken up into a hideous function instead.
+   * hopefully this makes things a little more understandable.
+   * - checks if the default value is defined
+   * - if so, and the default is not an array:
+   *   - ensures the types are the same
+   *   - ensures the values are equal
+   * - if so, and the default is an array:
+   *   - ensures the args value is an array
+   *   - ensures the args values do not differ from the default values
+   * @type {(dest: string) => boolean}
+   */
+  const isNotDefault = _.overEvery([
+    defaultIsDefined,
+    _.overSome([
+      typesDiffer,
+      _.overEvery([defaultValueIsArray, argValueNotArrayOrArraysDiffer]),
+      defaultValueNotArrayAndValuesDiffer,
+    ]),
+  ]);
+
+  const defaultsFromSchema = getDefaultsForSchema(true);
 
-  const nonDefaultArgs = getNonDefaultArgs(parser, args);
+  return _.reduce(
+    _.pickBy(args, (__, key) => isNotDefault(key)),
+    // explodes the flattened object back into nested one
+    (acc, {value, argSpec}) => _.set(acc, argSpec.dest, value),
+    /** @type {Args} */ ({})
+  );
+}
+
+/**
+ * Compacts an object for {@link showConfig}:
+ * 1. Removes `subcommand` key/value
+ * 2. Removes `undefined` values
+ * 3. Removes empty objects (but not `false` values)
+ * Does not operate recursively.
+ */
+const compactConfig = _.partial(
+  _.omitBy,
+  _,
+  (value, key) =>
+    key === 'subcommand' || _.isUndefined(value) || (_.isObject(value) && _.isEmpty(value))
+);
 
-  for (let [arg, validator] of _.toPairs(validations)) {
-    if (_.has(nonDefaultArgs, arg)) {
-      if (!validator(args[arg], arg)) {
-        throw new Error(`Invalid argument for param ${arg}: ${args[arg]}`);
-      }
-    }
+/**
+ * Shows a breakdown of the current config after CLI params, config file loaded & defaults applied.
+ *
+ * The actual shape of `preConfigParsedArgs` and `defaults` does not matter for the purposes of this function,
+ * but it's intended to be called with values of type {@link ParsedArgs} and `DefaultValues<true>`, respectively.
+ *
+ * @param {Partial<ParsedArgs>} nonDefaultPreConfigParsedArgs - Parsed CLI args (or param to `init()`) before config & defaults applied
+ * @param {import('./config-file').ReadConfigFileResult} configResult - Result of attempting to load a config file.  _Must_ be normalized
+ * @param {Partial<ParsedArgs>} defaults - Configuration defaults from schemas
+ * @param {ParsedArgs} parsedArgs - Entire parsed args object
+ */
+function showConfig(nonDefaultPreConfigParsedArgs, configResult, defaults, parsedArgs) {
+  console.log('Appium Configuration\n');
+  console.log('from defaults:\n');
+  console.dir(compactConfig(defaults));
+  if (configResult.config) {
+    console.log(`\nfrom config file at ${configResult.filepath}:\n`);
+    console.dir(compactConfig(configResult.config));
+  } else {
+    console.log(`\n(no configuration file loaded)`);
+  }
+  const compactedNonDefaultPreConfigArgs = compactConfig(nonDefaultPreConfigParsedArgs);
+  if (_.isEmpty(compactedNonDefaultPreConfigArgs)) {
+    console.log(`\n(no CLI parameters provided)`);
+  } else {
+    console.log('\nvia CLI or function call:\n');
+    console.dir(compactedNonDefaultPreConfigArgs);
   }
+  console.log('\nfinal configuration:\n');
+  console.dir(compactConfig(parsedArgs));
 }
 
-async function validateTmpDir (tmpDir) {
+/**
+ * @param {string} tmpDir
+ */
+async function validateTmpDir(tmpDir) {
   try {
-    await mkdirp(tmpDir);
+    await fs.mkdirp(tmpDir);
   } catch (e) {
-    throw new Error(`We could not ensure that the temp dir you specified ` +
-                    `(${tmpDir}) exists. Please make sure it's writeable.`);
+    throw new Error(
+      `We could not ensure that the temp dir you specified ` +
+        `(${tmpDir}) exists. Please make sure it's writeable.`
+    );
   }
 }
 
+const rootDir = fs.findRoot(__dirname);
+
 export {
-  getBuildInfo, validateServerArgs, checkNodeOk, showConfig,
-  warnNodeDeprecations, validateTmpDir, getNonDefaultArgs,
-  getGitRev, checkValidPort, APPIUM_VER, updateBuildInfo,
-  getDeprecatedArgs,
+  getBuildInfo,
+  checkNodeOk,
+  showBuildInfo,
+  warnNodeDeprecations,
+  validateTmpDir,
+  getNonDefaultServerArgs,
+  getGitRev,
+  APPIUM_VER,
+  updateBuildInfo,
+  showConfig,
+  rootDir,
 };
+
+/**
+ * @typedef {import('appium/types').ParsedArgs} ParsedArgs
+ * @typedef {import('appium/types').Args} Args
+ * @typedef {import('./schema/arg-spec').ArgSpec} ArgSpec
+ */

package/lib/constants.js

@@ -0,0 +1,79 @@
+import path from 'path';
+
+/**
+ * The name of the extension type for drivers
+ */
+export const DRIVER_TYPE = 'driver';
+
+/**
+ * The name of the extension type for plugins
+ */
+export const PLUGIN_TYPE = 'plugin';
+
+/**
+ * The `server` command of the `appium` CLI
+ */
+export const SERVER_SUBCOMMAND = 'server';
+
+/**
+ * The value of `--use-plugins` if _all_ plugins should be loaded
+ */
+export const USE_ALL_PLUGINS = 'all';
+
+// This is a map of plugin names to npm packages representing those plugins.
+// The plugins in this list will be available to the CLI so users can just
+// type 'appium plugin install 'name'', rather than having to specify the full
+// npm package. I.e., these are the officially recognized plugins.
+export const KNOWN_PLUGINS = Object.freeze(
+  /** @type {const} */ ({
+    images: '@appium/images-plugin',
+    'execute-driver': '@appium/execute-driver-plugin',
+    'relaxed-caps': '@appium/relaxed-caps-plugin',
+    'universal-xml': '@appium/universal-xml-plugin',
+  })
+);
+
+// This is a map of driver names to npm packages representing those drivers.
+// The drivers in this list will be available to the CLI so users can just
+// type 'appium driver install 'name'', rather than having to specify the full
+// npm package. I.e., these are the officially recognized drivers.
+export const KNOWN_DRIVERS = Object.freeze(
+  /** @type {const} */ ({
+    uiautomator2: 'appium-uiautomator2-driver',
+    xcuitest: 'appium-xcuitest-driver',
+    mac2: 'appium-mac2-driver',
+    espresso: 'appium-espresso-driver',
+    safari: 'appium-safari-driver',
+    gecko: 'appium-geckodriver',
+    chromium: 'appium-chromium-driver',
+  })
+);
+
+/**
+ * Relative path to directory containing any Appium internal files
+ */
+export const CACHE_DIR_RELATIVE_PATH = path.join('node_modules', '.cache', 'appium');
+
+/**
+ * Relative path to hashfile (from `APPIUM_HOME`) of consuming project's `package.json` (if it exists)
+ */
+export const PKG_HASHFILE_RELATIVE_PATH = path.join(CACHE_DIR_RELATIVE_PATH, 'package.hash');
+
+export const EXT_SUBCOMMAND_LIST = 'list';
+export const EXT_SUBCOMMAND_INSTALL = 'install';
+export const EXT_SUBCOMMAND_UNINSTALL = 'uninstall';
+export const EXT_SUBCOMMAND_UPDATE = 'update';
+export const EXT_SUBCOMMAND_RUN = 'run';
+
+/**
+ * Current revision of the manifest (`extensions.yaml`) schema
+ */
+export const CURRENT_SCHEMA_REV = 4;
+
+/**
+ * The default number of stack frames to show in a "long" stack trace, when enabled via `--long-stacktrace`
+ * @remarks This value may be increased in the future.
+ * @privateRemarks A value like `Infinity` may provide to have deleterious effects on
+ * memory usage, perf, and/or log output, and higher limits may be difficult to scan.
+ */
+export const LONG_STACKTRACE_LIMIT = 100;