appium 2.0.0-beta.35 → 2.0.0-beta.37

package/lib/extension/index.js

@@ -1,10 +1,10 @@
-
 import _ from 'lodash';
-import { USE_ALL_PLUGINS } from '../constants';
+import {USE_ALL_PLUGINS} from '../constants';
 import log from '../logger';
-import { DriverConfig } from './driver-config';
-import { Manifest } from './manifest';
-import { PluginConfig } from './plugin-config';
+import {DriverConfig} from './driver-config';
+import {Manifest} from './manifest';
+import {PluginConfig} from './plugin-config';
+import B from 'bluebird';
 
 /**
  * Loads extensions and creates `ExtensionConfig` instances.
@@ -17,15 +17,13 @@ import { PluginConfig } from './plugin-config';
  * @param {string} appiumHome
  * @returns {Promise<ExtensionConfigs>}
  */
-export async function loadExtensions (appiumHome) {
+export async function loadExtensions(appiumHome) {
   const manifest = Manifest.getInstance(appiumHome);
-  const {drivers, plugins} = await manifest.read();
-  const driverConfig =
-    DriverConfig.getInstance(manifest) ??
-    DriverConfig.create(manifest, {extData: drivers});
-  const pluginConfig =
-    PluginConfig.getInstance(manifest) ??
-    PluginConfig.create(manifest, {extData: plugins});
+  await manifest.read();
+  const driverConfig = DriverConfig.getInstance(manifest) ?? DriverConfig.create(manifest);
+  const pluginConfig = PluginConfig.getInstance(manifest) ?? PluginConfig.create(manifest);
+
+  await B.all([driverConfig.validate(), pluginConfig.validate()]);
   return {driverConfig, pluginConfig};
 }
 
@@ -37,31 +35,31 @@ export async function loadExtensions (appiumHome) {
  *
  * @param {import('./plugin-config').PluginConfig} pluginConfig - a plugin extension config
  * @param {string[]} usePlugins
- * @returns {import('../../types').PluginClass[]}
+ * @returns {PluginNameMap} Mapping of PluginClass to name
  */
-export function getActivePlugins (pluginConfig, usePlugins = []) {
-  return _.compact(
-    Object.keys(pluginConfig.installedExtensions)
-      .filter(
-        (pluginName) =>
-          _.includes(usePlugins, pluginName) ||
-          (usePlugins.length === 1 && usePlugins[0] === USE_ALL_PLUGINS),
-      )
-      .map((pluginName) => {
-        try {
-          log.info(`Attempting to load plugin ${pluginName}...`);
-          const PluginClass = pluginConfig.require(pluginName);
-
-          PluginClass.pluginName = pluginName; // store the plugin name on the class so it can be used later
-          return PluginClass;
-        } catch (err) {
-          log.error(
-            `Could not load plugin '${pluginName}', so it will not be available. Error ` +
-              `in loading the plugin was: ${err.message}`,
-          );
-          log.debug(err.stack);
-        }
-      }),
+export function getActivePlugins(pluginConfig, usePlugins = []) {
+  return new Map(
+    _.compact(
+      Object.keys(pluginConfig.installedExtensions)
+        .filter(
+          (pluginName) =>
+            _.includes(usePlugins, pluginName) ||
+            (usePlugins.length === 1 && usePlugins[0] === USE_ALL_PLUGINS)
+        )
+        .map((pluginName) => {
+          try {
+            log.info(`Attempting to load plugin ${pluginName}...`);
+            const PluginClass = pluginConfig.require(pluginName);
+            return [PluginClass, pluginName];
+          } catch (err) {
+            log.error(
+              `Could not load plugin '${pluginName}', so it will not be available. Error ` +
+                `in loading the plugin was: ${err.message}`
+            );
+            log.debug(err.stack);
+          }
+        })
+    )
   );
 }
 
@@ -72,31 +70,47 @@ export function getActivePlugins (pluginConfig, usePlugins = []) {
  *
  * @param {import('./driver-config').DriverConfig} driverConfig - a driver extension config
  * @param {string[]} [useDrivers] - optional list of drivers to load
+ * @returns {DriverNameMap}
  */
-export function getActiveDrivers (driverConfig, useDrivers = []) {
-  return _.compact(
-    Object.keys(driverConfig.installedExtensions)
-      .filter(
-        (driverName) =>
-          _.includes(useDrivers, driverName) || useDrivers.length === 0,
-      )
-      .map((driverName) => {
-        try {
-          log.info(`Attempting to load driver ${driverName}...`);
-          return driverConfig.require(driverName);
-        } catch (err) {
-          log.error(
-            `Could not load driver '${driverName}', so it will not be available. Error ` +
-              `in loading the driver was: ${err.message}`,
-          );
-          log.debug(err.stack);
-        }
-      }),
+export function getActiveDrivers(driverConfig, useDrivers = []) {
+  return new Map(
+    _.compact(
+      Object.keys(driverConfig.installedExtensions)
+        .filter((driverName) => _.includes(useDrivers, driverName) || useDrivers.length === 0)
+        .map((driverName) => {
+          try {
+            log.info(`Attempting to load driver ${driverName}...`);
+            const DriverClass = driverConfig.require(driverName);
+            return [DriverClass, driverName];
+          } catch (err) {
+            log.error(
+              `Could not load driver '${driverName}', so it will not be available. Error ` +
+                `in loading the driver was: ${err.message}`
+            );
+            log.debug(err.stack);
+          }
+        })
+    )
   );
 }
 
+/**
+ * A mapping of {@linkcode PluginClass} classes to their names.
+ * @typedef {Map<PluginClass,string>} PluginNameMap
+ */
+
+/**
+ * A mapping of {@linkcode DriverClass} classes to their names.
+ * @typedef {Map<DriverClass,string>} DriverNameMap
+ */
+
+/**
+ * @typedef {import('@appium/types').PluginClass} PluginClass
+ * @typedef {import('@appium/types').DriverClass} DriverClass
+ */
+
 /**
  * @typedef ExtensionConfigs
- * @property {DriverConfig} driverConfig
- * @property {PluginConfig} pluginConfig
+ * @property {import('./driver-config').DriverConfig} driverConfig
+ * @property {import('./plugin-config').PluginConfig} pluginConfig
  */

package/lib/extension/manifest.js

@@ -2,14 +2,14 @@
  * Module containing {@link Manifest} which handles reading & writing of extension config files.
  */
 
-import { env, fs } from '@appium/support';
+import {env, fs} from '@appium/support';
 import _ from 'lodash';
 import path from 'path';
 import YAML from 'yaml';
-import { DRIVER_TYPE, PLUGIN_TYPE } from '../constants';
+import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
 import log from '../logger';
-import { INSTALL_TYPE_NPM } from './extension-config';
-import { packageDidChange } from './package-changed';
+import {INSTALL_TYPE_NPM} from './extension-config';
+import {packageDidChange} from './package-changed';
 
 /**
  * Default depth to search in directory tree for whatever it is we're looking for.
@@ -61,7 +61,7 @@ const INITIAL_MANIFEST_DATA = Object.freeze({
  * @param {any} value
  * @returns {value is ExtPackageJson<ExtensionType>}
  */
-function isExtension (value) {
+function isExtension(value) {
   return (
     _.isPlainObject(value) &&
     _.isPlainObject(value.appium) &&
@@ -77,7 +77,7 @@ function isExtension (value) {
  * @param {any} value - Value to test
  * @returns {value is ExtPackageJson<DriverType>}
  */
-function isDriver (value) {
+function isDriver(value) {
   return (
     isExtension(value) &&
     _.isString(_.get(value, 'appium.driverName')) &&
@@ -93,7 +93,7 @@ function isDriver (value) {
  * @param {any} value - Value to test
  * @returns {value is ExtPackageJson<PluginType>}
  */
-function isPlugin (value) {
+function isPlugin(value) {
   return isExtension(value) && _.isString(_.get(value, 'appium.pluginName'));
 }
 
@@ -157,7 +157,7 @@ export class Manifest {
    * @param {string} appiumHome
    * @private
    */
-  constructor (appiumHome) {
+  constructor(appiumHome) {
     this._appiumHome = appiumHome;
     this._data = _.cloneDeep(INITIAL_MANIFEST_DATA);
   }
@@ -169,9 +169,7 @@ export class Manifest {
    * @param {string} appiumHome - Path to `APPIUM_HOME`
    * @returns {Manifest}
    */
-  static getInstance = _.memoize(function _getInstance (
-    appiumHome,
-  ) {
+  static getInstance = _.memoize(function _getInstance(appiumHome) {
     return new Manifest(appiumHome);
   });
 
@@ -180,24 +178,18 @@ export class Manifest {
    * @param {SyncWithInstalledExtensionsOpts} opts
    * @returns {Promise<boolean>} `true` if any extensions were added, `false` otherwise.
    */
-  async syncWithInstalledExtensions ({depthLimit = DEFAULT_SEARCH_DEPTH} = {}) {
+  async syncWithInstalledExtensions({depthLimit = DEFAULT_SEARCH_DEPTH} = {}) {
     const walkOpts = _.defaults({depthLimit}, DEFAULT_FIND_EXTENSIONS_OPTS);
     // this could be parallelized, but we can't use fs.walk as an async iterator
     let didChange = false;
-    for await (const {stats, path: filepath} of fs.walk(
-      this._appiumHome,
-      walkOpts,
-    )) {
+    for await (const {stats, path: filepath} of fs.walk(this._appiumHome, walkOpts)) {
       if (filepath !== this._appiumHome && stats.isDirectory()) {
         try {
           const pkg = await env.readPackageInDir(filepath);
           if (pkg && isExtension(pkg)) {
             // it's possible that this extension already exists in the manifest,
             // so only update `didChange` if it's new.
-            const added = this.addExtensionFromPackage(
-              pkg,
-              path.join(filepath, 'package.json'),
-            );
+            const added = this.addExtensionFromPackage(pkg, path.join(filepath, 'package.json'));
             didChange = didChange || added;
           }
         } catch {}
@@ -211,7 +203,7 @@ export class Manifest {
    * @param {string} name - Driver name
    * @returns {boolean}
    */
-  hasDriver (name) {
+  hasDriver(name) {
     return Boolean(this._data.drivers[name]);
   }
 
@@ -220,7 +212,7 @@ export class Manifest {
    * @param {string} name - Plugin name
    * @returns {boolean}
    */
-  hasPlugin (name) {
+  hasPlugin(name) {
     return Boolean(this._data.plugins[name]);
   }
 
@@ -233,13 +225,16 @@ export class Manifest {
    * @param {string} pkgPath
    * @returns {boolean} - `true` upon success, `false` if the extension is already registered.
    */
-  addExtensionFromPackage (pkgJson, pkgPath) {
+  addExtensionFromPackage(pkgJson, pkgPath) {
+    const extensionPath = path.dirname(pkgPath);
+
     /**
      * @type {InternalMetadata}
      */
     const internal = {
       pkgName: pkgJson.name,
       version: pkgJson.version,
+      appiumVersion: pkgJson.peerDependencies?.appium,
       installType: INSTALL_TYPE_NPM,
       installSpec: `${pkgJson.name}@${pkgJson.version}`,
     };
@@ -248,7 +243,7 @@ export class Manifest {
       if (!this.hasDriver(pkgJson.appium.driverName)) {
         this.addExtension(DRIVER_TYPE, pkgJson.appium.driverName, {
           ..._.omit(pkgJson.appium, 'driverName'),
-          ...internal
+          ...internal,
         });
         return true;
       }
@@ -264,9 +259,7 @@ export class Manifest {
       return false;
     } else {
       throw new TypeError(
-        `The extension in ${path.dirname(
-          pkgPath,
-        )} is neither a valid driver nor a valid plugin.`,
+        `The extension in ${extensionPath} is neither a valid driver nor a valid plugin.`
       );
     }
   }
@@ -280,23 +273,25 @@ export class Manifest {
    * @param {ExtType} extType - `driver` or `plugin`
    * @param {string} extName - Name of extension
    * @param {ExtManifest<ExtType>} extData - Extension metadata
-   * @returns {void}
+   * @returns {ExtManifest<ExtType>} A clone of `extData`, potentially with a mutated `appiumVersion` field
    */
-  addExtension (extType, extName, extData) {
-    this._data[`${extType}s`][extName] = extData;
+  addExtension(extType, extName, extData) {
+    const data = _.clone(extData);
+    this._data[`${extType}s`][extName] = data;
+    return data;
   }
 
   /**
    * Returns the APPIUM_HOME path
    */
-  get appiumHome () {
+  get appiumHome() {
     return this._appiumHome;
   }
 
   /**
    * Returns the path to the manifest file
    */
-  get manifestPath () {
+  get manifestPath() {
     return this._manifestPath;
   }
 
@@ -307,7 +302,7 @@ export class Manifest {
    * @param {ExtType} extType
    * @returns {ExtRecord<ExtType>}
    */
-  getExtensionData (extType) {
+  getExtensionData(extType) {
     return this._data[/** @type {string} */ (`${extType}s`)];
   }
 
@@ -321,7 +316,7 @@ export class Manifest {
    * Only one read operation should happen at a time.  This is controlled via the {@link Manifest._reading} property.
    * @returns {Promise<ManifestData>} The data
    */
-  async read () {
+  async read() {
     if (this._reading) {
       await this._reading;
       return this._data;
@@ -336,6 +331,7 @@ export class Manifest {
         log.debug(`Reading ${this._manifestPath}...`);
         const yaml = await fs.readFile(this._manifestPath, 'utf8');
         data = YAML.parse(yaml);
+        log.debug(`Parsed manifest file: ${JSON.stringify(data, null, 2)}`);
       } catch (err) {
         if (err.code === 'ENOENT') {
           data = _.cloneDeep(INITIAL_MANIFEST_DATA);
@@ -344,11 +340,11 @@ export class Manifest {
           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}`,
+                `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}`,
+              `Appium encountered an unknown problem. Specific error: ${err.message}`
             );
           }
         }
@@ -357,7 +353,7 @@ export class Manifest {
       this._data = data;
       let installedExtensionsChanged = false;
       if (
-        await env.hasAppiumDependency(this.appiumHome) &&
+        (await env.hasAppiumDependency(this.appiumHome)) &&
         (await packageDidChange(this.appiumHome))
       ) {
         installedExtensionsChanged = await this.syncWithInstalledExtensions();
@@ -382,14 +378,14 @@ export class Manifest {
    * @private
    * @returns {Promise<string>}
    */
-  async _setManifestPath () {
+  async _setManifestPath() {
     if (!this._manifestPath) {
       this._manifestPath = await env.resolveManifestPath(this._appiumHome);
 
       /* istanbul ignore if */
       if (path.relative(this._appiumHome, this._manifestPath).startsWith('.')) {
         throw new Error(
-          `Mismatch between location of APPIUM_HOME and manifest file. APPIUM_HOME: ${this.appiumHome}, manifest file: ${this._manifestPath}`,
+          `Mismatch between location of APPIUM_HOME and manifest file. APPIUM_HOME: ${this.appiumHome}, manifest file: ${this._manifestPath}`
         );
       }
     }
@@ -405,7 +401,7 @@ export class Manifest {
    * @todo If this becomes too much of a bottleneck, throttle it.
    * @returns {Promise<boolean>} Whether the data was written
    */
-  async write () {
+  async write() {
     if (this._writing) {
       return this._writing;
     }
@@ -416,21 +412,17 @@ export class Manifest {
       } catch (err) {
         throw new Error(
           `Appium could not create the directory for the manifest file: ${path.dirname(
-            this._manifestPath,
-          )}. Original error: ${err.message}`,
+            this._manifestPath
+          )}. Original error: ${err.message}`
         );
       }
       try {
-        await fs.writeFile(
-          this._manifestPath,
-          YAML.stringify(this._data),
-          'utf8',
-        );
+        await fs.writeFile(this._manifestPath, YAML.stringify(this._data), 'utf8');
         return true;
       } catch (err) {
         throw new Error(
           `Appium could not write to manifest at ${this._manifestPath} using APPIUM_HOME ${this._appiumHome}. ` +
-            `Please ensure it is writable. Original error: ${err.message}`,
+            `Please ensure it is writable. Original error: ${err.message}`
         );
       }
     })();
@@ -444,12 +436,12 @@ export class Manifest {
 
 /**
  * Type of the string referring to a driver (typically as a key or type string)
- * @typedef {import('../../types').DriverType} DriverType
+ * @typedef {import('@appium/types').DriverType} DriverType
  */
 
 /**
  * Type of the string referring to a plugin (typically as a key or type string)
- * @typedef {import('../../types').PluginType} PluginType
+ * @typedef {import('@appium/types').PluginType} PluginType
  */
 
 /**
@@ -458,27 +450,26 @@ export class Manifest {
  */
 
 /**
- * @typedef {import('../../types/appium-manifest').ManifestData} ManifestData
- * @typedef {import('../../types/appium-manifest').InternalMetadata} InternalMetadata
+ * @typedef {import('appium/types').ManifestData} ManifestData
+ * @typedef {import('appium/types').InternalMetadata} InternalMetadata
  */
 
 /**
  * @template T
- * @typedef {import('../../types/external-manifest').ExtPackageJson<T>} ExtPackageJson
+ * @typedef {import('appium/types').ExtPackageJson<T>} ExtPackageJson
  */
 
 /**
  * @template T
- * @typedef {import('../../types/appium-manifest').ExtManifest<T>} ExtManifest
+ * @typedef {import('appium/types').ExtManifest<T>} ExtManifest
  */
 
 /**
  * @template T
- * @typedef {import('../../types/appium-manifest').ExtRecord<T>} ExtRecord
+ * @typedef {import('appium/types').ExtRecord<T>} ExtRecord
  */
 
 /**
  * Either `driver` or `plugin` rn
- * @typedef {import('../../types').ExtensionType} ExtensionType
+ * @typedef {import('@appium/types').ExtensionType} ExtensionType
  */
-

package/lib/extension/package-changed.js

@@ -1,8 +1,7 @@
-
-import { fs } from '@appium/support';
-import { isPackageChanged } from 'package-changed';
+import {fs} from '@appium/support';
+import {isPackageChanged} from 'package-changed';
 import path from 'path';
-import { PKG_HASHFILE_RELATIVE_PATH } from '../constants';
+import {PKG_HASHFILE_RELATIVE_PATH} from '../constants';
 import log from '../logger';
 
 /**
@@ -14,7 +13,7 @@ import log from '../logger';
  * @param {string} appiumHome
  * @returns {Promise<boolean>} `true` if `package.json` `appiumHome` changed
  */
-export async function packageDidChange (appiumHome) {
+export async function packageDidChange(appiumHome) {
   const hashFilename = path.join(appiumHome, PKG_HASHFILE_RELATIVE_PATH);
 
   // XXX: the types in `package-changed` seem to be wrong.
@@ -35,7 +34,7 @@ export async function packageDidChange (appiumHome) {
     await fs.mkdirp(hashFilenameDir);
   } catch (err) {
     throw new Error(
-      `Appium could not create the directory for hash file: ${hashFilenameDir}. Original error: ${err.message}`,
+      `Appium could not create the directory for hash file: ${hashFilenameDir}. Original error: ${err.message}`
     );
   }
 
@@ -51,10 +50,12 @@ export async function packageDidChange (appiumHome) {
   if (isChanged) {
     try {
       writeHash();
-      log.debug(`Updated hash of ${appiumHome}/package.json from: ${oldHash ?? '(none)'} to: ${hash}`);
+      log.debug(
+        `Updated hash of ${appiumHome}/package.json from: ${oldHash ?? '(none)'} to: ${hash}`
+      );
     } catch (err) {
       throw new Error(
-        `Appium could not write hash file: ${hashFilenameDir}. Original error: ${err.message}`,
+        `Appium could not write hash file: ${hashFilenameDir}. Original error: ${err.message}`
       );
     }
   }