appium 2.5.4 → 2.7.0

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

@@ -1,15 +1,15 @@
-import npmlog from 'npmlog';
+import globalLog from '@appium/logger';
 import {createLogger, format, transports} from 'winston';
 import {fs, logger} from '@appium/support';
 import { APPIUM_LOGGER_NAME } from './logger';
 import _ from 'lodash';
 
 // set up distributed logging before everything else
-logger.patchLogger(npmlog);
-global._global_npmlog = npmlog;
+logger.patchLogger(globalLog);
+global._global_npmlog = globalLog;
 
 // npmlog is used only for emitting, we use winston for output
-npmlog.level = 'info';
+globalLog.level = 'info';
 const levels = {
   debug: 4,
   info: 3,
@@ -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;
 
@@ -193,7 +198,7 @@ function getColorizedPrefix(prefix) {
 }
 
 async function init(args) {
-  npmlog.level = 'silent';
+  globalLog.level = 'silent';
 
   // set de facto param passed to timestamp function
   useLocalTimeZone = args.localTimezone;
@@ -201,13 +206,16 @@ 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}) => {
+  globalLog.on('log', ({level, message, prefix}) => {
     const winstonLevel = npmToWinstonLevels[level] || 'info';
     let msg = message;
     if (prefix) {
@@ -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);
+      }
     }
   });
 }
@@ -230,7 +249,7 @@ function clear() {
       log.remove(transport);
     }
   }
-  npmlog.removeAllListeners('log');
+  globalLog.removeAllListeners('log');
 }
 
 export {init, clear};

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
  */

package/lib/utils.js

@@ -4,7 +4,7 @@ import {processCapabilities, PROTOCOLS, STANDARD_CAPS, errors} from '@appium/bas
 import {inspect as dump} from 'util';
 import {node, fs} from '@appium/support';
 import path from 'path';
-import {SERVER_SUBCOMMAND, DRIVER_TYPE, PLUGIN_TYPE} from './constants';
+import {SERVER_SUBCOMMAND, DRIVER_TYPE, PLUGIN_TYPE, SETUP_SUBCOMMAND} from './constants';
 import os from 'node:os';
 
 const W3C_APPIUM_PREFIX = 'appium';
@@ -330,6 +330,16 @@ export function isServerCommandArgs(args) {
   return args.subcommand === SERVER_SUBCOMMAND;
 }
 
+/**
+ * @template {CliCommand} Cmd
+ * @template {CliExtensionSubcommand|CliCommandSetupSubcommand|void} [SubCmd=void]
+ * @param {Args<Cmd, SubCmd>} args
+ * @returns {args is Args<SetupCommand>}
+ */
+export function isSetupCommandArgs(args) {
+  return args.subcommand === SETUP_SUBCOMMAND;
+}
+
 /**
  * @template {CliCommand} [Cmd=ServerCommand]
  * @template {CliExtensionSubcommand|void} [SubCmd=void]
@@ -451,19 +461,21 @@ export {
  * @typedef {import('appium/types').CliCommand} CliCommand
  * @typedef {import('appium/types').CliExtensionSubcommand} CliExtensionSubcommand
  * @typedef {import('appium/types').CliExtensionCommand} CliExtensionCommand
+ * @typedef {import('appium/types').CliCommandSetupSubcommand} CliCommandSetupSubcommand
  * @typedef {import('appium/types').CliCommandServer} ServerCommand
  * @typedef {import('appium/types').CliCommandDriver} DriverCommand
  * @typedef {import('appium/types').CliCommandPlugin} PluginCommand
+ * @typedef {import('appium/types').CliCommandSetup} SetupCommand
  */
 
 /**
  * @template {CliCommand} [Cmd=ServerCommand]
- * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @template {CliExtensionSubcommand|CliCommandSetupSubcommand|void} [SubCmd=void]
  * @typedef {import('appium/types').Args<Cmd, SubCmd>} Args
  */
 
 /**
  * @template {CliCommand} [Cmd=ServerCommand]
- * @template {CliExtensionSubcommand|void} [SubCmd=void]
+ * @template {CliExtensionSubcommand|CliCommandSetupSubcommand|void} [SubCmd=void]
  * @typedef {import('appium/types').ParsedArgs<Cmd, SubCmd>} ParsedArgs
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.5.4",
+  "version": "2.7.0",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -60,12 +60,12 @@
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/base-driver": "^9.6.0",
-    "@appium/base-plugin": "^2.2.31",
-    "@appium/docutils": "^1.0.7",
+    "@appium/base-driver": "^9.8.0",
+    "@appium/base-plugin": "^2.2.33",
+    "@appium/docutils": "^1.0.9",
     "@appium/schema": "~0.5.0",
-    "@appium/support": "^4.2.5",
-    "@appium/types": "^0.17.0",
+    "@appium/support": "^4.3.0",
+    "@appium/types": "^0.19.0",
     "@sidvind/better-ajv-errors": "2.1.3",
     "@types/argparse": "2.0.16",
     "@types/bluebird": "3.5.42",
@@ -73,28 +73,27 @@
     "@types/semver": "7.5.8",
     "@types/teen_process": "2.0.4",
     "@types/wrap-ansi": "3.0.0",
-    "ajv": "8.12.0",
+    "ajv": "8.16.0",
     "ajv-formats": "3.0.1",
     "argparse": "2.0.1",
     "async-lock": "1.4.1",
     "asyncbox": "3.0.0",
-    "axios": "1.6.8",
+    "axios": "1.7.2",
     "bluebird": "3.7.2",
     "cross-env": "7.0.3",
     "lilconfig": "3.1.1",
     "lodash": "4.17.21",
-    "npmlog": "7.0.1",
     "ora": "5.4.1",
     "package-changed": "3.0.0",
     "resolve-from": "5.0.0",
-    "semver": "7.6.0",
+    "semver": "7.6.2",
     "source-map-support": "0.5.21",
-    "teen_process": "2.1.1",
-    "type-fest": "4.10.1",
+    "teen_process": "2.1.4",
+    "type-fest": "4.19.0",
     "winston": "3.13.0",
     "wrap-ansi": "7.0.0",
-    "ws": "8.16.0",
-    "yaml": "2.4.1"
+    "ws": "8.17.0",
+    "yaml": "2.4.3"
   },
   "engines": {
     "node": "^14.17.0 || ^16.13.0 || >=18.0.0",
@@ -103,5 +102,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6344d14665178433b182749a15f0e07f9dc14258"
+  "gitHead": "339acd345fafa1292c8d286261553fcc6b440e46"
 }

package/types/cli.ts

@@ -2,6 +2,7 @@ import {DriverType, PluginType, ServerArgs} from '@appium/types';
 import {SetOptional} from 'type-fest';
 import {InstallType} from './manifest';
 export type CliCommandServer = 'server';
+export type CliCommandSetup = 'setup';
 export type CliCommandDriver = DriverType;
 export type CliCommandPlugin = PluginType;
 
@@ -13,7 +14,13 @@ export type CliExtensionCommand = CliCommandDriver | CliCommandPlugin;
 /**
  * Possible commands for the `appium` CLI.
  */
-export type CliCommand = CliCommandServer | CliExtensionCommand;
+export type CliCommand = CliCommandServer | CliExtensionCommand | CliCommandSetup;
+
+/**
+ * Possible subcommands of {@linkcode CliCommandSetup}.
+ * The command name will be preset name to get drivers/plugins to be installed.
+ */
+export type CliCommandSetupSubcommand = 'mobile' | 'browser' | 'desktop';
 
 /**
  * Possible subcommands of {@linkcode CliCommandDriver} or
@@ -55,6 +62,11 @@ export interface MoreArgs {
    */
   showConfig?: boolean;
 
+  /**
+   * If true, show the server debug info and exit
+   */
+  showDebugInfo?: boolean;
+
   /**
    * If true, open a REPL
    */
@@ -62,7 +74,7 @@ export interface MoreArgs {
 }
 
 /**
- * These arguments are _not_ supported by the CLI, but only via programmatic usage / tests.
+ * These arguments are not necessarily supported by the CLI, but via programmatic usage / tests.
  */
 export interface ProgrammaticArgs {
   /**
@@ -93,6 +105,11 @@ export interface ProgrammaticArgs {
    * If true, show config and exit
    */
   showConfig?: boolean;
+
+  /**
+   * If true, show debug info and exit
+   */
+  showDebugInfo?: boolean;
 }
 
 export interface DriverExtArgs {
@@ -105,6 +122,10 @@ export interface PluginExtArgs {
   plugin?: string;
 }
 
+export interface SetupArgs {
+  setupCommand?: CliCommandSetupSubcommand;
+}
+
 /**
  * These are args which the user will specify if using an extension command
  */
@@ -132,9 +153,11 @@ export interface BaseExtArgs<Cmd extends CliExtensionCommand> {
  */
 export type ExtArgs<
   Cmd extends CliExtensionCommand,
-  SubCmd extends CliExtensionSubcommand
+  SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand
 > = BaseExtArgs<Cmd> &
-  (Cmd extends CliCommandDriver
+  (Cmd extends CliCommandSetup
+    ? SetupArgs
+    : Cmd extends CliCommandDriver
     ? DriverExtArgs
     : Cmd extends CliCommandPlugin
     ? PluginExtArgs
@@ -152,13 +175,15 @@ export type ExtArgs<
  */
 export type CommonArgs<
   Cmd extends CliCommand = CliCommandServer,
-  SubCmd extends CliExtensionSubcommand | void = void
+  SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand | void = void
 > = MoreArgs &
   ProgrammaticArgs &
   (Cmd extends CliCommandServer
     ? ServerArgs
+    : Cmd extends CliCommandSetup
+    ? SetupArgs
     : Cmd extends CliExtensionCommand
-    ? SubCmd extends CliExtensionSubcommand
+    ? SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand
       ? ExtArgs<Cmd, SubCmd>
       : never
     : never);
@@ -168,7 +193,7 @@ export type CommonArgs<
  */
 export type ParsedArgs<
   Cmd extends CliCommand = CliCommandServer,
-  SubCmd extends CliExtensionSubcommand | void = void
+  SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand | void = void
 > = CommonArgs<Cmd, SubCmd>;
 
 /**
@@ -178,7 +203,7 @@ export type ParsedArgs<
  */
 export type Args<
   Cmd extends CliCommand = CliCommandServer,
-  SubCmd extends CliExtensionSubcommand | void = void
+  SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand | void = void
 > = Cmd extends CliCommandServer
   ? SetOptional<CommonArgs<Cmd>, keyof ServerArgs>
   : ParsedArgs<Cmd, SubCmd>;