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

package/lib/cli/extension.js

@@ -1,47 +1,74 @@
 /* eslint-disable no-console */
+import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
+import {isExtensionCommandArgs} from '../utils';
+import DriverCliCommand from './driver-command';
+import PluginCliCommand from './plugin-command';
+import {errAndQuit, JSON_SPACES} from './utils';
 
-import DriverCommand from './driver-command';
-import PluginCommand from './plugin-command';
-import DriverConfig from '../driver-config';
-import PluginConfig from '../plugin-config';
-import { DRIVER_TYPE } from '../extension-config';
-import { errAndQuit, log, JSON_SPACES } from './utils';
+export const commandClasses = Object.freeze(
+  /** @type {const} */ ({
+    [DRIVER_TYPE]: DriverCliCommand,
+    [PLUGIN_TYPE]: PluginCliCommand,
+  })
+);
 
 /**
  * Run a subcommand of the 'appium driver' type. Each subcommand has its own set of arguments which
  * can be represented as a JS object.
  *
- * @param {Object} args - JS object where the key is the parameter name (as defined in
+ * @template {import('appium/types').CliExtensionCommand} Cmd
+ * @template {import('appium/types').CliExtensionSubcommand} SubCmd
+ * @param {import('appium/types').Args<Cmd, SubCmd>} args - JS object where the key is the parameter name (as defined in
  * driver-parser.js)
+ * @param {import('../extension/extension-config').ExtensionConfig<Cmd>} config - Extension config object
  */
-async function runExtensionCommand (args, type) {
+async function runExtensionCommand(args, config) {
   // TODO driver config file should be locked while any of these commands are
   // running to prevent weird situations
   let jsonResult = null;
-  const extCmd = args[`${type}Command`];
-  if (!extCmd) {
+  const {extensionType: type} = config; // NOTE this is the same as `args.subcommand`
+  if (!isExtensionCommandArgs(args)) {
     throw new TypeError(`Cannot call ${type} command without a subcommand like 'install'`);
   }
-  const {json, appiumHome} = args;
-  const logFn = (msg) => log(json, msg);
-  const ConfigClass = type === DRIVER_TYPE ? DriverConfig : PluginConfig;
-  const CommandClass = type === DRIVER_TYPE ? DriverCommand : PluginCommand;
-  const config = new ConfigClass(appiumHome, logFn);
+  let {json, suppressOutput} = args;
+  json = Boolean(json);
+  if (suppressOutput) {
+    json = true;
+  }
+  const CommandClass = /** @type {ExtCommand<Cmd>} */ (commandClasses[type]);
   const cmd = new CommandClass({config, json});
   try {
-    await config.read();
     jsonResult = await cmd.execute(args);
   } catch (err) {
+    // in the suppress output case, we are calling this function internally and should
+    // just throw instead of printing an error and ending the process
+    if (suppressOutput) {
+      throw err;
+    }
     errAndQuit(json, err);
   }
 
-  if (json) {
+  if (json && !suppressOutput) {
     console.log(JSON.stringify(jsonResult, null, JSON_SPACES));
   }
 
   return jsonResult;
 }
 
-export {
-  runExtensionCommand,
-};
+export {runExtensionCommand};
+
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {ExtType extends DriverType ? Class<DriverCliCommand> : ExtType extends PluginType ? Class<PluginCliCommand> : never} ExtCommand
+ */
+
+/**
+ * @typedef {import('@appium/types').ExtensionType} ExtensionType
+ * @typedef {import('@appium/types').DriverType} DriverType
+ * @typedef {import('@appium/types').PluginType} PluginType
+ */
+
+/**
+ * @template T
+ * @typedef {import('@appium/types').Class<T>} Class
+ */

package/lib/cli/parser.js

@@ -1,117 +1,289 @@
-import path from 'path';
+import {fs} from '@appium/support';
+import {ArgumentParser} from 'argparse';
 import _ from 'lodash';
-import { ArgumentParser } from 'argparse';
-import { sharedArgs, serverArgs, extensionArgs } from './args';
-import { DRIVER_TYPE, PLUGIN_TYPE } from '../extension-config';
-import { rootDir } from '../utils';
+import path from 'path';
+import {DRIVER_TYPE, PLUGIN_TYPE, SERVER_SUBCOMMAND} from '../constants';
+import {finalizeSchema, getArgSpec, hasArgSpec} from '../schema';
+import {rootDir} from '../config';
+import {getExtensionArgs, getServerArgs} from './args';
 
+export const EXTRA_ARGS = 'extraArgs';
 
-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,
+    });
+
+    ArgParser._patchExit(parser);
+
+    /**
+     * Program name (typically `appium`)
+     * @type {string}
+     */
+    this.prog = 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);
+    /**
+     * 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: require(path.resolve(rootDir, 'package.json')).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.
+   * @template {import('appium/types').CliCommand} [Cmd=import('appium/types').CliCommandServer]
+   * @param {string[]} [args] - Array of arguments, ostensibly from `process.argv`. Gathers args from `process.argv` if not provided.
+   * @returns {import('appium/types').Args<Cmd>} - 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_known_args(args);
+      const [knownArgs, unknownArgs] = parsed;
+      // XXX: you'd think that argparse, when given an alias for a subcommand,
+      // would set this value to the original subcommand name, but it doesn't.
+      if (knownArgs?.driverCommand === 'ls') {
+        knownArgs.driverCommand = 'list';
+      } else if (knownArgs?.pluginCommand === 'ls') {
+        knownArgs.pluginCommand = 'list';
+      }
+      if (
+        unknownArgs?.length &&
+        (knownArgs.driverCommand === 'run' || knownArgs.pluginCommand === 'run')
+      ) {
+        return ArgParser._transformParsedArgs(knownArgs, unknownArgs);
+      } else if (unknownArgs?.length) {
+        throw new Error(`[ERROR] Unrecognized arguments: ${unknownArgs.join(' ')}`);
+      }
+      return ArgParser._transformParsedArgs(knownArgs);
+    } 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
+   * @param {string[]} [unknownArgs]
+   * @returns {object}
+   */
+  static _transformParsedArgs(args, unknownArgs = []) {
+    const result = _.reduce(
+      args,
+      (unpacked, value, key) => {
+        if (!_.isUndefined(value) && 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;
+      },
+      {}
+    );
+    result[EXTRA_ARGS] = unknownArgs;
+    return result;
   }
 
-  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) => {
+      if (code) {
+        throw new Error(msg);
+      }
+      process.exit();
+    };
   }
-  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`},
-    ];
-
-    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 /** @type {[DriverType, PluginType]} */ ([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();
+      /**
+       * @type { {command: import('appium/types').CliExtensionSubcommand, args: import('./args').ArgumentDefinitions, help: string, aliases?: import('argparse').SubArgumentParserOptions['aliases']}[] }
+       */
+      const parserSpecs = [
+        {
+          command: 'list',
+          args: extensionArgs[type].list,
+          help: `List available and installed ${type}s`,
+          aliases: ['ls'],
+        },
+        {
+          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, aliases} of parserSpecs) {
+        const parser = extSubParsers.add_parser(command, {help, aliases: aliases ?? []});
+
+        ArgParser._patchExit(parser);
+
+        for (const [flagsOrNames, opts] of args) {
+          // add_argument mutates params so make sure to send in copies instead
+          if (flagsOrNames.length === 2) {
+            parser.add_argument(flagsOrNames[0], flagsOrNames[1], {...opts});
+          } else {
+            parser.add_argument(flagsOrNames[0], {...opts});
+          }
+        }
       }
     }
   }
 }
 
-export default getParser;
-export { getParser, getDefaultServerArgs };
+/**
+ * Creates a {@link ArgParser} instance; finalizes the config schema.
+ *
+ * @constructs ArgParser
+ * @param {boolean} [debug] - If `true`, throw instead of exit upon parsing error
+ * @returns {ArgParser}
+ */
+function getParser(debug) {
+  finalizeSchema();
+
+  return new ArgParser(debug);
+}
+
+export {getParser, ArgParser};
+
+/**
+ * @typedef {import('@appium/types').DriverType} DriverType
+ * @typedef {import('@appium/types').PluginType} PluginType
+ */

package/lib/cli/plugin-command.js

@@ -1,43 +1,143 @@
 import _ from 'lodash';
-import ExtensionCommand from './extension-command';
-import { PLUGIN_TYPE } from '../extension-config';
-import { KNOWN_PLUGINS } from '../plugins';
+import ExtensionCliCommand from './extension-command';
+import {KNOWN_PLUGINS} from '../constants';
 
 const REQ_PLUGIN_FIELDS = ['pluginName', 'mainClass'];
 
-export default class PluginCommand extends ExtensionCommand {
-
-  constructor ({config, json}) {
-    super({config, json, type: PLUGIN_TYPE});
+/**
+ * @extends {ExtensionCliCommand<PluginType>}
+ */
+export default class PluginCliCommand extends ExtensionCliCommand {
+  /**
+   *
+   * @param {import('./extension-command').ExtensionCommandOptions<PluginType>} opts
+   */
+  constructor({config, json}) {
+    super({config, json});
     this.knownExtensions = KNOWN_PLUGINS;
   }
 
-  async install ({plugin, installType, packageName}) {
-    return await super.install({ext: plugin, installType, packageName});
+  /**
+   * Install a plugin
+   *
+   * @param {PluginInstallOpts} opts
+   * @returns {Promise<ExtRecord<PluginType>>}
+   */
+  async install({plugin, installType, packageName}) {
+    return await super._install({
+      installSpec: plugin,
+      installType,
+      packageName,
+    });
+  }
+
+  /**
+   * Uninstall a plugin
+   *
+   * @param {PluginUninstallOpts} opts
+   * @returns {Promise<ExtRecord<PluginType>>}
+   */
+  async uninstall({plugin}) {
+    return await super._uninstall({installSpec: plugin});
   }
 
-  async uninstall ({plugin}) {
-    return await super.uninstall({ext: plugin});
+  /**
+   * Update a plugin
+   *
+   * @param {PluginUpdateOpts} opts
+   * @returns {Promise<import('./extension-command').ExtensionUpdateResult>}
+   */
+  async update({plugin, unsafe}) {
+    return await super._update({installSpec: plugin, unsafe});
   }
 
-  async update ({plugin, unsafe}) {
-    return await super.update({ext: plugin, unsafe});
+  /**
+   *
+   * @param {PluginRunOptions} opts
+   * @returns {Promise<import('./extension-command').RunOutput>}
+   */
+  async run({plugin, scriptName, extraArgs}) {
+    return await super._run({
+      installSpec: plugin,
+      scriptName,
+      extraArgs,
+      bufferOutput: this.isJsonOutput,
+    });
   }
 
-  getPostInstallText ({extName, extData}) {
+  /**
+   *
+   * @param {import('./extension-command').ExtensionArgs} opts
+   * @returns {string}
+   */
+  getPostInstallText({extName, extData}) {
     return `Plugin ${extName}@${extData.version} successfully installed`.green;
   }
 
-  validateExtensionFields (appiumPkgData) {
-    const missingFields = REQ_PLUGIN_FIELDS.reduce((acc, field) => (
-      appiumPkgData[field] ? acc : [...acc, field]
-    ), []);
+  /**
+   * Validates fields in `appium` field of `pluginMetadata`
+   *
+   * For any `package.json` fields which a plugin requires, validate the type of
+   * those fields on the `package.json` data, throwing an error if anything is
+   * amiss.
+   * @param {import('appium/types').ExtMetadata<PluginType>} pluginMetadata
+   * @param {string} installSpec
+   * @returns {void}
+   */
+  validateExtensionFields(pluginMetadata, installSpec) {
+    const missingFields = REQ_PLUGIN_FIELDS.reduce(
+      (acc, field) => (pluginMetadata[field] ? acc : [...acc, field]),
+      []
+    );
 
     if (!_.isEmpty(missingFields)) {
-      throw new Error(`Installed plugin did not expose correct fields for compability ` +
-                      `with Appium. Missing fields: ${JSON.stringify(missingFields)}`);
+      throw new Error(
+        `Installed plugin "${installSpec}" did not expose correct fields for compability ` +
+          `with Appium. Missing fields: ${JSON.stringify(missingFields)}`
+      );
     }
-
   }
-
 }
+
+/**
+ * @typedef {import('@appium/types').ExtensionType} ExtensionType
+ * @typedef {import('@appium/types').PluginType} PluginType
+ */
+
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtRecord<ExtType>} ExtRecord
+ */
+
+/**
+ * Options for {@linkcode PluginCliCommand.install}
+ * @typedef PluginInstallOpts
+ * @property {string} plugin - the name or spec of a plugin to install
+ * @property {InstallType} installType - how to install this plugin. One of the INSTALL_TYPES
+ * @property {string} [packageName] - for git/github installs, the plugin node package name
+ */
+
+/**
+ * @typedef {import('appium/types').InstallType} InstallType
+ */
+
+/**
+ * Options for {@linkcode PluginCliCommand.uninstall}
+ * @typedef PluginUninstallOpts
+ * @property {string} plugin - the name or spec of a plugin to uninstall
+ */
+
+/**
+ * Options for {@linkcode PluginCliCommand.update}
+ * @typedef PluginUpdateOpts
+ * @property {string} plugin - the name of the plugin to update
+ * @property {boolean} unsafe - if true, will perform unsafe updates past major revision boundaries
+ */
+
+/**
+ * Options for {@linkcode PluginCliCommand.run}.
+ * @typedef PluginRunOptions
+ * @property {string} plugin - name of the plugin to run a script from
+ * @property {string} scriptName - name of the script to run
+ * @property {string[]} [extraArgs] - arguments to pass to the script
+ */