appium 2.0.0-beta.41 → 2.0.0-beta.44

package/lib/cli/extension-command.js

@@ -576,13 +576,14 @@ class ExtensionCommand {
     // this is a helper method, 'ext' is assumed to already be installed here, and of the npm
     // install type
     const {version, pkgName} = this.config.installedExtensions[ext];
+    /** @type {string?} */
     let unsafeUpdate = await npm.getLatestVersion(this.config.appiumHome, pkgName);
     let safeUpdate = await npm.getLatestSafeUpgradeVersion(
       this.config.appiumHome,
       pkgName,
       version
     );
-    if (!util.compareVersions(unsafeUpdate, '>', version)) {
+    if (unsafeUpdate !== null && !util.compareVersions(unsafeUpdate, '>', version)) {
       // the latest version is not greater than the current version, so there's no possible update
       unsafeUpdate = null;
       safeUpdate = null;
@@ -628,7 +629,7 @@ class ExtensionCommand {
    * @param {RunOptions} opts
    * @return {Promise<RunOutput>}
    */
-  async _run({installSpec, scriptName}) {
+  async _run({installSpec, scriptName, extraArgs = []}) {
     if (!this.config.isInstalled(installSpec)) {
       throw this._createFatalError(`The ${this.type} "${installSpec}" is not installed`);
     }
@@ -657,7 +658,7 @@ class ExtensionCommand {
       );
     }
 
-    const runner = new SubProcess(process.execPath, [extScripts[scriptName]], {
+    const runner = new SubProcess(process.execPath, [extScripts[scriptName], ...extraArgs], {
       cwd: this.config.getInstallPath(installSpec),
     });
 
@@ -755,6 +756,7 @@ export {ExtensionCommand};
  * @typedef RunOptions
  * @property {string} installSpec - name of the extension to run a script from
  * @property {string} scriptName - name of the script to run
+ * @property {string[]} [extraArgs] - arguments to pass to the script
  */
 
 /**

package/lib/cli/extension.js

@@ -15,9 +15,9 @@ export const commandClasses = Object.freeze(
  * Run a subcommand of the 'appium driver' type. Each subcommand has its own set of arguments which
  * can be represented as a JS object.
  *
- * @param {Object} args - JS object where the key is the parameter name (as defined in
+ * @param {import('appium/types').Args<import('appium/types').WithExtSubcommand>} args - JS object where the key is the parameter name (as defined in
  * driver-parser.js)
- * @template {import('../extension/manifest').ExtensionType} ExtType
+ * @template {ExtensionType} ExtType
  * @param {import('../extension/extension-config').ExtensionConfig<ExtType>} config - Extension config object
  */
 async function runExtensionCommand(args, config) {
@@ -30,6 +30,7 @@ async function runExtensionCommand(args, config) {
     throw new TypeError(`Cannot call ${type} command without a subcommand like 'install'`);
   }
   let {json, suppressOutput} = args;
+  json = Boolean(json);
   if (suppressOutput) {
     json = true;
   }
@@ -56,6 +57,17 @@ async function runExtensionCommand(args, config) {
 export {runExtensionCommand};
 
 /**
- * @template {import('@appium/types').ExtensionType} ExtType
- * @typedef {ExtType extends import('@appium/types').DriverType ? import('@appium/types').Class<DriverCommand> : ExtType extends import('@appium/types').PluginType ? import('@appium/types').Class<PluginCommand> : never} ExtCommand
+ * @template {ExtensionType} ExtType
+ * @typedef {ExtType extends DriverType ? Class<DriverCommand> : ExtType extends PluginType ? Class<PluginCommand> : never} ExtCommand
+ */
+
+/**
+ * @typedef {import('@appium/types').ExtensionType} ExtensionType
+ * @typedef {import('@appium/types').DriverType} DriverType
+ * @typedef {import('@appium/types').PluginType} PluginType
+ */
+
+/**
+ * @template T
+ * @typedef {import('@appium/types').Class<T>} Class
  */

package/lib/cli/parser.js

@@ -7,6 +7,8 @@ import {finalizeSchema, getArgSpec, hasArgSpec} from '../schema';
 import {rootDir} from '../config';
 import {getExtensionArgs, getServerArgs} from './args';
 
+export const EXTRA_ARGS = 'extraArgs';
+
 /**
  * If the parsed args do not contain any of these values, then we
  * will automatially inject the `server` subcommand.
@@ -97,8 +99,17 @@ class ArgParser {
     }
 
     try {
-      const parsed = this.parser.parse_args(args);
-      return ArgParser._transformParsedArgs(parsed);
+      const parsed = this.parser.parse_known_args(args);
+      const [knownArgs, unknownArgs] = parsed;
+      if (
+        unknownArgs?.length &&
+        (knownArgs.driverCommand === 'run' || knownArgs.pluginCommand === 'run')
+      ) {
+        return ArgParser._transformParsedArgs(knownArgs, unknownArgs);
+      } else if (unknownArgs?.length) {
+        throw new Error(`[ERROR] Unrecognized arguments: ${unknownArgs.join(' ')}`);
+      }
+      return ArgParser._transformParsedArgs(knownArgs);
     } catch (err) {
       if (this.debug) {
         throw err;
@@ -123,10 +134,11 @@ class ArgParser {
    *
    * E.g., `{'driver-foo-bar': baz}` becomes `{driver: {foo: {bar: 'baz'}}}`
    * @param {object} args
+   * @param {string[]} [unknownArgs]
    * @returns {object}
    */
-  static _transformParsedArgs(args) {
-    return _.reduce(
+  static _transformParsedArgs(args, unknownArgs = []) {
+    const result = _.reduce(
       args,
       (unpacked, value, key) => {
         if (!_.isUndefined(value) && hasArgSpec(key)) {
@@ -140,6 +152,8 @@ class ArgParser {
       },
       {}
     );
+    result[EXTRA_ARGS] = unknownArgs;
+    return result;
   }
 
   /**
@@ -183,7 +197,7 @@ class ArgParser {
    * @param {import('argparse').SubParser} subParsers
    */
   static _addExtensionCommandsToParser(subParsers) {
-    for (const type of [DRIVER_TYPE, PLUGIN_TYPE]) {
+    for (const type of /** @type {[DriverType, PluginType]} */ ([DRIVER_TYPE, PLUGIN_TYPE])) {
       const extParser = subParsers.add_parser(type, {
         add_help: true,
         help: `Access the ${type} management CLI commands`,
@@ -195,6 +209,9 @@ class ArgParser {
         dest: `${type}Command`,
       });
       const extensionArgs = getExtensionArgs();
+      /**
+       * @type { {command: import('appium/types').CliExtensionSubcommand, args: import('./args').ArgumentDefinitions, help: string}[] }
+       */
       const parserSpecs = [
         {
           command: 'list',
@@ -254,3 +271,8 @@ function getParser(debug) {
 }
 
 export {getParser, ArgParser};
+
+/**
+ * @typedef {import('@appium/types').DriverType} DriverType
+ * @typedef {import('@appium/types').PluginType} PluginType
+ */

package/lib/cli/plugin-command.js

@@ -33,8 +33,8 @@ export default class PluginCommand extends ExtensionCommand {
     return await super._update({installSpec: plugin, unsafe});
   }
 
-  async run({plugin, scriptName}) {
-    return await super._run({installSpec: plugin, scriptName});
+  async run({plugin, scriptName, extraArgs}) {
+    return await super._run({installSpec: plugin, scriptName, extraArgs});
   }
 
   getPostInstallText({extName, extData}) {

package/lib/config-file.js

@@ -161,7 +161,9 @@ export function normalizeConfig(config) {
 
     return _.mapValues(mappedObj, (value, property) => {
       const nextSection = section ? `${section}.${property}` : property;
-      return isSchemaTypeObject(value) ? normalize(config, nextSection) : value;
+      return isSchemaTypeObject(schema.properties?.[property])
+        ? normalize(config, nextSection)
+        : value;
     });
   };
 
@@ -169,7 +171,7 @@ export function normalizeConfig(config) {
    * Returns `true` if the schema prop references an object, or if it's an object itself
    * @param {import('ajv').SchemaObject|object} schema - Referencing schema object
    */
-  const isSchemaTypeObject = (schema) => Boolean(schema.properties);
+  const isSchemaTypeObject = (schema) => Boolean(schema?.properties || schema?.type === 'object');
 
   return normalize(config);
 }

package/lib/config.js

@@ -3,7 +3,6 @@ import _ from 'lodash';
 import {system, fs} from '@appium/support';
 import axios from 'axios';
 import {exec} from 'teen_process';
-import logger from './logger';
 import semver from 'semver';
 import findUp from 'find-up';
 import {getDefaultsForSchema, getAllArgSpecs} from './schema/schema';
@@ -12,6 +11,7 @@ const npmPackage = fs.readPackageJsonFrom(__dirname);
 
 const APPIUM_VER = npmPackage.version;
 const MIN_NODE_VERSION = npmPackage.engines.node;
+const MIN_NPM_VERSION = npmPackage.engines.npm;
 
 const GIT_META_ROOT = '.git';
 const GIT_BINARY = `git${system.isWindows() ? '.exe' : ''}`;
@@ -28,6 +28,15 @@ function getNodeVersion() {
   return /** @type {import('semver').SemVer} */ (semver.coerce(process.version));
 }
 
+/**
+ * Returns version of `npm`
+ * @returns {Promise<string>}
+ */
+async function getNpmVersion() {
+  const {stdout} = await exec(system.isWindows() ? 'npm.cmd' : 'npm', ['--version']);
+  return stdout.trim();
+}
+
 /**
  * @param {boolean} [useGithubApiFallback]
  */
@@ -133,7 +142,18 @@ function getBuildInfo() {
 function checkNodeOk() {
   const version = getNodeVersion();
   if (!semver.satisfies(version, MIN_NODE_VERSION)) {
-    logger.errorAndThrow(`Node version must be ${MIN_NODE_VERSION}. Currently ${version.version}`);
+    throw new Error(
+      `Node version must be at least ${MIN_NODE_VERSION}; current is ${version.version}`
+    );
+  }
+}
+
+export async function checkNpmOk() {
+  const npmVersion = await getNpmVersion();
+  if (!semver.satisfies(npmVersion, MIN_NPM_VERSION)) {
+    throw new Error(
+      `npm version must be at least ${MIN_NPM_VERSION}; current is ${npmVersion}. Run "npm install -g npm" to upgrade.`
+    );
   }
 }
 

package/lib/main.js

@@ -4,7 +4,7 @@ import {init as logsinkInit} from './logsink'; // this import needs to come firs
 import logger from './logger'; // logger needs to remain second
 // @ts-ignore
 import {routeConfiguringFunction as makeRouter, server as baseServer} from '@appium/base-driver';
-import {logger as logFactory, util, env, fs} from '@appium/support';
+import {logger as logFactory, util, env} from '@appium/support';
 import {asyncify} from 'asyncbox';
 import _ from 'lodash';
 import {AppiumDriver} from './appium';
@@ -15,21 +15,20 @@ import {
   checkNodeOk,
   getGitRev,
   getNonDefaultServerArgs,
-  rootDir,
   showConfig,
   showBuildInfo,
   validateTmpDir,
   warnNodeDeprecations,
+  checkNpmOk,
 } from './config';
 import {readConfigFile} from './config-file';
 import {loadExtensions, getActivePlugins, getActiveDrivers} from './extension';
 import {DRIVER_TYPE, PLUGIN_TYPE, SERVER_SUBCOMMAND} from './constants';
 import registerNode from './grid-register';
 import {getDefaultsForSchema, validate} from './schema/schema';
-import {inspect} from './utils';
-import path from 'path';
+import {inspect, adjustNodePath} from './utils';
 
-const {resolveAppiumHome, hasAppiumDependency} = env;
+const {resolveAppiumHome} = env;
 
 /**
  *
@@ -39,6 +38,7 @@ const {resolveAppiumHome, hasAppiumDependency} = env;
 async function preflightChecks(args, throwInsteadOfExit = false) {
   try {
     checkNodeOk();
+    await checkNpmOk();
     if (args.longStacktrace) {
       require('longjohn').async_trace_limit = -1;
     }
@@ -172,18 +172,7 @@ function areServerCommandArgs(args) {
 async function init(args) {
   const appiumHome = args?.appiumHome ?? (await resolveAppiumHome());
 
-  // this is here so extensions installed in e.g., `~/.appium` can find the peer dependency
-  // of `appium`, which lives wherever it lives (see `rootDir`).
-  if (!(await hasAppiumDependency(appiumHome))) {
-    try {
-      await fs.mkdirp(path.join(appiumHome, 'node_modules'));
-      await fs.symlink(rootDir, path.join(appiumHome, 'node_modules', 'appium'), 'junction');
-    } catch (err) {
-      if (err.code !== 'EEXIST') {
-        throw new Error(`Unable to create symlink to appium: ${err.message}`);
-      }
-    }
-  }
+  adjustNodePath();
 
   const {driverConfig, pluginConfig} = await loadExtensions(appiumHome);
 
@@ -222,20 +211,7 @@ async function init(args) {
   // 1. command line args
   // 2. config file
   // 3. defaults from config file.
-  if (!areServerCommandArgs(preConfigArgs)) {
-    // if the user has requested the 'driver' CLI, don't run the normal server,
-    // but instead pass control to the driver CLI
-    if (preConfigArgs.subcommand === DRIVER_TYPE) {
-      await runExtensionCommand(preConfigArgs, driverConfig);
-      return {};
-    }
-    if (preConfigArgs.subcommand === PLUGIN_TYPE) {
-      await runExtensionCommand(preConfigArgs, pluginConfig);
-      return {};
-    }
-    /* istanbul ignore next */
-    return {}; // should never happen
-  } else {
+  if (areServerCommandArgs(preConfigArgs)) {
     const defaults = getDefaultsForSchema(false);
 
     /** @type {ParsedArgs} */
@@ -282,6 +258,22 @@ async function init(args) {
       driverConfig,
       pluginConfig,
     });
+  } else {
+    const extensionCommandArgs = /** @type {Args<import('appium/types').WithExtSubcommand>} */ (
+      preConfigArgs
+    );
+    // if the user has requested the 'driver' CLI, don't run the normal server,
+    // but instead pass control to the driver CLI
+    if (preConfigArgs.subcommand === DRIVER_TYPE) {
+      await runExtensionCommand(extensionCommandArgs, driverConfig);
+      return {};
+    }
+    if (preConfigArgs.subcommand === PLUGIN_TYPE) {
+      await runExtensionCommand(extensionCommandArgs, pluginConfig);
+      return {};
+    }
+    /* istanbul ignore next */
+    return {}; // should never happen
   }
 }
 
@@ -314,6 +306,7 @@ async function main(args) {
   const serverUpdaters = getServerUpdaters(driverClasses, pluginClasses);
   const extraMethodMap = getExtraMethodMap(driverClasses, pluginClasses);
 
+  /** @type {import('@appium/base-driver').ServerOpts} */
   const serverOpts = {
     routeConfiguringFunction,
     port: parsedArgs.port,
@@ -322,6 +315,7 @@ async function main(args) {
     basePath: parsedArgs.basePath,
     serverUpdaters,
     extraMethodMap,
+    cliArgs: parsedArgs,
   };
   if (parsedArgs.keepAliveTimeout) {
     serverOpts.keepAliveTimeout = parsedArgs.keepAliveTimeout * 1000;

package/lib/schema/cli-transformers.js

@@ -94,8 +94,9 @@ export const transformers = {
       json = readFileSync(jsonOrPath, 'utf8');
       loadedFromFile = true;
     } catch (err) {
-      // unreadable files don't count... but other problems do.
-      if (err.code !== 'ENOENT') {
+      // unreadable files don't count.
+      // also `ENAMETOOLONG` can happen if we try to open a file that's a huge JSON string.
+      if (err.code !== 'ENOENT' && err.code !== 'ENAMETOOLONG') {
         throw err;
       }
     }

package/lib/utils.js

@@ -2,6 +2,8 @@ import _ from 'lodash';
 import logger from './logger';
 import {processCapabilities, PROTOCOLS} from '@appium/base-driver';
 import {inspect as dump} from 'util';
+import {node} from '@appium/support';
+import path from 'path';
 
 const W3C_APPIUM_PREFIX = 'appium';
 
@@ -209,6 +211,63 @@ function getPackageVersion(pkgName) {
   return pkgInfo.version;
 }
 
+/**
+ * Adjusts NODE_PATH environment variable,
+ * so drivers and plugins could load their peer dependencies.
+ * Read https://nodejs.org/api/modules.html#loading-from-the-global-folders
+ * for more details.
+ * @returns {void}
+ */
+function adjustNodePath() {
+  const selfRoot = node.getModuleRootSync('appium', __filename);
+  if (!selfRoot || path.dirname(selfRoot).length >= selfRoot.length) {
+    return;
+  }
+  const nodeModulesRoot = path.dirname(selfRoot);
+
+  const refreshRequirePaths = () => {
+    try {
+      // ! This hack allows us to avoid modification of import
+      // ! statements in client modules. It uses a private API though,
+      // ! so it could break (maybe, eventually).
+      // See https://gist.github.com/branneman/8048520#7-the-hack
+      // @ts-ignore
+      require('module').Module._initPaths();
+      return true;
+    } catch (e) {
+      logger.info(`Module init paths cannot be refreshed. Original error: ${e.message}`);
+      return false;
+    }
+  };
+
+  if (!process.env.NODE_PATH) {
+    process.env.NODE_PATH = nodeModulesRoot;
+    if (refreshRequirePaths()) {
+      logger.info(`Setting NODE_PATH to '${nodeModulesRoot}'`);
+      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(nodeModulesRoot)) {
+    logger.info(`NODE_PATH already includes '${nodeModulesRoot}'`);
+    process.env.APPIUM_OMIT_PEER_DEPS = '1';
+    return;
+  }
+
+  nodePathParts.push(nodeModulesRoot);
+  process.env.NODE_PATH = nodePathParts.join(path.delimiter);
+  if (refreshRequirePaths()) {
+    logger.info(`Adding '${nodeModulesRoot}' to NODE_PATH`);
+    process.env.APPIUM_OMIT_PEER_DEPS = '1';
+  } else {
+    process.env.NODE_PATH = _.without(nodePathParts, nodeModulesRoot).join(path.delimiter);
+  }
+}
+
 /**
  * Pulls the initial values of Appium settings from the given capabilities argument.
  * Each setting item must satisfy the following format:
@@ -250,6 +309,7 @@ export {
   getPackageVersion,
   pullSettings,
   removeAppiumPrefixes,
+  adjustNodePath,
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.0.0-beta.41",
+  "version": "2.0.0-beta.44",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -37,7 +37,6 @@
     "driver.*",
     "support.*",
     "plugin.*",
-    "test.*",
     "scripts/autoinstall-extensions.js",
     "types"
   ],
@@ -54,26 +53,25 @@
     "postinstall": "node ./scripts/autoinstall-extensions.js",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
     "prepare": "npm run build",
-    "publish:docs": "APPIUM_DOCS_PUBLISH=1 npm run build:docs",
+    "publish:docs": "cross-env APPIUM_DOCS_PUBLISH=1 npm run build:docs",
     "test": "npm run test:unit",
     "test:e2e": "mocha --timeout 1m --slow 30s \"./test/e2e/**/*.spec.js\"",
-    "test:smoke": "node ./index.js --show-build-info",
+    "test:smoke": "cross-env APPIUM_HOME=./local_appium_home node ./index.js driver install uiautomator2 && cross-env APPIUM_HOME=./local_appium_home node ./index.js driver list",
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/base-driver": "^8.6.0",
-    "@appium/base-plugin": "^1.10.0",
-    "@appium/docutils": "^0.0.8",
-    "@appium/schema": "^0.0.8",
-    "@appium/support": "^2.59.3",
-    "@appium/test-support": "^1.4.0",
-    "@appium/types": "^0.3.0",
-    "@babel/runtime": "7.18.9",
+    "@appium/base-driver": "^8.7.1",
+    "@appium/base-plugin": "^1.10.3",
+    "@appium/docutils": "^0.0.11",
+    "@appium/schema": "^0.0.9",
+    "@appium/support": "^2.60.0",
+    "@appium/types": "^0.4.1",
+    "@babel/runtime": "7.19.0",
     "@sidvind/better-ajv-errors": "2.0.0",
     "@types/argparse": "2.0.10",
     "@types/bluebird": "3.5.36",
     "@types/fancy-log": "2.0.0",
-    "@types/semver": "7.3.10",
+    "@types/semver": "7.3.12",
     "@types/teen_process": "1.16.1",
     "@types/wrap-ansi": "3.0.0",
     "ajv": "8.11.0",
@@ -83,6 +81,7 @@
     "asyncbox": "2.9.2",
     "axios": "0.27.2",
     "bluebird": "3.7.2",
+    "cross-env": "7.0.3",
     "find-up": "5.0.0",
     "lilconfig": "2.0.6",
     "lodash": "4.17.21",
@@ -94,18 +93,18 @@
     "semver": "7.3.7",
     "source-map-support": "0.5.21",
     "teen_process": "1.16.0",
-    "type-fest": "2.17.0",
+    "type-fest": "2.19.0",
     "winston": "3.8.1",
     "wrap-ansi": "7.0.0",
     "yaml": "2.1.1"
   },
   "engines": {
     "node": ">=14",
-    "npm": ">=6"
+    "npm": ">=8"
   },
   "publishConfig": {
     "access": "public",
     "tag": "next"
   },
-  "gitHead": "f6e6d7234e7fe92f989f4e37a71007044985dedf"
+  "gitHead": "c26af8f85230ac65cbc19f08f763942f74b0eb0c"
 }

package/types/cli.ts

@@ -92,6 +92,21 @@ export interface ExtArgs extends WithExtSubcommand {
    * Subcommands of `plugin` subcommand
    */
   pluginCommand?: CliExtensionSubcommand;
+
+  /**
+   * Output JSON instead of human-readable text
+   */
+  json?: boolean;
+
+  /**
+   * Output nothing
+   */
+  suppressOutput?: boolean;
+
+  /**
+   * Extra args to pass to extension scripts
+   */
+  extraArgs?: string[];
 }
 
 /**

package/test.d.ts

@@ -1,7 +0,0 @@
-export * from '@appium/test-support';
-/**
- * @typedef {import('@appium/test-support').SessionHelpers} SessionHelpers
- */
-/**
- * @typedef {import('@appium/test-support').E2ESetupOpts} E2ESetupOpts
- */

package/test.js

@@ -1,13 +0,0 @@
-'use strict';
-
-// @ts-check
-
-/**
- * This module is here to re-export `@appium/test-support` for Appium extensions.
- *
- * @see https://npm.im/@appium/test-support
- * @example
- * const { getPort } = require('appium/test');
- */
-
-module.exports = require('@appium/test-support');