appium 3.2.2 → 3.3.1

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);