appium 2.0.0-beta.41 → 2.0.0-beta.42

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.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,11 +15,11 @@ import {
   checkNodeOk,
   getGitRev,
   getNonDefaultServerArgs,
-  rootDir,
   showConfig,
   showBuildInfo,
   validateTmpDir,
   warnNodeDeprecations,
+  checkNpmOk,
 } from './config';
 import {readConfigFile} from './config-file';
 import {loadExtensions, getActivePlugins, getActiveDrivers} from './extension';
@@ -27,9 +27,8 @@ 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';
 
-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,19 +172,6 @@ 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}`);
-      }
-    }
-  }
-
   const {driverConfig, pluginConfig} = await loadExtensions(appiumHome);
 
   const parser = getParser();
@@ -222,20 +209,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 +256,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
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.0.0-beta.41",
+  "version": "2.0.0-beta.42",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -54,20 +54,20 @@
     "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",
+    "@appium/base-driver": "^8.6.1",
+    "@appium/base-plugin": "^1.10.1",
+    "@appium/docutils": "^0.0.9",
+    "@appium/schema": "^0.0.9",
+    "@appium/support": "^2.59.4",
+    "@appium/test-support": "^1.4.1",
+    "@appium/types": "^0.3.1",
     "@babel/runtime": "7.18.9",
     "@sidvind/better-ajv-errors": "2.0.0",
     "@types/argparse": "2.0.10",
@@ -83,6 +83,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 +95,18 @@
     "semver": "7.3.7",
     "source-map-support": "0.5.21",
     "teen_process": "1.16.0",
-    "type-fest": "2.17.0",
+    "type-fest": "2.18.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": "500c08f3929b1dd531d119872d11cea59d417eb7"
 }

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[];
 }
 
 /**