appium 2.0.0-beta.25 → 2.0.0-beta.28

package/lib/main.js

@@ -1,26 +1,26 @@
 #!/usr/bin/env node
 
-// transpile:main
-// @ts-check
 
-import logger from './logger'; // logger needs to remain first of imports
+import { init as logsinkInit } from './logsink'; // this import needs to come first since it sets up global npmlog
+import logger from './logger'; // logger needs to remain second
 // @ts-ignore
 import { routeConfiguringFunction as makeRouter, server as baseServer } from '@appium/base-driver';
-import { logger as logFactory, util } from '@appium/support';
+import { logger as logFactory, util, env } from '@appium/support';
 import { asyncify } from 'asyncbox';
 import _ from 'lodash';
 import { AppiumDriver } from './appium';
-import { driverConfig, pluginConfig, USE_ALL_PLUGINS } from './cli/args';
 import { runExtensionCommand } from './cli/extension';
-import { default as getParser, SERVER_SUBCOMMAND } from './cli/parser';
-import { APPIUM_VER, checkNodeOk, getGitRev, getNonDefaultServerArgs, showBuildInfo, validateTmpDir, warnNodeDeprecations, showConfig } from './config';
+import { getParser } from './cli/parser';
+import { APPIUM_VER, checkNodeOk, getGitRev, getNonDefaultServerArgs, showConfig, showBuildInfo, validateTmpDir, warnNodeDeprecations } from './config';
 import { readConfigFile } from './config-file';
-import { DRIVER_TYPE, PLUGIN_TYPE } from './extension-config';
+import { loadExtensions, getActivePlugins, getActiveDrivers } from './extension';
+import { DRIVER_TYPE, PLUGIN_TYPE, SERVER_SUBCOMMAND } from './constants';
 import registerNode from './grid-register';
-import { init as logsinkInit } from './logsink';
-import { getDefaultsForSchema } from './schema/schema';
+import { getDefaultsForSchema, validate } from './schema/schema';
 import { inspect } from './utils';
 
+const {resolveAppiumHome} = env;
+
 /**
  *
  * @param {ParsedArgs} args
@@ -38,6 +38,8 @@ async function preflightChecks (args, throwInsteadOfExit = false) {
     }
     warnNodeDeprecations();
 
+    validate(args);
+
     if (args.tmpDir) {
       await validateTmpDir(args.tmpDir);
     }
@@ -102,63 +104,11 @@ function logServerPort (address, port) {
   logger.info(logMessage);
 }
 
-/**
- * Find any plugin name which has been installed, and which has been requested for activation by
- * using the --use-plugins flag, and turn each one into its class, so we can send them as objects
- * to the server init. We also want to send/assign them to the umbrella driver so it can use them
- * to wrap command execution
- *
- * @param {Object} args - argparser parsed dict
- * @param {import('./plugin-config').default} pluginConfig - a plugin extension config
- * @returns {PluginExtensionClass[]}
- */
-function getActivePlugins (args, pluginConfig) {
-  return _.compact(Object.keys(pluginConfig.installedExtensions).filter((pluginName) =>
-    _.includes(args.usePlugins, pluginName) ||
-    (args.usePlugins.length === 1 && args.usePlugins[0] === USE_ALL_PLUGINS)
-  ).map((pluginName) => {
-    try {
-      logger.info(`Attempting to load plugin ${pluginName}...`);
-      const PluginClass = /** @type {PluginExtensionClass} */(pluginConfig.require(pluginName));
-
-      PluginClass.pluginName = pluginName; // store the plugin name on the class so it can be used later
-      return PluginClass;
-    } catch (err) {
-      logger.error(`Could not load plugin '${pluginName}', so it will not be available. Error ` +
-                   `in loading the plugin was: ${err.message}`);
-      logger.debug(err.stack);
-    }
-  }));
-}
-
-/**
- * Find any driver name which has been installed, and turn each one into its class, so we can send
- * them as objects to the server init in case they need to add methods/routes or update the server.
- * If the --drivers flag was given, this method only loads the given drivers.
- *
- * @param {Object} args - argparser parsed dict
- * @param {import('./driver-config').default} driverConfig - a driver extension config
- */
-function getActiveDrivers (args, driverConfig) {
-  return _.compact(Object.keys(driverConfig.installedExtensions).filter((driverName) =>
-    _.includes(args.useDrivers, driverName) || args.useDrivers.length === 0
-  ).map((driverName) => {
-    try {
-      logger.info(`Attempting to load driver ${driverName}...`);
-      return driverConfig.require(driverName);
-    } catch (err) {
-      logger.error(`Could not load driver '${driverName}', so it will not be available. Error ` +
-                   `in loading the driver was: ${err.message}`);
-      logger.debug(err.stack);
-    }
-  }));
-}
-
 /**
  * Gets a list of `updateServer` functions from all extensions
- * @param {DriverExtensionClass[]} driverClasses
- * @param {PluginExtensionClass[]} pluginClasses
- * @returns {StaticExtMembers['updateServer'][]}
+ * @param {DriverClass[]} driverClasses
+ * @param {PluginClass[]} pluginClasses
+ * @returns {import('@appium/base-driver/lib/basedriver/driver').UpdateServerCallback[]}
  */
 function getServerUpdaters (driverClasses, pluginClasses) {
   return _.compact(_.map([...driverClasses, ...pluginClasses], 'updateServer'));
@@ -166,9 +116,9 @@ function getServerUpdaters (driverClasses, pluginClasses) {
 
 /**
  * Makes a big `MethodMap` from all the little `MethodMap`s in the extensions
- * @param {DriverExtensionClass[]} driverClasses
- * @param {PluginExtensionClass[]} pluginClasses
- * @returns {import('@appium/base-driver').MethodMap}
+ * @param {DriverClass[]} driverClasses
+ * @param {PluginClass[]} pluginClasses
+ * @returns {import('@appium/types').MethodMap}
  */
 function getExtraMethodMap (driverClasses, pluginClasses) {
   return [...driverClasses, ...pluginClasses].reduce(
@@ -182,11 +132,10 @@ function getExtraMethodMap (driverClasses, pluginClasses) {
  *
  * Use this to get at the configuration schema.
  *
- * If `args` contains a non-empty `subcommand` which is not `server`, this function
- * will resolve with an empty object.
+ * If `args` contains a non-empty `subcommand` which is not `server`, this function will return an empty object.
  *
- * @param {ParsedArgs} [args] - Parsed args
- * @returns {Promise<Partial<{appiumDriver: AppiumDriver, parsedArgs: ParsedArgs}>>}
+ * @param {PartialArgs} [args] - Partial args (progammatic usage only)
+ * @returns {Promise<ServerInitResult | ExtCommandInitResult>}
  * @example
  * import {init, getSchema} from 'appium';
  * const options = {}; // config object
@@ -194,11 +143,15 @@ function getExtraMethodMap (driverClasses, pluginClasses) {
  * const schema = getSchema(); // entire config schema including plugins and drivers
  */
 async function init (args) {
-  const parser = await getParser();
+  const appiumHome = args?.appiumHome ?? await resolveAppiumHome();
+
+  const {driverConfig, pluginConfig} = await loadExtensions(appiumHome);
+
+  const parser = getParser();
   let throwInsteadOfExit = false;
   /** @type {ParsedArgs} */
   let preConfigParsedArgs;
-  /** @type {typeof preConfigParsedArgs & import('type-fest').AsyncReturnType<readConfigFile>['config']} */
+  /** @type {ParsedArgs} */
   let parsedArgs;
   /**
    * This is a definition (instead of declaration) because TS can't figure out
@@ -215,7 +168,7 @@ async function init (args) {
       // but remove it since it's not a real server arg per se
       delete args.throwInsteadOfExit;
     }
-    preConfigParsedArgs = {...args, subcommand: args.subcommand ?? SERVER_SUBCOMMAND};
+    preConfigParsedArgs = /** @type {ParsedArgs} */({...args, subcommand: args.subcommand ?? SERVER_SUBCOMMAND});
   } else {
     // otherwise parse from CLI
     preConfigParsedArgs = parser.parseArgs();
@@ -227,7 +180,6 @@ async function init (args) {
     throw new Error(`Errors in config file ${configResult.filepath}:\n ${configResult.reason ?? configResult.errors}`);
   }
 
-
   // merge config and apply defaults.
   // the order of precendece is:
   // 1. command line args
@@ -256,11 +208,11 @@ async function init (args) {
   // if the user has requested the 'driver' CLI, don't run the normal server,
   // but instead pass control to the driver CLI
   if (parsedArgs.subcommand === DRIVER_TYPE) {
-    await runExtensionCommand(parsedArgs, parsedArgs.subcommand, driverConfig);
+    await runExtensionCommand(parsedArgs, driverConfig);
     return {};
   }
   if (parsedArgs.subcommand === PLUGIN_TYPE) {
-    await runExtensionCommand(parsedArgs, parsedArgs.subcommand, pluginConfig);
+    await runExtensionCommand(parsedArgs, pluginConfig);
     return {};
   }
 
@@ -282,32 +234,32 @@ async function init (args) {
   appiumDriver.driverConfig = driverConfig;
   await preflightChecks(parsedArgs, throwInsteadOfExit);
 
-  return {appiumDriver, parsedArgs};
+  return /** @type {ServerInitResult} */({appiumDriver, parsedArgs, driverConfig, pluginConfig});
 }
 
 /**
  * Initializes Appium's config.  Starts server if appropriate and resolves the
  * server instance if so; otherwise resolves w/ `undefined`.
- * @param {ParsedArgs} [args] - Arguments from CLI or otherwise
- * @returns {Promise<import('express').Express|undefined>}
+ * @param {PartialArgs} [args] - Arguments from CLI or otherwise
+ * @returns {Promise<import('http').Server|undefined>}
  */
 async function main (args) {
-  const {appiumDriver, parsedArgs} = await init(args);
+  const {appiumDriver, parsedArgs, pluginConfig, driverConfig} = /** @type {ServerInitResult} */(await init(args));
 
-  if (!appiumDriver || !parsedArgs) {
+  if (!appiumDriver || !parsedArgs || !pluginConfig || !driverConfig) {
     // if this branch is taken, we've run a different subcommand, so there's nothing
     // left to do here.
     return;
   }
 
-  const pluginClasses = getActivePlugins(parsedArgs, pluginConfig);
+  const pluginClasses = getActivePlugins(pluginConfig, parsedArgs.usePlugins);
   // set the active plugins on the umbrella driver so it can use them for commands
   appiumDriver.pluginClasses = pluginClasses;
 
   await logStartupInfo(parsedArgs);
   let routeConfiguringFunction = makeRouter(appiumDriver);
 
-  const driverClasses = getActiveDrivers(parsedArgs, driverConfig);
+  const driverClasses = getActiveDrivers(driverConfig, parsedArgs.useDrivers);
   const serverUpdaters = getServerUpdaters(driverClasses, pluginClasses);
   const extraMethodMap = getExtraMethodMap(driverClasses, pluginClasses);
 
@@ -382,23 +334,33 @@ if (require.main === module) {
 }
 
 // everything below here is intended to be a public API.
-export { main, init };
-export { APPIUM_HOME } from './extension-config';
-export { getSchema, validate, finalizeSchema } from './schema/schema';
 export { readConfigFile } from './config-file';
+export { finalizeSchema, getSchema, validate } from './schema/schema';
+export { main, init, resolveAppiumHome };
+
+/**
+ * @typedef {import('../types/cli').ParsedArgs} ParsedArgs
+ */
 
 /**
- * @typedef {import('../types/types').ParsedArgs} ParsedArgs
+ * @typedef {import('../types/cli').PartialArgs} PartialArgs
+ * @typedef {import('../types').DriverType} DriverType
+ * @typedef {import('../types').PluginType} PluginType
+ * @typedef {import('../types/extension').DriverClass} DriverClass
+ * @typedef {import('../types/extension').PluginClass} PluginClass
  */
 
 /**
- * @typedef {import('./appium').PluginExtensionClass} PluginExtensionClass
+ * Literally an empty object
+ * @typedef { {} } ExtCommandInitResult
  */
 
 /**
- * @typedef {import('./appium').DriverExtensionClass} DriverExtensionClass
+ * @typedef ServerInitData
+ * @property {AppiumDriver} appiumDriver - The Appium driver
+ * @property {ParsedArgs} parsedArgs - The parsed arguments
  */
 
 /**
- * @typedef {import('./appium').StaticExtMembers} StaticExtMembers
+ * @typedef {ServerInitData & import('./extension').ExtensionConfigs} ServerInitResult
  */

package/lib/schema/arg-spec.js

@@ -28,6 +28,7 @@ const PROPERTIES = 'properties';
  * option) used for cross-referencing.
  *
  * This class has no instance methods, and is basically just a read-only "struct".
+ * @template D
  */
 export class ArgSpec {
   /**
@@ -81,7 +82,7 @@ export class ArgSpec {
   /**
    * Whatever the default value of this argument is, as specified by the
    * `default` property of the schema.
-   * @type {D}
+   * @type {D|undefined}
    */
   defaultValue;
 
@@ -92,7 +93,6 @@ export class ArgSpec {
    *
    * The _constructor_ is private. Use {@link ArgSpec.create} instead.
    * @private
-   * @template D
    * @param {string} name
    * @param {ArgSpecOptions<D>} [opts]
    */
@@ -176,12 +176,15 @@ export class ArgSpec {
   /**
    * When given the root ID of a schema for an extension (`<extType>-<normalizedExtName>.json`) Returns an object containing the extension type and the _normalized_ extension name.
    * @param {string} schemaId - Root schema ID
-   * @returns { {extType: ExtensionType|undefined, normalizedExtName: string|undefined} }
+   * @returns { {extType?: ExtensionType, normalizedExtName?: string} }
    */
   static extensionInfoFromRootSchemaId (schemaId) {
     const matches = schemaId.match(SCHEMA_ID_REGEXP);
     if (matches?.groups) {
-      const {extType, normalizedExtName} = matches.groups;
+      const {extType, normalizedExtName} =
+        /** @type { {extType: ExtensionType, normalizedExtName: string} } */ (
+          matches.groups
+        );
       return {extType, normalizedExtName};
     }
     return {};
@@ -192,7 +195,8 @@ export class ArgSpec {
    *
    * @param {string} name - The canonical name of the argument. Corresponds to a key in a schema's
    * `properties` property.
-   * @param {ArgSpecOptions} [opts] - Options
+   * @template D
+   * @param {ArgSpecOptions<D>} [opts] - Options
    * @returns {Readonly<ArgSpec>}
    */
   static create (name, opts) {
@@ -216,7 +220,7 @@ export class ArgSpec {
 /**
  * Options for {@link ArgSpec.create}
  * @template D
- * @typedef {Object} ArgSpecOptions
+ * @typedef ArgSpecOptions
  * @property {string} [extName]
  * @property {ExtensionType} [extType]
  * @property {string} [dest]
@@ -224,5 +228,5 @@ export class ArgSpec {
  */
 
 /**
- * @typedef {import('../ext-config-io').ExtensionType} ExtensionType
+ * @typedef {import('../extension/manifest').ExtensionType} ExtensionType
  */

package/lib/schema/cli-args.js

@@ -1,4 +1,3 @@
-// @ts-check
 
 import {ArgumentTypeError} from 'argparse';
 import _ from 'lodash';
@@ -139,6 +138,7 @@ function subSchemaToArgDef (subSchema, argSpec) {
   // handle special cases for various types
   switch (type) {
     // booleans do not have a type per `ArgumentOptions`, just an "action"
+    // NOTE: due to limitations of `argparse`, we cannot provide fancy help text, and must rely on its internal error messaging.
     case TYPENAMES.BOOLEAN: {
       argOpts.action = 'store_const';
       argOpts.const = true;

package/lib/schema/cli-transformers.js

@@ -1,4 +1,3 @@
-// @ts-check
 
 import { ArgumentTypeError } from 'argparse';
 import { readFileSync } from 'fs';

package/lib/schema/keywords.js

@@ -1,4 +1,3 @@
-// @ts-check
 
 import { transformers } from './cli-transformers';
 
@@ -120,7 +119,7 @@ export const keywords = {
 /**
  * These are the custom keywords that Appium recognizes.
  *
- * @typedef {Object} AppiumJSONSchemaKeywords
+ * @typedef AppiumJSONSchemaKeywords
  * @property {string} [appiumCliDest]
  * @property {string} [appiumCliDescription]
  * @property {string[]} [appiumCliAliases]

package/lib/schema/schema.js

@@ -1,15 +1,44 @@
-// @ts-check
 
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import _ from 'lodash';
 import path from 'path';
-import { DRIVER_TYPE, PLUGIN_TYPE } from '../extension-config';
-import { ReadonlyMap } from '../utils';
-import appiumConfigSchema from './appium-config-schema';
+import { DRIVER_TYPE, PLUGIN_TYPE } from '../constants';
+import { AppiumConfigJsonSchema } from '@appium/schema';
 import { APPIUM_CONFIG_SCHEMA_ID, ArgSpec, SERVER_PROP_NAME } from './arg-spec';
 import { keywords } from './keywords';
 
+/**
+ * Key/value pairs go in... but they don't come out.
+ *
+ * @template K,V
+ * @extends {Map<K,V>}
+ */
+export class RoachHotelMap extends Map {
+  /**
+   * @param {K} key
+   * @param {V} value
+   */
+  set (key, value) {
+    if (this.has(key)) {
+      throw new Error(`${key} is already set`);
+    }
+    return super.set(key, value);
+  }
+
+  /**
+   * @param {K} key
+   */
+  // eslint-disable-next-line no-unused-vars
+  delete (key) {
+    return false;
+  }
+
+  clear () {
+    throw new Error(`Cannot clear RoachHotelMap`);
+  }
+}
+
 /**
  * Extensions that an extension schema file can have.
  */
@@ -28,9 +57,9 @@ class AppiumSchema {
    *
    * Used to provide easy lookups of argument metadata when converting between different representations of those arguments.
    * @private
-   * @type {ReadonlyMap<string,ArgSpec>}
+   * @type {RoachHotelMap<string,ArgSpec>}
    */
-  _argSpecs = new ReadonlyMap();
+  _argSpecs = new RoachHotelMap();
 
   /**
    * A map of extension types to extension names to schema objects.
@@ -83,25 +112,27 @@ class AppiumSchema {
    * @returns {AppiumSchema}
    */
   static create () {
-    const instance = AppiumSchema._instance ?? new AppiumSchema();
-    AppiumSchema._instance = instance;
-
-    _.bindAll(instance, [
-      'finalize',
-      'flatten',
-      'getAllArgSpecs',
-      'getArgSpec',
-      'getDefaults',
-      'getDefaultsForExtension',
-      'getSchema',
-      'hasArgSpec',
-      'isFinalized',
-      'registerSchema',
-      'reset',
-      'validate',
-    ]);
-
-    return instance;
+    if (!AppiumSchema._instance) {
+      const instance = new AppiumSchema();
+      AppiumSchema._instance = instance;
+      _.bindAll(instance, [
+        'finalize',
+        'flatten',
+        'getAllArgSpecs',
+        'getArgSpec',
+        'getDefaults',
+        'getDefaultsForExtension',
+        'getSchema',
+        'hasArgSpec',
+        'isFinalized',
+        'registerSchema',
+        'hasRegisteredSchema',
+        'reset',
+        'validate',
+      ]);
+    }
+
+    return AppiumSchema._instance;
   }
 
   /**
@@ -150,7 +181,7 @@ class AppiumSchema {
    */
   finalize () {
     if (this.isFinalized()) {
-      return /** @type {Record<string,StrictSchemaObject>} */ (
+      return /** @type {NonNullable<typeof this._finalizedSchemas>} */ (
         this._finalizedSchemas
       );
     }
@@ -158,7 +189,7 @@ class AppiumSchema {
     const ajv = this._ajv;
 
     // Ajv will _mutate_ the schema, so we need to clone it.
-    const baseSchema = _.cloneDeep(appiumConfigSchema);
+    const baseSchema = _.cloneDeep(AppiumConfigJsonSchema);
 
     /**
      *
@@ -259,7 +290,7 @@ class AppiumSchema {
     for (const schemaId of Object.keys(this._finalizedSchemas ?? {})) {
       this._ajv.removeSchema(schemaId);
     }
-    this._argSpecs = new ReadonlyMap();
+    this._argSpecs = new RoachHotelMap();
     this._registeredSchemas = {
       [DRIVER_TYPE]: new Map(),
       [PLUGIN_TYPE]: new Map(),
@@ -276,7 +307,7 @@ class AppiumSchema {
    * This is "fail-fast" in that the schema will immediately be validated against JSON schema draft-07 _or_ whatever the value of the schema's `$schema` prop is.
    *
    * Does _not_ add the schema to the `ajv` instance (this is done by {@link AppiumSchema.finalize}).
-   * @param {import('../ext-config-io').ExtensionType} extType - Extension type
+   * @param {ExtensionType} extType - Extension type
    * @param {string} extName - Unique extension name for `type`
    * @param {SchemaObject} schema - Schema object
    * @throws {SchemaNameConflictError} If the schema is an invalid
@@ -666,12 +697,12 @@ export const {isAllowedSchemaFileExtension} = AppiumSchema;
  */
 
 /**
- * @typedef {import('../ext-config-io').ExtensionType} ExtensionType
+ * @typedef {import('../extension/manifest').ExtensionType} ExtensionType
  */
 
 /**
  * An object having property `additionalProperties: false`
- * @typedef {Object} StrictProp
+ * @typedef StrictProp
  * @property {false} additionalProperties
  */