appium 2.0.0-beta.3 → 2.0.0-beta.34

package/lib/main.js

@@ -1,42 +1,45 @@
 #!/usr/bin/env node
-// transpile:main
 
-import { init as logsinkInit } from './logsink';
-import logger from './logger'; // logger needs to remain first of imports
-import _ from 'lodash';
-import { server as baseServer, routeConfiguringFunction as makeRouter } from 'appium-base-driver';
+
+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, env } from '@appium/support';
 import { asyncify } from 'asyncbox';
-import { default as getParser, getDefaultServerArgs } from './cli/parser';
-import { USE_ALL_PLUGINS } from './cli/args';
-import { logger as logFactory, util } from 'appium-support';
-import {
-  showConfig, checkNodeOk, validateServerArgs,
-  warnNodeDeprecations, validateTmpDir, getNonDefaultArgs,
-  getGitRev, APPIUM_VER
-} from './config';
-import DriverConfig from './driver-config';
-import PluginConfig from './plugin-config';
-import { DRIVER_TYPE, PLUGIN_TYPE } from './extension-config';
-import { runExtensionCommand } from './cli/extension';
+import _ from 'lodash';
 import { AppiumDriver } from './appium';
+import { runExtensionCommand } from './cli/extension';
+import { getParser } from './cli/parser';
+import { APPIUM_VER, checkNodeOk, getGitRev, getNonDefaultServerArgs, showConfig, showBuildInfo, validateTmpDir, warnNodeDeprecations } from './config';
+import { readConfigFile } from './config-file';
+import { loadExtensions, getActivePlugins, getActiveDrivers } from './extension';
+import { DRIVER_TYPE, PLUGIN_TYPE, SERVER_SUBCOMMAND } from './constants';
 import registerNode from './grid-register';
-import { inspectObject } from './utils';
+import { getDefaultsForSchema, validate } from './schema/schema';
+import { inspect } from './utils';
 
+const {resolveAppiumHome} = env;
 
-async function preflightChecks ({parser, args, driverConfig, pluginConfig, throwInsteadOfExit = false}) {
+/**
+ *
+ * @param {ParsedArgs} args
+ * @param {boolean} [throwInsteadOfExit]
+ */
+async function preflightChecks (args, throwInsteadOfExit = false) {
   try {
     checkNodeOk();
     if (args.longStacktrace) {
       require('longjohn').async_trace_limit = -1;
     }
-    if (args.showConfig) {
-      await showConfig();
+    if (args.showBuildInfo) {
+      await showBuildInfo();
       process.exit(0);
     }
     warnNodeDeprecations();
-    validateServerArgs(parser, args);
-    await driverConfig.read();
-    await pluginConfig.read();
+
+    validate(args);
+
     if (args.tmpDir) {
       await validateTmpDir(args.tmpDir);
     }
@@ -50,18 +53,27 @@ async function preflightChecks ({parser, args, driverConfig, pluginConfig, throw
   }
 }
 
+/**
+ * @param {Args} args
+ */
 function logNonDefaultArgsWarning (args) {
   logger.info('Non-default server args:');
-  inspectObject(args);
+  inspect(args);
 }
 
+/**
+ * @param {Args['defaultCapabilities']} caps
+ */
 function logDefaultCapabilitiesWarning (caps) {
   logger.info('Default capabilities, which will be added to each request ' +
               'unless overridden by desired capabilities:');
-  inspectObject(caps);
+  inspect(caps);
 }
 
-async function logStartupInfo (parser, args) {
+/**
+ * @param {ParsedArgs} args
+ */
+async function logStartupInfo (args) {
   let welcome = `Welcome to Appium v${APPIUM_VER}`;
   let appiumRev = await getGitRev();
   if (appiumRev) {
@@ -69,7 +81,7 @@ async function logStartupInfo (parser, args) {
   }
   logger.info(welcome);
 
-  let showArgs = getNonDefaultArgs(parser, args);
+  let showArgs = getNonDefaultServerArgs(args);
   if (_.size(showArgs)) {
     logNonDefaultArgsWarning(showArgs);
   }
@@ -83,20 +95,77 @@ async function logStartupInfo (parser, args) {
   // }
 }
 
+/**
+ * Logs the address and port the server is listening on
+ * @param {string} address - Address
+ * @param {number} port - Port
+ * @returns {void}
+ */
 function logServerPort (address, port) {
   let logMessage = `Appium REST http interface listener started on ` +
                    `${address}:${port}`;
   logger.info(logMessage);
 }
 
-async function main (args = null) {
-  let parser = getParser();
+/**
+ * Gets a list of `updateServer` functions from all extensions
+ * @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'));
+}
+
+/**
+ * Makes a big `MethodMap` from all the little `MethodMap`s in the extensions
+ * @param {DriverClass[]} driverClasses
+ * @param {PluginClass[]} pluginClasses
+ * @returns {import('@appium/types').MethodMap}
+ */
+function getExtraMethodMap (driverClasses, pluginClasses) {
+  return [...driverClasses, ...pluginClasses].reduce(
+    (map, klass) => ({...map, .../** @type {DriverClass} */(klass).newMethodMap ?? {}}),
+    {}
+  );
+}
+
+/**
+ * @template [T=WithServerSubcommand]
+ * @param {Args<T>} args
+ * @returns {args is Args<WithServerSubcommand>}
+ */
+function areServerCommandArgs (args) {
+  return args.subcommand === SERVER_SUBCOMMAND;
+}
+
+/**
+ * Initializes Appium, but does not start the server.
+ *
+ * Use this to get at the configuration schema.
+ *
+ * If `args` contains a non-empty `subcommand` which is not `server`, this function will return an empty object.
+ *
+ * @template [T=WithServerSubcommand]
+ * @param {Args<T>} [args] - Partial args (progammatic usage only)
+ * @returns {Promise<ServerInitResult | ExtCommandInitResult>}
+ * @example
+ * import {init, getSchema} from 'appium';
+ * const options = {}; // config object
+ * await init(options);
+ * const schema = getSchema(); // entire config schema including plugins and drivers
+ */
+async function init (args) {
+  const appiumHome = args?.appiumHome ?? await resolveAppiumHome();
+
+  const {driverConfig, pluginConfig} = await loadExtensions(appiumHome);
+
+  const parser = getParser();
   let throwInsteadOfExit = false;
-  if (args) {
-    // a containing package passed in their own args, let's fill them out
-    // with defaults
-    args = Object.assign({}, getDefaultServerArgs(), args);
+  /** @type {Args<T>} */
+  let preConfigArgs;
 
+  if (args) {
     // if we have a containing package instead of running as a CLI process,
     // that package might not appreciate us calling 'process.exit' willy-
     // nilly, so give it the option to have us throw instead of exit
@@ -105,80 +174,136 @@ async function main (args = null) {
       // but remove it since it's not a real server arg per se
       delete args.throwInsteadOfExit;
     }
+    preConfigArgs = {...args, subcommand: args.subcommand ?? SERVER_SUBCOMMAND};
   } else {
     // otherwise parse from CLI
-    args = parser.parseArgs();
+    preConfigArgs = /** @type {Args<T>} */(parser.parseArgs());
   }
-  await logsinkInit(args);
 
-  // if the user has requested the 'driver' CLI, don't run the normal server,
-  // but instead pass control to the driver CLI
-  if (args.subcommand === DRIVER_TYPE || args.subcommand === PLUGIN_TYPE) {
-    await runExtensionCommand(args, args.subcommand);
-    process.exit();
+  const configResult = await readConfigFile(preConfigArgs.configFile);
+
+  if (!_.isEmpty(configResult.errors)) {
+    throw new Error(`Errors in config file ${configResult.filepath}:\n ${configResult.reason ?? configResult.errors}`);
   }
 
-  if (args.logFilters) {
-    const {issues, rules} = await logFactory.loadSecureValuesPreprocessingRules(args.logFilters);
-    if (!_.isEmpty(issues)) {
-      throw new Error(`The log filtering rules config '${args.logFilters}' has issues: ` +
-        JSON.stringify(issues, null, 2));
+  // merge config and apply defaults.
+  // the order of precendece is:
+  // 1. command line args
+  // 2. config file
+  // 3. defaults from config file.
+  if (!areServerCommandArgs(preConfigArgs)) {
+
+    // if the user has requested the 'driver' CLI, don't run the normal server,
+    // but instead pass control to the driver CLI
+    if (preConfigArgs.subcommand === DRIVER_TYPE) {
+      await runExtensionCommand(preConfigArgs, driverConfig);
+      return {};
     }
-    if (_.isEmpty(rules)) {
-      logger.warn(`Found no log filtering rules in '${args.logFilters}'. Is that expected?`);
-    } else {
-      logger.info(`Loaded ${util.pluralize('filtering rule', rules.length, true)} from '${args.logFilters}'`);
+    if (preConfigArgs.subcommand === PLUGIN_TYPE) {
+      await runExtensionCommand(preConfigArgs, pluginConfig);
+      return {};
     }
+    /* istanbul ignore next */
+    return {}; // should never happen
+  } else {
+    const defaults = getDefaultsForSchema(false);
+
+    /** @type {ParsedArgs} */
+    const serverArgs = _.defaultsDeep(
+      preConfigArgs,
+      configResult.config?.server,
+      defaults
+    );
+
+    if (preConfigArgs.showConfig) {
+      showConfig(getNonDefaultServerArgs(preConfigArgs), configResult, defaults, serverArgs);
+      return {};
+    }
+
+    await logsinkInit(serverArgs);
+
+    if (serverArgs.logFilters) {
+      const {issues, rules} = await logFactory.loadSecureValuesPreprocessingRules(serverArgs.logFilters);
+      if (!_.isEmpty(issues)) {
+        throw new Error(`The log filtering rules config '${serverArgs.logFilters}' has issues: ` +
+        JSON.stringify(issues, null, 2));
+      }
+      if (_.isEmpty(rules)) {
+        logger.warn(`Found no log filtering rules in '${serverArgs.logFilters}'. Is that expected?`);
+      } else {
+        logger.info(`Loaded ${util.pluralize('filtering rule', rules.length, true)} from '${serverArgs.logFilters}'`);
+      }
+    }
+
+    const appiumDriver = new AppiumDriver(serverArgs);
+    // set the config on the umbrella driver so it can match drivers to caps
+    appiumDriver.driverConfig = driverConfig;
+    await preflightChecks(serverArgs, throwInsteadOfExit);
+
+    return /** @type {ServerInitResult} */({appiumDriver, parsedArgs: serverArgs, driverConfig, pluginConfig});
   }
+}
 
-  let appiumDriver = new AppiumDriver(args);
-  const driverConfig = new DriverConfig(args.appiumHome);
-  const pluginConfig = new PluginConfig(args.appiumHome);
-  appiumDriver.driverConfig = driverConfig;
-  await preflightChecks({parser, args, driverConfig, pluginConfig, throwInsteadOfExit});
-  await logStartupInfo(parser, args);
+/**
+ * Initializes Appium's config.  Starts server if appropriate and resolves the
+ * server instance if so; otherwise resolves w/ `undefined`.
+ * @template [T=WithServerSubcommand]
+ * @param {Args<T>} [args] - Arguments from CLI or otherwise
+ * @returns {Promise<import('@appium/types').AppiumServer|undefined>}
+ */
+async function main (args) {
+  const {appiumDriver, parsedArgs, pluginConfig, driverConfig} = /** @type {ServerInitResult} */(await init(args));
+
+  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(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);
 
-  // find any plugin name which has been installed, and which has been requested for activation by
-  // using the --plugins flag, and turn each one into an instantiated plugin object, 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
-  const plugins = Object.keys(pluginConfig.installedExtensions).filter((pluginName) =>
-    _.includes(args.plugins, pluginName) ||
-    (args.plugins.length === 1 && args.plugins[0] === USE_ALL_PLUGINS)
-  ).map((pluginName) => {
-    try {
-      const PluginClass = pluginConfig.require(pluginName);
-      return new PluginClass(pluginName);
-    } catch (err) {
-      logger.error(`Could not load plugin '${pluginName}', so it will not be available. Error ` +
-                   `in loading the plugin was: ${err}`);
-      return false;
-    }
-  }).filter(Boolean);
-  appiumDriver.plugins = plugins;
+  const driverClasses = getActiveDrivers(driverConfig, parsedArgs.useDrivers);
+  const serverUpdaters = getServerUpdaters(driverClasses, pluginClasses);
+  const extraMethodMap = getExtraMethodMap(driverClasses, pluginClasses);
 
-  let server = await baseServer({
+  const serverOpts = {
     routeConfiguringFunction,
-    port: args.port,
-    hostname: args.address,
-    allowCors: args.allowCors,
-    basePath: args.basePath,
-    plugins,
-  });
-  if (args.allowCors) {
+    port: parsedArgs.port,
+    hostname: parsedArgs.address,
+    allowCors: parsedArgs.allowCors,
+    basePath: parsedArgs.basePath,
+    serverUpdaters,
+    extraMethodMap,
+  };
+  if (parsedArgs.keepAliveTimeout) {
+    serverOpts.keepAliveTimeout = parsedArgs.keepAliveTimeout * 1000;
+  }
+  let server;
+  try {
+    server = await baseServer(serverOpts);
+  } catch (err) {
+    logger.error(`Could not configure Appium server. It's possible that a driver or plugin tried ` +
+                 `to update the server and failed. Original error: ${err.message}`);
+    logger.debug(err.stack);
+    return process.exit(1);
+  }
+
+  if (parsedArgs.allowCors) {
     logger.warn('You have enabled CORS requests from any host. Be careful not ' +
                 'to visit sites which could maliciously try to start Appium ' +
                 'sessions on your machine');
   }
   appiumDriver.server = server;
   try {
-    // TODO prelaunch if args.launch is set
-    // TODO: startAlertSocket(server, appiumServer);
-
     // configure as node on grid, if necessary
-    if (args.nodeconfig !== null) {
-      await registerNode(args.nodeconfig, args.address, args.port, args.basePath);
+    // falsy values should not cause this to run
+    if (parsedArgs.nodeconfig) {
+      await registerNode(parsedArgs.nodeconfig, parsedArgs.address, parsedArgs.port, parsedArgs.basePath);
     }
   } catch (err) {
     await server.close();
@@ -202,15 +327,55 @@ async function main (args = null) {
     });
   }
 
-  logServerPort(args.address, args.port);
+  logServerPort(parsedArgs.address, parsedArgs.port);
   driverConfig.print();
-  pluginConfig.print(plugins);
+  pluginConfig.print(pluginClasses.map((p) => p.pluginName));
 
   return server;
 }
 
+// NOTE: this is here for backwards compat for any scripts referencing `main.js` directly
+// (more specifically, `build/lib/main.js`)
+// the executable is now `../index.js`, so that module will typically be `require.main`.
 if (require.main === module) {
   asyncify(main);
 }
 
-export { main };
+// everything below here is intended to be a public API.
+export { readConfigFile } from './config-file';
+export { finalizeSchema, getSchema, validate } from './schema/schema';
+export { main, init, resolveAppiumHome };
+
+/**
+ * @typedef {import('../types').DriverType} DriverType
+ * @typedef {import('../types').PluginType} PluginType
+ * @typedef {import('../types').DriverClass} DriverClass
+ * @typedef {import('../types').PluginClass} PluginClass
+ * @typedef {import('../types').WithServerSubcommand} WithServerSubcommand
+ */
+
+/**
+ * Literally an empty object
+ * @typedef { {} } ExtCommandInitResult
+ */
+
+/**
+ * @typedef ServerInitData
+ * @property {AppiumDriver} appiumDriver - The Appium driver
+ * @property {import('../types').ParsedArgs} parsedArgs - The parsed arguments
+ */
+
+/**
+ * @typedef {ServerInitData & import('./extension').ExtensionConfigs} ServerInitResult
+ */
+
+/**
+ * @template [T=WithServerSubcommand]
+ * @typedef {import('../types').Args<T>} Args
+ */
+
+/**
+ * @template [T=WithServerSubcommand]
+ * @typedef {import('../types').ParsedArgs<T>} ParsedArgs
+ */
+

package/lib/schema/arg-spec.js

@@ -0,0 +1,232 @@
+import _ from 'lodash';
+
+/**
+ * The original ID of the Appium config schema.
+ * We use this in the CLI to convert it to `argparse` options.
+ */
+export const APPIUM_CONFIG_SCHEMA_ID = 'appium.json';
+
+/**
+ * The schema prop containing server-related options. Everything in here
+ * is "native" to Appium.
+ * Used by {@link flattenSchema} for transforming the schema into CLI args.
+ */
+export const SERVER_PROP_NAME = 'server';
+
+/**
+ * Used to parse extension info from a schema ID.
+ */
+const SCHEMA_ID_REGEXP = /^(?<extType>.+?)-(?<normalizedExtName>.+)\.json$/;
+
+/**
+ * Avoid typos by using constants!
+ */
+const PROPERTIES = 'properties';
+
+/**
+ * An `ArgSpec` is a class representing metadata about an argument (or config
+ * option) used for cross-referencing.
+ *
+ * This class has no instance methods, and is basically just a read-only "struct".
+ * @template D
+ */
+export class ArgSpec {
+  /**
+   * The canonical name of the argument. Corresponds to key in schema's `properties` prop.
+   * @type {string}
+   */
+  name;
+
+  /**
+   * The `ExtensionType` of the argument. This will be set if the arg came from an extension;
+   * otherwise it will be `undefined`.
+   * @type {ExtensionType|undefined}
+   */
+  extType;
+
+  /**
+   * The name of the extension, if this argument came from an extension.
+   *
+   * Otherwise `undefined`.
+   * @type {string|undefined}
+   */
+  extName;
+
+  /**
+   * The schema ID (`$id`) for the argument.  This is automatically determined, and any user-provided `$id`s will be overwritten.
+   *
+   * @type {string}
+   */
+  ref;
+
+  /**
+   * The CLI argument, sans leading dashes.
+   * @type {string}
+   */
+  arg;
+
+  /**
+   * The desired keypath for the argument after arguments have been parsed.
+   *
+   * Typically this is camelCased.  If the arg came from an extension, it will be prefixed with
+   * `<extType>.<extName>.`
+   * @type {string}
+   */
+  dest;
+
+  /**
+   * The same as {@link ArgSpec.dest} but without the leading `<extType>.<extName>.` prefix.
+   */
+  rawDest;
+
+  /**
+   * Whatever the default value of this argument is, as specified by the
+   * `default` property of the schema.
+   * @type {D|undefined}
+   */
+  defaultValue;
+
+  /**
+   * Builds some computed fields and assigns them to the instance.
+   *
+   * Undefined properties are not assigned.
+   *
+   * The _constructor_ is private. Use {@link ArgSpec.create} instead.
+   * @private
+   * @param {string} name
+   * @param {ArgSpecOptions<D>} [opts]
+   */
+  constructor (name, {extType, extName, dest, defaultValue} = {}) {
+    // we must normalize the extension name to fit into our convention for CLI
+    // args.
+    const arg = ArgSpec.toArg(name, extType, extName);
+
+    const ref = ArgSpec.toSchemaRef(name, extType, extName);
+
+    // if no explicit `dest` provided, just camelCase the name to avoid needing
+    // to use bracket syntax when accessing props on the parsed args object.
+    const rawDest = _.camelCase(dest ?? name);
+
+    const destKeypath =
+      extType && extName ? [extType, extName, rawDest].join('.') : rawDest;
+
+    this.defaultValue = defaultValue;
+    this.name = name;
+    this.extType = extType;
+    this.extName = extName;
+    this.arg = arg;
+    this.dest = destKeypath;
+    this.ref = ref;
+    this.rawDest = rawDest;
+  }
+
+  /**
+   * Return the schema ID (`$id`) for the **argument** given the parameters.
+   *
+   * If you need the "root" or "base" schema ID, use {@link ArgSpec.toSchemaBaseRef} instead.
+   * @param {string} name - Argument name
+   * @param {ExtensionType} [extType] - Extension type
+   * @param {string} [extName] - Extension name
+   * @returns {string} Schema ID
+   */
+  static toSchemaRef (name, extType, extName) {
+    const baseRef = ArgSpec.toSchemaBaseRef(extType, extName);
+    if (extType && extName) {
+      return [`${baseRef}#`, PROPERTIES, name].join('/');
+    }
+    return [`${baseRef}#`, PROPERTIES, SERVER_PROP_NAME, PROPERTIES, name].join('/');
+  }
+
+  /**
+   * Return the schema ID for an extension or the base schema ID.
+   * @param {ExtensionType} [extType] - Extension type
+   * @param {string} [extName] - Extension name
+   */
+  static toSchemaBaseRef (extType, extName) {
+    if (extType && extName) {
+      return `${extType}-${ArgSpec.toNormalizedExtName(extName)}.json`;
+    }
+    return APPIUM_CONFIG_SCHEMA_ID;
+  }
+
+  /**
+   * Return the unique ID for the argument given the parameters.
+   * @param {string} name - Argument name
+   * @param {ExtensionType} [extType] - Extension type
+   * @param {string} [extName] - Extension name
+   * @returns {string} Unique ID
+   */
+  static toArg (name, extType, extName) {
+    const properName = _.kebabCase(name.replace(/^--?/, ''));
+    if (extType && extName) {
+      return [extType, _.kebabCase(extName), properName].join('-');
+    }
+    return properName;
+  }
+
+  /**
+   * Normalizes a raw extension name (not including the type).
+   * @param {string} extName - Extension name
+   * @returns {string} Normalized extension name
+   */
+  static toNormalizedExtName (extName) {
+    return _.kebabCase(extName);
+  }
+
+  /**
+   * 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, normalizedExtName?: string} }
+   */
+  static extensionInfoFromRootSchemaId (schemaId) {
+    const matches = schemaId.match(SCHEMA_ID_REGEXP);
+    if (matches?.groups) {
+      const {extType, normalizedExtName} =
+        /** @type { {extType: ExtensionType, normalizedExtName: string} } */ (
+          matches.groups
+        );
+      return {extType, normalizedExtName};
+    }
+    return {};
+  }
+
+  /**
+   * Creates an `ArgSpec`
+   *
+   * @param {string} name - The canonical name of the argument. Corresponds to a key in a schema's
+   * `properties` property.
+   * @template D
+   * @param {ArgSpecOptions<D>} [opts] - Options
+   * @returns {Readonly<ArgSpec>}
+   */
+  static create (name, opts) {
+    return Object.freeze(new ArgSpec(name, opts));
+  }
+
+  /**
+   * String representation, useful for debugging
+   * @returns {string}
+   */
+  /* istanbul ignore next */
+  toString () {
+    let str = `[ArgSpec] ${this.name} (${this.ref})`;
+    if (this.extType && this.extName) {
+      str += ` (ext: ${this.extType}/${this.extName})`;
+    }
+    return str;
+  }
+}
+
+/**
+ * Options for {@link ArgSpec.create}
+ * @template D
+ * @typedef ArgSpecOptions
+ * @property {string} [extName]
+ * @property {ExtensionType} [extType]
+ * @property {string} [dest]
+ * @property {D} [defaultValue]
+ */
+
+/**
+ * @typedef {import('../extension/manifest').ExtensionType} ExtensionType
+ */