appium 2.0.0-beta.46 → 2.0.0-beta.48

package/lib/cli/extension-command.js

@@ -18,6 +18,16 @@ const UPDATE_ALL = 'installed';
 class NotUpdatableError extends Error {}
 class NoUpdatesAvailableError extends Error {}
 
+/**
+ * Omits `driverName`/`pluginName` props from the receipt to make a {@linkcode ExtManifest}
+ * @template {ExtensionType} ExtType
+ * @param {ExtInstallReceipt<ExtType>} receipt
+ * @returns {ExtManifest<ExtType>}
+ */
+function receiptToManifest(receipt) {
+  return /** @type {ExtManifest<ExtType>} */ (_.omit(receipt, 'driverName', 'pluginName'));
+}
+
 /**
  * @template {ExtensionType} ExtType
  */
@@ -128,10 +138,14 @@ class ExtensionCommand {
           // also don't need to check for updates on non-npm exts
           continue;
         }
-        const updates = await this.checkForExtensionUpdate(ext);
-        data.updateVersion = updates.safeUpdate;
-        data.unsafeUpdateVersion = updates.unsafeUpdate;
-        data.upToDate = updates.safeUpdate === null && updates.unsafeUpdate === null;
+        try {
+          const updates = await this.checkForExtensionUpdate(ext);
+          data.updateVersion = updates.safeUpdate;
+          data.unsafeUpdateVersion = updates.unsafeUpdate;
+          data.upToDate = updates.safeUpdate === null && updates.unsafeUpdate === null;
+        } catch (e) {
+          data.updateError = e.message;
+        }
       }
     });
 
@@ -149,8 +163,15 @@ class ExtensionCommand {
       let upToDateTxt = '';
       let unsafeUpdateTxt = '';
       if (data.installed) {
-        const {installType, installSpec, updateVersion, unsafeUpdateVersion, version, upToDate} =
-          data;
+        const {
+          installType,
+          installSpec,
+          updateVersion,
+          unsafeUpdateVersion,
+          version,
+          upToDate,
+          updateError,
+        } = data;
         let typeTxt;
         switch (installType) {
           case INSTALL_TYPE_GIT:
@@ -166,14 +187,18 @@ class ExtensionCommand {
         installTxt = `@${version.yellow} ${('[installed ' + typeTxt + ']').green}`;
 
         if (showUpdates) {
-          if (updateVersion) {
-            updateTxt = ` [${updateVersion} available]`.magenta;
-          }
-          if (upToDate) {
-            upToDateTxt = ` [Up to date]`.green;
-          }
-          if (unsafeUpdateVersion) {
-            unsafeUpdateTxt = ` [${unsafeUpdateVersion} available (potentially unsafe)]`.cyan;
+          if (updateError) {
+            updateTxt = ` [Cannot check for updates: ${updateError}]`.red;
+          } else {
+            if (updateVersion) {
+              updateTxt = ` [${updateVersion} available]`.magenta;
+            }
+            if (upToDate) {
+              upToDateTxt = ` [Up to date]`.green;
+            }
+            if (unsafeUpdateVersion) {
+              unsafeUpdateTxt = ` [${unsafeUpdateVersion} available (potentially unsafe)]`.cyan;
+            }
           }
         }
       }
@@ -187,12 +212,12 @@ class ExtensionCommand {
   /**
    * Install an extension
    *
-   * @param {InstallArgs} args
+   * @param {InstallOpts} opts
    * @return {Promise<ExtRecord<ExtType>>} map of all installed extension names to extension data
    */
   async _install({installSpec, installType, packageName}) {
-    /** @type {ExtensionFields<ExtType>} */
-    let extData;
+    /** @type {ExtInstallReceipt<ExtType>} */
+    let receipt;
 
     if (packageName && [INSTALL_TYPE_LOCAL, INSTALL_TYPE_NPM].includes(installType)) {
       throw this._createFatalError(`When using --source=${installType}, cannot also use --package`);
@@ -205,7 +230,7 @@ class ExtensionCommand {
     /**
      * @type {InstallViaNpmArgs}
      */
-    let installOpts;
+    let installViaNpmOpts;
 
     /**
      * The probable (?) name of the extension derived from the install spec.
@@ -223,8 +248,9 @@ class ExtensionCommand {
             'it should be of the form <org>/<repo>'
         );
       }
-      installOpts = {
+      installViaNpmOpts = {
         installSpec,
+        installType,
         pkgName: /** @type {string} */ (packageName),
       };
       probableExtName = installSpec;
@@ -232,8 +258,9 @@ class ExtensionCommand {
       // git urls can have '.git' at the end, but this is not necessary and would complicate the
       // way we download and name directories, so we can just remove it
       installSpec = installSpec.replace(/\.git$/, '');
-      installOpts = {
+      installViaNpmOpts = {
         installSpec,
+        installType,
         pkgName: /** @type {string} */ (packageName),
       };
       probableExtName = installSpec;
@@ -279,7 +306,7 @@ class ExtensionCommand {
           installType = INSTALL_TYPE_NPM;
         }
       }
-      installOpts = {installSpec, pkgName, pkgVer};
+      installViaNpmOpts = {installSpec, pkgName, pkgVer, installType};
     }
 
     // fail fast here if we can
@@ -291,11 +318,12 @@ class ExtensionCommand {
       );
     }
 
-    extData = await this.installViaNpm(installOpts);
+    receipt = await this.installViaNpm(installViaNpmOpts);
 
     // this _should_ be the same as `probablyExtName` as the one derived above unless
     // install type is local.
-    const extName = extData[/** @type {string} */ (`${this.type}Name`)];
+    /** @type {string} */
+    const extName = receipt[/** @type {string} */ (`${this.type}Name`)];
 
     // check _a second time_ with the more-accurate extName
     if (this.config.isInstalled(extName)) {
@@ -308,10 +336,9 @@ class ExtensionCommand {
 
     // this field does not exist as such in the manifest (it's used as a property name instead)
     // so that's why it's being removed here.
-    delete extData[/** @type {string} */ (`${this.type}Name`)];
-
     /** @type {ExtManifest<ExtType>} */
-    const extManifest = {...extData, installType, installSpec};
+    const extManifest = receiptToManifest(receipt);
+
     const [errors, warnings] = await B.all([
       this.config.getProblems(extName, extManifest),
       this.config.getWarnings(extName, extManifest),
@@ -334,13 +361,13 @@ class ExtensionCommand {
 
     await this.config.addExtension(extName, extManifest);
 
-    // update the if we've changed the local `package.json`
+    // update the hash if we've changed the local `package.json`
     if (await env.hasAppiumDependency(this.config.appiumHome)) {
       await packageDidChange(this.config.appiumHome);
     }
 
     // log info for the user
-    this.log.info(this.getPostInstallText({extName, extData}));
+    this.log.info(this.getPostInstallText({extName, extData: receipt}));
 
     return this.config.installedExtensions;
   }
@@ -349,21 +376,28 @@ class ExtensionCommand {
    * Install an extension via NPM
    *
    * @param {InstallViaNpmArgs} args
+   * @returns {Promise<ExtInstallReceipt<ExtType>>}
    */
-  async installViaNpm({installSpec, pkgName, pkgVer}) {
+  async installViaNpm({installSpec, pkgName, pkgVer, installType}) {
     const npmSpec = `${pkgName}${pkgVer ? '@' + pkgVer : ''}`;
     const specMsg = npmSpec === installSpec ? '' : ` using NPM install spec '${npmSpec}'`;
     const msg = `Installing '${installSpec}'${specMsg}`;
     try {
-      const pkgJsonData = await spinWith(this.isJsonOutput, msg, async () => {
-        const pkgJsonData = await npm.installPackage(this.config.appiumHome, pkgName, {
+      const {pkg, path} = await spinWith(this.isJsonOutput, msg, async () => {
+        const {pkg, installPath: path} = await npm.installPackage(this.config.appiumHome, pkgName, {
           pkgVer,
+          installType,
         });
-        this.validatePackageJson(pkgJsonData, installSpec);
-        return pkgJsonData;
+        this.validatePackageJson(pkg, installSpec);
+        return {pkg, path};
       });
 
-      return this.getExtensionFields(pkgJsonData);
+      return this.getInstallationReceipt({
+        pkg,
+        installPath: path,
+        installType,
+        installSpec,
+      });
     } catch (err) {
       throw this._createFatalError(`Encountered an error when installing package: ${err.message}`);
     }
@@ -382,25 +416,31 @@ class ExtensionCommand {
   }
 
   /**
-   * Take an NPM module's package.json and extract Appium driver information from a special
-   * 'appium' field in the JSON data. We need this information to e.g. determine which class to
-   * load as the main driver class, or to be able to detect incompatibilities between driver and
-   * appium versions.
+   * Once a package is installed on-disk, this gathers some necessary metadata for validation.
    *
-   * @param {ExtPackageJson<ExtType>} pkgJson - the package.json data for a driver module, as if it had been straightforwardly 'require'd
-   * @returns {ExtensionFields<ExtType>}
+   * @param {GetInstallationReceiptOpts<ExtType>} opts
+   * @returns {ExtInstallReceipt<ExtType>}
    */
-  getExtensionFields(pkgJson) {
-    const {appium, name, version, peerDependencies} = pkgJson;
+  getInstallationReceipt({pkg, installPath, installType, installSpec}) {
+    const {appium, name, version, peerDependencies} = pkg;
 
-    /** @type {unknown} */
-    const result = {
-      ...appium,
+    /** @type {import('appium/types').InternalMetadata} */
+    const internal = {
       pkgName: name,
       version,
+      installType,
+      installSpec,
+      installPath,
       appiumVersion: peerDependencies?.appium,
     };
-    return /** @type {ExtensionFields<ExtType>} */ (result);
+
+    /** @type {ExtMetadata<ExtType>} */
+    const extMetadata = appium;
+
+    return {
+      ...internal,
+      ...extMetadata,
+    };
   }
 
   /**
@@ -410,13 +450,13 @@ class ExtensionCommand {
    * - `name`
    * - `version`
    * - `appium`
-   * @param {import('type-fest').PackageJson} pkgJson - `package.json` of extension
+   * @param {import('type-fest').PackageJson} pkg - `package.json` of extension
    * @param {string} installSpec - Extension name/spec
    * @throws {ReferenceError} If `package.json` has a missing or invalid field
-   * @returns {pkgJson is ExtPackageJson<ExtType>}
+   * @returns {pkg is ExtPackageJson<ExtType>}
    */
-  validatePackageJson(pkgJson, installSpec) {
-    const {appium, name, version} = /** @type {ExtPackageJson<ExtType>} */ (pkgJson);
+  validatePackageJson(pkg, installSpec) {
+    const {appium, name, version} = /** @type {ExtPackageJson<ExtType>} */ (pkg);
 
     /**
      *
@@ -608,9 +648,10 @@ class ExtensionCommand {
    * @returns {Promise<void>}
    */
   async updateExtension(installSpec, version) {
-    const {pkgName} = this.config.installedExtensions[installSpec];
+    const {pkgName, installType} = this.config.installedExtensions[installSpec];
     const extData = await this.installViaNpm({
       installSpec,
+      installType,
       pkgName,
       pkgVer: version,
     });
@@ -637,7 +678,7 @@ class ExtensionCommand {
     const extConfig = this.config.installedExtensions[installSpec];
 
     // note: TS cannot understand that _.has() is a type guard
-    if (!extConfig.scripts) {
+    if (!('scripts' in extConfig)) {
       throw this._createFatalError(
         `The ${this.type} named '${installSpec}' does not contain the ` +
           `"scripts" field underneath the "appium" field in its package.json`
@@ -646,13 +687,13 @@ class ExtensionCommand {
 
     const extScripts = extConfig.scripts;
 
-    if (!_.isPlainObject(extScripts)) {
+    if (!extScripts || !_.isPlainObject(extScripts)) {
       throw this._createFatalError(
         `The ${this.type} named '${installSpec}' "scripts" field must be a plain object`
       );
     }
 
-    if (!_.has(extScripts, scriptName)) {
+    if (!(scriptName in extScripts)) {
       throw this._createFatalError(
         `The ${this.type} named '${installSpec}' does not support the script: '${scriptName}'`
       );
@@ -701,6 +742,7 @@ export {ExtensionCommand};
  * @property {string?} updateVersion - If the extension is installed, the version it can be updated to
  * @property {string?} unsafeUpdateVersion - Same as above, but a major version bump
  * @property {boolean} upToDate - If the extension is installed and the latest
+ * @property {string?} updateError - Update check error message (if present)
  */
 
 /**
@@ -734,11 +776,14 @@ export {ExtensionCommand};
  * @typedef {import('appium/types').ExtPackageJson<ExtType>} ExtPackageJson
  */
 
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtInstallReceipt<ExtType>} ExtInstallReceipt
+ */
+
 /**
  * Possible return value for {@linkcode ExtensionCommand.list}
- * @typedef UninstalledExtensionListData
- * @property {string} pkgName
- * @property {false} installed
+ * @typedef {Partial<InstalledExtensionListData> & {pkgName: string, installed: false}} UninstalledExtensionListData
  */
 
 /**
@@ -806,6 +851,7 @@ export {ExtensionCommand};
  * @typedef InstallViaNpmArgs
  * @property {string} installSpec - the name or spec of an extension to install
  * @property {string} pkgName - the NPM package name of the extension
+ * @property {import('appium/types').InstallType} installType - type of install
  * @property {string} [pkgVer] - the specific version of the NPM package
  */
 
@@ -819,18 +865,12 @@ export {ExtensionCommand};
 
 /**
  * Options for {@linkcode ExtensionCommand._install}
- * @typedef InstallArgs
+ * @typedef InstallOpts
  * @property {string} installSpec - the name or spec of an extension to install
- * @property {import('appium/types').InstallType} installType - how to install this extension. One of the INSTALL_TYPES
+ * @property {InstallType} installType - how to install this extension. One of the INSTALL_TYPES
  * @property {string} [packageName] - for git/github installs, the extension node package name
  */
 
-/**
- * Returned by {@linkcode ExtensionCommand.getExtensionFields}
- * @template {ExtensionType} ExtType
- * @typedef {ExtMetadata<ExtType> & { pkgName: string, version: string, appiumVersion: string } & import('appium/types').CommonExtMetadata} ExtensionFields
- */
-
 /**
  * @template {ExtensionType} ExtType
  * @typedef {ExtType extends DriverType ? typeof import('../constants').KNOWN_DRIVERS : ExtType extends PluginType ? typeof import('../constants').KNOWN_PLUGINS : never} KnownExtensions
@@ -841,3 +881,17 @@ export {ExtensionCommand};
  * @property {boolean} showInstalled - whether should show only installed extensions
  * @property {boolean} showUpdates - whether should show available updates
  */
+
+/**
+ * Opts for {@linkcode ExtensionCommand.getInstallationReceipt}
+ * @template {ExtensionType} ExtType
+ * @typedef GetInstallationReceiptOpts
+ * @property {string} installPath
+ * @property {string} installSpec
+ * @property {ExtPackageJson<ExtType>} pkg
+ * @property {InstallType} installType
+ */
+
+/**
+ * @typedef {import('appium/types').InstallType} InstallType
+ */

package/lib/cli/extension.js

@@ -1,7 +1,8 @@
 /* eslint-disable no-console */
+import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
+import {isExtensionCommandArgs} from '../utils';
 import DriverCommand from './driver-command';
 import PluginCommand from './plugin-command';
-import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
 import {errAndQuit, JSON_SPACES} from './utils';
 
 export const commandClasses = Object.freeze(
@@ -15,18 +16,18 @@ 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 {import('appium/types').Args<import('appium/types').WithExtSubcommand>} args - JS object where the key is the parameter name (as defined in
+ * @template {import('appium/types').CliExtensionCommand} Cmd
+ * @template {import('appium/types').CliExtensionSubcommand} SubCmd
+ * @param {import('appium/types').Args<Cmd, SubCmd>} args - JS object where the key is the parameter name (as defined in
  * driver-parser.js)
- * @template {ExtensionType} ExtType
- * @param {import('../extension/extension-config').ExtensionConfig<ExtType>} config - Extension config object
+ * @param {import('../extension/extension-config').ExtensionConfig<Cmd>} config - Extension config object
  */
 async function runExtensionCommand(args, config) {
   // TODO driver config file should be locked while any of these commands are
   // running to prevent weird situations
   let jsonResult = null;
-  const {extensionType: type} = config;
-  const extCmd = args[`${type}Command`];
-  if (!extCmd) {
+  const {extensionType: type} = config; // NOTE this is the same as `args.subcommand`
+  if (!isExtensionCommandArgs(args)) {
     throw new TypeError(`Cannot call ${type} command without a subcommand like 'install'`);
   }
   let {json, suppressOutput} = args;
@@ -34,7 +35,7 @@ async function runExtensionCommand(args, config) {
   if (suppressOutput) {
     json = true;
   }
-  const CommandClass = /** @type {ExtCommand<ExtType>} */ (commandClasses[type]);
+  const CommandClass = /** @type {ExtCommand<Cmd>} */ (commandClasses[type]);
   const cmd = new CommandClass({config, json});
   try {
     jsonResult = await cmd.execute(args);

package/lib/cli/parser.js

@@ -89,9 +89,9 @@ class ArgParser {
    * If no subcommand is passed in, this method will inject the `server` subcommand.
    *
    * `ArgParser.prototype.parse_args` is an alias of this method.
-   * @template [T=import('appium/types').WithServerSubcommand]
+   * @template {import('appium/types').CliCommand} [Cmd=import('appium/types').ServerCommand]
    * @param {string[]} [args] - Array of arguments, ostensibly from `process.argv`. Gathers args from `process.argv` if not provided.
-   * @returns {import('appium/types').Args<T>} - The parsed arguments
+   * @returns {import('appium/types').Args<Cmd>} - The parsed arguments
    */
   parseArgs(args = process.argv.slice(2)) {
     if (!NON_SERVER_ARGS.has(args[0])) {

package/lib/config-file.js

@@ -154,9 +154,8 @@ export function normalizeConfig(config) {
   const normalize = (config, section) => {
     const obj = _.isUndefined(section) ? config : _.get(config, section, config);
 
-    const mappedObj = _.mapKeys(
-      obj,
-      (__, prop) => schema.properties[prop]?.appiumCliDest ?? _.camelCase(prop)
+    const mappedObj = _.mapKeys(obj, (__, prop) =>
+      _.get(schema, `properties.server.properties[${prop}].appiumCliDest`, _.camelCase(prop))
     );
 
     return _.mapValues(mappedObj, (value, property) => {

package/lib/config.js

@@ -298,11 +298,12 @@ function showConfig(nonDefaultPreConfigParsedArgs, configResult, defaults, parse
   } else {
     console.log(`\n(no configuration file loaded)`);
   }
-  if (_.isEmpty(nonDefaultPreConfigParsedArgs)) {
+  const compactedNonDefaultPreConfigArgs = compactConfig(nonDefaultPreConfigParsedArgs);
+  if (_.isEmpty(compactedNonDefaultPreConfigArgs)) {
     console.log(`\n(no CLI parameters provided)`);
   } else {
     console.log('\nvia CLI or function call:\n');
-    console.dir(compactConfig(nonDefaultPreConfigParsedArgs));
+    console.dir(compactedNonDefaultPreConfigArgs);
   }
   console.log('\nfinal configuration:\n');
   console.dir(compactConfig(parsedArgs));

package/lib/constants.js

@@ -29,6 +29,7 @@ export const KNOWN_PLUGINS = Object.freeze(
     images: '@appium/images-plugin',
     'execute-driver': '@appium/execute-driver-plugin',
     'relaxed-caps': '@appium/relaxed-caps-plugin',
+    'universal-xml': '@appium/universal-xml-plugin',
   })
 );
 
@@ -40,15 +41,11 @@ export const KNOWN_DRIVERS = Object.freeze(
   /** @type {const} */ ({
     uiautomator2: 'appium-uiautomator2-driver',
     xcuitest: 'appium-xcuitest-driver',
-    youiengine: 'appium-youiengine-driver',
-    windows: 'appium-windows-driver',
-    mac: 'appium-mac-driver',
     mac2: 'appium-mac2-driver',
     espresso: 'appium-espresso-driver',
-    tizen: 'appium-tizen-driver',
-    flutter: 'appium-flutter-driver',
     safari: 'appium-safari-driver',
     gecko: 'appium-geckodriver',
+    chromium: 'appium-chromium-driver',
   })
 );
 
@@ -67,3 +64,8 @@ export const EXT_SUBCOMMAND_INSTALL = 'install';
 export const EXT_SUBCOMMAND_UNINSTALL = 'uninstall';
 export const EXT_SUBCOMMAND_UPDATE = 'update';
 export const EXT_SUBCOMMAND_RUN = 'run';
+
+/**
+ * Current revision of the manifest (`extensions.yaml`) schema
+ */
+export const CURRENT_SCHEMA_REV = 3;