appium 2.5.4 → 2.6.0

package/lib/cli/args.js

@@ -290,6 +290,16 @@ const serverArgsDisallowedInConfig = new Map([
       help: 'Show info about the Appium build and exit',
     },
   ],
+  [
+    ['--show-debug-info'],
+    {
+      dest: 'showDebugInfo',
+      action: 'store_const',
+      const: true,
+      required: false,
+      help: 'Show debug info about the current Appium deployment and exit',
+    },
+  ],
   [
     ['--show-config'],
     {

package/lib/cli/parser.js

@@ -11,11 +11,19 @@ import {
   EXT_SUBCOMMAND_UNINSTALL,
   EXT_SUBCOMMAND_UPDATE,
   PLUGIN_TYPE,
-  SERVER_SUBCOMMAND
+  SERVER_SUBCOMMAND,
+  SETUP_SUBCOMMAND
 } from '../constants';
 import {finalizeSchema, getArgSpec, hasArgSpec} from '../schema';
 import {rootDir} from '../config';
 import {getExtensionArgs, getServerArgs} from './args';
+import {
+  SUBCOMMAND_MOBILE,
+  SUBCOMMAND_DESKTOP,
+  SUBCOMMAND_BROWSER,
+  getPresetDrivers,
+  determinePlatformName
+} from './setup-command';
 
 export const EXTRA_ARGS = 'extraArgs';
 
@@ -24,7 +32,7 @@ export const EXTRA_ARGS = 'extraArgs';
  * will automatially inject the `server` subcommand.
  */
 const NON_SERVER_ARGS = Object.freeze(
-  new Set([DRIVER_TYPE, PLUGIN_TYPE, SERVER_SUBCOMMAND, '-h', '--help', '-v', '--version'])
+  new Set([SETUP_SUBCOMMAND, DRIVER_TYPE, PLUGIN_TYPE, SERVER_SUBCOMMAND, '-h', '--help', '-v', '--version'])
 );
 
 const version = fs.readPackageJsonFrom(rootDir).version;
@@ -76,6 +84,9 @@ class ArgParser {
 
     const subParsers = parser.add_subparsers({dest: 'subcommand'});
 
+    // add the 'setup' command
+    ArgParser._addSetupToParser(subParsers);
+
     // add the 'server' subcommand, and store the raw arguments on the parser
     // object as a way for other parts of the code to work with the arguments
     // conceptually rather than just through argparse
@@ -280,6 +291,45 @@ class ArgParser {
       }
     }
   }
+
+  /**
+   * Add subcommand and sub-sub commands for 'setup' subcommand.
+   * @param {import('argparse').SubParser} subParser
+   */
+  static _addSetupToParser(subParser) {
+    const setupParser = subParser.add_parser('setup', {
+      add_help: true,
+      help: `Select a preset of official drivers/plugins to install ` +
+        `compatible with '${determinePlatformName()}' host platform. ` +
+        `Existing drivers/plugins will remain. The default preset is 'mobile'.`,
+    });
+
+
+    ArgParser._patchExit(setupParser);
+    const extSubParsers = setupParser.add_subparsers({
+      dest: `setupCommand`,
+    });
+
+    const parserSpecs = [
+      {
+        command: SUBCOMMAND_MOBILE,
+        help: `The preset for mobile devices: ${_.join(getPresetDrivers(SUBCOMMAND_MOBILE), ',')}`
+      },
+      {
+        command: SUBCOMMAND_BROWSER,
+        help: `The preset for desktop browser drivers: ${_.join(getPresetDrivers(SUBCOMMAND_BROWSER), ',')}`
+      },
+      {
+        command: SUBCOMMAND_DESKTOP,
+        help: `The preset for desktop application drivers: ${_.join(getPresetDrivers(SUBCOMMAND_DESKTOP), ',')}`
+      },
+    ];
+
+    for (const {command, help} of parserSpecs) {
+      const parser = extSubParsers.add_parser(command, {help});
+      ArgParser._patchExit(parser);
+    }
+  }
 }
 
 /**

package/lib/cli/setup-command.js

@@ -0,0 +1,185 @@
+import _ from 'lodash';
+import {
+  DESKTOP_BROWSERS,
+  DESKTOP_DRIVERS,
+  MOBILE_DRIVERS
+} from '../constants';
+import {runExtensionCommand} from './extension';
+import { system } from '@appium/support';
+import log from '../logger';
+
+/**
+ * Subcommands of preset for setup
+ */
+export const SUBCOMMAND_MOBILE = 'mobile';
+export const SUBCOMMAND_DESKTOP = 'desktop';
+export const SUBCOMMAND_BROWSER = 'browser';
+
+/**
+ * Pairs of preset subcommand and driver candidates.
+ * Driver names listed in KNOWN_DRIVERS to install by default
+ */
+const PRESET_PAIRS = Object.freeze(
+  /** @type {const} */ ({
+    mobile: _.keys(MOBILE_DRIVERS),
+    desktop: _.keys(DESKTOP_DRIVERS),
+    browser: _.keys(DESKTOP_BROWSERS)
+  }),
+);
+const DRIVERS_ONLY_MACOS = ['xcuitest', 'safari', 'mac2'];
+
+const DRIVERS_ONLY_WINDOWS = ['windows'];
+
+/**
+ * Plugin names listed in KNOWN_PLUGINS to install by default.
+ */
+export const DEFAULT_PLUGINS = ['images'];
+
+/**
+ * Return a list of drivers available for current host platform.
+ * @param {import('appium/types').CliCommandSetupSubcommand} presetName
+ * @returns {Array<string>}
+ */
+export function getPresetDrivers(presetName) {
+  return _.filter(PRESET_PAIRS[presetName], (driver) => {
+    if (_.includes(DRIVERS_ONLY_MACOS, driver)) {
+      return system.isMac();
+    }
+
+    if (_.includes(DRIVERS_ONLY_WINDOWS, driver)) {
+      return system.isWindows();
+    }
+
+    return true;
+  });
+
+}
+
+/**
+ * Return desktop platform name for setup command description.
+ * @returns {string}
+ */
+export function determinePlatformName() {
+  if (system.isMac()) {
+    return 'macOS';
+  } else if (system.isWindows()) {
+    return 'Windows';
+  }
+  return 'Linux';
+}
+
+/**
+ * Run 'setup' command to install drivers/plugins into the given appium home.
+ * @template {import('appium/types').CliCommandSetup} SetupCmd
+ * @param {import('appium/types').Args<SetupCmd>} preConfigArgs
+ * @param {string} appiumHome
+ * @param {DriverConfig} driverConfig
+ * @param {PluginConfig} pluginConfig
+ * @returns {Promise<void>}
+ */
+export async function runSetupCommand(appiumHome, preConfigArgs, driverConfig, pluginConfig) {
+  switch (preConfigArgs.setupCommand) {
+    case SUBCOMMAND_DESKTOP:
+      await setupDesktopAppDrivers(driverConfig);
+      await setupDefaultPlugins(pluginConfig);
+      break;
+    case SUBCOMMAND_BROWSER:
+      await setupBrowserDrivers(driverConfig);
+      await setupDefaultPlugins(pluginConfig);
+      break;
+    default:
+      await setupMobileDrivers(driverConfig);
+      await setupDefaultPlugins(pluginConfig);
+      break;
+  }
+};
+
+/**
+ * Install drivers listed in DEFAULT_DRIVERS.
+ * @param {DriverConfig} driverConfig
+ * @returns {Promise<void>}
+ */
+async function setupMobileDrivers(driverConfig) {
+  await installDrivers(SUBCOMMAND_MOBILE, driverConfig);
+}
+
+/**
+ * Install all of known drivers listed in BROWSER_DRIVERS.
+ * @param {DriverConfig} driverConfig
+ * @returns {Promise<void>}
+ */
+async function setupBrowserDrivers(driverConfig) {
+  await installDrivers(SUBCOMMAND_BROWSER, driverConfig);
+}
+
+/**
+ * Install all of known drivers listed in DESKTOP_APP_DRIVERS.
+ * @param {DriverConfig} driverConfig
+ * @returns {Promise<void>}
+ */
+async function setupDesktopAppDrivers(driverConfig) {
+  await installDrivers(SUBCOMMAND_DESKTOP, driverConfig);
+}
+
+/**
+ * Install the given driver name. It skips the installation if the given driver name was already installed.
+ * @param {import('appium/types').CliCommandSetupSubcommand} subcommand
+ * @param {DriverConfig} driverConfig
+ * @returns {Promise<void>}
+ */
+async function installDrivers(subcommand, driverConfig) {
+  for (const driverName of getPresetDrivers(subcommand)) {
+    await installExtension(driverName, extensionCommandArgs('driver', driverName, 'install'), driverConfig);
+  }
+}
+
+/**
+ * Install plugins listed in DEFAULT_PLUGINS.
+ * @param {PluginConfig} pluginConfig
+ * @returns {Promise<void>}
+ */
+async function setupDefaultPlugins(pluginConfig) {
+  for (const pluginName of DEFAULT_PLUGINS) {
+    await installExtension(pluginName, extensionCommandArgs('plugin', pluginName, 'install'), pluginConfig);
+  }
+}
+
+/**
+ * Run the given extensionConfigArgs command after checking if the given extensionName was already installed.
+ * @param {string} extensionName
+ * @param {Args} extensionConfigArgs
+ * @param {DriverConfig|PluginConfig} extensionConfig
+ * @returns
+ */
+async function installExtension(extensionName, extensionConfigArgs, extensionConfig) {
+  if (_.keys(extensionConfig.installedExtensions).includes(extensionName)) {
+    log.info(`${extensionName} (${extensionConfig.installedExtensions[extensionName].version}) is already installed. ` +
+      `Skipping the installation.`);
+    return;
+  }
+  await runExtensionCommand(extensionConfigArgs, extensionConfig);
+}
+
+/**
+ * Return the command config for driver or plugin.
+ * @param {CliExtensionCommand} extensionCommand
+ * @param {string} extensionName
+ * @param {CliExtensionSubcommand} command
+ * @returns {Args}
+ */
+function extensionCommandArgs(extensionCommand, extensionName, command) {
+  return (extensionCommand === 'plugin')
+    ? {'subcommand': 'plugin', 'pluginCommand': command, 'plugin': extensionName}
+    : {'subcommand': 'driver', 'driverCommand': command, 'driver': extensionName};
+}
+
+/**
+ * @typedef {import('appium/types').CliExtensionCommand} CliExtensionCommand
+ * @typedef {import('appium/types').CliExtensionSubcommand} CliExtensionSubcommand
+ * @typedef {import('../extension/extension-config').ExtensionConfig<CliExtensionCommand>} PluginConfig
+ * @typedef {import('../extension/extension-config').ExtensionConfig<CliExtensionCommand>} DriverConfig
+ */
+
+/**
+ * @typedef {import('appium/types').Args<CliExtensionCommand, CliExtensionSubcommand>} Args
+ */

package/lib/config.js

@@ -1,16 +1,18 @@
 /* eslint-disable no-console */
 import _ from 'lodash';
-import {system, fs} from '@appium/support';
+import {system, fs, npm} from '@appium/support';
 import axios from 'axios';
 import {exec} from 'teen_process';
 import semver from 'semver';
 import os from 'node:os';
 import {npmPackage} from './utils';
+import B from 'bluebird';
 import {getDefaultsForSchema, getAllArgSpecs} from './schema/schema';
 
 export const APPIUM_VER = npmPackage.version;
 const ENGINES = /** @type {Record<string,string>} */ (npmPackage.engines);
 const MIN_NODE_VERSION = ENGINES.node;
+export const rootDir = fs.findRoot(__dirname);
 
 const GIT_BINARY = `git${system.isWindows() ? '.exe' : ''}`;
 const GITHUB_API = 'https://api.github.com/repos/appium/appium';
@@ -28,8 +30,9 @@ function getNodeVersion() {
 
 /**
  * @param {boolean} [useGithubApiFallback]
+ * @returns {Promise<void>}
  */
-async function updateBuildInfo(useGithubApiFallback = false) {
+export async function updateBuildInfo(useGithubApiFallback = false) {
   const sha = await getGitRev(useGithubApiFallback);
   if (!sha) {
     return;
@@ -50,11 +53,61 @@ const getFullGitPath = _.memoize(async function getFullGitPath() {
   }
 });
 
+/**
+ * Prints server debug into into the console.
+ *
+ * @param {{
+ * driverConfig: import('./extension/driver-config').DriverConfig,
+ * pluginConfig: import('./extension/plugin-config').PluginConfig,
+ * appiumHome: string
+ * }} info
+ * @returns {Promise<void>}
+ */
+export async function showDebugInfo({driverConfig, pluginConfig, appiumHome}) {
+  const getNpmVersion = async () => {
+    const {stdout} = await npm.exec('--version', [], {cwd: process.cwd()});
+    return _.trim(stdout);
+  };
+  const findNpmLocation = async () => await fs.which(system.isWindows() ? 'npm.cmd' : 'npm');
+  const [npmVersion, npmLocation] = await B.all([
+    ...([getNpmVersion, findNpmLocation].map((f) => getSafeResult(f, 'unknown'))),
+    /** @type {any} */ (updateBuildInfo()),
+  ]);
+  const debugInfo = {
+    os: {
+      platform: os.platform(),
+      release: os.release(),
+      arch: os.arch(),
+      homedir: os.homedir(),
+      username: os.userInfo().username,
+    },
+    node: {
+      version: process.version,
+      arch: process.arch,
+      cwd: process.cwd(),
+      argv: process.argv,
+      env: process.env,
+      npm: {
+        location: npmLocation,
+        version: npmVersion,
+      },
+    },
+    appium: {
+      location: rootDir,
+      homedir: appiumHome,
+      build: getBuildInfo(),
+      drivers: driverConfig.installedExtensions,
+      plugins: pluginConfig.installedExtensions,
+    },
+  };
+  console.log(JSON.stringify(debugInfo, null, 2));
+}
+
 /**
  * @param {boolean} [useGithubApiFallback]
  * @returns {Promise<string?>}
  */
-async function getGitRev(useGithubApiFallback = false) {
+export async function getGitRev(useGithubApiFallback = false) {
   const fullGitPath = await getFullGitPath();
   if (fullGitPath) {
     try {
@@ -122,11 +175,15 @@ async function getGitTimestamp(commitSha, useGithubApiFallback = false) {
  * and succeeds.
  * @returns {import('appium/types').BuildInfo}
  */
-function getBuildInfo() {
+export function getBuildInfo() {
   return BUILD_INFO;
 }
 
-function checkNodeOk() {
+/**
+ * @returns {void}
+ * @throws {Error} If Node version is outside of the supported range
+ */
+export function checkNodeOk() {
   const version = getNodeVersion();
   if (!semver.satisfies(version, MIN_NODE_VERSION)) {
     throw new Error(
@@ -135,7 +192,7 @@ function checkNodeOk() {
   }
 }
 
-async function showBuildInfo() {
+export async function showBuildInfo() {
   await updateBuildInfo(true);
   console.log(JSON.stringify(getBuildInfo())); // eslint-disable-line no-console
 }
@@ -145,7 +202,7 @@ async function showBuildInfo() {
  * @param {Args} parsedArgs
  * @returns {Args}
  */
-function getNonDefaultServerArgs(parsedArgs) {
+export function getNonDefaultServerArgs(parsedArgs) {
   /**
    * Flattens parsed args into a single level object for comparison with
    * flattened defaults across server args and extension args.
@@ -253,7 +310,7 @@ const compactConfig = _.partial(
  * @param {Partial<ParsedArgs>} defaults - Configuration defaults from schemas
  * @param {ParsedArgs} parsedArgs - Entire parsed args object
  */
-function showConfig(nonDefaultPreConfigParsedArgs, configResult, defaults, parsedArgs) {
+export function showConfig(nonDefaultPreConfigParsedArgs, configResult, defaults, parsedArgs) {
   console.log('Appium Configuration\n');
   console.log('from defaults:\n');
   console.dir(compactConfig(defaults));
@@ -308,18 +365,22 @@ export async function requireDir(root, requireWriteable = true, displayName = 'f
   }
 }
 
-const rootDir = fs.findRoot(__dirname);
-
-export {
-  getBuildInfo,
-  checkNodeOk,
-  showBuildInfo,
-  getNonDefaultServerArgs,
-  getGitRev,
-  updateBuildInfo,
-  showConfig,
-  rootDir,
-};
+/**
+ * Calculates the result of the given function and return its value
+ * or the default one if there was an exception.
+ *
+ * @template T
+ * @param {() => Promise<T>} f
+ * @param {T} defaultValue
+ * @returns {Promise<T>}
+ */
+async function getSafeResult(f, defaultValue) {
+  try {
+    return await f();
+  } catch {
+    return defaultValue;
+  }
+}
 
 /**
  * @typedef {import('appium/types').ParsedArgs} ParsedArgs

package/lib/constants.js

@@ -15,6 +15,12 @@ export const PLUGIN_TYPE = 'plugin';
  */
 export const SERVER_SUBCOMMAND = 'server';
 
+/**
+ * The `setup` command of the `appium` CLI
+ */
+export const SETUP_SUBCOMMAND = 'setup';
+
+
 /**
  * The value of `--use-plugins` if _all_ plugins should be loaded
  */
@@ -33,22 +39,41 @@ export const KNOWN_PLUGINS = Object.freeze(
   }),
 );
 
-// This is a map of driver names to npm packages representing those drivers.
-// The drivers in this list will be available to the CLI so users can just
-// type 'appium driver install 'name'', rather than having to specify the full
-// npm package. I.e., these are the officially recognized drivers.
-export const KNOWN_DRIVERS = Object.freeze(
+export const MOBILE_DRIVERS = Object.freeze(
   /** @type {const} */ ({
     uiautomator2: 'appium-uiautomator2-driver',
     xcuitest: 'appium-xcuitest-driver',
-    mac2: 'appium-mac2-driver',
     espresso: 'appium-espresso-driver',
+  }),
+);
+
+export const DESKTOP_DRIVERS = Object.freeze(
+  /** @type {const} */ ({
+    mac2: 'appium-mac2-driver',
+    windows: 'appium-windows-driver',
+  }),
+);
+
+export const DESKTOP_BROWSERS = Object.freeze(
+  /** @type {const} */ ({
     safari: 'appium-safari-driver',
     gecko: 'appium-geckodriver',
     chromium: 'appium-chromium-driver',
   }),
 );
 
+// This is a map of driver names to npm packages representing those drivers.
+// The drivers in this list will be available to the CLI so users can just
+// type 'appium driver install 'name'', rather than having to specify the full
+// npm package. I.e., these are the officially recognized drivers.
+export const KNOWN_DRIVERS = Object.freeze(
+  /** @type {const} */ ({
+    ...MOBILE_DRIVERS,
+    ...DESKTOP_DRIVERS,
+    ...DESKTOP_BROWSERS,
+  }),
+);
+
 /**
  * Relative path to directory containing any Appium internal files
  */

package/lib/grid-register.js

@@ -57,13 +57,13 @@ function postRequest(configHolder, addr, port, basePath) {
   // Move Selenium 3 configuration properties to configuration object
   if (!_.has(configHolder, 'configuration')) {
     let configuration = {};
-    for (const property in configHolder) {
+    for (const property in /** @type {import('@appium/types').StringRecord} */ (configHolder)) {
       if (_.has(configHolder, property) && property !== 'capabilities') {
         configuration[property] = configHolder[property];
         delete configHolder[property];
       }
     }
-    configHolder.configuration = configuration;
+    /** @type {import('@appium/types').StringRecord} */ (configHolder).configuration = configuration;
   }
 
   // if the node config does not have the appium/webdriver url, host, and port,

package/lib/logsink.js

@@ -131,8 +131,13 @@ function createHttpTransport(args, logLvl) {
   });
 }
 
+/**
+ *
+ * @param {import('@appium/types').StringRecord} args
+ * @returns {Promise<import('winston-transport')[]>}
+ */
 async function createTransports(args) {
-  let transports = [];
+  const transports = [];
   let consoleLogLevel = null;
   let fileLogLevel = null;
 
@@ -201,11 +206,14 @@ async function init(args) {
   // clean up in case we have initiated before since npmlog is a global object
   clear();
 
+  const transports = await createTransports(args);
+  const transportNames = new Set(transports.map((tr) => tr.constructor.name));
   log = createLogger({
-    transports: await createTransports(args),
+    transports,
     levels,
   });
 
+  const reportedLoggerErrors = new Set();
   // Capture logs emitted via npmlog and pass them through winston
   npmlog.on('log', ({level, message, prefix}) => {
     const winstonLevel = npmToWinstonLevels[level] || 'info';
@@ -217,9 +225,20 @@ async function init(args) {
         : getColorizedPrefix(decoratedPrefix);
       msg = `${args.logNoColors ? decoratedPrefix : toColorizedDecoratedPrefix()} ${msg}`;
     }
-    log[winstonLevel](msg);
-    if (args.logHandler && _.isFunction(args.logHandler)) {
-      args.logHandler(level, msg);
+    try {
+      log[winstonLevel](msg);
+      if (_.isFunction(args.logHandler)) {
+        args.logHandler(level, msg);
+      }
+    } catch (e) {
+      if (!reportedLoggerErrors.has(e.message) && process.stderr.writable) {
+        // eslint-disable-next-line no-console
+        console.error(
+          `The log message '${_.truncate(msg, {length: 30})}' cannot be written into ` +
+          `one or more requested destinations: ${transportNames}. Original error: ${e.message}`
+        );
+        reportedLoggerErrors.add(e.message);
+      }
     }
   });
 }

package/lib/main.js

@@ -13,6 +13,7 @@ import {asyncify} from 'asyncbox';
 import _ from 'lodash';
 import {AppiumDriver} from './appium';
 import {runExtensionCommand} from './cli/extension';
+import { runSetupCommand } from './cli/setup-command';
 import {getParser} from './cli/parser';
 import {
   APPIUM_VER,
@@ -21,6 +22,7 @@ import {
   getNonDefaultServerArgs,
   showConfig,
   showBuildInfo,
+  showDebugInfo,
   requireDir,
 } from './config';
 import {readConfigFile} from './config-file';
@@ -38,6 +40,7 @@ import {
   fetchInterfaces,
   V4_BROADCAST_IP,
   V6_BROADCAST_IP,
+  isSetupCommandArgs,
 } from './utils';
 import net from 'node:net';
 
@@ -216,7 +219,7 @@ async function init(args) {
   }
 
   // merge config and apply defaults.
-  // the order of precendece is:
+  // the order of precedence is:
   // 1. command line args
   // 2. config file
   // 3. defaults from config file.
@@ -231,6 +234,15 @@ async function init(args) {
       return /** @type {InitResult<Cmd>} */ ({});
     }
 
+    if (preConfigArgs.showDebugInfo) {
+      await showDebugInfo({
+        driverConfig,
+        pluginConfig,
+        appiumHome,
+      });
+      return /** @type {InitResult<Cmd>} */ ({});
+    }
+
     await logsinkInit(serverArgs);
 
     if (serverArgs.logFilters) {
@@ -276,6 +288,9 @@ async function init(args) {
       pluginConfig,
       appiumHome,
     });
+  } else if (isSetupCommandArgs(preConfigArgs)) {
+    await runSetupCommand(appiumHome, preConfigArgs, driverConfig, pluginConfig);
+    return /** @type {InitResult<Cmd>} */ ({});
   } else {
     await requireDir(appiumHome, true, appiumHomeSourceName);
     if (isExtensionCommandArgs(preConfigArgs)) {
@@ -465,6 +480,7 @@ export {main, init, resolveAppiumHome};
  * @typedef {import('appium/types').CliCommandServer} ServerCommand
  * @typedef {import('appium/types').CliCommandDriver} DriverCommand
  * @typedef {import('appium/types').CliCommandPlugin} PluginCommand
+ * @typedef {import('appium/types').CliCommandSetup} SetupCommand
  * @typedef {import('./extension').DriverNameMap} DriverNameMap
  * @typedef {import('./extension').PluginNameMap} PluginNameMap
  */