appium 2.0.0-beta.20 → 2.0.0-beta.24

package/lib/cli/parser.js

@@ -146,7 +146,7 @@ class ArgParser {
     return _.reduce(
       args,
       (unpacked, value, key) => {
-        if (hasArgSpec(key)) {
+        if (!_.isUndefined(value) && hasArgSpec(key)) {
           const {dest} = /** @type {import('../schema/arg-spec').ArgSpec} */(getArgSpec(key));
           _.set(unpacked, dest, value);
         } else {
@@ -165,7 +165,10 @@ class ArgParser {
    */
   static _patchExit (parser) {
     parser.exit = (code, msg) => {
-      throw new Error(msg);
+      if (code) {
+        throw new Error(msg);
+      }
+      process.exit();
     };
   }
 

package/lib/config.js

@@ -1,3 +1,6 @@
+// @ts-check
+
+/* eslint-disable no-console */
 import _ from 'lodash';
 import { mkdirp, system, fs } from '@appium/support';
 import axios from 'axios';
@@ -5,11 +8,8 @@ import { exec } from 'teen_process';
 import { rootDir } from './utils';
 import logger from './logger';
 import semver from 'semver';
-import {
-  StoreDeprecatedDefaultCapabilityAction, DEFAULT_CAPS_ARG,
-} from './cli/argparse-actions';
 import findUp from 'find-up';
-import { getDefaultsFromSchema } from './schema/schema';
+import { getDefaultsForSchema } from './schema/schema';
 
 const npmPackage = fs.readPackageJsonFrom(__dirname);
 
@@ -25,12 +25,7 @@ const BUILD_INFO = {
 };
 
 function getNodeVersion () {
-  return semver.coerce(process.version);
-}
-
-function isSubClass (candidateClass, superClass) {
-  return _.isFunction(superClass) && _.isFunction(candidateClass)
-    && (candidateClass.prototype instanceof superClass || candidateClass === superClass);
+  return /** @type {import('semver').SemVer} */(semver.coerce(process.version));
 }
 
 async function updateBuildInfo (useGithubApiFallback = false) {
@@ -50,7 +45,7 @@ async function updateBuildInfo (useGithubApiFallback = false) {
  *
  * This is needed because Appium cannot assume `package.json` and `.git` are in the same
  * directory.  Monorepos, see?
- * @returns {string|void} Path to dir or `undefined` if not found
+ * @returns {Promise<string|undefined>} Path to dir or `undefined` if not found
  */
 async function findGitRoot () {
   return await findUp(GIT_META_ROOT, {cwd: rootDir, type: 'directory'});
@@ -88,6 +83,11 @@ async function getGitRev (useGithubApiFallback = false) {
   return null;
 }
 
+/**
+ * @param {string} commitSha
+ * @param {boolean} [useGithubApiFallback]
+ * @returns {Promise<number?>}
+ */
 async function getGitTimestamp (commitSha, useGithubApiFallback = false) {
   const gitRoot = await findGitRoot();
   if (gitRoot) {
@@ -152,37 +152,30 @@ function warnNodeDeprecations () {
   // }
 }
 
-async function showConfig () {
+async function showBuildInfo () {
   await updateBuildInfo(true);
   console.log(JSON.stringify(getBuildInfo())); // eslint-disable-line no-console
 }
 
-function getNonDefaultServerArgs (parser, args) {
+/**
+ * Returns k/v pairs of server arguments which are _not_ the defaults.
+ * @param {ParsedArgs} args
+ * @returns {Partial<ParsedArgs>}
+ */
+function getNonDefaultServerArgs (args) {
   // hopefully these function names are descriptive enough
 
-  function typesDiffer (dest) {
-    return typeof args[dest] !== typeof defaultsFromSchema[dest];
-  }
+  const typesDiffer = /** @param {string} dest */(dest) => typeof args[dest] !== typeof defaultsFromSchema[dest];
 
-  function defaultValueIsArray (dest) {
-    return _.isArray(defaultsFromSchema[dest]);
-  }
+  const defaultValueIsArray = /** @param {string} dest */(dest) => _.isArray(defaultsFromSchema[dest]);
 
-  function argsValueIsArray (dest) {
-    return _.isArray(args[dest]);
-  }
+  const argsValueIsArray = /** @param {string} dest */(dest) => _.isArray(args[dest]);
 
-  function arraysDiffer (dest) {
-    return _.difference(args[dest], defaultsFromSchema[dest]).length > 0;
-  }
+  const arraysDiffer = /** @param {string} dest */(dest) => _.gt(_.size(_.difference(args[dest], defaultsFromSchema[dest])), 0);
 
-  function valuesUnequal (dest) {
-    return args[dest] !== defaultsFromSchema[dest];
-  }
+  const valuesDiffer = /** @param {string} dest */(dest) => args[dest] !== defaultsFromSchema[dest];
 
-  function defaultIsDefined (dest) {
-    return !_.isUndefined(defaultsFromSchema[dest]);
-  }
+  const defaultIsDefined = /** @param {string} dest */(dest) => !_.isUndefined(defaultsFromSchema[dest]);
 
   // note that `_.overEvery` is like an "AND", and `_.overSome` is like an "OR"
 
@@ -191,8 +184,8 @@ function getNonDefaultServerArgs (parser, args) {
     arraysDiffer
   ]);
 
-  const defaultValueNotArrayAndValuesUnequal = _.overEvery([
-    _.negate(defaultValueIsArray), valuesUnequal
+  const defaultValueNotArrayAndValuesDiffer = _.overEvery([
+    _.negate(defaultValueIsArray), valuesDiffer
   ]);
 
   /**
@@ -205,8 +198,7 @@ function getNonDefaultServerArgs (parser, args) {
    * - if so, and the default is an array:
    *   - ensures the args value is an array
    *   - ensures the args values do not differ from the default values
-   * @param {string} dest - argument name (`dest` value)
-   * @returns {boolean}
+   * @type {(dest: string) => boolean}
    */
   const isNotDefault = _.overEvery([
     defaultIsDefined,
@@ -216,32 +208,55 @@ function getNonDefaultServerArgs (parser, args) {
         defaultValueIsArray,
         argValueNotArrayOrArraysDiffer
       ]),
-      defaultValueNotArrayAndValuesUnequal
+      defaultValueNotArrayAndValuesDiffer
     ])
   ]);
 
-  const defaultsFromSchema = getDefaultsFromSchema();
+  const defaultsFromSchema = getDefaultsForSchema();
 
   return _.pickBy(args, (__, key) => isNotDefault(key));
 }
 
-function getDeprecatedArgs (parser, args) {
-  // go through the server command line arguments and figure
-  // out which of the ones used are deprecated
-  return parser.rawArgs.reduce((acc, [[name], {dest, default: defaultValue, action}]) => {
-    if (!args[dest] || args[dest] === defaultValue) {
-      return acc;
-    }
+/**
+ * Compacts an object for {@link showConfig}:
+ * 1. Removes `subcommand` key/value
+ * 2. Removes `undefined` values
+ * 3. Removes empty objects (but not `false` values)
+ * Does not operate recursively.
+ */
+const compactConfig = _.partial(
+  _.omitBy,
+  _,
+  (value, key) => key === 'subcommand' || _.isUndefined(value) || (_.isObject(value) && _.isEmpty(value))
+);
 
-    if (action?.deprecated_for) {
-      acc[name] = action.deprecated_for;
-    } else if (isSubClass(action, StoreDeprecatedDefaultCapabilityAction)) {
-      acc[name] = DEFAULT_CAPS_ARG;
-    }
-    return acc;
-  }, {});
+/**
+ * Shows a breakdown of the current config after CLI params, config file loaded & defaults applied.
+ *
+ * The actual shape of `preConfigParsedArgs` and `defaults` does not matter for the purposes of this function,
+ * but it's intended to be called with values of type {@link ParsedArgs} and `DefaultValues<true>`, respectively.
+ *
+ * @param {object} preConfigParsedArgs - Parsed CLI args (or param to `init()`) before config & defaults applied
+ * @param {import('./config-file').ReadConfigFileResult} configResult - Result of attempting to load a config file
+ * @param {object} defaults - Configuration defaults from schemas
+ */
+function showConfig (preConfigParsedArgs, configResult, defaults) {
+  console.log('Appium Configuration\n');
+  if (configResult.config) {
+    console.log(`via config file at ${configResult.filepath}:\n`);
+    console.dir(compactConfig(configResult.config));
+  } else {
+    console.log(`(no configuration file loaded)\n`);
+  }
+  console.log('via CLI or function call:\n');
+  console.dir(compactConfig(preConfigParsedArgs));
+  console.log('\nvia defaults:\n');
+  console.dir(compactConfig(defaults));
 }
 
+/**
+ * @param {string} tmpDir
+ */
 async function validateTmpDir (tmpDir) {
   try {
     await mkdirp(tmpDir);
@@ -252,8 +267,11 @@ async function validateTmpDir (tmpDir) {
 }
 
 export {
-  getBuildInfo, checkNodeOk, showConfig,
+  getBuildInfo, checkNodeOk, showBuildInfo,
   warnNodeDeprecations, validateTmpDir, getNonDefaultServerArgs,
-  getGitRev, APPIUM_VER, updateBuildInfo,
-  getDeprecatedArgs
+  getGitRev, APPIUM_VER, updateBuildInfo, showConfig
 };
+
+/**
+ * @typedef {import('../types/types').ParsedArgs} ParsedArgs
+ */

package/lib/extension-config.js

@@ -270,7 +270,7 @@ export default class ExtensionConfig {
   /**
    * Loads extension and returns its main class
    * @param {string} extName
-   * @returns {(...args: any[]) => object }
+   * @returns {import('type-fest').Class<unknown>}
    */
   require (extName) {
     const {mainClass} = this.installedExtensions[extName];

package/lib/main.js

@@ -3,6 +3,7 @@
 // transpile:main
 // @ts-check
 
+import logger from './logger'; // logger needs to remain first of imports
 // @ts-ignore
 import { routeConfiguringFunction as makeRouter, server as baseServer } from '@appium/base-driver';
 import { logger as logFactory, util } from '@appium/support';
@@ -12,14 +13,13 @@ 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 { APPIUM_VER, checkNodeOk, getGitRev, getNonDefaultServerArgs, showBuildInfo, validateTmpDir, warnNodeDeprecations, showConfig } 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';
+import { getDefaultsForSchema } from './schema/schema';
+import { inspect } from './utils';
 
 /**
  *
@@ -32,14 +32,12 @@ async function preflightChecks (args, throwInsteadOfExit = false) {
     if (args.longStacktrace) {
       require('longjohn').async_trace_limit = -1;
     }
-    if (args.showConfig) {
-      await showConfig();
+    if (args.showBuildInfo) {
+      await showBuildInfo();
       process.exit(0);
     }
     warnNodeDeprecations();
 
-    validate(args);
-
     if (args.tmpDir) {
       await validateTmpDir(args.tmpDir);
     }
@@ -53,18 +51,24 @@ async function preflightChecks (args, throwInsteadOfExit = false) {
   }
 }
 
+/**
+ * @param {Partial<ParsedArgs>} 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);
+  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) {
@@ -72,7 +76,7 @@ async function logStartupInfo (parser, args) {
   }
   logger.info(welcome);
 
-  let showArgs = getNonDefaultServerArgs(parser, args);
+  let showArgs = getNonDefaultServerArgs(args);
   if (_.size(showArgs)) {
     logNonDefaultArgsWarning(showArgs);
   }
@@ -86,6 +90,12 @@ 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}`;
@@ -94,13 +104,13 @@ function logServerPort (address, port) {
 
 /**
  * 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 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
+ * 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))[]}
+ * @returns {PluginExtensionClass[]}
  */
 function getActivePlugins (args, pluginConfig) {
   return _.compact(Object.keys(pluginConfig.installedExtensions).filter((pluginName) =>
@@ -109,7 +119,7 @@ function getActivePlugins (args, pluginConfig) {
   ).map((pluginName) => {
     try {
       logger.info(`Attempting to load plugin ${pluginName}...`);
-      const PluginClass = /** @type {{pluginName: string} & ((...args: any[]) => unknown)} */(pluginConfig.require(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;
@@ -144,10 +154,22 @@ function getActiveDrivers (args, driverConfig) {
   }));
 }
 
+/**
+ * Gets a list of `updateServer` functions from all extensions
+ * @param {DriverExtensionClass[]} driverClasses
+ * @param {PluginExtensionClass[]} pluginClasses
+ * @returns {StaticExtMembers['updateServer'][]}
+ */
 function getServerUpdaters (driverClasses, pluginClasses) {
-  return [...driverClasses, ...pluginClasses].map((klass) => klass.updateServer).filter(Boolean);
+  return _.compact(_.map([...driverClasses, ...pluginClasses], 'updateServer'));
 }
 
+/**
+ * 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}
+ */
 function getExtraMethodMap (driverClasses, pluginClasses) {
   return [...driverClasses, ...pluginClasses].reduce(
     (map, klass) => ({...map, ...klass.newMethodMap}),
@@ -160,19 +182,30 @@ 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.
+ *
+ * @param {ParsedArgs} [args] - Parsed args
+ * @returns {Promise<Partial<{appiumDriver: AppiumDriver, parsedArgs: ParsedArgs}>>}
  * @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 preConfigParsedArgs;
+  /** @type {typeof preConfigParsedArgs & import('type-fest').AsyncReturnType<readConfigFile>['config']} */
   let parsedArgs;
+  /**
+   * This is a definition (instead of declaration) because TS can't figure out
+   * the value will be defined when it's used.
+   * @type {ReturnType<getDefaultsForSchema>}
+   */
+  let defaults = {};
   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-
@@ -182,47 +215,52 @@ async function init (args) {
       // but remove it since it's not a real server arg per se
       delete args.throwInsteadOfExit;
     }
-    parsedArgs = {...args, subcommand: args.subcommand ?? SERVER_SUBCOMMAND};
+    preConfigParsedArgs = {...args, subcommand: args.subcommand ?? SERVER_SUBCOMMAND};
   } else {
     // otherwise parse from CLI
-    parsedArgs = parser.parseArgs();
+    preConfigParsedArgs = parser.parseArgs();
   }
 
-  const configResult = await readConfigFile(parsedArgs.configFile);
+  const configResult = await readConfigFile(preConfigParsedArgs.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) {
+  if (preConfigParsedArgs.subcommand === SERVER_SUBCOMMAND) {
+    defaults = getDefaultsForSchema(false);
+
+    if (preConfigParsedArgs.showConfig) {
+      showConfig(preConfigParsedArgs, configResult, defaults);
+      return {};
+    }
+
     parsedArgs = _.defaultsDeep(
-      parsedArgs,
+      preConfigParsedArgs,
       configResult.config?.server,
-      getDefaultsFromSchema()
+      defaults
     );
+  } else {
+    parsedArgs = preConfigParsedArgs;
   }
 
-  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 (parsedArgs.subcommand === DRIVER_TYPE) {
     await runExtensionCommand(parsedArgs, parsedArgs.subcommand, driverConfig);
-    return {parser};
+    return {};
   }
   if (parsedArgs.subcommand === PLUGIN_TYPE) {
     await runExtensionCommand(parsedArgs, parsedArgs.subcommand, pluginConfig);
-    return {parser};
+    return {};
   }
 
   if (parsedArgs.logFilters) {
@@ -243,16 +281,17 @@ async function init (args) {
   appiumDriver.driverConfig = driverConfig;
   await preflightChecks(parsedArgs, throwInsteadOfExit);
 
-  return {parser, appiumDriver, parsedArgs};
+  return {appiumDriver, parsedArgs};
 }
 
 /**
- *
- * @param {ParsedArgs} [args]
- * @returns
+ * 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>}
  */
 async function main (args) {
-  const {parser, appiumDriver, parsedArgs} = await init(args);
+  const {appiumDriver, parsedArgs} = await init(args);
 
   if (!appiumDriver || !parsedArgs) {
     // if this branch is taken, we've run a different subcommand, so there's nothing
@@ -264,7 +303,7 @@ async function main (args) {
   // set the active plugins on the umbrella driver so it can use them for commands
   appiumDriver.pluginClasses = pluginClasses;
 
-  await logStartupInfo(parser, parsedArgs);
+  await logStartupInfo(parsedArgs);
   let routeConfiguringFunction = makeRouter(appiumDriver);
 
   const driverClasses = getActiveDrivers(parsedArgs, driverConfig);
@@ -298,7 +337,6 @@ async function main (args) {
                 '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
@@ -335,6 +373,9 @@ async function main (args) {
   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);
 }
@@ -348,3 +389,15 @@ export { readConfigFile } from './config-file';
 /**
  * @typedef {import('../types/types').ParsedArgs} ParsedArgs
  */
+
+/**
+ * @typedef {import('./appium').PluginExtensionClass} PluginExtensionClass
+ */
+
+/**
+ * @typedef {import('./appium').DriverExtensionClass} DriverExtensionClass
+ */
+
+/**
+ * @typedef {import('./appium').StaticExtMembers} StaticExtMembers
+ */

package/lib/plugin-config.js

@@ -57,7 +57,7 @@ export default class PluginConfig extends ExtensionConfig {
     }
 
     if (_.isEmpty(activeNames)) {
-      log.info('No plugins activated. Use the --plugins flag with names of plugins to activate');
+      log.info('No plugins activated. Use the --use-plugins flag with names of plugins to activate');
     }
   }
 }

package/lib/plugins.js

@@ -4,6 +4,8 @@
 // npm package. I.e., these are the officially recognized plugins.
 const KNOWN_PLUGINS = {
   images: '@appium/images-plugin',
+  'execute-driver': '@appium/execute-driver-plugin',
+  'relaxed-caps': '@appium/relaxed-caps-plugin',
 };
 
 export {

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

@@ -212,6 +212,7 @@ const schema = /** @type {const} */ ({
             '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',
+          appiumCliDest: 'relaxedSecurityEnabled'
         },
         'session-override': {
           default: false,

package/lib/schema/arg-spec.js

@@ -73,6 +73,11 @@ export class ArgSpec {
    */
   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.
@@ -100,10 +105,10 @@ export class ArgSpec {
 
     // 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 baseDest = _.camelCase(dest ?? name);
+    const rawDest = _.camelCase(dest ?? name);
 
     const destKeypath =
-      extType && extName ? [extType, extName, baseDest].join('.') : baseDest;
+      extType && extName ? [extType, extName, rawDest].join('.') : rawDest;
 
     this.defaultValue = defaultValue;
     this.name = name;
@@ -112,6 +117,7 @@ export class ArgSpec {
     this.arg = arg;
     this.dest = destKeypath;
     this.ref = ref;
+    this.rawDest = rawDest;
   }
 
   /**
@@ -216,3 +222,7 @@ export class ArgSpec {
  * @property {string} [dest]
  * @property {D} [defaultValue]
  */
+
+/**
+ * @typedef {import('../ext-config-io').ExtensionType} ExtensionType
+ */