appium 2.13.1 → 2.14.1

package/lib/cli/parser.js

@@ -18,9 +18,11 @@ import {finalizeSchema, getArgSpec, hasArgSpec} from '../schema';
 import {rootDir} from '../config';
 import {getExtensionArgs, getServerArgs} from './args';
 import {
+  DEFAULT_PLUGINS,
   SUBCOMMAND_MOBILE,
   SUBCOMMAND_DESKTOP,
   SUBCOMMAND_BROWSER,
+  SUBCOMMAND_RESET,
   getPresetDrivers,
   determinePlatformName
 } from './setup-command';
@@ -53,7 +55,8 @@ class ArgParser {
     const parser = new ArgumentParser({
       add_help: true,
       description:
-        'A webdriver-compatible server that facilitates automation of web, mobile, and other types of apps across various platforms.',
+        'A webdriver-compatible server that facilitates automation of web, mobile, and other ' +
+        'types of apps across various platforms.',
       prog,
     });
 
@@ -84,9 +87,6 @@ class ArgParser {
 
     const subParsers = parser.add_subparsers({dest: 'subcommand'});
 
-    // add the 'setup' command
-    ArgParser._addSetupToParser(subParsers);
-
     // add the 'server' subcommand, and store the raw arguments on the parser
     // object as a way for other parts of the code to work with the arguments
     // conceptually rather than just through argparse
@@ -97,6 +97,9 @@ class ArgParser {
     // add the 'driver' and 'plugin' subcommands
     ArgParser._addExtensionCommandsToParser(subParsers);
 
+    // add the 'setup' command
+    ArgParser._addSetupToParser(subParsers);
+
     // backwards compatibility / drop-in wrapper
     /**
      * @type {ArgParser['parseArgs']}
@@ -205,7 +208,8 @@ class ArgParser {
   static _addServerToParser(subParser) {
     const serverParser = subParser.add_parser('server', {
       add_help: true,
-      help: 'Run an Appium server',
+      help: 'Start an Appium server',
+      description: 'Start an Appium server (the "server" subcommand is optional)',
     });
 
     ArgParser._patchExit(serverParser);
@@ -227,7 +231,8 @@ class ArgParser {
     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`,
+        help: `Manage Appium ${type}s`,
+        description: `Manage Appium ${type}s using various subcommands`,
       });
 
       ArgParser._patchExit(extParser);
@@ -259,19 +264,17 @@ class ArgParser {
         {
           command: EXT_SUBCOMMAND_UPDATE,
           args: extensionArgs[type].update,
-          help: `Update installed ${type}s to the latest version`,
+          help: `Update one or more installed ${type}s to the latest version`,
         },
         {
           command: EXT_SUBCOMMAND_RUN,
           args: extensionArgs[type].run,
-          help:
-            `Run a script (defined inside the ${type}'s package.json under the ` +
-            `“scripts” field inside the “appium” field) from an installed ${type}`,
+          help: `Run a script (if available) from the given ${type}`,
         },
         {
           command: EXT_SUBCOMMAND_DOCTOR,
           args: extensionArgs[type].doctor,
-          help: `Run doctor checks (if any defined) for the given ${type}`,
+          help: `Run doctor checks (if available) for the given ${type}`,
         },
       ];
 
@@ -299,9 +302,12 @@ class ArgParser {
   static _addSetupToParser(subParser) {
     const setupParser = subParser.add_parser('setup', {
       add_help: true,
-      help: `Select a preset of official drivers/plugins to install ` +
-        `compatible with '${determinePlatformName()}' host platform. ` +
-        `Existing drivers/plugins will remain. The default preset is 'mobile'.`,
+      help: 'Batch install or uninstall Appium drivers and plugins',
+      description:
+        `Install a preset of official drivers/plugins compatible with the current host platform ` +
+        `(${determinePlatformName()}). Existing drivers/plugins will remain. The default preset ` +
+        `is "mobile". Providing the special "reset" subcommand will instead uninstall all ` +
+        `drivers and plugins, and remove their related manifest files.`,
     });
 
 
@@ -313,15 +319,25 @@ class ArgParser {
     const parserSpecs = [
       {
         command: SUBCOMMAND_MOBILE,
-        help: `The preset for mobile devices: ${_.join(getPresetDrivers(SUBCOMMAND_MOBILE), ',')}`
+        help:
+          `The preset for mobile devices ` +
+          `(drivers: ${_.join(getPresetDrivers(SUBCOMMAND_MOBILE), ',')}; plugins: ${DEFAULT_PLUGINS})`
       },
       {
         command: SUBCOMMAND_BROWSER,
-        help: `The preset for desktop browser drivers: ${_.join(getPresetDrivers(SUBCOMMAND_BROWSER), ',')}`
+        help:
+          `The preset for desktop browsers ` +
+          `(drivers: ${_.join(getPresetDrivers(SUBCOMMAND_BROWSER), ',')}; plugins: ${DEFAULT_PLUGINS})`
       },
       {
         command: SUBCOMMAND_DESKTOP,
-        help: `The preset for desktop application drivers: ${_.join(getPresetDrivers(SUBCOMMAND_DESKTOP), ',')}`
+        help:
+          `The preset for desktop applications ` +
+          `(drivers: ${_.join(getPresetDrivers(SUBCOMMAND_DESKTOP), ',')}; plugins: ${DEFAULT_PLUGINS})`
+      },
+      {
+        command: SUBCOMMAND_RESET,
+        help: 'Remove all installed drivers and plugins'
       },
     ];
 

package/lib/cli/utils.js

@@ -27,7 +27,9 @@ export function errAndQuit(json, msg) {
  * @param {string} msg - string to log
  */
 export function log(json, msg) {
-  !json && console.log(msg);
+  if (!json) {
+    console.log(msg);
+  }
 }
 
 /**

package/lib/config.js

@@ -3,7 +3,7 @@ import _ from 'lodash';
 import {system, fs, npm} from '@appium/support';
 import axios from 'axios';
 import {exec} from 'teen_process';
-import semver from 'semver';
+import * as semver from 'semver';
 import os from 'node:os';
 import {npmPackage} from './utils';
 import B from 'bluebird';
@@ -115,7 +115,7 @@ export async function getGitRev(useGithubApiFallback = false) {
         cwd: __dirname,
       });
       return stdout.trim();
-    } catch (ign) {}
+    } catch {}
   }
 
   if (!useGithubApiFallback) {
@@ -132,7 +132,7 @@ export async function getGitRev(useGithubApiFallback = false) {
         },
       })
     ).data?.object?.sha;
-  } catch (ign) {}
+  } catch {}
   return null;
 }
 
@@ -149,7 +149,7 @@ async function getGitTimestamp(commitSha, useGithubApiFallback = false) {
         cwd: __dirname,
       });
       return stdout.trim();
-    } catch (ign) {}
+    } catch {}
   }
 
   if (!useGithubApiFallback) {
@@ -164,7 +164,7 @@ async function getGitTimestamp(commitSha, useGithubApiFallback = false) {
         },
       })
     ).data?.tagger?.date;
-  } catch (ign) {}
+  } catch {}
   return null;
 }
 
@@ -194,7 +194,7 @@ export function checkNodeOk() {
 
 export async function showBuildInfo() {
   await updateBuildInfo(true);
-  console.log(JSON.stringify(getBuildInfo())); // eslint-disable-line no-console
+  console.log(JSON.stringify(getBuildInfo()));
 }
 
 /**
@@ -356,7 +356,7 @@ export async function requireDir(root, requireWriteable = true, displayName = 'f
   if (requireWriteable) {
     try {
       await fs.access(root, fs.constants.W_OK);
-    } catch (e) {
+    } catch {
       throw new Error(
         `The ${displayName} '${root}' must be ` +
         `writeable for the current user account '${os.userInfo().username}'`

package/lib/extension/extension-config.js

@@ -14,6 +14,7 @@ import {
 } from '../schema/schema';
 import { pathToFileURL } from 'url';
 
+const DEFAULT_ENTRY_POINT = 'index.js';
 /**
  * "npm" install type
  * Used when extension was installed by npm package name
@@ -567,23 +568,39 @@ export class ExtensionConfig {
     const {mainClass} = this.installedExtensions[extName];
     const moduleRoot = this.getInstallPath(extName);
     const packageJsonPath = path.join(moduleRoot, 'package.json');
-    let entryPointPath;
+    let extensionManifest;
     try {
-      entryPointPath = JSON.parse(await fs.readFile(packageJsonPath, 'utf8')).main ?? 'index.js';
+      extensionManifest = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
     } catch (e) {
-      throw new ReferenceError(`Could not find a ${this.extensionType} installed at ${moduleRoot}`);
+      throw new ReferenceError(
+        `Could not read the ${this.extensionType} manifest at ${packageJsonPath}: ${e.message}`
+      );
     }
-    if (entryPointPath) {
-      entryPointPath = path.resolve(moduleRoot, entryPointPath);
-    } else {
-      throw new ReferenceError(`Cannot find a valid ${this.extensionType} main entry point in '${packageJsonPath}'`);
+    /** @type {string | undefined} */
+    let entryPointRelativePath;
+    try {
+      if (extensionManifest.type === 'module' && extensionManifest.exports) {
+        entryPointRelativePath = resolveEsmEntryPoint(extensionManifest.exports);
+      }
+      entryPointRelativePath = entryPointRelativePath ?? extensionManifest.main ?? DEFAULT_ENTRY_POINT;
+    } catch (e) {
+      throw new ReferenceError(
+        `Could not find the ${this.extensionType} installed at ${moduleRoot}: ${e.message}`
+      );
+    }
+    const entryPointFullPath = path.resolve(moduleRoot, /** @type {string} */ (entryPointRelativePath));
+    if (!await fs.exists(entryPointFullPath)) {
+      throw new ReferenceError(
+        `Cannot find a valid ${this.extensionType} main entry point in '${packageJsonPath}'. ` +
+        `Assumed entry point: '${entryPointFullPath}'`
+      );
     }
     // note: this will only reload the entry point
-    if (process.env.APPIUM_RELOAD_EXTENSIONS && require.cache[entryPointPath]) {
-      log.debug(`Removing ${entryPointPath} from require cache`);
-      delete require.cache[entryPointPath];
+    if (process.env.APPIUM_RELOAD_EXTENSIONS && require.cache[entryPointFullPath]) {
+      log.debug(`Removing ${entryPointFullPath} from require cache`);
+      delete require.cache[entryPointFullPath];
     }
-    return [entryPointPath, mainClass];
+    return [entryPointFullPath, mainClass];
   }
 
   /**
@@ -672,6 +689,27 @@ export class ExtensionConfig {
   }
 }
 
+/**
+ * https://nodejs.org/api/packages.html#package-entry-points
+ *
+ * @param {any} exportsValue
+ * @returns {string | undefined}
+ */
+export function resolveEsmEntryPoint(exportsValue) {
+  if (_.isString(exportsValue) && exportsValue) {
+    return exportsValue;
+  }
+  if (!_.isPlainObject(exportsValue)) {
+    return;
+  }
+
+  for (const key of ['.', 'import']) {
+    if (exportsValue[key]) {
+      return resolveEsmEntryPoint(exportsValue[key]);
+    }
+  }
+}
+
 /**
  * An issue with the {@linkcode ExtManifest} for a particular extension.
  *

package/lib/extension/manifest.js

@@ -242,8 +242,8 @@ export class Manifest {
      * @type {InternalMetadata}
      */
     const internal = {
-      pkgName: pkgJson.name,
-      version: pkgJson.version,
+      pkgName: /** @type {string} */ (pkgJson.name),
+      version: /** @type {string} */ (pkgJson.version),
       appiumVersion: pkgJson.peerDependencies?.appium,
       installType,
       installSpec: `${pkgJson.name}@${pkgJson.version}`,

package/lib/schema/schema.js

@@ -1,4 +1,4 @@
-import Ajv from 'ajv';
+import {Ajv} from 'ajv';
 import addFormats from 'ajv-formats';
 import _ from 'lodash';
 import path from 'path';
@@ -453,7 +453,7 @@ class AppiumSchema {
           let refSchema;
           try {
             refSchema = this.getSchema($ref);
-          } catch (err) {
+          } catch {
             // this can happen if an extension schema supplies a $ref to a non-existent schema
             throw new SchemaUnknownSchemaError($ref);
           }

package/lib/utils.js

@@ -247,10 +247,10 @@ export function adjustNodePath() {
       // ! so it could break (maybe, eventually).
       // See https://gist.github.com/branneman/8048520#7-the-hack
       // @ts-ignore see above comment
-      // eslint-disable-next-line @typescript-eslint/no-var-requires
+
       require('module').Module._initPaths();
       return true;
-    } catch (e) {
+    } catch {
       return false;
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.13.1",
+  "version": "2.14.1",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -60,13 +60,13 @@
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/base-driver": "^9.13.1",
-    "@appium/base-plugin": "^2.2.50",
-    "@appium/docutils": "^1.0.26",
+    "@appium/base-driver": "^9.14.1",
+    "@appium/base-plugin": "^2.2.52",
+    "@appium/docutils": "^1.0.28",
     "@appium/logger": "^1.6.1",
-    "@appium/schema": "^0.7.0",
-    "@appium/support": "^6.0.0",
-    "@appium/types": "^0.22.3",
+    "@appium/schema": "^0.7.1",
+    "@appium/support": "^6.0.2",
+    "@appium/types": "^0.23.0",
     "@sidvind/better-ajv-errors": "3.0.1",
     "@types/argparse": "2.0.17",
     "@types/bluebird": "3.5.42",
@@ -89,12 +89,12 @@
     "resolve-from": "5.0.0",
     "semver": "7.6.3",
     "source-map-support": "0.5.21",
-    "teen_process": "2.2.2",
-    "type-fest": "4.30.0",
+    "teen_process": "2.2.3",
+    "type-fest": "4.31.0",
     "winston": "3.17.0",
     "wrap-ansi": "7.0.0",
     "ws": "8.18.0",
-    "yaml": "2.6.1"
+    "yaml": "2.7.0"
   },
   "engines": {
     "node": "^14.17.0 || ^16.13.0 || >=18.0.0",
@@ -103,5 +103,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "1d16ac6b4521b1ac06b8650c6bb5c311d8d49ae3"
+  "gitHead": "3467f32c8e3618db05b6b210544cfdc6a57bb73c"
 }

package/scripts/autoinstall-extensions.js

@@ -85,10 +85,10 @@ async function init() {
   }
   try {
     ({env, util, logger} = require('@appium/support'));
-    // @ts-ignore
+    // @ts-ignore This is OK
     ({runExtensionCommand} = require('../build/lib/cli/extension'));
     ({DRIVER_TYPE, PLUGIN_TYPE} = require('../build/lib/constants'));
-    // @ts-ignore
+    // @ts-ignore This is OK
     ({loadExtensions} = require('../build/lib/extension'));
     logger.getLogger('Appium').level = 'error';
 
@@ -119,7 +119,7 @@ async function main() {
 
   if (!driverEnv && !pluginEnv) {
     spinner.succeed(
-      wrap(`No drivers or plugins to automatically install. 
+      wrap(`No drivers or plugins to automatically install.
       If desired, provide arguments with comma-separated values "--drivers=<known_driver>[,known_driver...]" and/or "--plugins=<known_plugin>[,known_plugin...]" to the "npm install appium" command. The specified extensions will be installed automatically with Appium.  Note: to see the list of known extensions, run "appium <driver|plugin> list".`)
     );
     return;
@@ -193,7 +193,7 @@ async function checkAndInstallExtension({
   spinner,
 }) {
   const extList = await runExtensionCommand(
-    // @ts-ignore
+    // @ts-ignore This is OK
     {
       appiumHome,
       subcommand: type,
@@ -209,7 +209,7 @@ async function checkAndInstallExtension({
   }
   spinner.start(`Installing ${type} "${ext}"...`);
   await runExtensionCommand(
-    // @ts-ignore
+    // @ts-ignore this is OK
     {
       subcommand: type,
       appiumHome,