appium 3.0.0-beta.1 → 3.0.0-rc.2

package/lib/extension/driver-config.js

@@ -84,20 +84,18 @@ export class DriverConfig extends ExtensionConfig {
         err: 'Missing or incorrect supported platformNames list.',
         val: platformNames,
       });
+    } else if (_.isEmpty(platformNames)) {
+      problems.push({
+        err: 'Empty platformNames list.',
+        val: platformNames,
+      });
     } else {
-      if (_.isEmpty(platformNames)) {
-        problems.push({
-          err: 'Empty platformNames list.',
-          val: platformNames,
-        });
-      } else {
-        for (const pName of platformNames) {
-          if (!_.isString(pName)) {
-            problems.push({
-              err: 'Incorrectly formatted platformName.',
-              val: pName,
-            });
-          }
+      for (const pName of platformNames) {
+        if (!_.isString(pName)) {
+          problems.push({
+            err: 'Incorrectly formatted platformName.',
+            val: pName,
+          });
         }
       }
     }

package/lib/extension/extension-config.js

@@ -240,20 +240,17 @@ export class ExtensionConfig {
       for (const summary of errorSummaries) {
         log.error(summary);
       }
-    } else {
+    } else if (!_.isEmpty(warningSummaries)) {
       // only display warnings if there are no errors!
-
-      if (!_.isEmpty(warningSummaries)) {
-        log.warn(
-          `Appium encountered ${util.pluralize(
-            'warning',
-            warningMap.size,
-            true
-          )} while validating ${this.extensionType}s found in manifest ${this.manifestPath}`
-        );
-        for (const summary of warningSummaries) {
-          log.warn(summary);
-        }
+      log.warn(
+        `Appium encountered ${util.pluralize(
+          'warning',
+          warningMap.size,
+          true
+        )} while validating ${this.extensionType}s found in manifest ${this.manifestPath}`
+      );
+      for (const summary of warningSummaries) {
+        log.warn(summary);
       }
     }
     return exts;
@@ -464,7 +461,7 @@ export class ExtensionConfig {
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   getConfigProblems(extManifest, extName) {
-    // shoud override this method if special validation is necessary for this extension type
+    // should override this method if special validation is necessary for this extension type
     return [];
   }
 

package/lib/extension/manifest.js

@@ -390,19 +390,17 @@ export class Manifest {
         if (err.code === 'ENOENT') {
           data = _.cloneDeep(INITIAL_MANIFEST_DATA);
           shouldWrite = true;
+        } else if (this.#manifestPath) {
+          throw new Error(
+            `Appium had trouble loading the extension installation ` +
+              `cache file (${this.#manifestPath}). It may be invalid YAML. Specific error: ${
+                err.message
+              }`
+          );
         } else {
-          if (this.#manifestPath) {
-            throw new Error(
-              `Appium had trouble loading the extension installation ` +
-                `cache file (${this.#manifestPath}). It may be invalid YAML. Specific error: ${
-                  err.message
-                }`
-            );
-          } else {
-            throw new Error(
-              `Appium encountered an unknown problem. Specific error: ${err.message}`
-            );
-          }
+          throw new Error(
+            `Appium encountered an unknown problem. Specific error: ${err.message}`
+          );
         }
       }
 

package/lib/insecure-features.ts

@@ -0,0 +1,129 @@
+import _ from 'lodash';
+import logger from './logger';
+
+import type {AppiumDriver} from './appium';
+import type {ExternalDriver} from '@appium/types';
+
+const ALL_DRIVERS_MATCH = '*';
+const FEATURE_NAME_SEPARATOR = ':';
+
+/**
+ * Configures insecure features according to the values in `args.relaxedSecurityEnabled`,
+ * `args.allowInsecure`, and `args.denyInsecure`, and informs the user about any
+ * globally-applied features.
+ * Uses `logger` instead of `this.log` to reduce user confusion.
+ */
+export function configureGlobalFeatures(this: AppiumDriver) {
+  if (this.args.relaxedSecurityEnabled) {
+    logger.info(
+      `Enabling relaxed security. All insecure features will be ` +
+        `enabled unless explicitly disabled by --deny-insecure`,
+    );
+    this.relaxedSecurityEnabled = true;
+  } else if (!_.isEmpty(this.args.allowInsecure)) {
+    this.allowInsecure = validateFeatures(this.args.allowInsecure);
+    const globalAllowedFeatures = filterInsecureFeatures(this.allowInsecure);
+    if (!_.isEmpty(globalAllowedFeatures)) {
+      logger.info('Explicitly enabling insecure features:');
+      globalAllowedFeatures.forEach((a) => logger.info(`    ${a}`));
+    }
+  }
+  if (_.isEmpty(this.args.denyInsecure)) {
+    return;
+  }
+  this.denyInsecure = validateFeatures(this.args.denyInsecure);
+  const globalDeniedFeatures = filterInsecureFeatures(this.denyInsecure);
+  if (_.isEmpty(globalDeniedFeatures)) {
+    return;
+  }
+  logger.info('Explicitly disabling insecure features:');
+  globalDeniedFeatures.forEach((a) => logger.info(`    ${a}`));
+}
+
+/**
+ * If anything in the umbrella driver's insecure feature configuration applies to this driver,
+ * assign it to the driver instance
+ *
+ * @param driver
+ * @param driverName
+ */
+export function configureDriverFeatures(
+  this: AppiumDriver,
+  driver: ExternalDriver,
+  driverName: string,
+) {
+  if (this.relaxedSecurityEnabled) {
+    this.log.info(
+      `Enabling relaxed security for this session as per the server configuration. ` +
+        `All insecure features will be enabled unless explicitly disabled by --deny-insecure`,
+    );
+    driver.relaxedSecurityEnabled = true;
+  }
+  const allowedDriverFeatures = filterInsecureFeatures(this.allowInsecure, driverName);
+  if (!_.isEmpty(allowedDriverFeatures)) {
+    this.log.info('Explicitly enabling insecure features for this session ' +
+      'as per the server configuration:',
+    );
+    allowedDriverFeatures.forEach((a) => this.log.info(`    ${a}`));
+    driver.allowInsecure = allowedDriverFeatures;
+  }
+  const deniedDriverFeatures = filterInsecureFeatures(this.denyInsecure, driverName);
+  if (_.isEmpty(deniedDriverFeatures)) {
+    return;
+  }
+  this.log.info('Explicitly disabling insecure features for this session ' +
+    'as per the server configuration:',
+  );
+  deniedDriverFeatures.forEach((a) => this.log.info(`    ${a}`));
+  driver.denyInsecure = deniedDriverFeatures;
+}
+
+/**
+ * Validates the list of allowed/denied server features
+ *
+ * @param features
+ */
+function validateFeatures(features: string[]): string[] {
+  const validator = (fullName: string) => {
+    const errMsg = `The full feature name must include both the destination automation name or the ` +
+      `'${ALL_DRIVERS_MATCH}' wildcard to apply the feature to all installed drivers, and ` +
+      `the feature name split by a colon. Got '${fullName}' instead`;
+
+    const separatorPos = fullName.indexOf(FEATURE_NAME_SEPARATOR);
+    if (separatorPos < 0) {
+      throw new Error(errMsg);
+    }
+    const [automationName, featureName] = [
+      fullName.substring(0, separatorPos),
+      fullName.substring(separatorPos + 1)
+    ];
+    if (!automationName || !featureName) {
+      throw new Error(errMsg);
+    }
+    return fullName;
+  };
+  return features.map(validator);
+}
+
+/**
+ * Filters the list of insecure features to only those that are
+ * applicable to the given driver name.
+ * Assumes that all feature names have already been validated
+ *
+ * @param features
+ * @param driverName
+ */
+function filterInsecureFeatures(
+  features: string[],
+  driverName: string = ALL_DRIVERS_MATCH
+): string[] {
+  const filterFn = (fullName: string) => {
+    const separatorPos = fullName.indexOf(FEATURE_NAME_SEPARATOR);
+    if (separatorPos <= 0) {
+      return false;
+    }
+    const automationName = fullName.substring(0, separatorPos);
+    return [driverName, ALL_DRIVERS_MATCH].includes(automationName);
+  };
+  return features.filter(filterFn);
+}

package/lib/logsink.js

@@ -61,6 +61,8 @@ export async function init(args) {
   log = createLogger({
     transports,
     levels: LEVELS_MAP,
+    handleExceptions: true,
+    exitOnError: false
   });
 
   const reportedLoggerErrors = new Set();
@@ -131,12 +133,9 @@ const stripColorFormat = format(function stripColor(info) {
  * @returns {transports.ConsoleTransportInstance}
  */
 function createConsoleTransport(args, logLvl) {
-  return new transports.Console({
-    // @ts-expect-error The 'name' property should exist
+  /** @type {AppiumConsoleTransportOptions} */
+  const opt = {
     name: 'console',
-    handleExceptions: true,
-    exitOnError: false,
-    json: false,
     level: logLvl,
     stderrLevels: ['error'],
     format: format.combine(
@@ -144,7 +143,8 @@ function createConsoleTransport(args, logLvl) {
       isLogColorEnabled(args) ? colorizeFormat : stripColorFormat,
       formatLog(args, true),
     ),
-  });
+  };
+  return new transports.Console(opt);
 }
 
 /**
@@ -154,21 +154,19 @@ function createConsoleTransport(args, logLvl) {
  * @returns {transports.FileTransportInstance}
  */
 function createFileTransport(args, logLvl) {
-  return new transports.File({
-    // @ts-expect-error The 'name' property should exist
+  /** @type {AppiumFileTransportOptions} */
+  const opt = {
     name: 'file',
     filename: args.logFile,
     maxFiles: 1,
-    handleExceptions: true,
-    exitOnError: false,
-    json: false,
     level: logLvl,
     format: format.combine(
       stripColorFormat,
       formatTimestamp(args),
       formatLog(args, false),
     ),
-  });
+  };
+  return new transports.File(opt);
 }
 
 /**
@@ -187,21 +185,19 @@ function createHttpTransport(args, logLvl) {
     port = parseInt(hostAndPort[1], 10);
   }
 
-  return new transports.Http({
-    // @ts-expect-error The 'name' property should exist
+  /** @type {AppiumHttpTransportOptions} */
+  const opt = {
     name: 'http',
     host,
     port,
     path: '/',
-    handleExceptions: true,
-    exitOnError: false,
-    json: false,
     level: logLvl,
     format: format.combine(
       stripColorFormat,
       formatLog(args, false),
     ),
-  });
+  };
+  return new transports.Http(opt);
 }
 
 /**
@@ -362,4 +358,7 @@ export default init;
 /**
  * @typedef {import('appium/types').ParsedArgs} ParsedArgs
  * @typedef {import('@appium/logger').MessageObject} MessageObject
+ * @typedef {transports.ConsoleTransportOptions & {name: string}} AppiumConsoleTransportOptions
+ * @typedef {transports.FileTransportOptions & {name: string}} AppiumFileTransportOptions
+ * @typedef {transports.HttpTransportOptions & {name: string}} AppiumHttpTransportOptions
  */

package/lib/main.js

@@ -177,7 +177,7 @@ function determineAppiumHomeSource(appiumHomeFromArgs) {
  *
  * @template {CliCommand} [Cmd=ServerCommand]
  * @template {CliExtensionSubcommand|void} [SubCmd=void]
- * @param {Args<Cmd, SubCmd>} [args] - Partial args (progammatic usage only)
+ * @param {Args<Cmd, SubCmd>} [args] - Partial args (programmatic usage only)
  * @returns {Promise<InitResult<Cmd>>}
  * @example
  * import {init, getSchema} from 'appium';
@@ -375,6 +375,9 @@ async function main(args) {
 
   await logStartupInfo(parsedArgs);
 
+  // handle the insecure feature configuration since some features may apply globally
+  appiumDriver.configureGlobalFeatures();
+
   const appiumHomeSourceName = determineAppiumHomeSource(args?.appiumHome);
   logger.debug(`The ${appiumHomeSourceName}: ${appiumHome}`);
 

package/lib/schema/cli-args.js

@@ -1,6 +1,6 @@
 import {ArgumentTypeError} from 'argparse';
 import _ from 'lodash';
-import {formatErrors as formatErrors} from '../config-file';
+import {formatErrors} from '../config-file';
 import {flattenSchema, validate} from './schema';
 import {transformers, parseCsvLine} from './cli-transformers';
 
@@ -225,7 +225,7 @@ function subSchemaToArgDef(subSchema, argSpec) {
  * ArgumentDefinitions for handoff to `argparse`.
  *
  * @throws If schema has not been added to ajv (via `finalizeSchema()`)
- * @returns {import('../cli/args').ArgumentDefinitions} A map of arryas of
+ * @returns {import('../cli/args').ArgumentDefinitions} A map of arrays of
  * aliases to `argparse` arguments; empty if no schema found
  */
 export function toParserArgs() {

package/lib/schema/schema.js

@@ -421,7 +421,7 @@ class AppiumSchema {
    * name. Used when translating to `argparse` options or getting the list of
    * default values (see {@link AppiumSchema.getDefaults}) for CLI or otherwise.
    *
-   * The return value is an intermediate reprsentation used by `cli-args`
+   * The return value is an intermediate representation used by `cli-args`
    * module's `toParserArgs`, which converts the finalized schema to parameters
    * used by `argparse`.
    * @throws If {@link AppiumSchema.finalize} has not been called yet.

package/lib/utils.js

@@ -17,8 +17,6 @@ const STANDARD_CAPS_LOWERCASE = new Set([...STANDARD_CAPS].map((cap) => cap.toLo
 export const V4_BROADCAST_IP = '0.0.0.0';
 export const V6_BROADCAST_IP = '::';
 export const npmPackage = fs.readPackageJsonFrom(__dirname);
-const ALL_DRIVERS_MATCH = '*';
-const FEATURE_NAME_SEPARATOR = ':';
 
 /**
  *
@@ -191,19 +189,37 @@ export function getPackageVersion(pkgName) {
   return pkgInfo.version;
 }
 
+/**
+ * Returns the root directory of the Appium module.
+ *
+ * @returns {string} - The absolute path to the Appium module root directory.
+ * @throws {Error} - If the Appium module root cannot be determined.
+ */
+export const getAppiumModuleRoot = _.memoize(function getAppiumModuleRoot() {
+  const selfRoot = node.getModuleRootSync('appium', __filename);
+  if (!selfRoot) {
+    throw new Error('Cannot find the appium module root. This is likely a bug in Appium.');
+  }
+  return selfRoot;
+});
+
 /**
  * Adjusts NODE_PATH environment variable,
- * so drivers and plugins could load their peer dependencies.
+ * so CJS drivers and plugins could load their peer dependencies.
  * Read https://nodejs.org/api/modules.html#loading-from-the-global-folders
  * for more details.
+ *
+ * Unfortunately this hack does not work with ESM modules,
  * @returns {void}
  */
 export function adjustNodePath() {
-  const selfRoot = node.getModuleRootSync('appium', __filename);
-  if (!selfRoot || path.dirname(selfRoot).length >= selfRoot.length) {
+  let appiumModuleSearchRoot;
+  try {
+    appiumModuleSearchRoot = path.dirname(getAppiumModuleRoot());
+  } catch (error) {
+    logger.warn(error.message);
     return;
   }
-  const nodeModulesRoot = path.dirname(selfRoot);
 
   const refreshRequirePaths = () => {
     try {
@@ -221,7 +237,7 @@ export function adjustNodePath() {
   };
 
   if (!process.env.NODE_PATH) {
-    process.env.NODE_PATH = nodeModulesRoot;
+    process.env.NODE_PATH = appiumModuleSearchRoot;
     if (refreshRequirePaths()) {
       process.env.APPIUM_OMIT_PEER_DEPS = '1';
     } else {
@@ -231,17 +247,17 @@ export function adjustNodePath() {
   }
 
   const nodePathParts = process.env.NODE_PATH.split(path.delimiter);
-  if (nodePathParts.includes(nodeModulesRoot)) {
+  if (nodePathParts.includes(appiumModuleSearchRoot)) {
     process.env.APPIUM_OMIT_PEER_DEPS = '1';
     return;
   }
 
-  nodePathParts.push(nodeModulesRoot);
+  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, nodeModulesRoot).join(path.delimiter);
+    process.env.NODE_PATH = _.without(nodePathParts, appiumModuleSearchRoot).join(path.delimiter);
   }
 }
 
@@ -346,7 +362,7 @@ export function isPluginCommandArgs(args) {
  *
  * @param {4|6|null} family Either 4 to include ipv4 addresses only,
  * 6 to include ipv6 addresses only, or null to include all of them
- * @returns {os.NetworkInterfaceInfo[]} The list of matched interfcaes
+ * @returns {os.NetworkInterfaceInfo[]} The list of matched interfaces
  */
 export function fetchInterfaces (family = null) {
   let familyValue = null;
@@ -427,34 +443,6 @@ export function isBroadcastIp(address) {
   return [V4_BROADCAST_IP, V6_BROADCAST_IP, `[${V6_BROADCAST_IP}]`].includes(address);
 }
 
-/**
- * Validates the list of allowed/denied server features
- *
- * @param {string[]} features
- * @returns {string[]}
- */
-export function validateFeatures(features) {
-  const validator = (/** @type {string} */ fullName) => {
-    const errMsg = `The full feature name must include both the destination automation name or the ` +
-      `'${ALL_DRIVERS_MATCH}' wildcard to apply the feature to all installed drivers, and ` +
-      `the feature name split by a colon. Got '${fullName}' instead`;
-
-    const separatorPos = fullName.indexOf(FEATURE_NAME_SEPARATOR);
-    if (separatorPos < 0) {
-      throw new Error(errMsg);
-    }
-    const [automationName, featureName] = [
-      fullName.substring(0, separatorPos),
-      fullName.substring(separatorPos + 1)
-    ];
-    if (!automationName || !featureName) {
-      throw new Error(errMsg);
-    }
-    return fullName;
-  };
-  return features.map(validator);
-}
-
 /**
  * @typedef {import('@appium/types').StringRecord} StringRecord
  * @typedef {import('@appium/types').BaseDriverCapConstraints} BaseDriverCapConstraints

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-rc.2",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -60,43 +60,43 @@
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/base-driver": "^10.0.0-beta.2",
-    "@appium/base-plugin": "^3.0.0-beta.2",
-    "@appium/docutils": "^1.1.0",
-    "@appium/logger": "^1.7.0",
-    "@appium/schema": "^0.8.1",
-    "@appium/support": "^6.1.0",
-    "@appium/types": "^0.25.3",
-    "@sidvind/better-ajv-errors": "3.0.1",
+    "@appium/base-driver": "^10.0.0-rc.2",
+    "@appium/base-plugin": "^3.0.0-rc.2",
+    "@appium/docutils": "^2.0.0-rc.1",
+    "@appium/logger": "^2.0.0-rc.1",
+    "@appium/schema": "^1.0.0-rc.1",
+    "@appium/support": "^7.0.0-rc.1",
+    "@appium/types": "^1.0.0-rc.1",
+    "@sidvind/better-ajv-errors": "4.0.0",
     "ajv": "8.17.1",
     "ajv-formats": "3.0.1",
     "argparse": "2.0.1",
     "async-lock": "1.4.1",
     "asyncbox": "3.0.0",
-    "axios": "1.9.0",
+    "axios": "1.11.0",
     "bluebird": "3.7.2",
     "lilconfig": "3.1.3",
     "lodash": "4.17.21",
-    "lru-cache": "10.4.3",
+    "lru-cache": "11.1.0",
     "ora": "5.4.1",
     "package-changed": "3.0.0",
     "resolve-from": "5.0.0",
-    "semver": "7.7.1",
+    "semver": "7.7.2",
     "source-map-support": "0.5.21",
-    "teen_process": "2.3.1",
-    "type-fest": "4.40.0",
+    "teen_process": "2.3.3",
+    "type-fest": "4.41.0",
     "winston": "3.17.0",
     "wrap-ansi": "7.0.0",
-    "ws": "8.18.1",
-    "yaml": "2.7.1"
+    "ws": "8.18.3",
+    "yaml": "2.8.1"
   },
   "engines": {
-    "node": "^20.9.0 || >=22.11.0",
+    "node": "^20.19.0 || ^22.12.0 || >=24.0.0",
     "npm": ">=10"
   },
   "publishConfig": {
     "access": "public",
-    "tag": "beta"
+    "tag": "rc"
   },
-  "gitHead": "dc5ef8d5f62c8a0775131305107a4037cd9ec9c9"
+  "gitHead": "157425ce6aa01c009533f5bf6a56b14570222b00"
 }