appium 2.0.0-beta.9 → 2.0.0-rc.1

package/lib/main.js

@@ -1,42 +1,65 @@
 #!/usr/bin/env node
-// transpile:main
 
-import { init as logsinkInit } from './logsink';
-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
+import {routeConfiguringFunction as makeRouter, server as baseServer} from '@appium/base-driver';
+import {logger as logFactory, util, env, fs} from '@appium/support';
+import {asyncify} from 'asyncbox';
 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';
-import { logger as logFactory, util } from 'appium-support';
+import {AppiumDriver} from './appium';
+import {runExtensionCommand} from './cli/extension';
+import {getParser} from './cli/parser';
 import {
-  showConfig, checkNodeOk, validateServerArgs,
-  warnNodeDeprecations, validateTmpDir, getNonDefaultArgs,
-  getGitRev, APPIUM_VER
+  APPIUM_VER,
+  checkNodeOk,
+  getGitRev,
+  getNonDefaultServerArgs,
+  showConfig,
+  showBuildInfo,
+  validateTmpDir,
+  warnNodeDeprecations,
+  checkNpmOk,
 } 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 { AppiumDriver } from './appium';
+import {readConfigFile} from './config-file';
+import {loadExtensions, getActivePlugins, getActiveDrivers} from './extension';
+import {SERVER_SUBCOMMAND, LONG_STACKTRACE_LIMIT} from './constants';
 import registerNode from './grid-register';
-import { inspectObject } from './utils';
+import {getDefaultsForSchema, validate} from './schema/schema';
+import {
+  inspect,
+  adjustNodePath,
+  isDriverCommandArgs,
+  isExtensionCommandArgs,
+  isPluginCommandArgs,
+  isServerCommandArgs,
+  fetchIpAddresses,
+  V4_BROADCAST_IP,
+  V6_BROADCAST_IP,
+} from './utils';
+import os from 'node:os';
 
+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();
+    await checkNpmOk();
     if (args.longStacktrace) {
-      require('longjohn').async_trace_limit = -1;
+      Error.stackTraceLimit = LONG_STACKTRACE_LIMIT;
     }
-    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 +73,29 @@ async function preflightChecks ({parser, args, driverConfig, pluginConfig, throw
   }
 }
 
-function logNonDefaultArgsWarning (args) {
+/**
+ * @param {Args} args
+ */
+function logNonDefaultArgsWarning(args) {
   logger.info('Non-default server args:');
-  inspectObject(args);
+  inspect(args);
 }
 
-function logDefaultCapabilitiesWarning (caps) {
-  logger.info('Default capabilities, which will be added to each request ' +
-              'unless overridden by desired capabilities:');
-  inspectObject(caps);
+/**
+ * @param {Args['defaultCapabilities']} caps
+ */
+function logDefaultCapabilitiesWarning(caps) {
+  logger.info(
+    'Default capabilities, which will be added to each request ' +
+      'unless overridden by desired capabilities:'
+  );
+  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 +103,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 +117,114 @@ async function logStartupInfo (parser, args) {
   // }
 }
 
-function logServerPort (address, port) {
-  let logMessage = `Appium REST http interface listener started on ` +
-                   `${address}:${port}`;
-  logger.info(logMessage);
+/**
+ * Gets a list of `updateServer` functions from all extensions
+ * @param {DriverNameMap} driverClasses
+ * @param {PluginNameMap} pluginClasses
+ * @returns {import('@appium/types').UpdateServerCallback[]}
+ */
+function getServerUpdaters(driverClasses, pluginClasses) {
+  return _.compact(_.map([...driverClasses.keys(), ...pluginClasses.keys()], 'updateServer'));
+}
+
+/**
+ * Makes a big `MethodMap` from all the little `MethodMap`s in the extensions
+ * @param {DriverNameMap} driverClasses
+ * @param {PluginNameMap} pluginClasses
+ * @returns {import('@appium/types').MethodMap<import('@appium/types').Driver>}
+ */
+function getExtraMethodMap(driverClasses, pluginClasses) {
+  return [...driverClasses.keys(), ...pluginClasses.keys()].reduce(
+    (map, klass) => ({
+      ...map,
+      ...(klass.newMethodMap ?? {}),
+    }),
+    {}
+  );
+}
+
+/**
+ * Prepares and validates appium home path folder
+ *
+ * @param {string} name The name of the appium home source (needed for error messages)
+ * @param {string} appiumHome The actual value to be verified
+ * @returns {Promise<string>} Same appiumHome value
+ * @throws {Error} If the validation has failed
+ */
+async function prepareAppiumHome(name, appiumHome) {
+  let stat;
+  try {
+    stat = await fs.stat(appiumHome);
+  } catch (e) {
+    let err = e;
+    if (e.code === 'ENOENT') {
+      try {
+        await fs.mkdir(appiumHome, {recursive: true});
+        return appiumHome;
+      } catch (e1) {
+        err = e1;
+      }
+    }
+    throw new Error(
+      `The path '${appiumHome}' provided in the ${name} must point ` +
+        `to a valid folder writeable for the current user account '${os.userInfo().username}'. ` +
+        `Original error: ${err.message}`
+    );
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(
+      `The path '${appiumHome}' provided in the ${name} must point to a valid folder`
+    );
+  }
+  try {
+    await fs.access(appiumHome, fs.constants.W_OK);
+  } catch (e) {
+    throw new Error(
+      `The folder path '${appiumHome}' provided in the ${name} must be ` +
+        `writeable for the current user account '${os.userInfo().username}. ` +
+        `Original error: ${e.message}`
+    );
+  }
+  return appiumHome;
 }
 
-async function main (args = null) {
-  let parser = getParser();
+/**
+ * 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 {CliCommand} [Cmd=ServerCommand]
+ * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @param {Args<Cmd, SubCmd>} [args] - Partial args (progammatic usage only)
+ * @returns {Promise<InitResult<Cmd>>}
+ * @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());
+  let appiumHomeSourceName = 'autodetected appium home path';
+  if (!_.isNil(args?.appiumHome)) {
+    appiumHomeSourceName = 'appiumHome config value';
+  } else if (process.env.APPIUM_HOME) {
+    appiumHomeSourceName = 'APPIUM_HOME environment variable';
+  }
+  await prepareAppiumHome(appiumHomeSourceName, appiumHome);
+
+  adjustNodePath();
+
+  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<Cmd, SubCmd>} */
+  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,84 +233,192 @@ 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.parse_args();
+    preConfigArgs = /** @type {Args<Cmd, SubCmd>} */ (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 (isServerCommandArgs(preConfigArgs)) {
+    const defaults = getDefaultsForSchema(false);
+
+    /** @type {ParsedArgs} */
+    const serverArgs = _.defaultsDeep({}, preConfigArgs, configResult.config?.server, defaults);
+
+    if (preConfigArgs.showConfig) {
+      showConfig(getNonDefaultServerArgs(preConfigArgs), configResult, defaults, serverArgs);
+      return /** @type {InitResult<Cmd>} */ ({});
+    }
+
+    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
+          }'`
+        );
+      }
     }
-    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}'`);
+
+    const appiumDriver = new AppiumDriver(
+      /** @type {import('@appium/types').DriverOpts<import('./appium').AppiumDriverConstraints>} */ (
+        serverArgs
+      )
+    );
+    // set the config on the umbrella driver so it can match drivers to caps
+    appiumDriver.driverConfig = driverConfig;
+    await preflightChecks(serverArgs, throwInsteadOfExit);
+
+    return /** @type {InitResult<Cmd>} */ ({
+      appiumDriver,
+      parsedArgs: serverArgs,
+      driverConfig,
+      pluginConfig,
+    });
+  } else {
+    if (isExtensionCommandArgs(preConfigArgs)) {
+      // if the user has requested the 'driver' CLI, don't run the normal server,
+      // but instead pass control to the driver CLI
+      if (isDriverCommandArgs(preConfigArgs)) {
+        await runExtensionCommand(preConfigArgs, driverConfig);
+      }
+      if (isPluginCommandArgs(preConfigArgs)) {
+        await runExtensionCommand(preConfigArgs, pluginConfig);
+      }
     }
+    return /** @type {InitResult<Cmd>} */ ({});
   }
+}
+
+/**
+ * Prints the actual server address and the list of URLs that
+ * could be used to connect to the current server.
+ * Properly replaces broadcast addresses in client URLs.
+ *
+ * @param {string} url The URL the server is listening on
+ */
+function logServerAddress(url) {
+  logger.info(`Appium REST http interface listener started on ${url}`);
+  const urlObj = new URL(url);
+  if (![V4_BROADCAST_IP, V6_BROADCAST_IP].includes(urlObj.hostname)) {
+    return;
+  }
+
+  const ips = fetchIpAddresses(urlObj.hostname === V4_BROADCAST_IP ? 4 : 6);
+  logger.info(
+    `You can provide the following ${util.pluralize('URL', ips.length, false)} ` +
+      `in your client code to connect to this server:\n` +
+      ips.map((x) => `\t${urlObj.href.replace(urlObj.hostname, x)}`).join('\n')
+  );
+}
+
+/**
+ * Initializes Appium's config.  Starts server if appropriate and resolves the
+ * server instance if so; otherwise resolves w/ `undefined`.
+ * @template {CliCommand} [Cmd=ServerCommand]
+ * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @param {Args<Cmd, SubCmd>} [args] - Arguments from CLI or otherwise
+ * @returns {Promise<Cmd extends ServerCommand ? import('@appium/types').AppiumServer : void>}
+ */
+async function main(args) {
+  const initResult = await init(args);
+
+  if (_.isEmpty(initResult)) {
+    // if this branch is taken, we've run a different subcommand, so there's nothing
+    // left to do here.
+    return /** @type {Cmd extends ServerCommand ? import('@appium/types').AppiumServer : void} */ (
+      undefined
+    );
+  }
+
+  const {appiumDriver, pluginConfig, driverConfig, parsedArgs} =
+    /** @type {InitResult<ServerCommand>} */ (initResult);
 
-  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);
+  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);
 
+  /** @type {import('@appium/base-driver').ServerOpts} */
   const serverOpts = {
     routeConfiguringFunction,
-    port: args.port,
-    hostname: args.address,
-    allowCors: args.allowCors,
-    basePath: args.basePath,
-    plugins,
+    port: parsedArgs.port,
+    hostname: parsedArgs.address,
+    allowCors: parsedArgs.allowCors,
+    basePath: parsedArgs.basePath,
+    serverUpdaters,
+    extraMethodMap,
+    cliArgs: parsedArgs,
   };
-  if (args.keepAliveTimeout) {
-    serverOpts.keepAliveTimeout = args.keepAliveTimeout * 1000;
+  if (parsedArgs.keepAliveTimeout) {
+    serverOpts.keepAliveTimeout = parsedArgs.keepAliveTimeout * 1000;
   }
-  let server = await baseServer(serverOpts);
-  if (args.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');
+  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();
@@ -190,7 +426,7 @@ async function main (args = null) {
   }
 
   for (const signal of ['SIGINT', 'SIGTERM']) {
-    process.once(signal, async function onSignal () {
+    process.once(signal, async function onSignal() {
       logger.info(`Received ${signal} - shutting down`);
       try {
         await appiumDriver.deleteAllSessions({
@@ -206,15 +442,67 @@ async function main (args = null) {
     });
   }
 
-  logServerPort(args.address, args.port);
+  logServerAddress(`http://${parsedArgs.address}:${parsedArgs.port}${parsedArgs.basePath}`);
+
   driverConfig.print();
-  pluginConfig.print(plugins);
+  pluginConfig.print([...pluginClasses.values()]);
 
-  return server;
+  return /** @type {Cmd extends ServerCommand ? import('@appium/types').AppiumServer : void} */ (
+    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('@appium/types').DriverType} DriverType
+ * @typedef {import('@appium/types').PluginType} PluginType
+ * @typedef {import('@appium/types').DriverClass} DriverClass
+ * @typedef {import('@appium/types').PluginClass} PluginClass
+ * @typedef {import('appium/types').CliCommand} CliCommand
+ * @typedef {import('appium/types').CliExtensionSubcommand} CliExtensionSubcommand
+ * @typedef {import('appium/types').CliExtensionCommand} CliExtensionCommand
+ * @typedef {import('appium/types').CliCommandServer} ServerCommand
+ * @typedef {import('appium/types').CliCommandDriver} DriverCommand
+ * @typedef {import('appium/types').CliCommandPlugin} PluginCommand
+ * @typedef {import('./extension').DriverNameMap} DriverNameMap
+ * @typedef {import('./extension').PluginNameMap} PluginNameMap
+ */
+
+/**
+ * Literally an empty object
+ * @typedef { {} } ExtCommandInitResult
+ */
+
+/**
+ * @typedef ServerInitData
+ * @property {import('./appium').AppiumDriver} appiumDriver - The Appium driver
+ * @property {import('appium/types').ParsedArgs} parsedArgs - The parsed arguments
+ */
+
+/**
+ * @template {CliCommand} Cmd
+ * @typedef {Cmd extends ServerCommand ? ServerInitData & import('./extension').ExtensionConfigs : ExtCommandInitResult} InitResult
+ */
+
+/**
+ * @template {CliCommand} [Cmd=ServerCommand]
+ * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @typedef {import('appium/types').Args<Cmd, SubCmd>} Args
+ */
+
+/**
+ * @template {CliCommand} [Cmd=ServerCommand]
+ * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @typedef {import('appium/types').ParsedArgs<Cmd, SubCmd>} ParsedArgs
+ */