appium 3.2.2 → 3.3.1

package/lib/extension/driver-config.js

@@ -1,245 +0,0 @@
-import _ from 'lodash';
-import {DRIVER_TYPE} from '../constants';
-import log from '../logger';
-import {ExtensionConfig} from './extension-config';
-
-/**
- * @extends {ExtensionConfig<DriverType>}
- */
-export class DriverConfig extends ExtensionConfig {
-  /**
-   * A set of unique automation names used by drivers.
-   * @type {Set<string>}
-   */
-  knownAutomationNames;
-
-  /**
-   * A mapping of {@link Manifest} instances to {@link DriverConfig} instances.
-   *
-   * `Manifest` and `ExtensionConfig` have a one-to-many relationship; each `Manifest` should be associated with a `DriverConfig` and a `PluginConfig`; no more, no less.
-   *
-   * This variable tracks the `Manifest`-to-`DriverConfig` portion.
-   *
-   * @type {WeakMap<Manifest,DriverConfig>}
-   * @private
-   */
-  static _instances = new WeakMap();
-
-  /**
-   * Call {@link DriverConfig.create} instead.
-   * @private
-   * @param {import('./manifest').Manifest} manifest - Manifest instance
-   */
-  constructor(manifest) {
-    super(DRIVER_TYPE, manifest);
-
-    this.knownAutomationNames = new Set();
-  }
-
-  /**
-   * Creates a new {@link DriverConfig} instance for a {@link Manifest} instance.
-   *
-   * @param {Manifest} manifest
-   * @throws If `manifest` already associated with a `DriverConfig`
-   * @returns {DriverConfig}
-   */
-  static create(manifest) {
-    const instance = new DriverConfig(manifest);
-    if (DriverConfig.getInstance(manifest)) {
-      throw new Error(
-        `Manifest with APPIUM_HOME ${manifest.appiumHome} already has a DriverConfig; use DriverConfig.getInstance() to retrieve it.`
-      );
-    }
-    DriverConfig._instances.set(manifest, instance);
-    return instance;
-  }
-
-  /**
-   * Returns a DriverConfig associated with a Manifest
-   * @param {Manifest} manifest
-   * @returns {DriverConfig|undefined}
-   */
-  static getInstance(manifest) {
-    return DriverConfig._instances.get(manifest);
-  }
-
-  /**
-   * Checks extensions for problems
-   */
-  async validate() {
-    this.knownAutomationNames.clear();
-    return await super._validate(this.manifest.getExtensionData(DRIVER_TYPE));
-  }
-
-  /**
-   * @param {ExtManifest<DriverType>} extData
-   * @returns {import('./extension-config').ExtManifestProblem[]}
-   */
-  getConfigProblems(extData) {
-    const problems = [];
-    const {platformNames, automationName} = extData;
-
-    if (!_.isArray(platformNames)) {
-      problems.push({
-        err: 'Missing or incorrect supported platformNames list.',
-        val: platformNames,
-      });
-    } else if (_.isEmpty(platformNames)) {
-      problems.push({
-        err: 'Empty platformNames list.',
-        val: platformNames,
-      });
-    } else {
-      for (const pName of platformNames) {
-        if (!_.isString(pName)) {
-          problems.push({
-            err: 'Incorrectly formatted platformName.',
-            val: pName,
-          });
-        }
-      }
-    }
-
-    if (!_.isString(automationName)) {
-      problems.push({
-        err: 'Missing or incorrect automationName',
-        val: automationName,
-      });
-    }
-
-    if (this.knownAutomationNames.has(automationName)) {
-      problems.push({
-        err: 'Multiple drivers claim support for the same automationName',
-        val: automationName,
-      });
-    }
-
-    // should we retain the name at the end of this function, once we've checked there are no problems?
-    this.knownAutomationNames.add(automationName);
-
-    return problems;
-  }
-
-  /**
-   * @param {ExtName<DriverType>} driverName
-   * @param {ExtManifest<DriverType>} extData
-   * @returns {string}
-   */
-  extensionDesc(driverName, {version, automationName}) {
-    return `${driverName}@${version} (automationName '${automationName}')`;
-  }
-
-  /**
-   * Given capabilities, find a matching driver within the config. Load its class and return it along with version and driver name.
-   * @template {import('@appium/types').StringRecord} C
-   * @param {C} caps
-   * @returns {Promise<MatchedDriver>}
-   */
-  async findMatchingDriver({automationName, platformName}) {
-    if (!_.isString(platformName)) {
-      throw new Error('You must include a platformName capability');
-    }
-
-    if (!_.isString(automationName)) {
-      throw new Error('You must include an automationName capability');
-    }
-
-    log.info(
-      `Attempting to find matching driver for automationName ` +
-        `'${automationName}' and platformName '${platformName}'`
-    );
-
-    try {
-      const {driverName, mainClass, version} = this._getDriverBySupport(
-        automationName,
-        platformName
-      );
-      log.info(`The '${driverName}' driver was installed and matched caps.`);
-      log.info(`Will require it at ${this.getInstallPath(driverName)}`);
-      const driver = await this.requireAsync(driverName);
-      if (!driver) {
-        throw new Error(
-          `Driver '${driverName}' did not export a class with name '${mainClass}'. Contact the author of the driver!`
-        );
-      }
-      return {driver, version, driverName};
-    } catch (err) {
-      const msg =
-        `Could not find a driver for automationName ` +
-        `'${automationName}' and platformName '${platformName}'. ` +
-        `Have you installed a driver that supports those ` +
-        `capabilities? Run 'appium driver list --installed' to see. ` +
-        `(Lower-level error: ${err.message})`;
-      throw new Error(msg);
-    }
-  }
-
-  /**
-   * Given an automation name and platform name, find a suitable driver and return its extension data.
-   * @param {string} matchAutomationName
-   * @param {string} matchPlatformName
-   * @returns {ExtMetadata<DriverType> & import('appium/types').InternalMetadata & import('appium/types').CommonExtMetadata}
-   */
-  _getDriverBySupport(matchAutomationName, matchPlatformName) {
-    const drivers = this.installedExtensions;
-    for (const [driverName, driverData] of _.toPairs(drivers)) {
-      const {automationName, platformNames} = driverData;
-      const aNameMatches = automationName.toLowerCase() === matchAutomationName.toLowerCase();
-      const pNameMatches = _.includes(
-        platformNames.map(_.toLower),
-        matchPlatformName.toLowerCase()
-      );
-
-      if (aNameMatches && pNameMatches) {
-        return {driverName, ...driverData};
-      }
-
-      if (aNameMatches) {
-        throw new Error(
-          `Driver '${driverName}' supports automationName ` +
-            `'${automationName}', but Appium could not find ` +
-            `support for platformName '${matchPlatformName}'. Supported ` +
-            `platformNames are: ` +
-            JSON.stringify(platformNames)
-        );
-      }
-    }
-
-    throw new Error(`Could not find installed driver to support given caps`);
-  }
-}
-
-/**
- * @template {ExtensionType} T
- * @typedef {import('appium/types').ExtMetadata<T>} ExtMetadata
- */
-
-/**
- * @template {ExtensionType} T
- * @typedef {import('appium/types').ExtManifest<T>} ExtManifest
- */
-
-/**
- * @typedef {import('@appium/types').ExtensionType} ExtensionType
- * @typedef {import('appium/types').ManifestData} ManifestData
- * @typedef {import('@appium/types').DriverType} DriverType
- * @typedef {import('./manifest').Manifest} Manifest
- */
-
-/**
- * @template {ExtensionType} T
- * @typedef {import('appium/types').ExtRecord<T>} ExtRecord
- */
-
-/**
- * @template {ExtensionType} T
- * @typedef {import('appium/types').ExtName<T>} ExtName
- */
-
-/**
- * Return value of {@linkcode DriverConfig.findMatchingDriver}
- * @typedef MatchedDriver
- * @property {import('@appium/types').DriverClass} driver
- * @property {string} version
- * @property {string} driverName
- */

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
- */