appium 3.2.2 → 3.3.1

package/lib/bootstrap/grid-v3-register.ts

@@ -0,0 +1,250 @@
+import axios from 'axios';
+import {fs} from '@appium/support';
+import type {StringRecord} from '@appium/types';
+import _ from 'lodash';
+import {log as logger} from '../logger';
+
+/**
+ * Selenium **Grid 3** (legacy hub) node integration.
+ *
+ * Registers this Appium process as a node with a Selenium Grid 3 hub using the classic
+ * `/grid/register` endpoint and `/grid/api/proxy` for re-registration checks.
+ * This does **not** apply to Selenium Grid 4 (which uses a different topology and APIs).
+ *
+ * @see https://www.selenium.dev/documentation/legacy/grid_3/
+ */
+
+/** REST paths exposed by a Selenium Grid 3 hub. */
+const GRID_V3_REGISTER_PATH = '/grid/register';
+const GRID_V3_PROXY_API_PATH = '/grid/api/proxy';
+
+interface Grid3HubConfiguration {
+  hubProtocol?: string;
+  hubHost?: string;
+  hubPort?: number;
+  url?: string;
+  host?: string;
+  port?: number;
+  id?: string;
+  register?: boolean;
+  registerCycle?: number;
+}
+
+interface Grid3NodeConfig extends StringRecord {
+  configuration?: Grid3HubConfiguration;
+  capabilities?: unknown;
+}
+
+interface Grid3ProxyApiResponse {
+  success: boolean;
+  msg?: string;
+}
+
+export default async function registerNode(
+  data: string,
+  addr: string,
+  port: number,
+  basePath: string
+): Promise<void>;
+export default async function registerNode(
+  data: Grid3NodeConfig,
+  addr?: string,
+  port?: number,
+  basePath?: string
+): Promise<void>;
+/**
+ * Registers this server as a node with a **Selenium Grid 3** hub.
+ *
+ * When `data` is a path to a JSON config file, `addr`, `port`, and `basePath` are required (they define
+ * how the hub reaches this Appium server). When `data` is an inline config object, those parameters are
+ * optional and only used to fill missing node URL fields in the config.
+ *
+ * @deprecated Selenium Grid 3 registration is legacy and slated for removal.
+ * Use Selenium Grid 4 integration (node relay) instead.
+ *
+ * @param data - Path to a JSON file or an inline parsed config object
+ * @param addr - Bind to this address
+ * @param port - Bind to this port
+ * @param basePath - Base path for the Appium server (used in the node URL sent to the hub; may be `''`)
+ */
+export default async function registerNode(
+  data: string | Grid3NodeConfig,
+  addr?: string,
+  port?: number,
+  basePath?: string
+): Promise<void> {
+  if (typeof data === 'string') {
+    if (addr === undefined || port === undefined || basePath === undefined) {
+      throw logger.errorWithException(
+        'When the first argument is a Selenium Grid 3 node config file path, address, port, and basePath ' +
+          'are required (e.g. match your Appium `--address`, `--port`, and base path).'
+      );
+    }
+    if (typeof port !== 'number' || !Number.isFinite(port)) {
+      throw logger.errorWithException(
+        'When registering from a node config file path, port must be a finite number.'
+      );
+    }
+  }
+
+  let configHolder: Grid3NodeConfig;
+  if (_.isString(data)) {
+    const configFilePath = data;
+    let fileContent: string;
+    try {
+      fileContent = await fs.readFile(data, 'utf-8');
+    } catch (err) {
+      logger.error(
+        `Unable to load Selenium Grid 3 node configuration file ${configFilePath} to ` +
+        `register with the hub: ${(err as Error).message}`
+      );
+      return;
+    }
+    try {
+      configHolder = JSON.parse(fileContent) as Grid3NodeConfig;
+    } catch (err) {
+      throw logger.errorWithException(
+        `Syntax error in Selenium Grid 3 node configuration file ${configFilePath}: ` +
+        (err as Error).message
+      );
+    }
+  } else {
+    configHolder = data;
+  }
+
+  postRequest(configHolder, addr, port, basePath);
+}
+
+/** Base URL for the Selenium Grid 3 hub (protocol + host + port). */
+function hubUri(config: Grid3HubConfiguration): string {
+  const protocol = config.hubProtocol || 'http';
+  return `${protocol}://${config.hubHost}:${config.hubPort}`;
+}
+
+/** POST registration payload to the Selenium Grid 3 hub. */
+async function registerToGrid(
+  postOptions: {url: string; method: string; data: Grid3NodeConfig},
+  configHolder: Grid3NodeConfig
+): Promise<void> {
+  const hubCfg = configHolder.configuration;
+  if (!hubCfg) {
+    return;
+  }
+  try {
+    const {status} = await axios(postOptions);
+    if (status !== 200) {
+      throw new Error(`Request failed with code ${status}`);
+    }
+    logger.debug(
+      `Appium successfully registered with the Selenium Grid 3 hub at ` + hubUri(hubCfg)
+    );
+  } catch (err) {
+    logger.error(
+      `An attempt to register with the Selenium Grid 3 hub was unsuccessful: ` +
+      (err as Error).message
+    );
+  }
+}
+
+function postRequest(
+  configHolder: Grid3NodeConfig,
+  addr?: string,
+  port?: number,
+  basePath?: string
+): void {
+  // Move Selenium Grid 3 (flat) configuration properties into `configuration`
+  if (!_.has(configHolder, 'configuration')) {
+    const configuration: StringRecord = {};
+    const holder = configHolder as StringRecord;
+    for (const property in holder) {
+      if (_.has(holder, property) && property !== 'capabilities') {
+        configuration[property] = holder[property];
+        delete holder[property];
+      }
+    }
+    holder.configuration = configuration as Grid3HubConfiguration;
+  }
+
+  const cfg = configHolder.configuration;
+  if (!cfg) {
+    return;
+  }
+
+  // if the node config does not have the appium/webdriver url, host, and port,
+  // automatically add it based on how appium was initialized
+  // otherwise, we will take whatever the user setup
+  // because we will always set localhost/127.0.0.1. this won't work if your
+  // node and hub aren't in the same place
+  if (!cfg.url || !cfg.host || !cfg.port) {
+    cfg.url = `http://${addr}:${port}${basePath}`;
+    cfg.host = addr;
+    cfg.port = port;
+  }
+  // if the node config does not have id automatically add it
+  if (!cfg.id) {
+    cfg.id = `http://${cfg.host}:${cfg.port}`;
+  }
+
+  // the post options
+  const regRequest = {
+    url: `${hubUri(cfg)}${GRID_V3_REGISTER_PATH}`,
+    method: 'POST',
+    data: configHolder,
+  };
+
+  if (cfg.register !== true) {
+    logger.debug(`No Selenium Grid 3 hub registration sent (${cfg.register} = false)`);
+    return;
+  }
+
+  const registerCycleInterval = cfg.registerCycle;
+  if (registerCycleInterval === undefined || isNaN(registerCycleInterval) || registerCycleInterval <= 0) {
+    logger.warn(
+      `'registerCycle' is not a valid positive number. ` +
+        `No registration request will be sent to the Selenium Grid 3 hub.`
+    );
+    return;
+  }
+  // initiate a new Thread
+  let first = true;
+  logger.debug(
+    `Starting auto-register thread for Selenium Grid 3. ` +
+      `Will try to register every ${registerCycleInterval} ms.`
+  );
+  setInterval(async function registerRetry() {
+    if (first) {
+      first = false;
+      await registerToGrid(regRequest, configHolder);
+    } else if (!(await isAlreadyRegistered(configHolder))) {
+      // make the http POST to the Selenium Grid 3 hub for registration
+      await registerToGrid(regRequest, configHolder);
+    }
+  }, registerCycleInterval);
+}
+
+/** Query the Selenium Grid 3 hub to see if this node id is already registered. */
+async function isAlreadyRegistered(configHolder: Grid3NodeConfig): Promise<boolean | undefined> {
+  //check if node is already registered
+  const hubCfg = configHolder.configuration;
+  if (!hubCfg?.id) {
+    return;
+  }
+  const id = hubCfg.id;
+  try {
+    const {data, status} = await axios<Grid3ProxyApiResponse>({
+      url: `${hubUri(hubCfg)}${GRID_V3_PROXY_API_PATH}`,
+      params: {id},
+      timeout: 10000,
+    });
+    if (status !== 200) {
+      throw new Error(`Request failed with code ${status}`);
+    }
+    if (!data.success) {
+      // if register fail, print the debug msg
+      logger.debug(`Selenium Grid 3 hub registration check: ${data.msg}`);
+    }
+    return data.success;
+  } catch (err) {
+    logger.debug(`Selenium Grid 3 hub down or not responding: ${(err as Error).message}`);
+  }
+}

package/lib/bootstrap/init-types.ts

@@ -0,0 +1,31 @@
+import type {AppiumDriver} from '../appium';
+import type {
+  Args,
+  CliCommand,
+  CliCommandServer,
+  CliCommandSetupSubcommand,
+  CliExtensionSubcommand,
+  ParsedArgs,
+} from 'appium/types';
+import type {ExtensionConfigs} from '../extension';
+
+/** Empty object returned when `init` completes for non-server CLI flows (extension/setup). */
+export type ExtCommandInitResult = Record<string, never>;
+
+/** Driver/plugin config plus server instance and merged server args after successful server `init`. */
+export type ServerInitData = ExtensionConfigs & {
+  appiumDriver: AppiumDriver;
+  parsedArgs: ParsedArgs<CliCommandServer>;
+  appiumHome: string;
+};
+
+/** Discriminated by CLI command: server subcommand yields {@link ServerInitData}; otherwise {@link ExtCommandInitResult}. */
+export type InitResult<Cmd extends CliCommand = CliCommandServer> = Cmd extends CliCommandServer
+  ? ServerInitData
+  : ExtCommandInitResult;
+
+/** CLI + programmatic args before `init` narrows by `subcommand`. */
+export type PreConfigArgs = Args<
+  CliCommand,
+  CliExtensionSubcommand | CliCommandSetupSubcommand | void
+>;

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;
+  }
+}