appium 2.0.0-beta.2 → 2.0.0-beta.23

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,18 +1,32 @@
-import _ from 'lodash';
+// @ts-check
+
 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';
 
 export default class NPM {
 
+  /**
+   * @param {string} appiumHome
+   */
   constructor (appiumHome) {
+    /** @type {string} */
     this.appiumHome = appiumHome;
   }
 
+  /**
+   * Execute `npm` with given args.
+   *
+   * If the process exits with a nonzero code, the contents of `STDOUT` and `STDERR` will be in the
+   * `message` of the {@link TeenProcessExecError} rejected.
+   * @param {string} cmd
+   * @param {string[]} args
+   * @param {{ json?: boolean; cwd?: string; lockFile?: string; }} opts
+   */
   async exec (cmd, args, opts, execOpts = {}) {
     let { cwd, json, lockFile } = opts;
     if (!cwd) {
@@ -21,40 +35,60 @@ 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};
 
     args.unshift(cmd);
     if (json) {
-      args.push('-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;
       runner = async () => await acquireLock(_runner);
     }
-    const {stdout, stderr, code} = await runner();
-    const ret = {stdout, stderr, code, json: null};
 
-    if (json) {
+    let ret;
+    try {
+      const {stdout, stderr, code} = await runner();
+      ret = /** @type {TeenProcessExecResult} */({stdout, stderr, code});
       // if possible, parse NPM's json output. During NPM install 3rd-party
       // packages can write to stdout, so sometimes the json output can't be
       // guaranteed to be parseable
       try {
         ret.json = JSON.parse(stdout);
       } catch (ign) {}
+    } catch (e) {
+      const {stdout, stderr, code} = /** @type {TeenProcessExecError} */(e);
+      const err = new Error(`npm command '${cmd} ${args.join(' ')}' failed with code ${code}.\n\nSTDOUT:\n${stdout.trim()}\n\nSTDERR:\n${stderr.trim()}`);
+      throw err;
     }
-
     return ret;
   }
 
+  /**
+   * @param {string} pkg
+   */
   async getLatestVersion (pkg) {
     return (await this.exec('view', [pkg, 'dist-tags'], {
       json: true
-    })).json.latest;
+    })).json?.latest;
   }
 
+  /**
+   * @param {string} pkg
+   * @param {string} curVersion
+   */
   async getLatestSafeUpgradeVersion (pkg, curVersion) {
     const allVersions = (await this.exec('view', [pkg, 'versions'], {
       json: true
@@ -107,6 +141,11 @@ export default class NPM {
     return safeUpgradeVer;
   }
 
+  /**
+   *
+   * @param {{pkgDir: string, pkgName: string, pkgVer?: string}} param0
+   * @returns {Promise<import('type-fest').PackageJson>}
+   */
   async installPackage ({pkgDir, pkgName, pkgVer}) {
     const res = await this.exec('install', [
       '--no-save',
@@ -124,14 +163,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
@@ -148,6 +179,9 @@ export default class NPM {
     }
   }
 
+  /**
+   * @param {string} pkgPath
+   */
   async linkPackage (pkgPath) {
     // from the path alone we don't know the npm package name, so we need to
     // look in package.json
@@ -159,8 +193,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);
     }
@@ -174,6 +214,10 @@ export default class NPM {
     }
   }
 
+  /**
+   * @param {string} pkgDir
+   * @param {string} pkg
+   */
   async uninstallPackage (pkgDir, pkg) {
     await this.exec('uninstall', [pkg], {
       cwd: pkgDir,
@@ -181,3 +225,27 @@ export default class NPM {
     });
   }
 }
+
+
+/**
+ * Result from a non-zero-exit execution of `appium`
+ * @typedef {Object} TeenProcessExecResult
+ * @property {string} stdout - Stdout
+ * @property {string} stderr - Stderr
+ * @property {number?} code - Exit code
+ * @property {any} json - JSON parsed from stdout
+ */
+
+/**
+ * Extra props `teen_process.exec` adds to its error objects
+ * @typedef {Object} TeenProcessExecErrorProps
+ * @property {string} stdout - STDOUT
+ * @property {string} stderr - STDERR
+ * @property {number?} code - Exit code
+ */
+
+
+/**
+ * Error thrown by `teen_process.exec`
+ * @typedef {Error & TeenProcessExecErrorProps} TeenProcessExecError
+ */