appium 2.0.0-beta.33 → 2.0.0-beta.37

package/lib/cli/extension.js

@@ -1,14 +1,15 @@
 /* eslint-disable no-console */
-
 import DriverCommand from './driver-command';
 import PluginCommand from './plugin-command';
-import { DRIVER_TYPE, PLUGIN_TYPE } from '../constants';
-import { errAndQuit, log, JSON_SPACES } from './utils';
+import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
+import {errAndQuit, JSON_SPACES} from './utils';
 
-const commandClasses = Object.freeze(/** @type {const} */({
-  [DRIVER_TYPE]: DriverCommand,
-  [PLUGIN_TYPE]: PluginCommand
-}));
+export const commandClasses = Object.freeze(
+  /** @type {const} */ ({
+    [DRIVER_TYPE]: DriverCommand,
+    [PLUGIN_TYPE]: PluginCommand,
+  })
+);
 
 /**
  * Run a subcommand of the 'appium driver' type. Each subcommand has its own set of arguments which
@@ -17,13 +18,13 @@ const commandClasses = Object.freeze(/** @type {const} */({
  * @param {Object} args - JS object where the key is the parameter name (as defined in
  * driver-parser.js)
  * @template {import('../extension/manifest').ExtensionType} ExtType
- * @param {import('../extension/extension-config').ExtensionConfig<ExtType>} configObject - Extension config object
+ * @param {import('../extension/extension-config').ExtensionConfig<ExtType>} config - Extension config object
  */
-async function runExtensionCommand (args, configObject) {
+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 {extensionType: type} = configObject;
+  const {extensionType: type} = config;
   const extCmd = args[`${type}Command`];
   if (!extCmd) {
     throw new TypeError(`Cannot call ${type} command without a subcommand like 'install'`);
@@ -32,10 +33,7 @@ async function runExtensionCommand (args, configObject) {
   if (suppressOutput) {
     json = true;
   }
-  const logFn = (msg) => log(json, msg);
-  let config = configObject;
-  config.log = logFn;
-  const CommandClass = /** @type {ExtCommand<ExtType>} */(commandClasses[type]);
+  const CommandClass = /** @type {ExtCommand<ExtType>} */ (commandClasses[type]);
   const cmd = new CommandClass({config, json});
   try {
     jsonResult = await cmd.execute(args);
@@ -55,11 +53,9 @@ async function runExtensionCommand (args, configObject) {
   return jsonResult;
 }
 
-export {
-  runExtensionCommand,
-};
+export {runExtensionCommand};
 
 /**
- * @template {import('../../types').ExtensionType} ExtType
- * @typedef {ExtType extends import('../../types').DriverType ? import('@appium/types').Class<DriverCommand> : ExtType extends import('../../types').PluginType ? import('@appium/types').Class<PluginCommand> : never} ExtCommand
+ * @template {import('@appium/types').ExtensionType} ExtType
+ * @typedef {ExtType extends import('@appium/types').DriverType ? import('@appium/types').Class<DriverCommand> : ExtType extends import('@appium/types').PluginType ? import('@appium/types').Class<PluginCommand> : never} ExtCommand
  */

package/lib/cli/parser.js

@@ -1,30 +1,18 @@
-
-import { fs } from '@appium/support';
-import { ArgumentParser } from 'argparse';
+import {fs} from '@appium/support';
+import {ArgumentParser} from 'argparse';
 import _ from 'lodash';
 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';
+import {DRIVER_TYPE, PLUGIN_TYPE, SERVER_SUBCOMMAND} from '../constants';
+import {finalizeSchema, getArgSpec, hasArgSpec} from '../schema';
+import {rootDir} from '../config';
+import {getExtensionArgs, getServerArgs} from './args';
 
 /**
  * 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'
-  ])
+  new Set([DRIVER_TYPE, PLUGIN_TYPE, SERVER_SUBCOMMAND, '-h', '--help', '-v', '--version'])
 );
 
 const version = fs.readPackageJsonFrom(rootDir).version;
@@ -40,7 +28,7 @@ class ArgParser {
   /**
    * @param {boolean} [debug] - If true, throw instead of exit on error.
    */
-  constructor (debug = false) {
+  constructor(debug = false) {
     const prog = process.argv[1] ? path.basename(process.argv[1]) : 'appium';
     const parser = new ArgumentParser({
       add_help: true,
@@ -99,11 +87,11 @@ class ArgParser {
    * If no subcommand is passed in, this method will inject the `server` subcommand.
    *
    * `ArgParser.prototype.parse_args` is an alias of this method.
-   * @template [T=import('../../types').WithServerSubcommand]
+   * @template [T=import('appium/types').WithServerSubcommand]
    * @param {string[]} [args] - Array of arguments, ostensibly from `process.argv`. Gathers args from `process.argv` if not provided.
-   * @returns {import('../../types').Args<T>} - The parsed arguments
+   * @returns {import('appium/types').Args<T>} - The parsed arguments
    */
-  parseArgs (args = process.argv.slice(2)) {
+  parseArgs(args = process.argv.slice(2)) {
     if (!NON_SERVER_ARGS.has(args[0])) {
       args.unshift(SERVER_SUBCOMMAND);
     }
@@ -137,12 +125,12 @@ class ArgParser {
    * @param {object} args
    * @returns {object}
    */
-  static _transformParsedArgs (args) {
+  static _transformParsedArgs(args) {
     return _.reduce(
       args,
       (unpacked, value, key) => {
         if (!_.isUndefined(value) && hasArgSpec(key)) {
-          const {dest} = /** @type {import('../schema/arg-spec').ArgSpec} */(getArgSpec(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
@@ -150,7 +138,7 @@ class ArgParser {
         }
         return unpacked;
       },
-      {},
+      {}
     );
   }
 
@@ -158,7 +146,7 @@ class ArgParser {
    * Patches the `exit()` method of the parser to throw an error, so we can handle it manually.
    * @param {ArgumentParser} parser
    */
-  static _patchExit (parser) {
+  static _patchExit(parser) {
     parser.exit = (code, msg) => {
       if (code) {
         throw new Error(msg);
@@ -172,7 +160,7 @@ class ArgParser {
    * @param {import('argparse').SubParser} subParser
    * @returns {import('./args').ArgumentDefinitions}
    */
-  static _addServerToParser (subParser) {
+  static _addServerToParser(subParser) {
     const serverParser = subParser.add_parser('server', {
       add_help: true,
       help: 'Run an Appium server',
@@ -194,7 +182,7 @@ class ArgParser {
    * Adds extension sub-sub-commands to `driver`/`plugin` subcommands
    * @param {import('argparse').SubParser} subParsers
    */
-  static _addExtensionCommandsToParser (subParsers) {
+  static _addExtensionCommandsToParser(subParsers) {
     for (const type of [DRIVER_TYPE, PLUGIN_TYPE]) {
       const extParser = subParsers.add_parser(type, {
         add_help: true,
@@ -259,10 +247,10 @@ class ArgParser {
  * @param {boolean} [debug] - If `true`, throw instead of exit upon parsing error
  * @returns {ArgParser}
  */
-function getParser (debug) {
+function getParser(debug) {
   finalizeSchema();
 
   return new ArgParser(debug);
 }
 
-export { getParser, ArgParser };
+export {getParser, ArgParser};

package/lib/cli/plugin-command.js

@@ -1,56 +1,71 @@
 import _ from 'lodash';
 import ExtensionCommand from './extension-command';
-import { KNOWN_PLUGINS } from '../constants';
+import {KNOWN_PLUGINS} from '../constants';
 
 const REQ_PLUGIN_FIELDS = ['pluginName', 'mainClass'];
 
+/**
+ * @extends {ExtensionCommand<PluginType>}
+ */
 export default class PluginCommand extends ExtensionCommand {
-
   /**
    *
-   * @param {PluginCommandOptions} opts
+   * @param {import('./extension-command').ExtensionCommandOptions<PluginType>} opts
    */
-  constructor ({config, json}) {
+  constructor({config, json}) {
     super({config, json});
     this.knownExtensions = KNOWN_PLUGINS;
   }
 
-  async install ({plugin, installType, packageName}) {
-    return await super._install({ext: plugin, installType, packageName});
+  async install({plugin, installType, packageName}) {
+    return await super._install({
+      installSpec: plugin,
+      installType,
+      packageName,
+    });
   }
 
-  async uninstall ({plugin}) {
-    return await super._uninstall({ext: plugin});
+  async uninstall({plugin}) {
+    return await super._uninstall({installSpec: plugin});
   }
 
-  async update ({plugin, unsafe}) {
-    return await super._update({ext: plugin, unsafe});
+  async update({plugin, unsafe}) {
+    return await super._update({installSpec: plugin, unsafe});
   }
 
-  async run ({plugin, scriptName}) {
-    return await super._run({ext: plugin, scriptName});
+  async run({plugin, scriptName}) {
+    return await super._run({installSpec: plugin, scriptName});
   }
 
-  getPostInstallText ({extName, extData}) {
+  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 `driverMetadata`
+   *
+   * For any `package.json` fields which a driver 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 PluginCommandOptions
- * @property {import('../extension/extension-config').ExtensionConfig<import('../extension/manifest').PluginType>} config
- * @property {boolean} json
+ * @typedef {import('@appium/types').PluginType} PluginType
  */

package/lib/cli/utils.js

@@ -9,7 +9,7 @@ const JSON_SPACES = 4;
  * @param {boolean} json - whether we should log json or text
  * @param {any} msg - error message, object, Error instance, etc.
  */
-function errAndQuit (json, msg) {
+function errAndQuit(json, msg) {
   if (json) {
     console.log(JSON.stringify({error: `${msg}`}, null, JSON_SPACES));
   } else {
@@ -26,7 +26,7 @@ function errAndQuit (json, msg) {
  * @param {boolean} json - whether we are in json mode (and should therefore not log)
  * @param {string} msg - string to log
  */
-function log (json, msg) {
+function log(json, msg) {
   !json && console.log(msg);
 }
 
@@ -36,7 +36,7 @@ function log (json, msg) {
  * @param {string} msg - string to log
  * @param {function} fn - function to wrap with spinning
  */
-async function spinWith (json, msg, fn) {
+async function spinWith(json, msg, fn) {
   if (json) {
     return await fn();
   }
@@ -53,17 +53,17 @@ async function spinWith (json, msg, fn) {
 }
 
 class RingBuffer {
-  constructor (size = 50) {
+  constructor(size = 50) {
     this.size = size;
     this.buffer = [];
   }
-  getBuff () {
+  getBuff() {
     return this.buffer;
   }
-  dequeue () {
+  dequeue() {
     this.buffer.shift();
   }
-  enqueue (item) {
+  enqueue(item) {
     if (this.buffer.length >= this.size) {
       this.dequeue();
     }
@@ -71,10 +71,4 @@ class RingBuffer {
   }
 }
 
-export {
-  errAndQuit,
-  log,
-  spinWith,
-  JSON_SPACES,
-  RingBuffer
-};
+export {errAndQuit, log, spinWith, JSON_SPACES, RingBuffer};

package/lib/config-file.js

@@ -1,15 +1,14 @@
-
 import betterAjvErrors from '@sidvind/better-ajv-errors';
-import { lilconfig } from 'lilconfig';
+import {lilconfig} from 'lilconfig';
 import _ from 'lodash';
 import yaml from 'yaml';
-import { getSchema, validate } from './schema/schema';
+import {getSchema, validate} from './schema/schema';
 
 /**
  * lilconfig loader to handle `.yaml` files
  * @type {import('lilconfig').LoaderSync}
  */
-function yamlLoader (filepath, content) {
+function yamlLoader(filepath, content) {
   return yaml.parse(content);
 }
 
@@ -26,7 +25,7 @@ const rawConfig = new Map();
  * If it weren't for this cache, this would be unnecessary.
  * @type {import('lilconfig').LoaderSync}
  */
-function jsonLoader (filepath, content) {
+function jsonLoader(filepath, content) {
   rawConfig.set(filepath, content);
   return JSON.parse(content);
 }
@@ -37,13 +36,15 @@ function jsonLoader (filepath, content) {
  * @param {string} filepath - Path to config file
  * @returns {Promise<import('lilconfig').LilconfigResult>}
  */
-async function loadConfigFile (lc, filepath) {
+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}`;
+  } 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
@@ -59,7 +60,7 @@ async function loadConfigFile (lc, filepath) {
  * @param {LilconfigAsyncSearcher} lc - lilconfig instance
  * @returns {Promise<import('lilconfig').LilconfigResult>}
  */
-async function searchConfigFile (lc) {
+async function searchConfigFile(lc) {
   return await lc.search();
 }
 
@@ -78,7 +79,7 @@ async function searchConfigFile (lc) {
  * @throws {TypeError} If `errors` is empty
  * @returns {string}
  */
-export function formatErrors (errors = [], config = {}, opts = {}) {
+export function formatErrors(errors = [], config = {}, opts = {}) {
   if (errors && !errors.length) {
     throw new TypeError('Array of errors must be non-empty');
   }
@@ -97,7 +98,7 @@ export function formatErrors (errors = [], config = {}, opts = {}) {
  * @public
  * @returns {Promise<ReadConfigFileResult>} Contains config and filepath, if found, and any errors
  */
-export async function readConfigFile (filepath, opts = {}) {
+export async function readConfigFile(filepath, opts = {}) {
   const lc = lilconfig('appium', {
     loaders: {
       '.yaml': yamlLoader,
@@ -105,12 +106,10 @@ export async function readConfigFile (filepath, opts = {}) {
       '.json': jsonLoader,
       noExt: jsonLoader,
     },
-    packageProp: 'appiumConfig'
+    packageProp: 'appiumConfig',
   });
 
-  const result = filepath
-    ? await loadConfigFile(lc, filepath)
-    : await searchConfigFile(lc);
+  const result = filepath ? await loadConfigFile(lc, filepath) : await searchConfigFile(lc);
 
   if (result?.filepath && !result?.isEmpty) {
     const {pretty = true} = opts;
@@ -124,15 +123,11 @@ export async function readConfigFile (filepath, opts = {}) {
           json: rawConfig.get(result.filepath),
           pretty,
         });
-        configResult = reason
-          ? {...result, errors, reason}
-          : {...result, errors};
+        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),
-      );
+      configResult.config = normalizeConfig(/** @type {AppiumConfig} */ (configResult.config));
 
       return configResult;
     } finally {
@@ -148,7 +143,7 @@ export async function readConfigFile (filepath, opts = {}) {
  * @param {AppiumConfig} config - Configuration object
  * @returns {NormalizedAppiumConfig} New object with camel-cased keys (or `dest` keys).
  */
-export function normalizeConfig (config) {
+export function normalizeConfig(config) {
   const schema = getSchema();
   /**
    * @param {AppiumConfig} config
@@ -159,8 +154,9 @@ export function normalizeConfig (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),
+    const mappedObj = _.mapKeys(
+      obj,
+      (__, prop) => schema.properties[prop]?.appiumCliDest ?? _.camelCase(prop)
     );
 
     return _.mapValues(mappedObj, (value, property) => {