appium 2.0.0-beta.3 → 2.0.0-beta.30

package/lib/config-file.js

@@ -0,0 +1,223 @@
+
+import betterAjvErrors from '@sidvind/better-ajv-errors';
+import { lilconfig } from 'lilconfig';
+import _ from 'lodash';
+import yaml from 'yaml';
+import { getSchema, validate } from './schema/schema';
+
+/**
+ * lilconfig loader to handle `.yaml` files
+ * @type {import('lilconfig').LoaderSync}
+ */
+function yamlLoader (filepath, content) {
+  return yaml.parse(content);
+}
+
+/**
+ * A cache of the raw config file (a JSON string) at a filepath.
+ * This is used for better error reporting.
+ * Note that config files needn't be JSON, but it helps if they are.
+ * @type {Map<string,RawJson>}
+ */
+const rawConfig = new Map();
+
+/**
+ * Custom JSON loader that caches the raw config file (for use with `better-ajv-errors`).
+ * If it weren't for this cache, this would be unnecessary.
+ * @type {import('lilconfig').LoaderSync}
+ */
+function jsonLoader (filepath, content) {
+  rawConfig.set(filepath, content);
+  return JSON.parse(content);
+}
+
+/**
+ * Loads a config file from an explicit path
+ * @param {LilconfigAsyncSearcher} lc - lilconfig instance
+ * @param {string} filepath - Path to config file
+ * @returns {Promise<import('lilconfig').LilconfigResult>}
+ */
+async function loadConfigFile (lc, filepath) {
+  try {
+    // removing "await" will cause any rejection to _not_ be caught in this block!
+    return await lc.load(filepath);
+  } catch (/** @type {unknown} */err) {
+    if (/** @type {NodeJS.ErrnoException} */(err).code === 'ENOENT') {
+      /** @type {NodeJS.ErrnoException} */(err).message = `Config file not found at user-provided path: ${filepath}`;
+      throw err;
+    } else if (err instanceof SyntaxError) {
+      // generally invalid JSON
+      err.message = `Config file at user-provided path ${filepath} is invalid:\n${err.message}`;
+      throw err;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Searches for a config file
+ * @param {LilconfigAsyncSearcher} lc - lilconfig instance
+ * @returns {Promise<import('lilconfig').LilconfigResult>}
+ */
+async function searchConfigFile (lc) {
+  return await lc.search();
+}
+
+/**
+ * Given an array of errors and the result of loading a config file, generate a
+ * helpful string for the user.
+ *
+ * - If `opts` contains a `json` property, this should be the original JSON
+ *   _string_ of the config file.  This is only applicable if the config file
+ *   was in JSON format. If present, it will associate line numbers with errors.
+ * - If `errors` happens to be empty, this will throw.
+ * @param {import('ajv').ErrorObject[]} errors - Non-empty array of errors. Required.
+ * @param {ReadConfigFileResult['config']|any} [config] -
+ * Configuration & metadata
+ * @param {FormatConfigErrorsOptions} [opts]
+ * @throws {TypeError} If `errors` is empty
+ * @returns {string}
+ */
+export function formatErrors (errors = [], config = {}, opts = {}) {
+  if (errors && !errors.length) {
+    throw new TypeError('Array of errors must be non-empty');
+  }
+  return betterAjvErrors(getSchema(opts.schemaId), config, errors, {
+    json: opts.json,
+    format: 'cli',
+  });
+}
+
+/**
+ * Given an optional path, read a config file. Validates the config file.
+ *
+ * Call {@link validate} if you already have a config object.
+ * @param {string} [filepath] - Path to config file, if we have one
+ * @param {ReadConfigFileOptions} [opts] - Options
+ * @public
+ * @returns {Promise<ReadConfigFileResult>} Contains config and filepath, if found, and any errors
+ */
+export async function readConfigFile (filepath, opts = {}) {
+  const lc = lilconfig('appium', {
+    loaders: {
+      '.yaml': yamlLoader,
+      '.yml': yamlLoader,
+      '.json': jsonLoader,
+      noExt: jsonLoader,
+    },
+    packageProp: 'appiumConfig'
+  });
+
+  const result = filepath
+    ? await loadConfigFile(lc, filepath)
+    : await searchConfigFile(lc);
+
+  if (result?.filepath && !result?.isEmpty) {
+    const {pretty = true} = opts;
+    try {
+      let configResult;
+      const errors = validate(result.config);
+      if (_.isEmpty(errors)) {
+        configResult = {...result, errors};
+      } else {
+        const reason = formatErrors(errors, result.config, {
+          json: rawConfig.get(result.filepath),
+          pretty,
+        });
+        configResult = reason
+          ? {...result, errors, reason}
+          : {...result, errors};
+      }
+
+      // normalize (to camel case) all top-level property names of the config file
+      configResult.config = normalizeConfig(
+        /** @type {AppiumConfig} */ (configResult.config),
+      );
+
+      return configResult;
+    } finally {
+      // clean up the raw config file cache, which is only kept to better report errors.
+      rawConfig.delete(result.filepath);
+    }
+  }
+  return result ?? {};
+}
+
+/**
+ * Convert schema property names to either a) the value of the `appiumCliDest` property, if any; or b) camel-case
+ * @param {AppiumConfig} config - Configuration object
+ * @returns {NormalizedAppiumConfig} New object with camel-cased keys (or `dest` keys).
+ */
+export function normalizeConfig (config) {
+  const schema = getSchema();
+  /**
+   * @param {AppiumConfig} config
+   * @param {string} [section] - Keypath (lodash `_.get()` style) to section of config. If omitted, assume root Appium config schema
+   * @todo Rewrite as a loop
+   * @returns Normalized section of config
+   */
+  const normalize = (config, section) => {
+    const obj = _.isUndefined(section) ? config : _.get(config, section, config);
+
+    const mappedObj = _.mapKeys(obj, (__, prop) =>
+      schema.properties[prop]?.appiumCliDest ?? _.camelCase(prop),
+    );
+
+    return _.mapValues(mappedObj, (value, property) => {
+      const nextSection = section ? `${section}.${property}` : property;
+      return isSchemaTypeObject(value) ? normalize(config, nextSection) : value;
+    });
+  };
+
+  /**
+   * Returns `true` if the schema prop references an object, or if it's an object itself
+   * @param {import('ajv').SchemaObject|object} schema - Referencing schema object
+   */
+  const isSchemaTypeObject = (schema) => Boolean(schema.properties);
+
+  return normalize(config);
+}
+
+/**
+ * Result of calling {@link readConfigFile}.
+ * @typedef ReadConfigFileResult
+ * @property {import('ajv').ErrorObject[]} [errors] - Validation errors
+ * @property {string} [filepath] - The path to the config file, if found
+ * @property {boolean} [isEmpty] - If `true`, the config file exists but is empty
+ * @property {NormalizedAppiumConfig} [config] - The parsed configuration
+ * @property {string|import('@sidvind/better-ajv-errors').IOutputError[]} [reason] - Human-readable error messages and suggestions. If the `pretty` option is `true`, this will be a nice string to print.
+ */
+
+/**
+ * Options for {@link readConfigFile}.
+ * @typedef ReadConfigFileOptions
+ * @property {boolean} [pretty=true] If `false`, do not use color and fancy formatting in the `reason` property of the {@link ReadConfigFileResult}. The value of `reason` is then suitable for machine-reading.
+ */
+
+/**
+ * This is an `AsyncSearcher` which is inexplicably _not_ exported by the `lilconfig` type definition.
+ * @typedef {ReturnType<import('lilconfig')["lilconfig"]>} LilconfigAsyncSearcher
+ */
+
+/**
+ * The contents of an Appium config file. Generated from schema
+ * @typedef {import('@appium/types').AppiumConfig} AppiumConfig
+ */
+
+/**
+ * The contents of an Appium config file with camelcased property names (and using `appiumCliDest` value if present). Generated from {@link AppiumConfig}
+ * @typedef {import('@appium/types').NormalizedAppiumConfig} NormalizedAppiumConfig
+ */
+
+/**
+ * The string should be a raw JSON string.
+ * @typedef {string} RawJson
+ */
+
+/**
+ * Options for {@link formatErrors}.
+ * @typedef FormatConfigErrorsOptions
+ * @property {import('./config-file').RawJson} [json] - Raw JSON config (as string)
+ * @property {boolean} [pretty=true] - Whether to format errors as a CLI-friendly string
+ * @property {string}  [schemaId] - Specific ID of a prop; otherwise entire schema
+ */

package/lib/config.js

@@ -1,14 +1,15 @@
+/* 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 semver from 'semver';
+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;
 
@@ -16,12 +17,15 @@ const GIT_META_ROOT = '.git';
 const GIT_BINARY = `git${system.isWindows() ? '.exe' : ''}`;
 const GITHUB_API = 'https://api.github.com/repos/appium/appium';
 
+/**
+ * @type {import('../types/cli').BuildInfo}
+ */
 const BUILD_INFO = {
   version: APPIUM_VER,
 };
 
 function getNodeVersion () {
-  return semver.coerce(process.version);
+  return /** @type {import('semver').SemVer} */(semver.coerce(process.version));
 }
 
 async function updateBuildInfo (useGithubApiFallback = false) {
@@ -31,16 +35,28 @@ async function updateBuildInfo (useGithubApiFallback = false) {
   }
   BUILD_INFO['git-sha'] = sha;
   const built = await getGitTimestamp(sha, useGithubApiFallback);
-  if (!_.isEmpty(built)) {
+  if (built) {
     BUILD_INFO.built = built;
   }
 }
 
+/**
+ * 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'});
+}
+
 async function getGitRev (useGithubApiFallback = false) {
-  if (await fs.exists(path.resolve(rootDir, GIT_META_ROOT))) {
+  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) {}
@@ -67,11 +83,17 @@ async function getGitRev (useGithubApiFallback = false) {
   return null;
 }
 
+/**
+ * @param {string} commitSha
+ * @param {boolean} [useGithubApiFallback]
+ * @returns {Promise<string?>}
+ */
 async function getGitTimestamp (commitSha, useGithubApiFallback = false) {
-  if (await fs.exists(path.resolve(rootDir, GIT_META_ROOT))) {
+  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) {}
@@ -100,10 +122,11 @@ async function getGitTimestamp (commitSha, useGithubApiFallback = false) {
 }
 
 /**
- * @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('../types/cli').BuildInfo}
  */
 function getBuildInfo () {
   return BUILD_INFO;
@@ -130,83 +153,160 @@ 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) {
-  let nonDefaults = {};
-  for (let rawArg of parser.rawArgs) {
-    let arg = rawArg[1].dest;
-    if (args[arg] && args[arg] !== rawArg[1].defaultValue) {
-      nonDefaults[arg] = args[arg];
-    }
-  }
-  return nonDefaults;
-}
-
-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;
-}
-
-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++;
+/**
+ * Returns k/v pairs of server arguments which are _not_ the defaults.
+ * @param {ParsedArgs} parsedArgs
+ * @returns {Partial<ParsedArgs>}
+ */
+function getNonDefaultServerArgs (parsedArgs) {
+  /**
+   * Flattens parsed args into a single level object for comparison with
+   * flattened defaults across server args and extension args.
+   * @param {ParsedArgs} 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};
       }
-    }
-    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`);
-    }
-  }
+      return acc;
+    }, /** @type {Record<string, { value: any, argSpec: ArgSpec }>} */({}));
 
-  const validations = {
-    port: checkValidPort,
-    callbackPort: checkValidPort,
-    bootstrapPort: checkValidPort,
-    chromedriverPort: checkValidPort,
-    robotPort: checkValidPort,
-    backendRetries: (r) => r >= 0
+    return flattened;
   };
 
-  const nonDefaultArgs = getNonDefaultArgs(parser, args);
+  const args = flatten(parsedArgs);
 
-  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]}`);
-      }
-    }
+  // hopefully these function names are descriptive enough
+  const typesDiffer = /** @param {string} dest */(dest) => typeof args[dest].value !== typeof defaultsFromSchema[dest];
+
+  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);
+
+  return _.reduce(
+    _.pickBy(args, (__, key) => isNotDefault(key)),
+    // explodes the flattened object back into nested one
+    (acc, {value, argSpec}) => _.set(acc, argSpec.dest, value), /** @type {Partial<ParsedArgs>} */({})
+  );
+}
+
+/**
+ * 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))
+);
+
+/**
+ * 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)`);
+  }
+  if (_.isEmpty(nonDefaultPreConfigParsedArgs)) {
+    console.log(`\n(no CLI parameters provided)`);
+  } else {
+    console.log('\nvia CLI or function call:\n');
+    console.dir(compactConfig(nonDefaultPreConfigParsedArgs));
   }
+  console.log('\nfinal configuration:\n');
+  console.dir(compactConfig(parsedArgs));
 }
 
+/**
+ * @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.`);
   }
 }
 
+const rootDir = fs.findRoot(__dirname);
+
 export {
-  getBuildInfo, validateServerArgs, checkNodeOk, showConfig,
-  warnNodeDeprecations, validateTmpDir, getNonDefaultArgs,
-  getGitRev, checkValidPort, APPIUM_VER, updateBuildInfo,
+  getBuildInfo, checkNodeOk, showBuildInfo,
+  warnNodeDeprecations, validateTmpDir, getNonDefaultServerArgs,
+  getGitRev, APPIUM_VER, updateBuildInfo, showConfig, rootDir
 };
+
+/**
+ * @typedef {import('../types/cli').ParsedArgs} ParsedArgs
+ * @typedef {import('./schema/arg-spec').ArgSpec} ArgSpec
+ */
+

package/lib/constants.js

@@ -0,0 +1,78 @@
+
+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',
+  }),
+);
+
+// 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',
+    youiengine: 'appium-youiengine-driver',
+    windows: 'appium-windows-driver',
+    mac: 'appium-mac-driver',
+    mac2: 'appium-mac2-driver',
+    espresso: 'appium-espresso-driver',
+    tizen: 'appium-tizen-driver',
+    flutter: 'appium-flutter-driver',
+    safari: 'appium-safari-driver',
+    gecko: 'appium-geckodriver',
+  }),
+);
+
+/**
+ * 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';