appium 2.0.0-beta.8 → 2.0.0-rc.1

package/lib/extension/index.js

@@ -0,0 +1,116 @@
+import _ from 'lodash';
+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 B from 'bluebird';
+
+/**
+ * Loads extensions and creates `ExtensionConfig` instances.
+ *
+ * - Reads the manifest file, creating if necessary
+ * - Using the parsed extension data, creates/gets the `ExtensionConfig` subclass instances
+ * - Returns these instances
+ *
+ * If `appiumHome` is needed, use `resolveAppiumHome` from the `env` module in `@appium/support`.
+ * @param {string} appiumHome
+ * @returns {Promise<ExtensionConfigs>}
+ */
+export async function loadExtensions(appiumHome) {
+  const manifest = Manifest.getInstance(appiumHome);
+  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};
+}
+
+/**
+ * Find any plugin name which has been installed, and which has been requested for activation by
+ * using the --use-plugins flag, and turn each one into its class, so we can send them as objects
+ * to the server init. We also want to send/assign them to the umbrella driver so it can use them
+ * to wrap command execution
+ *
+ * @param {import('./plugin-config').PluginConfig} pluginConfig - a plugin extension config
+ * @param {string[]} usePlugins
+ * @returns {PluginNameMap} Mapping of PluginClass to name
+ */
+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);
+          }
+        })
+    )
+  );
+}
+
+/**
+ * Find any driver name which has been installed, and turn each one into its class, so we can send
+ * them as objects to the server init in case they need to add methods/routes or update the server.
+ * If the --drivers flag was given, this method only loads the given drivers.
+ *
+ * @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 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 {import('./driver-config').DriverConfig} driverConfig
+ * @property {import('./plugin-config').PluginConfig} pluginConfig
+ */

package/lib/extension/manifest-migrations.js

@@ -0,0 +1,136 @@
+import {CURRENT_SCHEMA_REV, DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
+import log from '../logger';
+
+/**
+ * This contains logic to migrate old versions of `extensions.yaml` to new versions.
+ *
+ * @module
+ */
+
+/**
+ * Constant for v3 of the schema rev.
+ */
+const SCHEMA_REV_3 = 3;
+
+/**
+ * Constant for v4 of the schema rev.
+ */
+const SCHEMA_REV_4 = 4;
+
+/**
+ * Collection of functions to migrate from one version to another.
+ *
+ * These functions _should not actually perform the migration_; rather, they
+ * should return `true` if the migration should be performed.  The migration
+ * itself will happen within {@linkcode Manifest.syncWithInstalledExtensions}; the extensions
+ * will be checked and the manifest file updated per the state of the filesystem.
+ *
+ * @type { {[P in keyof ManifestDataVersions]?: Migration} }
+ */
+const Migrations = {
+  /**
+   * If `installPath` is missing from the `ExtManifest` for any extension, return `true`.
+   *
+   * We cannot easily determine the path of any given extension here, but returning `true`
+   * will cause the `Manifest` to sync with the filesystem, which will populate the missing field.
+   *
+   * @type {Migration}
+   */
+  [SCHEMA_REV_3]: (manifest) => {
+    /** @type {Array<ExtManifest<PluginType>|ExtManifest<DriverType>>} */
+    const allExtData = [
+      ...Object.values(manifest.getExtensionData(DRIVER_TYPE)),
+      ...Object.values(manifest.getExtensionData(PLUGIN_TYPE)),
+    ];
+    return allExtData.some((metadata) => !('installPath' in metadata));
+  },
+  /**
+   * Updates installed extensions to use `InstallType` of `dev` if appropriate.
+   *
+   * Previously, these types of extensions (automatically discovered) would use the default `InstallType` of `npm`, so we need
+   * to refresh any with this install type.
+   *
+   * This should only happen once; we do not want to re-check everything with `npm` install type
+   * every time.
+   * @type {Migration}
+   */
+  [SCHEMA_REV_4]: (manifest) => {
+    if (manifest.schemaRev < SCHEMA_REV_4) {
+      const allExtData = [
+        ...Object.values(manifest.getExtensionData(DRIVER_TYPE)),
+        ...Object.values(manifest.getExtensionData(PLUGIN_TYPE)),
+      ];
+      return allExtData.some((metadata) => metadata.installType === 'npm');
+    }
+    return false;
+  },
+};
+
+/**
+ * Set `schemaRev` to a specific version.
+ *
+ * This _does_ mutate `data` in-place, unlike functions in
+ * {@linkcode Migrations}.
+ *
+ * Again, returning `true` means that the manifest should be--at
+ * minimum--persisted to disk, since we changed it.
+ * @param {Readonly<Manifest>} manifest
+ * @param {keyof ManifestDataVersions} version
+ * @returns {boolean} Whether the data was modified
+ */
+function setSchemaRev(manifest, version) {
+  if ((manifest.schemaRev ?? 0) < version) {
+    manifest.setSchemaRev(version);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Applies a series of migration functions to a manifest to update its manifest schema version.
+ *
+ * `data` is modified in-place.
+ *
+ * @param {Readonly<Manifest>} manifest
+ * @returns {Promise<boolean>} If `true` existing packages should be synced from disk and the manifest should be persisted.
+ */
+export async function migrate(manifest) {
+  let didChange = false;
+  for await (const migration of Object.values(Migrations)) {
+    didChange = (await migration(manifest)) || didChange;
+  }
+  didChange = setSchemaRev(manifest, CURRENT_SCHEMA_REV) || didChange;
+  if (didChange) {
+    // this is not _technically_ true, since we don't actually write the file here.
+    log.debug(`Upgraded extension manifest to schema v${manifest.schemaRev}`);
+  }
+
+  return didChange;
+}
+
+/**
+ * A migration function. It will return `true` if a change _should be made_.
+ *
+ * A migration function should not modify `schemaRev`, as this is done automatically.
+ *
+ * Note that at the time of writing, we're not able to determine the version of the _current_ manifest file if there is no `schemaRev` prop present (and we may not want to trust it anyway).
+ * @callback Migration
+ * @param {Readonly<Manifest>} manifest - The `Manifest` instance
+ * @returns {boolean|Promise<boolean>} If `true`, then something changed
+ */
+
+/**
+ * @typedef {import('appium/types').ManifestData} ManifestData
+ * @typedef {import('@appium/types').DriverType} DriverType
+ * @typedef {import('@appium/types').PluginType} PluginType
+ * @typedef {import('appium/types').AnyManifestDataVersion} AnyManifestDataVersion
+ * @typedef {import('appium/types').ManifestDataVersions} ManifestDataVersions
+ * @typedef {import('@appium/types').ExtensionType} ExtensionType
+ * @typedef {import('appium/types').ManifestV2.ManifestData} ManifestDataV2
+ * @typedef {import('./manifest').Manifest} Manifest
+ */
+
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtManifest<ExtType>} ExtManifest
+ */