appium 3.3.0 → 3.3.1

package/lib/extension/index.js

@@ -1,169 +0,0 @@
-import _ from 'lodash';
-import {USE_ALL_PLUGINS} from '../constants';
-import log from '../logger';
-import {DriverConfig} from './driver-config';
-import {Manifest} from './manifest';
-import {timing} from '@appium/support';
-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};
-}
-
-/**
- * @template {'driver'|'plugin'} TExtType
- * @param {TExtType} extType
- * @param {import('./extension-config').ExtensionConfig} config
- * @param {string[]} extNames
- * @param {number} asyncImportChunkSize
- * @returns {Promise<[TExtType extends 'driver' ? DriverClass : PluginClass, string][]>}
- */
-async function importExtensions(extType, config, extNames, asyncImportChunkSize) {
-  /** @type {B[]} */
-  const allPromises = [];
-  /** @type {B[]} */
-  const activePromisesChunk = [];
-  for (const extName of extNames) {
-    _.remove(activePromisesChunk, (p) => p.isFulfilled());
-    if (activePromisesChunk.length >= asyncImportChunkSize) {
-      await B.any(activePromisesChunk);
-    }
-    const promise = B.resolve((async () => {
-      log.info(`Attempting to load ${extType} ${extName}...`);
-      const timer = new timing.Timer().start();
-      try {
-        const extClass = await config.requireAsync(extName);
-        log.debug(`${extClass.name} has been successfully loaded in ${timer.getDuration().asSeconds.toFixed(3)}s`);
-        return extClass;
-      } catch (err) {
-        log.error(
-          `Could not load ${extType} '${extName}', so it will not be available. Error ` +
-            `in loading the ${extType} was: ${err.message}`
-        );
-        log.debug(err.stack);
-      }
-    })());
-    activePromisesChunk.push(promise);
-    allPromises.push(promise);
-  }
-  return /** @type {[TExtType extends 'driver' ? DriverClass : PluginClass, string][]} */ (
-    _.zip(await B.all(allPromises), extNames).filter(([extClass,]) => Boolean(extClass))
-  );
-}
-
-/**
- * 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 {number} maxParallelImports the maximum amount of plugins to import in parallel
- * @param {string[]} usePlugins
- * @returns {Promise<PluginNameMap>} Mapping of PluginClass to name
- */
-export async function getActivePlugins(pluginConfig, maxParallelImports, usePlugins = []) {
-  if (_.isEmpty(usePlugins)) {
-    return new Map();
-  }
-
-  /** @type {string[]} */
-  let filteredPluginNames = [];
-  if (usePlugins.length === 1 && usePlugins[0] === USE_ALL_PLUGINS) {
-    filteredPluginNames = _.keys(pluginConfig.installedExtensions);
-  } else {
-    // It is important to load plugins in the same order that was used while enumerating them
-    for (const pluginName of usePlugins) {
-      if (pluginName in pluginConfig.installedExtensions) {
-        filteredPluginNames.push(pluginName);
-      } else if (pluginName === USE_ALL_PLUGINS) {
-        throw new Error(
-          `The reserved plugin name '${pluginName}' cannot be combined with other names.`
-        );
-      } else {
-        const suffix = _.isEmpty(pluginConfig.installedExtensions)
-          ? `You don't have any plugins installed yet.`
-          : `Only the following ${_.size(pluginConfig.installedExtensions) === 1 ? `plugin is` : `plugins are`} ` +
-            `available: ${_.keys(pluginConfig.installedExtensions)}`;
-        throw new Error(
-          `Could not load the plugin '${pluginName}' because it is not installed. ${suffix}`
-        );
-      }
-    }
-  }
-  return new Map(await importExtensions('plugin', pluginConfig, filteredPluginNames, maxParallelImports));
-}
-
-/**
- * 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 {number} maxParallelImports the maximum amount of plugins to import in parallel
- * @param {string[]} [useDrivers] - optional list of drivers to load
- * @returns {Promise<DriverNameMap>}
- */
-export async function getActiveDrivers(driverConfig, maxParallelImports, useDrivers = []) {
-  /** @type {string[]} */
-  let filteredDriverNames = [];
-  if (_.isEmpty(useDrivers)) {
-    // load all drivers if none are requested
-    filteredDriverNames = _.keys(driverConfig.installedExtensions);
-  } else {
-    // Load drivers in the same order that was used while enumerating them
-    for (const driverName of useDrivers) {
-      if (driverName in driverConfig.installedExtensions) {
-        filteredDriverNames.push(driverName);
-      } else {
-        const suffix = _.isEmpty(driverConfig.installedExtensions)
-          ? `You don't have any drivers installed yet.`
-          : `Only the following ${_.size(driverConfig.installedExtensions) === 1 ? `driver is` : `drivers are`} ` +
-            `available: ${_.keys(driverConfig.installedExtensions)}`;
-        throw new Error(
-          `Could not load the driver '${driverName}' because it is not installed. ${suffix}`
-        );
-      }
-    }
-  }
-  return new Map(await importExtensions('driver', driverConfig, filteredDriverNames, maxParallelImports));
-}
-
-/**
- * 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

@@ -1,136 +0,0 @@
-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
- */