appium 2.0.0-beta.17 → 2.0.0-beta.20

package/lib/cli/parser.js

@@ -1,121 +1,273 @@
-import path from 'path';
-import _ from 'lodash';
+// @ts-check
+
+import { fs } from '@appium/support';
 import { ArgumentParser } from 'argparse';
-import { sharedArgs, serverArgs, extensionArgs } from './args';
+import B from 'bluebird';
+import _ from 'lodash';
+import path from 'path';
 import { DRIVER_TYPE, PLUGIN_TYPE } from '../extension-config';
+import { finalizeSchema, getArgSpec, hasArgSpec } from '../schema';
 import { rootDir } from '../utils';
-import { fs } from '@appium/support';
+import {
+  driverConfig,
+  getExtensionArgs,
+  getServerArgs,
+  pluginConfig
+} from './args';
 
+export const SERVER_SUBCOMMAND = 'server';
 
-function makeDebugParser (parser) {
-  parser.exit = (status, message = undefined) => {
-    throw new Error(message);
-  };
-}
+/**
+ * If the parsed args do not contain any of these values, then we
+ * will automatially inject the `server` subcommand.
+ */
+const NON_SERVER_ARGS = Object.freeze(
+  new Set([
+    DRIVER_TYPE,
+    PLUGIN_TYPE,
+    SERVER_SUBCOMMAND,
+    '-h',
+    '--help',
+    '-v',
+    '--version'
+  ])
+);
+
+const version = fs.readPackageJsonFrom(rootDir).version;
+
+/**
+ * A wrapper around `argparse`
+ *
+ * - Handles instantiation, configuration, and monkeypatching of an
+ *    `ArgumentParser` instance for Appium server and its extensions
+ * - Handles error conditions, messages, and exit behavior
+ */
+class ArgParser {
+  /**
+   * @param {boolean} [debug] - If true, throw instead of exit on error.
+   */
+  constructor (debug = false) {
+    const prog = process.argv[1] ? path.basename(process.argv[1]) : 'appium';
+    const parser = new ArgumentParser({
+      add_help: true,
+      description:
+        'A webdriver-compatible server that facilitates automation of web, mobile, and other types of apps across various platforms.',
+      prog,
+    });
 
-function getParser (debug = false) {
-  const parser = new ArgumentParser({
-    add_help: true,
-    description: 'A webdriver-compatible server for use with native and hybrid iOS and Android applications.',
-    prog: process.argv[1] ? path.basename(process.argv[1]) : 'appium',
-  });
-  if (debug) {
-    makeDebugParser(parser);
+    ArgParser._patchExit(parser);
+
+    /**
+     * Program name (typically `appium`)
+     * @type {string}
+     */
+    this.prog = prog;
+
+    /**
+     * If `true`, throw an error on parse failure instead of printing help
+     * @type {boolean}
+     */
+    this.debug = debug;
+
+    /**
+     * Wrapped `ArgumentParser` instance
+     * @type {ArgumentParser}
+     */
+    this.parser = parser;
+
+    parser.add_argument('-v', '--version', {
+      action: 'version',
+      version,
+    });
+
+    const subParsers = parser.add_subparsers({dest: 'subcommand'});
+
+    // add the 'server' subcommand, and store the raw arguments on the parser
+    // object as a way for other parts of the code to work with the arguments
+    // conceptually rather than just through argparse
+    const serverArgs = ArgParser._addServerToParser(subParsers);
+
+    this.rawArgs = serverArgs;
+
+    // add the 'driver' and 'plugin' subcommands
+    ArgParser._addExtensionCommandsToParser(subParsers);
+
+    // backwards compatibility / drop-in wrapper
+    /**
+     * @type {ArgParser['parseArgs']}
+     */
+    this.parse_args = this.parseArgs;
   }
-  parser.add_argument('-v', '--version', {
-    action: 'version',
-    version: fs.readPackageJsonFrom(rootDir).version
-  });
-  const subParsers = parser.add_subparsers({dest: 'subcommand'});
-
-  // add the 'server' subcommand, and store the raw arguments on the parser
-  // object as a way for other parts of the code to work with the arguments
-  // conceptually rather than just through argparse
-  const serverArgs = addServerToParser(sharedArgs, subParsers, debug);
-  parser.rawArgs = serverArgs;
-
-  // add the 'driver' and 'plugin' subcommands
-  addExtensionsToParser(sharedArgs, subParsers, debug);
-
-  // modify the parse_args function to insert the 'server' subcommand if the
-  // user hasn't specified a subcommand or the global help command
-  parser._parse_args = parser.parse_args.bind(parser);
-  parser.parse_args = function (args, namespace) {
-    if (_.isUndefined(args)) {
-      args = [...process.argv.slice(2)];
-    }
-    if (!_.includes([DRIVER_TYPE, PLUGIN_TYPE, 'server', '-h', '--help', '-v', '--version'], args[0])) {
-      args.splice(0, 0, 'server');
+
+  /**
+   * Parse arguments from the command line.
+   *
+   * If no subcommand is passed in, this method will inject the `server` subcommand.
+   *
+   * `ArgParser.prototype.parse_args` is an alias of this method.
+   * @param {string[]} [args] - Array of arguments, ostensibly from `process.argv`. Gathers args from `process.argv` if not provided.
+   * @returns {import('../../types/types').ParsedArgs} - The parsed arguments
+   */
+  parseArgs (args = process.argv.slice(2)) {
+    if (!NON_SERVER_ARGS.has(args[0])) {
+      args.unshift(SERVER_SUBCOMMAND);
     }
-    return this._parse_args(args, namespace);
-  }.bind(parser);
-  return parser;
-}
 
-function addServerToParser (sharedArgs, subParsers, debug = false) {
-  const serverParser = subParsers.add_parser('server', {
-    add_help: true,
-    help: 'Run an Appium server',
-  });
+    try {
+      const parsed = this.parser.parse_args(args);
+      return ArgParser._transformParsedArgs(parsed);
+    } catch (err) {
+      if (this.debug) {
+        throw err;
+      }
+      // this isn't tested via unit tests (we use `debug: true`) so may escape coverage.
 
-  if (debug) {
-    makeDebugParser(serverParser);
+      /* istanbul ignore next */
+      {
+        // eslint-disable-next-line no-console
+        console.error(); // need an extra space since argparse prints usage.
+        // eslint-disable-next-line no-console
+        console.error(err.message);
+        process.exit(1);
+      }
+    }
   }
 
-  for (const [flagsOrNames, opts] of [...sharedArgs, ...serverArgs]) {
-    // add_argument mutates arguments so make copies
-    serverParser.add_argument(...flagsOrNames, {...opts});
+  /**
+   * Given an object full of arguments as returned by `argparser.parse_args`,
+   * expand the ones for extensions into a nested object structure and rename
+   * keys to match the intended destination.
+   *
+   * E.g., `{'driver-foo-bar': baz}` becomes `{driver: {foo: {bar: 'baz'}}}`
+   * @param {object} args
+   * @returns {object}
+   */
+  static _transformParsedArgs (args) {
+    return _.reduce(
+      args,
+      (unpacked, value, key) => {
+        if (hasArgSpec(key)) {
+          const {dest} = /** @type {import('../schema/arg-spec').ArgSpec} */(getArgSpec(key));
+          _.set(unpacked, dest, value);
+        } else {
+          // this could be anything that _isn't_ a server arg
+          unpacked[key] = value;
+        }
+        return unpacked;
+      },
+      {},
+    );
   }
 
-  return serverArgs;
-}
-
-function getDefaultServerArgs () {
-  let defaults = {};
-  for (let [, arg] of serverArgs) {
-    defaults[arg.dest] = arg.default;
+  /**
+   * Patches the `exit()` method of the parser to throw an error, so we can handle it manually.
+   * @param {ArgumentParser} parser
+   */
+  static _patchExit (parser) {
+    parser.exit = (code, msg) => {
+      throw new Error(msg);
+    };
   }
-  return defaults;
-}
 
-function addExtensionsToParser (sharedArgs, subParsers, debug = false) {
-  for (const type of [DRIVER_TYPE, PLUGIN_TYPE]) {
-    const extParser = subParsers.add_parser(type, {
+  /**
+   *
+   * @param {import('argparse').SubParser} subParser
+   * @returns {import('./args').ArgumentDefinitions}
+   */
+  static _addServerToParser (subParser) {
+    const serverParser = subParser.add_parser('server', {
       add_help: true,
-      help: `Access the ${type} management CLI commands`,
+      help: 'Run an Appium server',
     });
-    if (debug) {
-      makeDebugParser(extParser);
+
+    ArgParser._patchExit(serverParser);
+
+    const serverArgs = getServerArgs();
+    for (const [flagsOrNames, opts] of serverArgs) {
+      // TS doesn't like the spread operator here.
+      // @ts-ignore
+      serverParser.add_argument(...flagsOrNames, {...opts});
     }
-    const extSubParsers = extParser.add_subparsers({
-      dest: `${type}Command`,
-    });
-    const parserSpecs = [
-      {command: 'list', args: extensionArgs[type].list,
-       help: `List available and installed ${type}s`},
-      {command: 'install', args: extensionArgs[type].install,
-       help: `Install a ${type}`},
-      {command: 'uninstall', args: extensionArgs[type].uninstall,
-       help: `Uninstall a ${type}`},
-      {command: 'update', args: extensionArgs[type].update,
-       help: `Update installed ${type}s to the latest version`},
-      {command: 'run', args: extensionArgs[type].run,
-       help: `Run a script (defined inside the ${type}'s package.json under the ` +
-             `“scripts” field inside the “appium” field) from an installed ${type}`}
-    ];
-
-    for (const {command, args, help} of parserSpecs) {
-      const parser = extSubParsers.add_parser(command, {help});
-      if (debug) {
-        makeDebugParser(parser);
-      }
-      for (const [flagsOrNames, opts] of [...sharedArgs, ...args]) {
-        // add_argument mutates params so make sure to send in copies instead
-        parser.add_argument(...flagsOrNames, {...opts});
+
+    return serverArgs;
+  }
+
+  /**
+   * Adds extension sub-sub-commands to `driver`/`plugin` subcommands
+   * @param {import('argparse').SubParser} subParsers
+   */
+  static _addExtensionCommandsToParser (subParsers) {
+    for (const type of [DRIVER_TYPE, PLUGIN_TYPE]) {
+      const extParser = subParsers.add_parser(type, {
+        add_help: true,
+        help: `Access the ${type} management CLI commands`,
+      });
+
+      ArgParser._patchExit(extParser);
+
+      const extSubParsers = extParser.add_subparsers({
+        dest: `${type}Command`,
+      });
+      const extensionArgs = getExtensionArgs();
+      const parserSpecs = [
+        {
+          command: 'list',
+          args: extensionArgs[type].list,
+          help: `List available and installed ${type}s`,
+        },
+        {
+          command: 'install',
+          args: extensionArgs[type].install,
+          help: `Install a ${type}`,
+        },
+        {
+          command: 'uninstall',
+          args: extensionArgs[type].uninstall,
+          help: `Uninstall a ${type}`,
+        },
+        {
+          command: 'update',
+          args: extensionArgs[type].update,
+          help: `Update installed ${type}s to the latest version`,
+        },
+        {
+          command: 'run',
+          args: extensionArgs[type].run,
+          help:
+            `Run a script (defined inside the ${type}'s package.json under the ` +
+            `“scripts” field inside the “appium” field) from an installed ${type}`,
+        },
+      ];
+
+      for (const {command, args, help} of parserSpecs) {
+        const parser = extSubParsers.add_parser(command, {help});
+
+        ArgParser._patchExit(parser);
+
+        for (const [flagsOrNames, opts] of args) {
+          // add_argument mutates params so make sure to send in copies instead
+          // @ts-ignore
+          parser.add_argument(...flagsOrNames, {...opts});
+        }
       }
     }
   }
 }
 
+/**
+ * Creates a {@link ArgParser} instance.  Necessarily reads extension configuration
+ * beforehand, and finalizes the config schema.
+ *
+ * @constructs ArgParser
+ * @param {boolean} [debug] - If `true`, throw instead of exit upon parsing error
+ * @returns {Promise<ArgParser>}
+ */
+async function getParser (debug = false) {
+  await B.all([driverConfig.read(), pluginConfig.read()]);
+  finalizeSchema();
+
+  return new ArgParser(debug);
+}
+
 export default getParser;
-export { getParser, getDefaultServerArgs };
+export { getParser, ArgParser };

package/lib/config-file.js

@@ -0,0 +1,227 @@
+// @ts-check
+
+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 && !result.isEmpty && result.filepath) {
+    const {normalize = true, pretty = true} = opts;
+    try {
+      /** @type {ReadConfigFileResult} */
+      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};
+      }
+
+      if (normalize) {
+        // 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).
+ */
+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
+   * @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 {Object} 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 {AppiumConfig} [config] - The parsed configuration
+ * @property {string|betterAjvErrors.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 {Object} 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.
+ * @property {boolean} [normalize=true] If `false`, do not normalize key names to camel case.
+ */
+
+/**
+ * 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('../types/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('../types/types').NormalizedAppiumConfig} NormalizedAppiumConfig
+ */
+
+/**
+ * The string should be a raw JSON string.
+ * @typedef {string} RawJson
+ */
+
+/**
+ * Options for {@link formatErrors}.
+ * @typedef {Object} 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
+ */