appium 2.0.0-beta.2 → 2.0.0-beta.20

package/lib/cli/extension-command.js

@@ -3,8 +3,9 @@
 import _ from 'lodash';
 import NPM from './npm';
 import path from 'path';
-import { fs, util } from 'appium-support';
-import { log, spinWith } from './utils';
+import { fs, util } from '@appium/support';
+import { log, spinWith, RingBuffer } from './utils';
+import { SubProcess} from 'teen_process';
 import { INSTALL_TYPE_NPM, INSTALL_TYPE_GIT, INSTALL_TYPE_GITHUB,
          INSTALL_TYPE_LOCAL } from '../extension-config';
 
@@ -482,8 +483,72 @@ export default class ExtensionCommand {
    */
   async updateExtension (ext, version) {
     const {pkgName} = this.config.installedExtensions[ext];
-    await this.installViaNpm({ext, pkgName, pkgVer: version});
-    this.config.installedExtensions[ext].version = version;
-    await this.config.write();
+    await fs.rimraf(this.config.getInstallPath(ext));
+    const extData = await this.installViaNpm({ext, pkgName, pkgVer: version});
+    delete extData[`${this.type}Name`];
+    await this.config.updateExtension(ext, extData);
+  }
+
+  /**
+   * Runs a script cached inside the "scripts" field under "appium"
+   * inside of the driver/plugins "package.json" file. Will throw
+   * an error if the driver/plugin does not contain a "scripts" field
+   * underneath the "appium" field in its package.json, if the
+   * "scripts" field is not a plain object, or if the scriptName is
+   * not found within "scripts" object.
+   *
+   * @param {string} ext - name of the extension to run a script from
+   * @param {string} scriptName - name of the script to run
+   * @return {RunOutput}
+   */
+  async run ({ext, scriptName}) {
+    if (!_.has(this.config.installedExtensions, ext)) {
+      throw new Error(`please install the ${this.type} first`);
+    }
+
+    const extConfig = this.config.installedExtensions[ext];
+
+    if (!_.has(extConfig, 'scripts')) {
+      throw new Error(`The ${this.type} named '${ext}' does not contain the ` +
+                      `"scripts" field underneath the "appium" field in its package.json`);
+    }
+
+    const extScripts = extConfig.scripts;
+
+    if (!_.isPlainObject(extScripts)) {
+      throw new Error(`The ${this.type} named '${ext}' "scripts" field must be a plain object`);
+    }
+
+    if (!_.has(extScripts, scriptName)) {
+      throw new Error(`The ${this.type} named '${ext}' does not support the script: '${scriptName}'`);
+    }
+
+    const runner = new SubProcess(process.execPath, [extScripts[scriptName]], {
+      cwd: this.config.getExtensionRequirePath(ext)
+    });
+
+    const output = new RingBuffer(50);
+
+    runner.on('stream-line', (line) => {
+      output.enqueue(line);
+      log(this.isJsonOutput, line);
+    });
+
+    await runner.start(0);
+
+    try {
+      await runner.join();
+      log(this.isJsonOutput, `${scriptName} successfully ran`.green);
+      return {output: output.getBuff()};
+    } catch (err) {
+      log(this.isJsonOutput, `Encountered an error when running '${scriptName}': ${err.message}`.red);
+      return {error: err.message, output: output.getBuff()};
+    }
   }
 }
+
+/**
+ * @typedef {Object} RunOutput
+ * @property {string|undefined} error - error message if script ran unsuccessfully, otherwise undefined
+ * @property {string[]} output - script output
+ */

package/lib/cli/extension.js

@@ -6,6 +6,7 @@ import DriverConfig from '../driver-config';
 import PluginConfig from '../plugin-config';
 import { DRIVER_TYPE } from '../extension-config';
 import { errAndQuit, log, JSON_SPACES } from './utils';
+import { APPIUM_HOME } from './args';
 
 /**
  * Run a subcommand of the 'appium driver' type. Each subcommand has its own set of arguments which
@@ -13,25 +14,44 @@ import { errAndQuit, log, JSON_SPACES } from './utils';
  *
  * @param {Object} args - JS object where the key is the parameter name (as defined in
  * driver-parser.js)
+ * @param {import('../ext-config-io').ExtensionType} type - Extension type
+ * @oaram {ExtensionConfig} [configObject] - Extension config object, if we have one
  */
-async function runExtensionCommand (args, type) {
+async function runExtensionCommand (args, type, configObject) {
   // TODO driver config file should be locked while any of these commands are
   // running to prevent weird situations
   let jsonResult = null;
-  const {json, appiumHome} = args;
+  const extCmd = args[`${type}Command`];
+  if (!extCmd) {
+    throw new TypeError(`Cannot call ${type} command without a subcommand like 'install'`);
+  }
+  let {json, suppressOutput} = args;
+  if (suppressOutput) {
+    json = true;
+  }
   const logFn = (msg) => log(json, msg);
-  const ConfigClass = type === DRIVER_TYPE ? DriverConfig : PluginConfig;
+  let config;
+  if (configObject) {
+    config = configObject;
+    config.log = logFn;
+  } else {
+    config = (type === DRIVER_TYPE ? DriverConfig : PluginConfig).getInstance(APPIUM_HOME, logFn);
+  }
   const CommandClass = type === DRIVER_TYPE ? DriverCommand : PluginCommand;
-  const config = new ConfigClass(appiumHome, logFn);
   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));
   }
 

package/lib/cli/npm.js

@@ -1,8 +1,7 @@
-import _ from 'lodash';
 import path from 'path';
 import semver from 'semver';
 import { exec } from 'teen_process';
-import { mkdirp, util } from 'appium-support';
+import { fs, mkdirp, util, system } from '@appium/support';
 
 const INSTALL_LOCKFILE = '.appium.install.lock';
 const LINK_LOCKFILE = '.appium.link.lock';
@@ -21,6 +20,14 @@ export default class NPM {
     // ensure the directory we want to install inside of exists
     await mkdirp(cwd);
 
+    // not only this, this directory needs a 'package.json' inside of it, otherwise, if any
+    // directory in the filesystem tree ABOVE cwd happens to have a package.json or a node_modules
+    // dir in it, NPM will install the module up there instead (silly NPM)
+    const dummyPkgJson = path.resolve(cwd, 'package.json');
+    if (!await fs.exists(dummyPkgJson)) {
+      await fs.writeFile(dummyPkgJson, '{}');
+    }
+
     // make sure we perform the current operation in cwd
     execOpts = {...execOpts, cwd};
 
@@ -28,7 +35,8 @@ export default class NPM {
     if (json) {
       args.push('-json');
     }
-    let runner = async () => await exec('npm', args, execOpts);
+    const npmCmd = system.isWindows() ? 'npm.cmd' : 'npm';
+    let runner = async () => await exec(npmCmd, args, execOpts);
     if (lockFile) {
       const acquireLock = util.getLockFileGuard(path.resolve(cwd, lockFile));
       const _runner = runner;
@@ -124,14 +132,6 @@ export default class NPM {
       if (res.json.error) {
         throw new Error(res.json.error);
       }
-
-      // if we tried to install a package via git/github, we might not have been
-      // certain of the package name, so if we can retrieve it unambiguously from
-      // the json report of the install, do so
-      const names = _.uniq([...res.json.added, ...res.json.updated].map((x) => x.name));
-      if (names.length === 1) {
-        pkgName = names[0];
-      }
     }
 
     // Now read package data from the installed package to return, and make sure
@@ -159,8 +159,14 @@ export default class NPM {
                       `provided: ${pkgPath}`);
     }
 
+    // this is added to handle commands with relative paths
+    // ie: "node . driver install --source=local ../fake-driver"
+    pkgPath = path.resolve(process.cwd(), pkgPath);
+
     const pkgHome = path.resolve(this.appiumHome, pkgName);
-    const res = await this.exec('link', [pkgPath], {cwd: pkgHome, lockFile: LINK_LOCKFILE});
+
+    // call link with --no-package-lock to ensure no corruption while installing local packages
+    const res = await this.exec('link', ['--no-package-lock', pkgPath], {cwd: pkgHome, lockFile: LINK_LOCKFILE});
     if (res.json && res.json.error) {
       throw new Error(res.json.error);
     }

package/lib/cli/parser.js

@@ -1,98 +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 {
+  driverConfig,
+  getExtensionArgs,
+  getServerArgs,
+  pluginConfig
+} from './args';
 
-function getParser (debug = false) {
-  const parser = new ArgumentParser({
-    version: require(path.resolve(rootDir, 'package.json')).version,
-    addHelp: 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',
-    debug
-  });
-  const subParsers = parser.addSubparsers({dest: 'subcommand', debug});
-
-  // 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 parseArgs function to insert the 'server' subcommand if the
-  // user hasn't specified a subcommand or the global help command
-  parser._parseArgs = parser.parseArgs;
-  parser.parseArgs = function (args, namespace) {
-    if (_.isUndefined(args)) {
-      args = [...process.argv.slice(2)];
-    }
-    if (!_.includes([DRIVER_TYPE, PLUGIN_TYPE, 'server', '-h'], args[0])) {
-      args.splice(0, 0, 'server');
+export const SERVER_SUBCOMMAND = 'server';
+
+/**
+ * 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;
+
+    /**
+     * 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;
+  }
+
+  /**
+   * 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._parseArgs(args, namespace);
-  }.bind(parser);
-  return parser;
-}
 
-function addServerToParser (sharedArgs, subParsers, debug) {
-  const serverParser = subParsers.addParser('server', {
-    addHelp: true,
-    help: 'Run an Appium server',
-    debug
-  });
+    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.
 
-  for (const [flags, opts] of [...sharedArgs, ...serverArgs]) {
-    // addArgument mutates arguments so make copies
-    serverParser.addArgument([...flags], {...opts});
+      /* 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);
+      }
+    }
   }
 
-  return serverArgs;
-}
+  /**
+   * 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;
+      },
+      {},
+    );
+  }
 
-function getDefaultServerArgs () {
-  let defaults = {};
-  for (let [, arg] of serverArgs) {
-    defaults[arg.dest] = arg.defaultValue;
+  /**
+   * 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) {
-  for (const type of [DRIVER_TYPE, PLUGIN_TYPE]) {
-    const extParser = subParsers.addParser(type, {
-      addHelp: true,
-      help: `Access the ${type} management CLI commands`,
-      debug
-    });
-    const extSubParsers = extParser.addSubparsers({
-      dest: `${type}Command`,
-      debug
+  /**
+   *
+   * @param {import('argparse').SubParser} subParser
+   * @returns {import('./args').ArgumentDefinitions}
+   */
+  static _addServerToParser (subParser) {
+    const serverParser = subParser.add_parser('server', {
+      add_help: true,
+      help: 'Run an Appium server',
     });
-    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.addParser(command, {help, debug});
-      for (const [flags, opts] of [...sharedArgs, ...args]) {
-        // addArgument mutates params so make sure to send in copies instead
-        parser.addArgument([...flags], {...opts});
+
+    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});
+    }
+
+    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/cli/plugin-command.js

@@ -24,6 +24,10 @@ export default class PluginCommand extends ExtensionCommand {
     return await super.update({ext: plugin, unsafe});
   }
 
+  async run ({plugin, scriptName}) {
+    return await super.run({ext: plugin, scriptName});
+  }
+
   getPostInstallText ({extName, extData}) {
     return `Plugin ${extName}@${extData.version} successfully installed`.green;
   }

package/lib/cli/utils.js

@@ -52,9 +52,29 @@ async function spinWith (json, msg, fn) {
   }
 }
 
+class RingBuffer {
+  constructor (size = 50) {
+    this.size = size;
+    this.buffer = [];
+  }
+  getBuff () {
+    return this.buffer;
+  }
+  dequeue () {
+    this.buffer.shift();
+  }
+  enqueue (item) {
+    if (this.buffer.length >= this.size) {
+      this.dequeue();
+    }
+    this.buffer.push(item);
+  }
+}
+
 export {
   errAndQuit,
   log,
   spinWith,
-  JSON_SPACES
+  JSON_SPACES,
+  RingBuffer
 };