appium 3.2.2 → 3.3.1

package/lib/bidi-commands.ts

@@ -5,11 +5,7 @@ import {errors} from '@appium/base-driver';
 import {BIDI_BASE_PATH, BIDI_EVENT_NAME} from './constants';
 import WebSocket from 'ws';
 import os from 'node:os';
-import {
-  isBroadcastIp,
-  fetchInterfaces,
-  V4_BROADCAST_IP,
-} from './utils';
+import {isBroadcastIp, fetchInterfaces, V4_BROADCAST_IP} from './helpers/network';
 import type {IncomingMessage} from 'node:http';
 import type {AppiumDriver} from './appium';
 import type {
@@ -99,15 +95,6 @@ export function onBidiConnection(this: AppiumDriver, ws: WebSocket, req: Incomin
   }
 }
 
-function wrapCommandWithPlugins(driver: ExtensionCore, plugins: ExtensionCore[], method: string, params: StringRecord): () => Promise<BiDiResultData> {
-    const [moduleName, methodName] = method.split('.');
-    let next = async () => await driver.executeBidiCommand(method, params);
-    for (const plugin of plugins.filter((p) => p.doesBidiCommandExist(moduleName, methodName))) {
-      next = ((_next) => async () => await plugin.executeBidiCommand(method, params, _next, driver))(next);
-    }
-    return next;
-}
-
 /**
  * @param data
  * @param driver
@@ -204,6 +191,15 @@ export function cleanupBidiSockets(this: AppiumDriver, sessionId: string): void
   delete this.bidiProxyClients[sessionId];
 }
 
+function wrapCommandWithPlugins(driver: ExtensionCore, plugins: ExtensionCore[], method: string, params: StringRecord): () => Promise<BiDiResultData> {
+  const [moduleName, methodName] = method.split('.');
+  let next = async () => await driver.executeBidiCommand(method, params);
+  for (const plugin of plugins.filter((p) => p.doesBidiCommandExist(moduleName, methodName))) {
+    next = ((_next) => async () => await plugin.executeBidiCommand(method, params, _next, driver))(next);
+  }
+  return next;
+}
+
 // #region Private functions
 
 /**

package/lib/bootstrap/appium-initializer.ts

@@ -0,0 +1,212 @@
+import {init as logsinkInit} from '../logsink';
+import {log as logger} from '../logger';
+import {util, env} from '@appium/support';
+import _ from 'lodash';
+import type {DriverOpts} from '@appium/types';
+import {AppiumDriver, type AppiumDriverConstraints} from '../appium';
+import {runExtensionCommand} from '../cli/extension';
+import {runSetupCommand} from '../cli/setup-command';
+import {getParser, ArgParser} from '../cli/parser';
+import {readConfigFile} from './config-file';
+import {getNonDefaultServerArgs, showConfig} from './startup-config';
+import {adjustNodePath, requireDir, showDebugInfo} from './node-helpers';
+import {loadExtensions, type ExtensionConfigs} from '../extension';
+import {SERVER_SUBCOMMAND} from '../constants';
+import {injectAppiumSymlinks} from '../cli/extension-command';
+import {getDefaultsForSchema} from '../schema/schema';
+import {
+  isDriverCommandArgs,
+  isExtensionCommandArgs,
+  isPluginCommandArgs,
+  isServerCommandArgs,
+  isSetupCommandArgs,
+} from '../schema/cli-args-guards';
+import type {
+  Args,
+  CliCommand,
+  CliCommandServer,
+  CliCommandSetupSubcommand,
+  CliExtensionSubcommand,
+  ParsedArgs,
+} from 'appium/types';
+import {determineAppiumHomeSource, preflightChecks} from './main-helpers';
+import type {InitResult, PreConfigArgs} from './init-types';
+
+/**
+ * Parses CLI/programmatic args, loads config and extensions, and returns server-ready state or runs extension/setup flows.
+ */
+export class AppiumInitializer {
+  private throwInsteadOfExit = false;
+
+  /**
+   * Resolves Appium home, loads config, and either returns server-ready state for the server subcommand
+   * or performs setup/extension CLI work and returns an empty result.
+   *
+   * @param args - Optional programmatic args; when omitted, parses `process.argv`
+   */
+  async init<
+    Cmd extends CliCommand = CliCommandServer,
+    SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand | void = void,
+  >(args?: Args<Cmd, SubCmd>): Promise<InitResult<Cmd>> {
+    this.throwInsteadOfExit = false;
+
+    const appiumHome = args?.appiumHome ?? (await env.resolveAppiumHome());
+    const appiumHomeSourceName = determineAppiumHomeSource(args?.appiumHome);
+    await requireDir(appiumHome, false, appiumHomeSourceName);
+
+    adjustNodePath();
+
+    const {driverConfig, pluginConfig} = await loadExtensions(appiumHome);
+
+    const {preConfigArgs, throwInsteadOfExit} = await this.parsePreConfigArgs(args);
+    this.throwInsteadOfExit = throwInsteadOfExit;
+
+    const configResult = await readConfigFile(preConfigArgs.configFile);
+    this.assertConfigFileOk(configResult);
+
+    if (isServerCommandArgs(preConfigArgs)) {
+      return this.finishServerInit(
+        preConfigArgs,
+        configResult,
+        driverConfig,
+        pluginConfig,
+        appiumHome,
+        appiumHomeSourceName,
+      );
+    }
+
+    if (isSetupCommandArgs(preConfigArgs)) {
+      await runSetupCommand(preConfigArgs, driverConfig, pluginConfig);
+      return {} as InitResult<Cmd>;
+    }
+
+    await requireDir(appiumHome, true, appiumHomeSourceName);
+    await this.runExtensionCliIfNeeded(preConfigArgs, driverConfig, pluginConfig);
+    return {} as InitResult<Cmd>;
+  }
+
+  private async parsePreConfigArgs<
+    Cmd extends CliCommand,
+    SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand | void,
+  >(args?: Args<Cmd, SubCmd>): Promise<{preConfigArgs: PreConfigArgs; throwInsteadOfExit: boolean}> {
+    const parser = await getParser();
+    let throwInsteadOfExit = false;
+
+    if (args) {
+      if (args.throwInsteadOfExit) {
+        throwInsteadOfExit = true;
+        delete args.throwInsteadOfExit;
+      }
+      const preConfigArgs = {...args, subcommand: args.subcommand ?? SERVER_SUBCOMMAND} as PreConfigArgs;
+      ArgParser.normalizeServerArgs(preConfigArgs);
+      return {preConfigArgs, throwInsteadOfExit};
+    }
+
+    return {preConfigArgs: parser.parseArgs() as PreConfigArgs, throwInsteadOfExit};
+  }
+
+  private assertConfigFileOk(configResult: Awaited<ReturnType<typeof readConfigFile>>): void {
+    if (!_.isEmpty(configResult.errors)) {
+      throw new Error(
+        `Errors in config file ${configResult.filepath}:\n ${configResult.reason ?? configResult.errors}`,
+      );
+    }
+  }
+
+  private async finishServerInit<Cmd extends CliCommand>(
+    preConfigArgs: PreConfigArgs,
+    configResult: Awaited<ReturnType<typeof readConfigFile>>,
+    driverConfig: ExtensionConfigs['driverConfig'],
+    pluginConfig: ExtensionConfigs['pluginConfig'],
+    appiumHome: string,
+    appiumHomeSourceName: string,
+  ): Promise<InitResult<Cmd>> {
+    const defaults = getDefaultsForSchema(false);
+    const serverArgs = _.defaultsDeep(
+      {},
+      preConfigArgs,
+      configResult.config?.server,
+      defaults,
+    ) as ParsedArgs<CliCommandServer>;
+
+    if (preConfigArgs.showConfig) {
+      showConfig(getNonDefaultServerArgs(preConfigArgs as Args), configResult, defaults, serverArgs);
+      return {} as InitResult<Cmd>;
+    }
+
+    if (preConfigArgs.showDebugInfo) {
+      await showDebugInfo({
+        driverConfig,
+        pluginConfig,
+        appiumHome,
+      });
+      return {} as InitResult<Cmd>;
+    }
+
+    await logsinkInit(serverArgs);
+    await this.applyLogFilters(serverArgs);
+
+    if (!serverArgs.noPermsCheck) {
+      await requireDir(appiumHome, true, appiumHomeSourceName);
+    }
+
+    const appiumDriver = new AppiumDriver(serverArgs as DriverOpts<AppiumDriverConstraints>);
+    appiumDriver.driverConfig = driverConfig;
+    await preflightChecks(serverArgs, this.throwInsteadOfExit);
+
+    return {
+      appiumDriver,
+      parsedArgs: serverArgs,
+      driverConfig,
+      pluginConfig,
+      appiumHome,
+    } as InitResult<Cmd>;
+  }
+
+  private async applyLogFilters(serverArgs: ParsedArgs<CliCommandServer>): Promise<void> {
+    if (!serverArgs.logFilters) {
+      return;
+    }
+    const {issues, rules} = await logger.unwrap().loadSecureValuesPreprocessingRules(serverArgs.logFilters);
+    const argToLog = _.truncate(JSON.stringify(serverArgs.logFilters), {
+      length: 150,
+    });
+    if (!_.isEmpty(issues)) {
+      throw new Error(
+        `The log filtering rules config ${argToLog} has issues: ` + JSON.stringify(issues, null, 2),
+      );
+    }
+    if (_.isEmpty(rules)) {
+      logger.warn(
+        `Found no log filtering rules in the ${argToLog} config. ` + `Is that expected?`,
+      );
+    } else {
+      logger.info(`Loaded ${util.pluralize('filtering rule', rules.length, true)}`);
+    }
+  }
+
+  private async runExtensionCliIfNeeded(
+    preConfigArgs: PreConfigArgs,
+    driverConfig: ExtensionConfigs['driverConfig'],
+    pluginConfig: ExtensionConfigs['pluginConfig'],
+  ): Promise<void> {
+    if (!isExtensionCommandArgs(preConfigArgs)) {
+      return;
+    }
+    if (isDriverCommandArgs(preConfigArgs)) {
+      await runExtensionCommand(preConfigArgs, driverConfig);
+    }
+    if (isPluginCommandArgs(preConfigArgs)) {
+      await runExtensionCommand(preConfigArgs, pluginConfig);
+    }
+
+    if (isDriverCommandArgs(preConfigArgs) || isPluginCommandArgs(preConfigArgs)) {
+      const cmd = isDriverCommandArgs(preConfigArgs)
+        ? preConfigArgs.driverCommand
+        : preConfigArgs.pluginCommand;
+      if (cmd === 'install') {
+        await injectAppiumSymlinks(driverConfig, pluginConfig, logger);
+      }
+    }
+  }
+}

package/lib/bootstrap/appium-main-runner.ts

@@ -0,0 +1,172 @@
+import {log as logger} from '../logger';
+import _ from 'lodash';
+import type {AppiumServer} from '@appium/types';
+import {getActivePlugins, getActiveDrivers} from '../extension';
+import registerNode from './grid-v3-register';
+import {
+  determineAppiumHomeSource,
+  logStartupInfo,
+  buildServerOpts,
+  createAppiumServer,
+  logServerAddress,
+} from './main-helpers';
+import type {InitResult, ServerInitData} from './init-types';
+import type {
+  Args,
+  CliCommand,
+  CliCommandServer,
+  CliCommandSetupSubcommand,
+  CliExtensionSubcommand,
+} from 'appium/types';
+import type {ServerOpts} from '@appium/base-driver';
+import net from 'node:net';
+
+const MAX_SERVER_PROCESS_LISTENERS = 100;
+
+/**
+ * Starts the Appium HTTP server after {@link AppiumInitializer.init}: loads drivers/plugins, binds, grid register, signals.
+ */
+export class AppiumMainRunner {
+  /**
+   * For server init: builds listeners, registers with Grid 3 if configured, and returns the server.
+   * For non-server commands, `initResult` is empty and this resolves to `undefined`.
+   *
+   * @param initResult - Output of {@link AppiumInitializer.init}
+   * @param args - Original args (used to describe `appiumHome` source in logs)
+   */
+  async run<
+    Cmd extends CliCommand = CliCommandServer,
+    SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand | void = void,
+  >(initResult: InitResult<Cmd>, args?: Args<Cmd, SubCmd>): Promise<Cmd extends CliCommandServer ? AppiumServer : void> {
+    if (_.isEmpty(initResult)) {
+      return undefined as Cmd extends CliCommandServer ? AppiumServer : void;
+    }
+
+    const {appiumDriver, pluginConfig, driverConfig, parsedArgs, appiumHome} = initResult as ServerInitData;
+
+    const pluginClasses = await getActivePlugins(
+      pluginConfig,
+      parsedArgs.pluginsImportChunkSize,
+      parsedArgs.usePlugins,
+    );
+    for (const [pluginClass, name] of pluginClasses) {
+      appiumDriver.pluginClasses.set(pluginClass, name);
+    }
+
+    await logStartupInfo(parsedArgs);
+
+    appiumDriver.configureGlobalFeatures();
+
+    const appiumHomeSourceName = determineAppiumHomeSource(args?.appiumHome);
+    logger.debug(`The ${appiumHomeSourceName}: ${appiumHome}`);
+
+    const driverClasses = await getActiveDrivers(
+      driverConfig,
+      parsedArgs.driversImportChunkSize,
+      parsedArgs.useDrivers,
+    );
+    const {serverOpts, normalizedBasePath} = buildServerOpts(
+      appiumDriver,
+      parsedArgs,
+      driverClasses,
+      pluginClasses,
+    );
+
+    const server = await this.startHttpServer(serverOpts, appiumDriver, normalizedBasePath);
+    if (!server) {
+      return undefined as Cmd extends CliCommandServer ? AppiumServer : void;
+    }
+
+    this.warnIfCorsEnabled(parsedArgs);
+    appiumDriver.server = server;
+
+    await this.registerGridOrClose(server, parsedArgs, normalizedBasePath);
+    this.attachSignalHandlers(appiumDriver, server);
+    this.logListeningUrl(server, parsedArgs, normalizedBasePath);
+
+    driverConfig.print();
+    pluginConfig.print([...pluginClasses.values()]);
+
+    return server as Cmd extends CliCommandServer ? AppiumServer : void;
+  }
+
+  private async startHttpServer(
+    serverOpts: ServerOpts,
+    appiumDriver: ServerInitData['appiumDriver'],
+    normalizedBasePath: string,
+  ): Promise<AppiumServer | undefined> {
+    try {
+      return await createAppiumServer(serverOpts, appiumDriver, normalizedBasePath);
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : String(err);
+      const stack = err instanceof Error ? err.stack : undefined;
+      logger.error(
+        `Could not configure Appium server. It's possible that a driver or plugin tried ` +
+          `to update the server and failed. Original error: ${message}`,
+      );
+      logger.debug(stack);
+      process.exit(1);
+      return undefined;
+    }
+  }
+
+  private warnIfCorsEnabled(parsedArgs: ServerInitData['parsedArgs']): void {
+    if (parsedArgs.allowCors) {
+      logger.warn(
+        'You have enabled CORS requests from any host. Be careful not ' +
+          'to visit sites which could maliciously try to start Appium ' +
+          'sessions on your machine',
+      );
+    }
+  }
+
+  private async registerGridOrClose(
+    server: AppiumServer,
+    parsedArgs: ServerInitData['parsedArgs'],
+    normalizedBasePath: string,
+  ): Promise<void> {
+    try {
+      if (parsedArgs.nodeconfig) {
+        await registerNode(
+          parsedArgs.nodeconfig,
+          parsedArgs.address,
+          parsedArgs.port,
+          normalizedBasePath,
+        );
+      }
+    } catch (err: unknown) {
+      await server.close();
+      throw err;
+    }
+  }
+
+  private attachSignalHandlers(
+    appiumDriver: ServerInitData['appiumDriver'],
+    server: AppiumServer,
+  ): void {
+    process.setMaxListeners(MAX_SERVER_PROCESS_LISTENERS);
+    for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+      process.once(signal, async function onSignal() {
+        logger.info(`Received ${signal} - shutting down`);
+        try {
+          await appiumDriver.shutdown(`The process has received ${signal} signal`);
+          await server.close();
+          process.exit(0);
+        } catch (e: unknown) {
+          logger.warn(e);
+          process.exit(1);
+        }
+      });
+    }
+  }
+
+  private logListeningUrl(
+    server: AppiumServer,
+    parsedArgs: ServerInitData['parsedArgs'],
+    normalizedBasePath: string,
+  ): void {
+    const protocol = server.isSecure() ? 'https' : 'http';
+    const address = net.isIPv6(parsedArgs.address) ? `[${parsedArgs.address}]` : parsedArgs.address;
+    logServerAddress(`${protocol}://${address}:${parsedArgs.port}${normalizedBasePath}`);
+  }
+}

package/lib/bootstrap/config-file.ts

@@ -0,0 +1,178 @@
+import type {IOutputError} from '@sidvind/better-ajv-errors';
+import type {ErrorObject, SchemaObject} from 'ajv';
+import {lilconfig, type LoaderSync, type LilconfigResult} from 'lilconfig';
+import _ from 'lodash';
+import * as yaml from 'yaml';
+import type {AppiumConfig, NormalizedAppiumConfig} from '@appium/types';
+import {getSchema, validate} from '../schema/schema';
+import {formatErrors} from '../schema/format-errors';
+
+/**
+ * A cache of the raw config file (a JSON string) at a filepath.
+ * This is used for better error reporting.
+ * Note that config files needn't be JSON, but it helps if they are.
+ */
+const rawConfig = new Map<string, string>();
+
+/**
+ * Result of calling {@link readConfigFile}.
+ */
+export interface ReadConfigFileResult {
+  errors?: ErrorObject[];
+  filepath?: string;
+  isEmpty?: boolean;
+  config?: NormalizedAppiumConfig;
+  reason?: string | IOutputError[];
+}
+
+/**
+ * Options for {@link readConfigFile}.
+ */
+export interface ReadConfigFileOptions {
+  pretty?: boolean;
+}
+
+/**
+ * This is an `AsyncSearcher` which is inexplicably _not_ exported by the `lilconfig` type definition.
+ */
+type LilconfigAsyncSearcher = ReturnType<typeof lilconfig>;
+
+/**
+ * Given an optional path, read a config file. Validates the config file.
+ *
+ * Call {@link validate} if you already have a config object.
+ * @public
+ * @param filepath - Explicit config path; when omitted, searches with lilconfig
+ * @param opts - e.g. `pretty` for formatted validation errors
+ * @returns Contains config and filepath, if found, and any errors
+ */
+export async function readConfigFile(
+  filepath?: string,
+  opts: ReadConfigFileOptions = {}
+): Promise<ReadConfigFileResult> {
+  const lc = lilconfig('appium', {
+    loaders: {
+      '.yaml': yamlLoader as LoaderSync,
+      '.yml': yamlLoader as LoaderSync,
+      '.json': jsonLoader as LoaderSync,
+      noExt: jsonLoader as LoaderSync,
+    },
+    packageProp: 'appiumConfig',
+  });
+
+  const result = filepath ? await loadConfigFile(lc, filepath) : await searchConfigFile(lc);
+
+  if (result?.filepath && !result?.isEmpty) {
+    const {pretty = true} = opts;
+    try {
+      let configResult: ReadConfigFileResult;
+      const errors = validate(result.config) as ErrorObject[];
+      if (_.isEmpty(errors)) {
+        configResult = {...result, errors};
+      } else {
+        const reason = formatErrors(errors, result.config as Record<string, unknown>, {
+          json: rawConfig.get(result.filepath),
+          pretty,
+        });
+        configResult = reason ? {...result, errors, reason} : {...result, errors};
+      }
+
+      // normalize (to camel case) all top-level property names of the config file
+      configResult.config = normalizeConfig(configResult.config as AppiumConfig);
+
+      return configResult;
+    } finally {
+      // clean up the raw config file cache, which is only kept to better report errors.
+      rawConfig.delete(result.filepath);
+    }
+  }
+  return result ?? {};
+}
+
+/**
+ * Converts schema property names to either the `appiumCliDest` value, if any, or camelCase.
+ *
+ * @param config - Raw config object as parsed from file
+ * @returns New object with camel-cased keys (or CLI `dest` keys).
+ */
+export function normalizeConfig(config: AppiumConfig): NormalizedAppiumConfig {
+  const schema = getSchema();
+
+  const isSchemaTypeObject = (schemaObj: SchemaObject | Record<string, unknown> | undefined): boolean =>
+    Boolean((schemaObj as SchemaObject | undefined)?.properties || (schemaObj as SchemaObject | undefined)?.type === 'object');
+
+  const normalize = (rootConfig: AppiumConfig, section?: string): Record<string, unknown> => {
+    const obj = _.isUndefined(section)
+      ? rootConfig
+      : (_.get(rootConfig, section, rootConfig) as Record<string, unknown>);
+
+    const mappedObj = _.mapKeys(obj, (_v, prop) =>
+      _.get(schema, `properties.server.properties[${prop}].appiumCliDest`, _.camelCase(prop))
+    );
+
+    return _.mapValues(mappedObj, (value, property) => {
+      const nextSection = section ? `${section}.${property}` : property;
+      return isSchemaTypeObject((schema as any).properties?.[property])
+        ? normalize(rootConfig, nextSection)
+        : value;
+    });
+  };
+
+  return normalize(config) as NormalizedAppiumConfig;
+}
+
+/**
+ * lilconfig loader to handle `.yaml` files
+ */
+function yamlLoader(filepath: string, content: string): unknown {
+  try {
+    return yaml.parse(content);
+  } catch (e) {
+    throw new Error(
+      `The YAML config at '${filepath}' cannot be loaded. Original error: ${(e as Error).message}`
+    );
+  }
+}
+
+/**
+ * Custom JSON loader that caches the raw config file (for use with `better-ajv-errors`).
+ * If it weren't for this cache, this would be unnecessary.
+ */
+function jsonLoader(filepath: string, content: string): unknown {
+  rawConfig.set(filepath, content);
+  try {
+    return JSON.parse(content);
+  } catch (e) {
+    rawConfig.delete(filepath);
+    throw new Error(
+      `The JSON config at '${filepath}' cannot be loaded. Original error: ${(e as Error).message}`
+    );
+  }
+}
+
+/**
+ * Loads a config file from an explicit path
+ */
+async function loadConfigFile(lc: LilconfigAsyncSearcher, filepath: string): Promise<LilconfigResult> {
+  try {
+    // removing "await" will cause any rejection to _not_ be caught in this block!
+    return await lc.load(filepath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      (err as NodeJS.ErrnoException).message = `Config file not found at user-provided path: ${filepath}`;
+      throw err;
+    } else if (err instanceof SyntaxError) {
+      // generally invalid JSON
+      err.message = `Config file at user-provided path ${filepath} is invalid:\n${err.message}`;
+      throw err;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Searches for a config file
+ */
+async function searchConfigFile(lc: LilconfigAsyncSearcher): Promise<LilconfigResult> {
+  return await lc.search();
+}