appium 3.3.0 → 3.4.0

package/lib/extension/plugin-config.ts

@@ -0,0 +1,62 @@
+import _ from 'lodash';
+import type {PluginType} from '@appium/types';
+import type {ExtManifest, ExtName, ExtRecord} from 'appium/types';
+import {PLUGIN_TYPE} from '../constants';
+import {log} from '../logger';
+import {ExtensionConfig} from './extension-config';
+import type {Manifest} from './manifest';
+
+export class PluginConfig extends ExtensionConfig<PluginType> {
+  private static readonly _instances = new WeakMap<Manifest, PluginConfig>();
+
+  private constructor(manifest: Manifest) {
+    super(PLUGIN_TYPE, manifest);
+  }
+
+  static create(manifest: Manifest): PluginConfig {
+    const instance = new PluginConfig(manifest);
+    if (PluginConfig.getInstance(manifest)) {
+      throw new Error(
+        `Manifest with APPIUM_HOME ${manifest.appiumHome} already has a PluginConfig; use PluginConfig.getInstance() to retrieve it.`
+      );
+    }
+    PluginConfig._instances.set(manifest, instance);
+    return instance;
+  }
+
+  static getInstance(manifest: Manifest): PluginConfig | undefined {
+    return PluginConfig._instances.get(manifest);
+  }
+
+  async validate(): Promise<ExtRecord<PluginType>> {
+    return await super._validate(this.manifest.getExtensionData(PLUGIN_TYPE));
+  }
+
+  public override extensionDesc(
+    pluginName: ExtName<PluginType>,
+    {version}: ExtManifest<PluginType>
+  ): string {
+    return `${String(pluginName)}@${version}`;
+  }
+
+  override print(activeNames: ExtName<PluginType>[] = []): void {
+    const pluginNames = Object.keys(this.installedExtensions);
+
+    if (_.isEmpty(pluginNames)) {
+      log.info(
+        `No plugins have been installed. Use the "appium plugin" ` + 'command to install the one(s) you want to use.'
+      );
+      return;
+    }
+
+    log.info(`Available plugins:`);
+    for (const [pluginName, pluginData] of _.toPairs(this.installedExtensions)) {
+      const activeTxt = _.includes(activeNames, pluginName as ExtName<PluginType>) ? ' (ACTIVE)' : '';
+      log.info(`  - ${this.extensionDesc(pluginName as ExtName<PluginType>, pluginData)}${activeTxt}`);
+    }
+
+    if (_.isEmpty(activeNames)) {
+      log.info('No plugins activated. Use the --use-plugins flag with names of plugins to activate');
+    }
+  }
+}

package/lib/helpers/build.ts

@@ -0,0 +1,111 @@
+import _ from 'lodash';
+import axios from 'axios';
+import {exec} from 'teen_process';
+import {system, fs} from '@appium/support';
+import type {BuildInfo} from 'appium/types';
+import {npmPackage} from '../utils';
+
+export const APPIUM_VER = npmPackage.version;
+export const rootDir = fs.findRoot(__dirname);
+
+const GIT_BINARY = `git${system.isWindows() ? '.exe' : ''}`;
+const GITHUB_API = 'https://api.github.com/repos/appium/appium';
+
+const getFullGitPath = _.memoize(async function getFullGitPath(): Promise<string | null> {
+  try {
+    return await fs.which(GIT_BINARY);
+  } catch {
+    return null;
+  }
+});
+
+/**
+ * Returns the current git commit SHA for this Appium checkout.
+ *
+ * Attempts to read from local git first; when unavailable and fallback is enabled,
+ * queries the GitHub API for the tag matching the current Appium version.
+ */
+export async function getGitRev(useGithubApiFallback = false): Promise<string | null> {
+  const fullGitPath = await getFullGitPath();
+  if (fullGitPath) {
+    try {
+      const {stdout} = await exec(fullGitPath, ['rev-parse', 'HEAD'], {
+        cwd: __dirname,
+      });
+      return stdout.trim();
+    } catch {}
+  }
+
+  if (!useGithubApiFallback) {
+    return null;
+  }
+
+  // If the package folder is not a valid git repository
+  // then fetch the corresponding tag info from GitHub
+  try {
+    return (
+      await axios.get(`${GITHUB_API}/git/refs/tags/appium@${APPIUM_VER}`, {
+        headers: {
+          'User-Agent': `Appium ${APPIUM_VER}`,
+        },
+      })
+    ).data?.object?.sha;
+  } catch {}
+  return null;
+}
+
+async function getGitTimestamp(commitSha: string, useGithubApiFallback = false): Promise<string | null> {
+  const fullGitPath = await getFullGitPath();
+  if (fullGitPath) {
+    try {
+      const {stdout} = await exec(fullGitPath, ['show', '-s', '--format=%ci', commitSha], {
+        cwd: __dirname,
+      });
+      return stdout.trim();
+    } catch {}
+  }
+
+  if (!useGithubApiFallback) {
+    return null;
+  }
+
+  try {
+    return (
+      await axios.get(`${GITHUB_API}/git/tags/${commitSha}`, {
+        headers: {
+          'User-Agent': `Appium ${APPIUM_VER}`,
+        },
+      })
+    ).data?.tagger?.date;
+  } catch {}
+  return null;
+}
+
+const BUILD_INFO: BuildInfo = {
+  version: APPIUM_VER,
+};
+
+/**
+ * Update mutable build info metadata from local git or GitHub fallback.
+ */
+export async function updateBuildInfo(useGithubApiFallback = false): Promise<void> {
+  const sha = await getGitRev(useGithubApiFallback);
+  if (!sha) {
+    return;
+  }
+  BUILD_INFO['git-sha'] = sha;
+  const buildTimestamp = await getGitTimestamp(sha, useGithubApiFallback);
+  if (buildTimestamp) {
+    BUILD_INFO.built = buildTimestamp;
+  }
+}
+
+/**
+ * Mutable object containing Appium build information. By default it
+ * only contains the Appium version, but is updated with the build timestamp
+ * and git commit hash asynchronously as soon as `updateBuildInfo` is called
+ * and succeeds.
+ */
+export function getBuildInfo(): BuildInfo {
+  return BUILD_INFO;
+}

package/lib/helpers/capability.ts

@@ -0,0 +1,171 @@
+import type {
+  BaseDriverCapConstraints,
+  Capabilities,
+  Constraints,
+  NSCapabilities,
+  W3CCapabilities,
+} from '@appium/types';
+import _ from 'lodash';
+import {log as logger} from '../logger';
+import {
+  processCapabilities,
+  STANDARD_CAPS,
+  errors,
+  isW3cCaps,
+} from '@appium/base-driver';
+
+const W3C_APPIUM_PREFIX = 'appium';
+const STANDARD_CAPS_LOWERCASE = new Set([...STANDARD_CAPS].map((cap) => cap.toLowerCase()));
+
+/** Result of successfully parsing W3C capabilities for the inner driver. */
+export interface ParsedDriverCaps<C extends Constraints = BaseDriverCapConstraints> {
+  desiredCaps: Capabilities<C>;
+  processedW3CCapabilities: W3CCapabilities<C>;
+}
+
+/** Result when capability parsing fails or caps are invalid. */
+export interface InvalidCaps<C extends Constraints = BaseDriverCapConstraints> {
+  error: Error;
+  desiredCaps?: Capabilities<C>;
+  processedW3CCapabilities?: W3CCapabilities<C>;
+}
+
+/**
+ * Creates an error when a session receives non-W3C capabilities.
+ */
+export function makeNonW3cCapsError(): Error {
+  return new errors.SessionNotCreatedError(
+    'Session capabilities format must comply to the W3C standard. Make sure your client is up to date. ' +
+      'See https://www.w3.org/TR/webdriver/#new-session for more details.'
+  );
+}
+
+/**
+ * Parses W3C capabilities for the inner driver and applies defaults.
+ *
+ * @returns Parsed caps or an invalid result with an error.
+ */
+export function parseCapsForInnerDriver<C extends Constraints = BaseDriverCapConstraints>(
+  w3cCapabilities: W3CCapabilities<C>,
+  constraints: C = {} as C,
+  defaultCapabilities: NSCapabilities<C> = {}
+): ParsedDriverCaps<C> | InvalidCaps<C> {
+  if (!isW3cCaps(w3cCapabilities)) {
+    return {error: makeNonW3cCapsError()};
+  }
+
+  let desiredCaps: Capabilities<C> = {} as Capabilities<C>;
+  // eslint-disable-next-line prefer-const -- assigned in success path after try
+  let processedW3CCapabilities: W3CCapabilities<C> | undefined;
+
+  w3cCapabilities = _.cloneDeep(w3cCapabilities);
+  defaultCapabilities = _.cloneDeep(defaultCapabilities);
+
+  if (!_.isEmpty(defaultCapabilities)) {
+    for (const [defaultCapKey, defaultCapValue] of _.toPairs(defaultCapabilities)) {
+      let isCapAlreadySet = false;
+      for (const firstMatchEntry of w3cCapabilities.firstMatch ?? []) {
+        if (
+          _.isPlainObject(firstMatchEntry) &&
+          _.has(removeAppiumPrefixes(firstMatchEntry as NSCapabilities<C>), removeAppiumPrefix(defaultCapKey))
+        ) {
+          isCapAlreadySet = true;
+          break;
+        }
+      }
+      isCapAlreadySet =
+        isCapAlreadySet ||
+        (_.isPlainObject(w3cCapabilities.alwaysMatch) &&
+          _.has(
+            removeAppiumPrefixes(w3cCapabilities.alwaysMatch),
+            removeAppiumPrefix(defaultCapKey)
+          ));
+      if (isCapAlreadySet) {
+        continue;
+      }
+
+      if (_.isEmpty(w3cCapabilities.firstMatch)) {
+        w3cCapabilities.firstMatch = [{[defaultCapKey]: defaultCapValue}] as W3CCapabilities<C>['firstMatch'];
+      } else {
+        (w3cCapabilities.firstMatch[0] as Record<string, unknown>)[defaultCapKey] = defaultCapValue;
+      }
+    }
+  }
+
+  try {
+    desiredCaps = processCapabilities(w3cCapabilities, constraints, true) as Capabilities<C>;
+  } catch (error) {
+    logger.info(`Could not parse W3C capabilities: ${(error as Error).message}`);
+    return {
+      desiredCaps,
+      processedW3CCapabilities,
+      error: error as Error,
+    };
+  }
+
+  processedW3CCapabilities = {
+    alwaysMatch: {...insertAppiumPrefixes(desiredCaps)},
+    firstMatch: [{}],
+  } as W3CCapabilities<C>;
+
+  return {
+    desiredCaps,
+    processedW3CCapabilities,
+  };
+}
+
+/**
+ * Prefixes capability keys with `appium:` where appropriate.
+ */
+export function insertAppiumPrefixes<C extends Constraints = BaseDriverCapConstraints>(
+  caps: Capabilities<C>
+): NSCapabilities<C> {
+  return _.mapKeys(caps, (_, key) =>
+    STANDARD_CAPS_LOWERCASE.has(key.toLowerCase()) || key.includes(':')
+      ? key
+      : `${W3C_APPIUM_PREFIX}:${key}`
+  ) as NSCapabilities<C>;
+}
+
+/**
+ * Removes `appium:` prefix from capability keys.
+ */
+export function removeAppiumPrefixes<C extends Constraints = BaseDriverCapConstraints>(
+  caps: NSCapabilities<C>
+): Capabilities<C> {
+  return _.mapKeys(caps, (_, key) => removeAppiumPrefix(key)) as Capabilities<C>;
+}
+
+/**
+ * Pulls Appium settings from capabilities (mutates caps). Supports
+ * `settings[key]: value` and `settings: { key: value }`.
+ *
+ * @returns Parsed settings object; empty if none found.
+ */
+export function pullSettings(caps: Record<string, unknown> | null | undefined): Record<string, unknown> {
+  if (!_.isPlainObject(caps) || _.isEmpty(caps)) {
+    return {};
+  }
+
+  const result: Record<string, unknown> = {};
+  const singleSettings: Record<string, unknown> = {};
+  for (const [key, value] of _.toPairs(caps)) {
+    let match: RegExpExecArray | null;
+    if (/^(s|appium:s)ettings$/.test(key) && _.isPlainObject(value)) {
+      Object.assign(result, value);
+      delete caps[key];
+    } else if ((match = /^(s|appium:s)ettings\[(\S+)\]$/.exec(key))) {
+      singleSettings[match[2]] = value;
+      delete caps[key];
+    }
+  }
+  if (!_.isEmpty(singleSettings)) {
+    Object.assign(result, singleSettings);
+  }
+  return result;
+}
+
+function removeAppiumPrefix(key: string): string {
+  const prefix = `${W3C_APPIUM_PREFIX}:`;
+  return _.startsWith(key, prefix) ? key.substring(prefix.length) : key;
+}

package/lib/helpers/network.ts

@@ -0,0 +1,30 @@
+import _ from 'lodash';
+import os from 'node:os';
+
+export const V4_BROADCAST_IP = '0.0.0.0';
+export const V6_BROADCAST_IP = '::';
+
+/**
+ * Returns network interfaces for the given IP family.
+ *
+ * @param family - 4 for IPv4, 6 for IPv6, or null for all.
+ */
+export function fetchInterfaces(family: 4 | 6 | null = null): os.NetworkInterfaceInfo[] {
+  let familyValue: (4 | 6 | string)[] | null = null;
+  if (family === 4) {
+    familyValue = [4, 'IPv4'];
+  } else if (family === 6) {
+    familyValue = [6, 'IPv6'];
+  }
+  const ifaces = _.values(os.networkInterfaces()).filter(Boolean) as os.NetworkInterfaceInfo[][];
+  return _.flatMap(ifaces).filter(
+    (info) => !familyValue || familyValue.includes(info.family as 4 | 6 | string)
+  );
+}
+
+/**
+ * Returns true if the address is a broadcast IP (0.0.0.0 or ::).
+ */
+export function isBroadcastIp(address: string): boolean {
+  return [V4_BROADCAST_IP, V6_BROADCAST_IP, `[${V6_BROADCAST_IP}]`].includes(address);
+}

package/lib/insecure-features.ts

@@ -1,5 +1,5 @@
 import _ from 'lodash';
-import logger from './logger';
+import {log as logger} from './logger';
 
 import type {AppiumDriver} from './appium';
 import type {ExternalDriver} from '@appium/types';

package/lib/inspector-commands.ts

@@ -21,7 +21,9 @@ import type {
 } from '@appium/types';
 import type {AppiumDriver} from './appium';
 
-
+/**
+ * Returns available REST and BiDi commands for base, driver and plugins.
+ */
 export async function listCommands(this: AppiumDriver, sessionId?: string): Promise<ListCommandsResponse> {
   let driverRestMethodMap: MethodMap<any> = {};
   let driverBiDiCommands: BidiModuleMap = {};
@@ -46,6 +48,9 @@ export async function listCommands(this: AppiumDriver, sessionId?: string): Prom
   };
 }
 
+/**
+ * Returns available execute methods exposed by driver and plugins.
+ */
 export async function listExtensions(this: AppiumDriver, sessionId?: string): Promise<ListExtensionsResponse> {
   let driverExecuteMethodMap: ExecuteMethodMap<any> = {};
   let pluginExecuteMethodMaps: Record<string, ExecuteMethodMap<any>> = {};

package/lib/{logger.js → logger.ts}

@@ -1,6 +1,5 @@
 import {logger} from '@appium/support';
 
 export const APPIUM_LOGGER_NAME = 'Appium';
-let log = logger.getLogger(APPIUM_LOGGER_NAME);
 
-export default log;
+export const log = logger.getLogger(APPIUM_LOGGER_NAME);

package/lib/main.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+import './logsink'; // must run first: global npmlog / log sink setup (see logsink module)
+import './logger'; // load Appium logger immediately after logsink (order matters for log wiring)
+import {env} from '@appium/support';
+import type {AppiumServer} from '@appium/types';
+import type {
+  Args,
+  CliCommand,
+  CliCommandServer,
+  CliCommandSetupSubcommand,
+  CliExtensionSubcommand,
+} from 'appium/types';
+import {AppiumInitializer} from './bootstrap/appium-initializer';
+import {AppiumMainRunner} from './bootstrap/appium-main-runner';
+import type {ExtCommandInitResult, InitResult, ServerInitData} from './bootstrap/init-types';
+
+const initializer = new AppiumInitializer();
+const mainRunner = new AppiumMainRunner();
+
+/**
+ * Initializes Appium, but does not start the server.
+ *
+ * Use this to get at the configuration schema.
+ *
+ * If `args` contains a non-empty `subcommand` which is not `server`, this function will return an empty object.
+ */
+export async function init<
+  Cmd extends CliCommand = CliCommandServer,
+  SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand | void = void,
+>(args?: Args<Cmd, SubCmd>): Promise<InitResult<Cmd>> {
+  return initializer.init(args);
+}
+
+/**
+ * Initializes Appium's config. Starts server if appropriate and resolves the
+ * server instance if so; otherwise resolves with `undefined`.
+ */
+export async function main<
+  Cmd extends CliCommand = CliCommandServer,
+  SubCmd extends CliExtensionSubcommand | CliCommandSetupSubcommand | void = void,
+>(args?: Args<Cmd, SubCmd>): Promise<Cmd extends CliCommandServer ? AppiumServer : void> {
+  const initResult = await init(args);
+  return mainRunner.run(initResult, args);
+}
+
+// NOTE: backwards compat for scripts referencing `build/lib/main.js` directly.
+// The executable is `../index.js`, so that module will typically be `require.main`.
+if (require.main === module) {
+  void main();
+}
+
+// Re-export helpers from the same package so `import { … } from 'appium'` stays a supported
+// programmatic API (this file is the package `types` entry). The monorepo does not import these
+// from `'appium'`; consumers use local paths or `@appium/support`. Dropping them is semver-major.
+export {readConfigFile} from './bootstrap/config-file';
+export {finalizeSchema, getSchema, validate} from './schema/schema';
+export const resolveAppiumHome = env.resolveAppiumHome;
+
+export type {ExtCommandInitResult, InitResult, ServerInitData};

package/lib/schema/cli-args-guards.ts

@@ -0,0 +1,67 @@
+import type {
+  Args,
+  CliCommand,
+  CliCommandDriver,
+  CliCommandPlugin,
+  CliCommandServer,
+  CliCommandSetup,
+  CliExtensionCommand,
+  CliExtensionSubcommand,
+  CliCommandSetupSubcommand,
+} from 'appium/types';
+import {SERVER_SUBCOMMAND, DRIVER_TYPE, PLUGIN_TYPE, SETUP_SUBCOMMAND} from '../constants';
+
+type AnyArgs = Args<CliCommand, CliExtensionSubcommand | CliCommandSetupSubcommand | void>;
+
+/**
+ * Type guard: args are for the server command.
+ *
+ * @param args - Parsed args before full subcommand-specific narrowing
+ */
+export function isServerCommandArgs(args: AnyArgs): args is Args<CliCommandServer, void> {
+  return args.subcommand === SERVER_SUBCOMMAND;
+}
+
+/**
+ * Type guard: args are for the setup command.
+ *
+ * @param args - Parsed args before full subcommand-specific narrowing
+ */
+export function isSetupCommandArgs(
+  args: AnyArgs
+): args is Args<CliCommandSetup, CliCommandSetupSubcommand> {
+  return args.subcommand === SETUP_SUBCOMMAND;
+}
+
+/**
+ * Type guard: args are for an extension command (driver or plugin).
+ *
+ * @param args - Parsed args before full subcommand-specific narrowing
+ */
+export function isExtensionCommandArgs(
+  args: AnyArgs
+): args is Args<CliExtensionCommand, CliExtensionSubcommand> {
+  return args.subcommand === DRIVER_TYPE || args.subcommand === PLUGIN_TYPE;
+}
+
+/**
+ * Type guard: args are for a driver extension command.
+ *
+ * @param args - Parsed args before full subcommand-specific narrowing
+ */
+export function isDriverCommandArgs(
+  args: AnyArgs
+): args is Args<CliCommandDriver, CliExtensionSubcommand> {
+  return args.subcommand === DRIVER_TYPE;
+}
+
+/**
+ * Type guard: args are for a plugin extension command.
+ *
+ * @param args - Parsed args before full subcommand-specific narrowing
+ */
+export function isPluginCommandArgs(
+  args: AnyArgs
+): args is Args<CliCommandPlugin, CliExtensionSubcommand> {
+  return args.subcommand === PLUGIN_TYPE;
+}

package/lib/schema/cli-args.ts

@@ -1,7 +1,7 @@
 import {ArgumentTypeError, type ArgumentOptions} from 'argparse';
 import _ from 'lodash';
 import type {JSONSchema7, JSONSchema7TypeName} from 'json-schema';
-import {formatErrors} from '../config-file';
+import {formatErrors} from './format-errors';
 import {flattenSchema, validate} from './schema';
 import {transformers, parseCsvLine} from './cli-transformers';
 import type {ArgSpec} from './arg-spec';

package/lib/schema/cli-transformers.ts

@@ -41,7 +41,7 @@ export const transformers = {
       const msg = loadedFromFile
         ? `The provided value of '${csvOrPath}' must be a valid CSV`
         : `Must be a comma-delimited string, e.g., "foo,bar,baz"`;
-      throw new TypeError(`${msg}. Original error: ${(err as Error).message}`);
+      throw new TypeError(`${msg}. Original error: ${(err as Error).message}`, {cause: err});
     }
   },
 
@@ -66,7 +66,7 @@ export const transformers = {
       const msg = loadedFromFile
         ? `'${jsonOrPath}' must be a valid JSON`
         : `The provided value must be a valid JSON`;
-      throw new TypeError(`${msg}. Original error: ${(e as Error).message}`);
+      throw new TypeError(`${msg}. Original error: ${(e as Error).message}`, {cause: e});
     }
   },
 } as const;

package/lib/schema/format-errors.ts

@@ -0,0 +1,43 @@
+import betterAjvErrors, {type IOutputError} from '@sidvind/better-ajv-errors';
+import type {ErrorObject} from 'ajv';
+import type {NormalizedAppiumConfig} from '@appium/types';
+import {getSchema} from './schema';
+
+/**
+ * The string should be a raw JSON string.
+ */
+export type RawJson = string;
+
+/**
+ * Options for {@link formatErrors}.
+ */
+export interface FormatConfigErrorsOptions {
+  json?: RawJson;
+  pretty?: boolean;
+  schemaId?: string;
+}
+
+/**
+ * Given an array of errors and the result of loading a config file, generate a
+ * helpful string for the user.
+ *
+ * - If `opts` contains a `json` property, this should be the original JSON
+ *   _string_ of the config file.  This is only applicable if the config file
+ *   was in JSON format. If present, it will associate line numbers with errors.
+ * - If `errors` happens to be empty, this will throw.
+ *
+ * @throws {TypeError} If `errors` is empty
+ */
+export function formatErrors(
+  errors: ErrorObject[] = [],
+  config: NormalizedAppiumConfig | Record<string, unknown> | string | undefined = {},
+  opts: FormatConfigErrorsOptions = {}
+): string | IOutputError[] {
+  if (errors && !errors.length) {
+    throw new TypeError('Array of errors must be non-empty');
+  }
+  return betterAjvErrors(getSchema(opts.schemaId), config, errors, {
+    json: opts.json,
+    format: opts.pretty === false ? 'js' : 'cli',
+  });
+}

package/lib/schema/index.ts

@@ -1,2 +1,4 @@
 export * from './schema';
+export * from './format-errors';
 export * from './cli-args';
+export * from './cli-args-guards';