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

package/lib/main.js

@@ -1,29 +1,32 @@
 #!/usr/bin/env node
+
 // transpile:main
+// @ts-check
 
-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';
+// @ts-ignore
+import { routeConfiguringFunction as makeRouter, server as baseServer } from '@appium/base-driver';
+import { logger as logFactory, util } 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 { 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, showConfig, validateTmpDir, warnNodeDeprecations } from './config';
+import { readConfigFile } from './config-file';
+import { DRIVER_TYPE, PLUGIN_TYPE } from './extension-config';
 import registerNode from './grid-register';
+import logger from './logger'; // logger needs to remain first of imports
+import { init as logsinkInit } from './logsink';
+import { getDefaultsFromSchema, validate } from './schema/schema';
 import { inspectObject } from './utils';
 
-
-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) {
@@ -34,9 +37,9 @@ async function preflightChecks ({parser, args, driverConfig, pluginConfig, throw
       process.exit(0);
     }
     warnNodeDeprecations();
-    validateServerArgs(parser, args);
-    await driverConfig.read();
-    await pluginConfig.read();
+
+    validate(args);
+
     if (args.tmpDir) {
       await validateTmpDir(args.tmpDir);
     }
@@ -69,7 +72,7 @@ async function logStartupInfo (parser, args) {
   }
   logger.info(welcome);
 
-  let showArgs = getNonDefaultArgs(parser, args);
+  let showArgs = getNonDefaultServerArgs(parser, args);
   if (_.size(showArgs)) {
     logNonDefaultArgsWarning(showArgs);
   }
@@ -89,14 +92,88 @@ function logServerPort (address, port) {
   logger.info(logMessage);
 }
 
-async function main (args = null) {
-  let parser = getParser();
+/**
+ * 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 {({pluginName: string} & ((...args: any[]) => unknown))[]}
+ */
+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 {{pluginName: string} & ((...args: any[]) => unknown)} */(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);
+    }
+  }));
+}
+
+function getServerUpdaters (driverClasses, pluginClasses) {
+  return [...driverClasses, ...pluginClasses].map((klass) => klass.updateServer).filter(Boolean);
+}
+
+function getExtraMethodMap (driverClasses, pluginClasses) {
+  return [...driverClasses, ...pluginClasses].reduce(
+    (map, klass) => ({...map, ...klass.newMethodMap}),
+    {}
+  );
+}
+
+/**
+ * Initializes Appium, but does not start the server.
+ *
+ * Use this to get at the configuration schema.
+ *
+ * @example
+ * import {init, getSchema} from 'appium';
+ * const options = {}; // config object
+ * await init(options);
+ * const schema = getSchema(); // entire config schema including plugins and drivers
+ * @param {ParsedArgs} [args] - Parsed args
+ * @returns {Promise<{parser: import('./cli/parser').ArgParser} & Partial<{appiumDriver: AppiumDriver, parsedArgs: ParsedArgs}>>}
+ */
+async function init (args) {
+  const parser = await getParser();
   let throwInsteadOfExit = false;
+  /** @type {ParsedArgs} */
+  let parsedArgs;
   if (args) {
-    // a containing package passed in their own args, let's fill them out
-    // with defaults
-    args = Object.assign({}, getDefaultServerArgs(), 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 +182,129 @@ async function main (args = null) {
       // but remove it since it's not a real server arg per se
       delete args.throwInsteadOfExit;
     }
+    parsedArgs = {...args, subcommand: args.subcommand ?? SERVER_SUBCOMMAND};
   } else {
     // otherwise parse from CLI
-    args = parser.parseArgs();
+    parsedArgs = parser.parseArgs();
+  }
+
+  const configResult = await readConfigFile(parsedArgs.configFile);
+
+  if (!_.isEmpty(configResult.errors)) {
+    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
+  // 2. config file
+  // 3. defaults from config file.
+  if (parsedArgs.subcommand === SERVER_SUBCOMMAND) {
+    parsedArgs = _.defaultsDeep(
+      parsedArgs,
+      configResult.config?.server,
+      getDefaultsFromSchema()
+    );
   }
-  await logsinkInit(args);
+
+  parsedArgs = _.defaultsDeep(
+    parsedArgs,
+    configResult.config ?? {},
+  );
+
+  await logsinkInit(parsedArgs);
 
   // 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();
+  if (parsedArgs.subcommand === DRIVER_TYPE) {
+    await runExtensionCommand(parsedArgs, parsedArgs.subcommand, driverConfig);
+    return {parser};
+  }
+  if (parsedArgs.subcommand === PLUGIN_TYPE) {
+    await runExtensionCommand(parsedArgs, parsedArgs.subcommand, pluginConfig);
+    return {parser};
   }
 
-  if (args.logFilters) {
-    const {issues, rules} = await logFactory.loadSecureValuesPreprocessingRules(args.logFilters);
+  if (parsedArgs.logFilters) {
+    const {issues, rules} = await logFactory.loadSecureValuesPreprocessingRules(parsedArgs.logFilters);
     if (!_.isEmpty(issues)) {
-      throw new Error(`The log filtering rules config '${args.logFilters}' has issues: ` +
+      throw new Error(`The log filtering rules config '${parsedArgs.logFilters}' has issues: ` +
         JSON.stringify(issues, null, 2));
     }
     if (_.isEmpty(rules)) {
-      logger.warn(`Found no log filtering rules in '${args.logFilters}'. Is that expected?`);
+      logger.warn(`Found no log filtering rules in '${parsedArgs.logFilters}'. Is that expected?`);
     } else {
-      logger.info(`Loaded ${util.pluralize('filtering rule', rules.length, true)} from '${args.logFilters}'`);
+      logger.info(`Loaded ${util.pluralize('filtering rule', rules.length, true)} from '${parsedArgs.logFilters}'`);
     }
   }
 
-  let appiumDriver = new AppiumDriver(args);
-  const driverConfig = new DriverConfig(args.appiumHome);
-  const pluginConfig = new PluginConfig(args.appiumHome);
+  const appiumDriver = new AppiumDriver(parsedArgs);
+  // set the config on the umbrella driver so it can match drivers to caps
   appiumDriver.driverConfig = driverConfig;
-  await preflightChecks({parser, args, driverConfig, pluginConfig, throwInsteadOfExit});
-  await logStartupInfo(parser, args);
+  await preflightChecks(parsedArgs, throwInsteadOfExit);
+
+  return {parser, appiumDriver, parsedArgs};
+}
+
+/**
+ *
+ * @param {ParsedArgs} [args]
+ * @returns
+ */
+async function main (args) {
+  const {parser, appiumDriver, parsedArgs} = await init(args);
+
+  if (!appiumDriver || !parsedArgs) {
+    // 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);
+  // set the active plugins on the umbrella driver so it can use them for commands
+  appiumDriver.pluginClasses = pluginClasses;
+
+  await logStartupInfo(parser, 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(parsedArgs, driverConfig);
+  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');
   }
+  // @ts-ignore
   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);
+    // 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 +328,26 @@ 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 { main, init };
+export { APPIUM_HOME } from './extension-config';
+export { getSchema, validate, finalizeSchema } from './schema/schema';
+export { readConfigFile } from './config-file';
+
+/**
+ * @typedef {import('../types/types').ParsedArgs} ParsedArgs
+ */

package/lib/plugin-config.js

@@ -1,19 +1,48 @@
 import _ from 'lodash';
-import ExtensionConfig, { PLUGIN_TYPE } from './extension-config';
+import ExtensionConfig from './extension-config';
+import { PLUGIN_TYPE } from './ext-config-io';
 import log from './logger';
 
 export default class PluginConfig extends ExtensionConfig {
-  constructor (appiumHome, logFn = null) {
+
+  /**
+   * A mapping of `APPIUM_HOME` values to {@link PluginConfig} instances.
+   * Each `APPIUM_HOME` should only have one associated `PluginConfig` instance.
+   * @type {Record<string,PluginConfig>}
+   * @private
+   */
+  static _instances = {};
+
+  /**
+   * Call {@link PluginConfig.getInstance} instead.
+   *
+   * Just calls the superclass' constructor with the correct extension type
+   * @private
+   * @param {string} appiumHome - `APPIUM_HOME` path
+   * @param {(...args: any[]) => void)} [logFn] - Optional logging function
+   */
+  constructor (appiumHome, logFn) {
     super(appiumHome, PLUGIN_TYPE, logFn);
   }
 
+  /**
+   * Creates or gets an instance of {@link PluginConfig} based value of `appiumHome`
+   * @param {string} appiumHome - `APPIUM_HOME` path
+   * @param {(...args: any[]) => void} [logFn] - Optional logging function
+   * @returns {PluginConfig}
+   */
+  static getInstance (appiumHome, logFn) {
+    const instance = PluginConfig._instances[appiumHome] ?? new PluginConfig(appiumHome, logFn);
+    PluginConfig._instances[appiumHome] = instance;
+    return instance;
+  }
+
   extensionDesc (pluginName, {version}) {
     return `${pluginName}@${version}`;
   }
 
-  print (activePlugins) {
+  print (activeNames) {
     const pluginNames = Object.keys(this.installedExtensions);
-    const activeNames = activePlugins.map((p) => p.name);
 
     if (_.isEmpty(pluginNames)) {
       log.info(`No plugins have been installed. Use the "appium plugin" ` +
@@ -27,8 +56,8 @@ export default class PluginConfig extends ExtensionConfig {
       log.info(`  - ${this.extensionDesc(pluginName, pluginData)}${activeTxt}`);
     }
 
-    if (_.isEmpty(activePlugins)) {
-      log.info('No plugins activated. Use the --plugins flag with names of plugins to activate');
+    if (_.isEmpty(activeNames)) {
+      log.info('No plugins activated. Use the --use-plugins flag with names of plugins to activate');
     }
   }
 }

package/lib/plugins.js

@@ -3,6 +3,7 @@
 // type 'appium plugin install 'name'', rather than having to specify the full
 // npm package. I.e., these are the officially recognized plugins.
 const KNOWN_PLUGINS = {
+  images: '@appium/images-plugin',
 };
 
 export {