appium 2.0.0-beta.18 → 2.0.0-beta.21

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';
-import { asyncify } from 'asyncbox';
-import { default as getParser, getDefaultServerArgs } from './cli/parser';
-import { USE_ALL_PLUGINS } from './cli/args';
+// @ts-ignore
+import { routeConfiguringFunction as makeRouter, server as baseServer } from '@appium/base-driver';
 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 { 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, 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);
   }
@@ -96,25 +99,26 @@ function logServerPort (address, port) {
  * wrap command execution
  *
  * @param {Object} args - argparser parsed dict
- * @param {PluginConfig} pluginConfig - a plugin extension config
+ * @param {import('./plugin-config').default} pluginConfig - a plugin extension config
+ * @returns {({pluginName: string} & ((...args: any[]) => unknown))[]}
  */
 function getActivePlugins (args, pluginConfig) {
-  return Object.keys(pluginConfig.installedExtensions).filter((pluginName) =>
-    _.includes(args.plugins, pluginName) ||
-    (args.plugins.length === 1 && args.plugins[0] === USE_ALL_PLUGINS)
+  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 = pluginConfig.require(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);
-      return false;
     }
-  }).filter(Boolean);
+  }));
 }
 
 /**
@@ -123,11 +127,11 @@ function getActivePlugins (args, pluginConfig) {
  * If the --drivers flag was given, this method only loads the given drivers.
  *
  * @param {Object} args - argparser parsed dict
- * @param {DriverConfig} driverConfig - a driver extension config
+ * @param {import('./driver-config').default} driverConfig - a driver extension config
  */
 function getActiveDrivers (args, driverConfig) {
-  return Object.keys(driverConfig.installedExtensions).filter((driverName) =>
-    _.includes(args.drivers, driverName) || args.drivers.length === 0
+  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}...`);
@@ -136,9 +140,8 @@ function getActiveDrivers (args, driverConfig) {
       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);
-      return false;
     }
-  }).filter(Boolean);
+  }));
 }
 
 function getServerUpdaters (driverClasses, pluginClasses) {
@@ -152,14 +155,25 @@ function getExtraMethodMap (driverClasses, pluginClasses) {
   );
 }
 
-async function main (args = null) {
-  let parser = getParser();
+/**
+ * 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
@@ -168,59 +182,106 @@ 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.parse_args();
+    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 appiumDriver = new AppiumDriver(parsedArgs);
   // set the config on the umbrella driver so it can match drivers to caps
   appiumDriver.driverConfig = driverConfig;
-  const pluginConfig = new PluginConfig(args.appiumHome);
-  await preflightChecks({parser, args, driverConfig, pluginConfig, throwInsteadOfExit});
-  const pluginClasses = getActivePlugins(args, pluginConfig);
+  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, args);
+
+  await logStartupInfo(parser, parsedArgs);
   let routeConfiguringFunction = makeRouter(appiumDriver);
 
-  const driverClasses = getActiveDrivers(args, driverConfig);
+  const driverClasses = getActiveDrivers(parsedArgs, driverConfig);
   const serverUpdaters = getServerUpdaters(driverClasses, pluginClasses);
   const extraMethodMap = getExtraMethodMap(driverClasses, pluginClasses);
 
   const serverOpts = {
     routeConfiguringFunction,
-    port: args.port,
-    hostname: args.address,
-    allowCors: args.allowCors,
-    basePath: args.basePath,
+    port: parsedArgs.port,
+    hostname: parsedArgs.address,
+    allowCors: parsedArgs.allowCors,
+    basePath: parsedArgs.basePath,
     serverUpdaters,
     extraMethodMap,
   };
-  if (args.keepAliveTimeout) {
-    serverOpts.keepAliveTimeout = args.keepAliveTimeout * 1000;
+  if (parsedArgs.keepAliveTimeout) {
+    serverOpts.keepAliveTimeout = parsedArgs.keepAliveTimeout * 1000;
   }
   let server;
   try {
@@ -232,16 +293,18 @@ async function main (args = null) {
     return process.exit(1);
   }
 
-  if (args.allowCors) {
+  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 {
     // 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();
@@ -265,7 +328,7 @@ async function main (args = null) {
     });
   }
 
-  logServerPort(args.address, args.port);
+  logServerPort(parsedArgs.address, parsedArgs.port);
   driverConfig.print();
   pluginConfig.print(pluginClasses.map((p) => p.pluginName));
 
@@ -276,4 +339,12 @@ 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,12 +1,42 @@
 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}`;
   }

package/lib/schema/appium-config-schema.js

@@ -0,0 +1,286 @@
+// @ts-check
+
+const schema = /** @type {const} */ ({
+  $schema: 'http://json-schema.org/draft-07/schema',
+  additionalProperties: false,
+  description: 'A schema for Appium configuration files',
+  properties: {
+    server: {
+      additionalProperties: false,
+      description: 'Configuration when running Appium as a server',
+      properties: {
+        address: {
+          $comment:
+            'I think hostname covers both DNS and IPv4...could be wrong',
+          appiumCliAliases: ['a'],
+          default: '0.0.0.0',
+          description: 'IP address to listen on',
+          format: 'hostname',
+          title: 'address config',
+          type: 'string',
+        },
+        'allow-cors': {
+          description:
+            'Whether the Appium server should allow web browser connections from any host',
+          title: 'allow-cors config',
+          type: 'boolean',
+          default: false,
+        },
+        'allow-insecure': {
+          appiumCliTransformer: 'csv',
+          default: [],
+          description:
+            'Set which insecure features are allowed to run in this server\'s sessions. Features are defined on a driver level; see documentation for more details. Note that features defined via "deny-insecure" will be disabled, even if also listed here. If string, a path to a text file containing policy or a comma-delimited list.',
+          items: {
+            type: 'string',
+          },
+          title: 'allow-insecure config',
+          type: 'array',
+          uniqueItems: true,
+        },
+        'base-path': {
+          appiumCliAliases: ['pa'],
+          default: '',
+          description:
+            'Base path to use as the prefix for all webdriver routes running on the server',
+          title: 'base-path config',
+          type: 'string',
+        },
+        'callback-address': {
+          appiumCliAliases: ['ca'],
+          description: 'Callback IP address (default: same as "address")',
+          title: 'callback-address config',
+          type: 'string',
+        },
+        'callback-port': {
+          appiumCliAliases: ['cp'],
+          default: 4723,
+          description: 'Callback port (default: same as "port")',
+          maximum: 65535,
+          minimum: 1,
+          title: 'callback-port config',
+          type: 'integer',
+        },
+        'debug-log-spacing': {
+          default: false,
+          description:
+            'Add exaggerated spacing in logs to help with visual inspection',
+          title: 'debug-log-spacing config',
+          type: 'boolean',
+        },
+        'default-capabilities': {
+          $comment: 'TODO',
+          appiumCliAliases: ['dc'],
+          description:
+            'Set the default desired capabilities, which will be set on each session unless overridden by received capabilities. If a string, a path to a JSON file containing the capabilities, or raw JSON.',
+          title: 'default-capabilities config',
+          type: 'object',
+        },
+        'deny-insecure': {
+          $comment: 'Allowed values are defined by drivers',
+          appiumCliTransformer: 'csv',
+          default: [],
+          description:
+            'Set which insecure features are not allowed to run in this server\'s sessions. Features are defined on a driver level; see documentation for more details. Features listed here will not be enabled even if also listed in "allow-insecure", and even if "relaxed-security" is enabled. If string, a path to a text file containing policy or a comma-delimited list.',
+          items: {
+            type: 'string',
+          },
+          title: 'deny-insecure config',
+          type: 'array',
+          uniqueItems: true,
+        },
+        driver: {
+          description:
+            'Driver-specific configuration. Keys should correspond to driver package names',
+          properties: {},
+          title: 'driver config',
+          type: 'object',
+        },
+        'keep-alive-timeout': {
+          appiumCliAliases: ['ka'],
+          default: 600,
+          description:
+            'Number of seconds the Appium server should apply as both the keep-alive timeout and the connection timeout for all requests. A value of 0 disables the timeout.',
+          minimum: 0,
+          title: 'keep-alive-timeout config',
+          type: 'integer',
+        },
+        'local-timezone': {
+          default: false,
+          description: 'Use local timezone for timestamps',
+          title: 'local-timezone config',
+          type: 'boolean',
+        },
+        log: {
+          appiumCliAliases: ['g'],
+          appiumCliDest: 'logFile',
+          description: 'Also send log output to this file',
+          title: 'log config',
+          type: 'string',
+        },
+        'log-filters': {
+          $comment: 'TODO',
+          description: 'One or more log filtering rules',
+          items: {
+            type: 'string',
+          },
+          title: 'log-filters config',
+          type: 'array',
+        },
+        'log-level': {
+          appiumCliDest: 'loglevel',
+          default: 'debug',
+          description: 'Log level (console[:file])',
+          enum: [
+            'info',
+            'info:debug',
+            'info:info',
+            'info:warn',
+            'info:error',
+            'warn',
+            'warn:debug',
+            'warn:info',
+            'warn:warn',
+            'warn:error',
+            'error',
+            'error:debug',
+            'error:info',
+            'error:warn',
+            'error:error',
+            'debug',
+            'debug:debug',
+            'debug:info',
+            'debug:warn',
+            'debug:error',
+          ],
+          title: 'log-level config',
+          type: 'string',
+        },
+        'log-no-colors': {
+          default: false,
+          description: 'Do not use color in console output',
+          title: 'log-no-colors config',
+          type: 'boolean',
+        },
+        'log-timestamp': {
+          default: false,
+          description: 'Show timestamps in console output',
+          title: 'log-timestamp config',
+          type: 'boolean',
+        },
+        'long-stacktrace': {
+          default: false,
+          description:
+            'Add long stack traces to log entries. Recommended for debugging only.',
+          title: 'long-stacktrace config',
+          type: 'boolean',
+        },
+        'no-perms-check': {
+          default: false,
+          description:
+            'Do not check that needed files are readable and/or writable',
+          title: 'no-perms-check config',
+          type: 'boolean',
+        },
+        nodeconfig: {
+          $comment:
+            'Selenium Grid 3 is unmaintained and Selenium Grid 4 no longer supports this file.',
+          description:
+            'Path to configuration JSON file to register Appium as a node with Selenium Grid 3; otherwise the configuration itself',
+          title: 'nodeconfig config',
+          type: 'object',
+        },
+        plugin: {
+          description:
+            'Plugin-specific configuration. Keys should correspond to plugin package names',
+          properties: {},
+          title: 'plugin config',
+          type: 'object',
+        },
+        port: {
+          appiumCliAliases: ['p'],
+          default: 4723,
+          description: 'Port to listen on',
+          maximum: 65535,
+          minimum: 1,
+          title: 'port config',
+          type: 'integer',
+        },
+        'relaxed-security': {
+          default: false,
+          description:
+            'Disable additional security checks, so it is possible to use some advanced features, provided by drivers supporting this option. Only enable it if all the clients are in the trusted network and it\'s not the case if a client could potentially break out of the session sandbox. Specific features can be overridden by using "deny-insecure"',
+          title: 'relaxed-security config',
+          type: 'boolean',
+        },
+        'session-override': {
+          default: false,
+          description: 'Enables session override (clobbering)',
+          title: 'session-override config',
+          type: 'boolean',
+        },
+        'strict-caps': {
+          default: false,
+          description:
+            'Cause sessions to fail if desired caps are sent in that Appium does not recognize as valid for the selected device',
+          title: 'strict-caps config',
+          type: 'boolean',
+        },
+        tmp: {
+          appiumCliDest: 'tmpDir',
+          description:
+            'Absolute path to directory Appium can use to manage temp files. Defaults to C:\\Windows\\Temp on Windows and /tmp otherwise.',
+          title: 'tmp config',
+          type: 'string',
+        },
+        'trace-dir': {
+          description:
+            'Absolute path to directory Appium can use to save iOS instrument traces; defaults to <tmp>/appium-instruments',
+          title: 'trace-dir config',
+          type: 'string',
+        },
+        'use-drivers': {
+          appiumCliDescription:
+            'A list of drivers to activate. Can be a comma-delimited string or path to CSV file. By default, all installed drivers will be activated.',
+          default: [],
+          description:
+            'A list of drivers to activate. By default, all installed drivers will be activated.',
+          items: {
+            type: 'string',
+          },
+          title: 'use-drivers config',
+          type: 'array',
+          uniqueItems: true,
+        },
+        'use-plugins': {
+          appiumCliDescription:
+            'A list of plugins to activate. Can be a comma-delimited string, path to CSV file, or the string "all" to use all installed plugins.',
+          default: [],
+          description:
+            'A list of plugins to activate. To activate all plugins, the value should be an array with a single item "all".',
+          items: {
+            type: 'string',
+          },
+          title: 'use-plugins config',
+          type: 'array',
+          uniqueItems: true,
+        },
+        webhook: {
+          $comment:
+            'This should probably use a uri-template format to restrict the protocol to http/https',
+          appiumCliAliases: ['G'],
+          description: 'Also send log output to this http listener',
+          format: 'uri',
+          title: 'webhook config',
+          type: 'string',
+        },
+      },
+      title: 'server config',
+      type: 'object',
+    },
+  },
+  title: 'Appium Configuration',
+  type: 'object',
+});
+
+export default schema;