appium 3.3.0 → 3.3.1

package/lib/bootstrap/main-helpers.ts

@@ -0,0 +1,223 @@
+import {inspect as dump, type InspectOptions} from 'node:util';
+import {log as logger} from '../logger';
+import {
+  routeConfiguringFunction as makeRouter,
+  normalizeBasePath,
+  server as baseServer,
+  type ServerOpts,
+} from '@appium/base-driver';
+import _ from 'lodash';
+import type {AppiumServer, Driver, MethodMap, UpdateServerCallback} from '@appium/types';
+import {WebSocketServer} from 'ws';
+import type {NetworkInterfaceInfo} from 'node:os';
+import type {AppiumDriver} from '../appium';
+import {APPIUM_VER, getBuildInfo, getGitRev, updateBuildInfo} from '../helpers/build';
+import {checkNodeOk, requireDir} from './node-helpers';
+import {getNonDefaultServerArgs} from './startup-config';
+import {validate as validateSchema} from '../schema/schema';
+import {fetchInterfaces, V4_BROADCAST_IP, isBroadcastIp} from '../helpers/network';
+import {LONG_STACKTRACE_LIMIT, BIDI_BASE_PATH} from '../constants';
+import type {Args, ParsedArgs, CliCommandServer} from 'appium/types';
+import type {DriverNameMap, PluginNameMap} from '../extension';
+
+const isStdoutTTY = process.stdout.isTTY;
+
+/**
+ * Logs a value to the console using the info logger (with util.inspect formatting).
+ */
+export const inspect = _.flow(
+  _.partialRight(dump as (object: unknown, options: InspectOptions) => string, {
+    colors: true,
+    depth: null,
+    compact: !isStdoutTTY,
+  }),
+  (...args: unknown[]) => {
+    logger.info(...args);
+  },
+);
+
+/**
+ * Prints the current build info JSON to stdout.
+ *
+ * This updates build metadata first (using GitHub fallback) and then logs the
+ * resulting {@link BuildInfo} object.
+ */
+export async function showBuildInfo(): Promise<void> {
+  await updateBuildInfo(true);
+  // eslint-disable-next-line no-console -- CLI output for --build-info
+  console.log(JSON.stringify(getBuildInfo()));
+}
+
+/**
+ * Human-readable label for where Appium resolved `APPIUM_HOME` from (CLI, env, or autodetect).
+ */
+export function determineAppiumHomeSource(appiumHomeFromArgs?: string | null): string {
+  if (!_.isNil(appiumHomeFromArgs)) {
+    return 'appiumHome config value';
+  }
+  if (process.env.APPIUM_HOME) {
+    return 'APPIUM_HOME environment variable';
+  }
+  return 'autodetected Appium home path';
+}
+
+/**
+ * Logs the REST listener URL; if the bind address is a broadcast address, lists concrete interface URLs.
+ */
+export function logServerAddress(url: string): void {
+  const urlObj = new URL(url);
+  logger.info(`Appium REST http interface listener started on ${url}`);
+  if (!isBroadcastIp(urlObj.hostname)) {
+    return;
+  }
+
+  const interfaces = fetchInterfaces(urlObj.hostname === V4_BROADCAST_IP ? 4 : 6);
+  const toLabel = (iface: NetworkInterfaceInfo) => {
+    const href = urlObj.href.replace(urlObj.hostname, iface.address);
+    return iface.internal ? `${href} (only accessible from the same host)` : href;
+  };
+  logger.info(
+    `You can provide the following ${interfaces.length === 1 ? 'URL' : 'URLs'} ` +
+      `in your client code to connect to this server:\n` +
+      interfaces.map((iface) => `\t${toLabel(iface)}`).join('\n'),
+  );
+}
+
+/**
+ * Validates Node version, optional long stack traces, schema, tmp dir, and `--build-info` early exit.
+ *
+ * @param args - Parsed server CLI args
+ * @param throwInsteadOfExit - When true, rethrows failures instead of calling `process.exit(1)`
+ */
+export async function preflightChecks(
+  args: ParsedArgs<CliCommandServer>,
+  throwInsteadOfExit = false,
+): Promise<void> {
+  try {
+    checkNodeOk();
+    if (args.longStacktrace) {
+      Error.stackTraceLimit = LONG_STACKTRACE_LIMIT;
+    }
+    if (args.showBuildInfo) {
+      await showBuildInfo();
+      process.exit(0);
+    }
+
+    validateSchema(args);
+
+    if (args.tmpDir) {
+      await requireDir(args.tmpDir, !args.noPermsCheck, 'tmpDir argument value');
+    }
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    logger.error((message as string & {red: string}).red);
+    if (throwInsteadOfExit) {
+      throw err;
+    }
+
+    process.exit(1);
+  }
+}
+
+/**
+ * Prints welcome line (version + optional git rev), non-default server args, and default capabilities.
+ */
+export async function logStartupInfo(args: ParsedArgs<CliCommandServer>): Promise<void> {
+  let welcome = `Welcome to Appium v${APPIUM_VER}`;
+  const appiumRev = await getGitRev();
+  if (appiumRev) {
+    welcome += ` (REV ${appiumRev})`;
+  }
+  logger.info(welcome);
+
+  const showArgs = getNonDefaultServerArgs(args);
+  if (_.size(showArgs)) {
+    logNonDefaultArgsWarning(showArgs);
+  }
+  if (!_.isEmpty(args.defaultCapabilities)) {
+    logDefaultCapabilitiesWarning(args.defaultCapabilities);
+  }
+}
+
+/**
+ * Collects `updateServer` hooks from active driver and plugin classes for HTTP server customization.
+ */
+export function getServerUpdaters(
+  driverClasses: DriverNameMap,
+  pluginClasses: PluginNameMap,
+): UpdateServerCallback[] {
+  return _.compact(_.map([...driverClasses.keys(), ...pluginClasses.keys()], 'updateServer'));
+}
+
+/**
+ * Merges `newMethodMap` contributions from all active drivers and plugins into one method map.
+ */
+export function getExtraMethodMap(driverClasses: DriverNameMap, pluginClasses: PluginNameMap): MethodMap<Driver> {
+  return [...driverClasses.keys(), ...pluginClasses.keys()].reduce<MethodMap<Driver>>(
+    (map, klass) => ({
+      ...map,
+      ...(klass.newMethodMap ?? {}),
+    }),
+    {},
+  );
+}
+
+/**
+ * Builds {@link ServerOpts} and normalized base path for the Appium HTTP server from CLI args and extensions.
+ */
+export function buildServerOpts(
+  appiumDriver: AppiumDriver,
+  parsedArgs: ParsedArgs<CliCommandServer>,
+  driverClasses: DriverNameMap,
+  pluginClasses: PluginNameMap,
+): {serverOpts: ServerOpts; normalizedBasePath: string} {
+  const routeConfiguringFunction = makeRouter(appiumDriver);
+  const serverOpts: ServerOpts = {
+    routeConfiguringFunction,
+    port: parsedArgs.port,
+    hostname: parsedArgs.address,
+    allowCors: parsedArgs.allowCors,
+    basePath: parsedArgs.basePath,
+    serverUpdaters: getServerUpdaters(driverClasses, pluginClasses),
+    extraMethodMap: getExtraMethodMap(driverClasses, pluginClasses),
+    cliArgs: parsedArgs,
+  };
+  const normalizedBasePath = normalizeBasePath(parsedArgs.basePath);
+  for (const timeoutArgName of ['keepAliveTimeout', 'requestTimeout'] as const) {
+    if (_.isInteger(parsedArgs[timeoutArgName])) {
+      serverOpts[timeoutArgName] = parsedArgs[timeoutArgName] * 1000;
+    }
+  }
+  return {serverOpts, normalizedBasePath};
+}
+
+/**
+ * Creates the Appium HTTP server and attaches WebSocket handlers for BiDi under the normalized base path.
+ */
+export async function createAppiumServer(
+  serverOpts: ServerOpts,
+  appiumDriver: AppiumDriver,
+  normalizedBasePath: string,
+): Promise<AppiumServer> {
+  const bidiServer = new WebSocketServer({noServer: true});
+  bidiServer.on('connection', appiumDriver.onBidiConnection.bind(appiumDriver));
+  bidiServer.on('error', appiumDriver.onBidiServerError.bind(appiumDriver));
+  const server = await baseServer(serverOpts);
+  const bidiBasePath = `${normalizedBasePath}${BIDI_BASE_PATH}`;
+  await server.addWebSocketHandler(bidiBasePath, bidiServer);
+  await server.addWebSocketHandler(`${bidiBasePath}/:sessionId`, bidiServer);
+  return server;
+}
+
+function logNonDefaultArgsWarning(args: Args): void {
+  logger.info('Non-default server args:');
+  inspect(args);
+}
+
+function logDefaultCapabilitiesWarning(caps: ParsedArgs<CliCommandServer>['defaultCapabilities']): void {
+  logger.info(
+    'Default capabilities, which will be added to each request ' +
+      'unless overridden by desired capabilities:',
+  );
+  inspect(caps);
+}

package/lib/bootstrap/node-helpers.ts

@@ -0,0 +1,180 @@
+/* eslint-disable no-console */
+import _ from 'lodash';
+import path from 'node:path';
+import os from 'node:os';
+import * as semver from 'semver';
+import B from 'bluebird';
+import {system, fs, npm} from '@appium/support';
+import {log as logger} from '../logger';
+import {getAppiumModuleRoot, npmPackage} from '../utils';
+import {rootDir, updateBuildInfo, getBuildInfo} from '../helpers/build';
+
+const MIN_NODE_VERSION = (npmPackage.engines as Record<string, string>).node;
+
+interface NodeModuleWithInitPaths {
+  Module: {_initPaths(): void};
+}
+
+interface DebugInfoInput {
+  driverConfig: {installedExtensions: unknown};
+  pluginConfig: {installedExtensions: unknown};
+  appiumHome: string;
+}
+
+/**
+ * @throws {Error} If Node version is outside of the supported range
+ */
+export function checkNodeOk(): void {
+  const version = getNodeVersion();
+  if (!semver.satisfies(version, MIN_NODE_VERSION)) {
+    throw new Error(`Node version must be at least ${MIN_NODE_VERSION}; current is ${version.version}`);
+  }
+}
+
+/**
+ * Adjusts NODE_PATH so CJS drivers/plugins can load peer deps. Does not work with ESM.
+ */
+export function adjustNodePath(): void {
+  let appiumModuleSearchRoot: string;
+  try {
+    appiumModuleSearchRoot = path.dirname(getAppiumModuleRoot());
+  } catch (error) {
+    logger.warn((error as Error).message);
+    return;
+  }
+
+  const refreshRequirePaths = (): boolean => {
+    try {
+      // Private API; see https://gist.github.com/branneman/8048520#7-the-hack
+      (require('node:module') as NodeModuleWithInitPaths).Module._initPaths();
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  if (!process.env.NODE_PATH) {
+    process.env.NODE_PATH = appiumModuleSearchRoot;
+    if (refreshRequirePaths()) {
+      process.env.APPIUM_OMIT_PEER_DEPS = '1';
+    } else {
+      delete process.env.NODE_PATH;
+    }
+    return;
+  }
+
+  const nodePathParts = process.env.NODE_PATH.split(path.delimiter);
+  if (nodePathParts.includes(appiumModuleSearchRoot)) {
+    process.env.APPIUM_OMIT_PEER_DEPS = '1';
+    return;
+  }
+
+  nodePathParts.push(appiumModuleSearchRoot);
+  process.env.NODE_PATH = nodePathParts.join(path.delimiter);
+  if (refreshRequirePaths()) {
+    process.env.APPIUM_OMIT_PEER_DEPS = '1';
+  } else {
+    process.env.NODE_PATH = _.without(nodePathParts, appiumModuleSearchRoot).join(path.delimiter);
+  }
+}
+
+/**
+ * Prints JSON debug info (OS, Node/npm, Appium build, installed drivers/plugins) to stdout.
+ * Input combines extension config snapshots with the resolved Appium home path.
+ */
+export async function showDebugInfo({driverConfig, pluginConfig, appiumHome}: DebugInfoInput): Promise<void> {
+  const getNpmVersion = async (): Promise<string> => {
+    const {stdout} = await npm.exec('--version', [], {cwd: process.cwd()});
+    return _.trim(stdout);
+  };
+  const findNpmLocation = async (): Promise<string> =>
+    await fs.which(system.isWindows() ? 'npm.cmd' : 'npm');
+
+  const [npmVersion, npmLocation] = await B.all([
+    ...[getNpmVersion, findNpmLocation].map((f) => getSafeResult(f, 'unknown')),
+    updateBuildInfo() as Promise<unknown>,
+  ]);
+
+  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));
+}
+
+/**
+ * Ensures a directory exists and (optionally) is writeable.
+ *
+ * If the directory does not exist, this attempts to create it recursively.
+ *
+ * @throws {Error}
+ */
+export async function requireDir(
+  root: string,
+  requireWriteable = true,
+  displayName = 'folder path'
+): Promise<void> {
+  let stat;
+  try {
+    stat = await fs.stat(root);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
+      try {
+        await fs.mkdir(root, {recursive: true});
+        return;
+      } catch {}
+    }
+    throw new Error(`The ${displayName} '${root}' must exist and be a valid directory`);
+  }
+  if (stat && !stat.isDirectory()) {
+    throw new Error(`The ${displayName} '${root}' must be a valid directory`);
+  }
+  if (requireWriteable) {
+    try {
+      await fs.access(root, fs.constants.W_OK);
+    } catch {
+      throw new Error(
+        `The ${displayName} '${root}' must be writeable for the current user account '${os.userInfo().username}'`
+      );
+    }
+  }
+}
+
+function getNodeVersion(): semver.SemVer {
+  return semver.coerce(process.version) as semver.SemVer;
+}
+
+/**
+ * Calculates the result of the given function and return its value
+ * or the default one if there was an exception.
+ */
+async function getSafeResult<T>(f: () => Promise<T>, defaultValue: T): Promise<T> {
+  try {
+    return await f();
+  } catch {
+    return defaultValue;
+  }
+}

package/lib/bootstrap/startup-config.ts

@@ -0,0 +1,143 @@
+/* eslint-disable no-console */
+import _ from 'lodash';
+import {getDefaultsForSchema, getAllArgSpecs} from '../schema/schema';
+import type {Args} from 'appium/types';
+import type {ReadConfigFileResult} from './config-file';
+
+interface FlattenedArg {
+  value: unknown;
+  argSpec: {dest: string};
+}
+
+/**
+ * Returns key/value pairs of server arguments that differ from schema defaults (flattened comparison).
+ *
+ * @param parsedArgs - Fully merged server args (CLI + config + defaults)
+ */
+export function getNonDefaultServerArgs(parsedArgs: Args): Args {
+  /**
+   * Flattens parsed args into a single level object for comparison with
+   * flattened defaults across server args and extension args.
+   */
+  const flatten = (args: Args): Record<string, FlattenedArg> => {
+    const argSpecs = getAllArgSpecs();
+    const flattened = _.reduce(
+      [...argSpecs.values()],
+      (acc: Record<string, FlattenedArg>, argSpec: {dest: string}) => {
+        if (_.has(args, argSpec.dest)) {
+          acc[argSpec.dest] = {value: _.get(args, argSpec.dest), argSpec};
+        }
+        return acc;
+      },
+      {}
+    );
+
+    return flattened;
+  };
+
+  const args = flatten(parsedArgs);
+
+  // hopefully these function names are descriptive enough
+  const typesDiffer = (dest: string): boolean =>
+    typeof args[dest].value !== typeof defaultsFromSchema[dest];
+
+  const defaultValueIsArray = (dest: string): boolean => _.isArray(defaultsFromSchema[dest]);
+
+  const argsValueIsArray = (dest: string): boolean => _.isArray(args[dest].value);
+
+  const arraysDiffer = (dest: string): boolean =>
+    _.gt(_.size(_.difference(args[dest].value as any[], defaultsFromSchema[dest] as any[])), 0);
+
+  const valuesDiffer = (dest: string): boolean => args[dest].value !== defaultsFromSchema[dest];
+
+  const defaultIsDefined = (dest: string): boolean => !_.isUndefined(defaultsFromSchema[dest]);
+
+  // note that `_.overEvery` is like an "AND", and `_.overSome` is like an "OR"
+  const argValueNotArrayOrArraysDiffer = _.overSome([_.negate(argsValueIsArray), arraysDiffer]);
+
+  const defaultValueNotArrayAndValuesDiffer = _.overEvery([
+    _.negate(defaultValueIsArray),
+    valuesDiffer,
+  ]);
+
+  /**
+   * This used to be a hideous conditional, but it's broken up into a hideous function instead.
+   * hopefully this makes things a little more understandable.
+   * - checks if the default value is defined
+   * - if so, and the default is not an array:
+   *   - ensures the types are the same
+   *   - ensures the values are equal
+   * - 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
+   */
+  const isNotDefault = _.overEvery([
+    defaultIsDefined,
+    _.overSome([
+      typesDiffer,
+      _.overEvery([defaultValueIsArray, argValueNotArrayOrArraysDiffer]),
+      defaultValueNotArrayAndValuesDiffer,
+    ]),
+  ]);
+
+  const defaultsFromSchema = getDefaultsForSchema(true) as Record<string, unknown>;
+
+  return _.reduce(
+    _.pickBy(args, (_v, key) => isNotDefault(key)),
+    // explodes the flattened object back into nested one
+    (acc: Args, {value, argSpec}: FlattenedArg) => _.set(acc, argSpec.dest, value),
+    {} as Args
+  );
+}
+
+/**
+ * Prints a breakdown of configuration: defaults, config file, CLI/programmatic overrides, and final merged args.
+ *
+ * The actual shape of `nonDefaultPreConfigParsedArgs` 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 nonDefaultPreConfigParsedArgs - CLI-only (or programmatic) args that differ from defaults
+ * @param configResult - Result of {@link readConfigFile}
+ * @param defaults - Schema default values
+ * @param parsedArgs - Final merged configuration
+ */
+export function showConfig(
+  nonDefaultPreConfigParsedArgs: Partial<Args>,
+  configResult: ReadConfigFileResult,
+  defaults: Partial<Args>,
+  parsedArgs: Args
+): void {
+  console.log('Appium Configuration\n');
+  console.log('from defaults:\n');
+  console.dir(compactConfig(defaults));
+  if (configResult.config) {
+    console.log(`\nfrom config file at ${configResult.filepath}:\n`);
+    console.dir(compactConfig(configResult.config));
+  } else {
+    console.log(`\n(no configuration file loaded)`);
+  }
+  const compactedNonDefaultPreConfigArgs = compactConfig(nonDefaultPreConfigParsedArgs);
+  if (_.isEmpty(compactedNonDefaultPreConfigArgs)) {
+    console.log(`\n(no CLI parameters provided)`);
+  } else {
+    console.log('\nvia CLI or function call:\n');
+    console.dir(compactedNonDefaultPreConfigArgs);
+  }
+  console.log('\nfinal configuration:\n');
+  console.dir(compactConfig(parsedArgs));
+}
+
+/**
+ * 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: unknown, key: string) =>
+    key === 'subcommand' || _.isUndefined(value) || (_.isObject(value) && _.isEmpty(value))
+);

package/lib/cli/args.ts

@@ -70,6 +70,16 @@ export const getExtensionArgs = _.memoize(function getExtensionArgs(): Record<
   return extensionArgs;
 });
 
+/**
+ * Returns CLI argument definitions for the `server` command.
+ *
+ * This includes schema-derived options and additional CLI-only options which
+ * are intentionally disallowed in config files.
+ */
+export function getServerArgs(): ArgumentDefinitions {
+  return new Map([...toParserArgs(), ...serverArgsDisallowedInConfig]);
+}
+
 /**
  * Builds options for the `list` subcommand for an extension type.
  */
@@ -246,16 +256,6 @@ function makeRunArgs(type: ExtensionType): ArgumentDefinitions {
   ]);
 }
 
-/**
- * Returns CLI argument definitions for the `server` command.
- *
- * This includes schema-derived options and additional CLI-only options which
- * are intentionally disallowed in config files.
- */
-export function getServerArgs(): ArgumentDefinitions {
-  return new Map([...toParserArgs(), ...serverArgsDisallowedInConfig]);
-}
-
 /**
  * These don't make sense in the context of a config file for obvious reasons.
  */