appium 2.0.0-beta.3 → 2.0.0-beta.30

package/lib/extension/driver-config.js

@@ -0,0 +1,249 @@
+
+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
+   * @param {DriverConfigOptions} [opts]
+   */
+   constructor (manifest, {logFn, extData} = {}) {
+     super(DRIVER_TYPE, manifest, logFn);
+
+     this.knownAutomationNames = new Set();
+
+     if (extData) {
+       this.validate(extData);
+     }
+   }
+
+   /**
+    * Creates a new {@link DriverConfig} instance for a {@link Manifest} instance.
+    *
+    * @param {Manifest} manifest
+    * @param {DriverConfigOptions} [opts]
+    * @throws If `manifest` already associated with a `DriverConfig`
+    * @returns {DriverConfig}
+    */
+   static create (manifest, {extData, logFn} = {}) {
+     const instance = new DriverConfig(manifest, {logFn, extData});
+     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
+   * @param {ExtRecord<DriverType>} exts
+   */
+   validate (exts) {
+     this.knownAutomationNames.clear();
+     return super.validate(exts);
+   }
+
+   /**
+   * @param {ExtManifest<DriverType>} extData
+   * @returns {import('./extension-config').Problem[]}
+   */
+   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.
+   * @param {Capabilities} caps
+   * @returns {MatchedDriver}
+   */
+   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 = this.require(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('../../types/appium-manifest').InternalMetadata & import('../../types/external-manifest').CommonMetadata}
+   */
+   _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`);
+   }
+}
+
+/**
+ * @typedef DriverConfigOptions
+ * @property {import('./extension-config').ExtensionLogFn} [logFn] - Optional logging function
+ * @property {ManifestData['drivers']} [extData] - Extension data
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types').ExtMetadata<T>} ExtMetadata
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types').ExtManifest<T>} ExtManifest
+ */
+
+/**
+ * @typedef {import('../../types').ManifestData} ManifestData
+ * @typedef {import('../../types').DriverType} DriverType
+ * @typedef {import('./manifest').Manifest} Manifest
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types').ExtRecord<T>} ExtRecord
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types').ExtName<T>} ExtName
+ */
+
+
+/**
+ * Return value of {@linkcode DriverConfig.findMatchingDriver}
+ * @typedef MatchedDriver
+ * @property {import('../../types/extension').DriverClass} driver
+ * @property {string} version
+ * @property {string} driverName
+ */
+
+/**
+ * @typedef {import('@appium/types').Capabilities} Capabilities
+ */

package/lib/extension/extension-config.js

@@ -0,0 +1,458 @@
+
+import _ from 'lodash';
+import path from 'path';
+import resolveFrom from 'resolve-from';
+import log from '../logger';
+import {
+  ALLOWED_SCHEMA_EXTENSIONS,
+  isAllowedSchemaFileExtension,
+  registerSchema,
+} from '../schema/schema';
+
+const INSTALL_TYPE_NPM = 'npm';
+const INSTALL_TYPE_LOCAL = 'local';
+const INSTALL_TYPE_GITHUB = 'github';
+const INSTALL_TYPE_GIT = 'git';
+
+/** @type {Set<InstallType>} */
+const INSTALL_TYPES = new Set([
+  INSTALL_TYPE_GIT,
+  INSTALL_TYPE_GITHUB,
+  INSTALL_TYPE_LOCAL,
+  INSTALL_TYPE_NPM,
+]);
+
+/**
+ * This class is abstract. It should not be instantiated directly.
+ *
+ * Subclasses should provide the generic parameter to implement.
+ * @template {ExtensionType} ExtType
+ */
+export class ExtensionConfig {
+  /** @type {ExtType} */
+  extensionType;
+
+  /** @type {`${ExtType}s`} */
+  configKey;
+
+  /** @type {ExtRecord<ExtType>} */
+  installedExtensions;
+
+  /** @type {ExtensionLogFn} */
+  log;
+
+  /** @type {Manifest} */
+  manifest;
+
+  /**
+   * @protected
+   * @param {ExtType} extensionType - Type of extension
+   * @param {Manifest} manifest - `Manifest` instance
+   * @param {ExtensionLogFn} [logFn]
+   */
+  constructor (extensionType, manifest, logFn) {
+    const logger = _.isFunction(logFn) ? logFn : log.error.bind(log);
+    this.extensionType = extensionType;
+    this.configKey = `${extensionType}s`;
+    this.installedExtensions = manifest.getExtensionData(extensionType);
+    this.log = logger;
+    this.manifest = manifest;
+  }
+
+  get manifestPath () {
+    return this.manifest.manifestPath;
+  }
+
+  get appiumHome () {
+    return this.manifest.appiumHome;
+  }
+
+  /**
+   * Checks extensions for problems
+   * @param {ExtRecord<ExtType>} exts - Extension data
+   */
+  validate (exts) {
+    const foundProblems =
+      /** @type {Record<ExtName<ExtType>,Problem[]>} */ ({});
+    for (const [
+      extName,
+      extData,
+    ] of /** @type {[ExtName<ExtType>, ExtManifest<ExtType>][]} */ (
+        _.toPairs(exts)
+      )) {
+      foundProblems[extName] = [
+        ...this.getGenericConfigProblems(extData, extName),
+        ...this.getConfigProblems(extData),
+        ...this.getSchemaProblems(extData, extName),
+      ];
+    }
+
+    const problemSummaries = [];
+    for (const [extName, problems] of _.toPairs(foundProblems)) {
+      if (_.isEmpty(problems)) {
+        continue;
+      }
+      // remove this extension from the list since it's not valid
+      delete exts[extName];
+      problemSummaries.push(
+        `${this.extensionType} ${extName} had errors and will not ` +
+          `be available. Errors:`,
+      );
+      for (const problem of problems) {
+        problemSummaries.push(
+          `  - ${problem.err} (Actual value: ` +
+            `${JSON.stringify(problem.val)})`,
+        );
+      }
+    }
+
+    if (!_.isEmpty(problemSummaries)) {
+      this.log(
+        `Appium encountered one or more errors while validating ` +
+          `the ${this.configKey} extension file (${this.manifestPath}):`,
+      );
+      for (const summary of problemSummaries) {
+        this.log(summary);
+      }
+    }
+
+    return exts;
+  }
+
+  /**
+   * @param {ExtManifest<ExtType>} extData
+   * @param {ExtName<ExtType>} extName
+   * @returns {Problem[]}
+   */
+  getSchemaProblems (extData, extName) {
+    const problems = [];
+    const {schema: argSchemaPath} = extData;
+    if (ExtensionConfig.extDataHasSchema(extData)) {
+      if (_.isString(argSchemaPath)) {
+        if (isAllowedSchemaFileExtension(argSchemaPath)) {
+          try {
+            this.readExtensionSchema(extName, extData);
+          } catch (err) {
+            problems.push({
+              err: `Unable to register schema at path ${argSchemaPath}; ${err.message}`,
+              val: argSchemaPath,
+            });
+          }
+        } else {
+          problems.push({
+            err: `Schema file has unsupported extension. Allowed: ${[
+              ...ALLOWED_SCHEMA_EXTENSIONS,
+            ].join(', ')}`,
+            val: argSchemaPath,
+          });
+        }
+      } else if (_.isPlainObject(argSchemaPath)) {
+        try {
+          this.readExtensionSchema(extName, extData);
+        } catch (err) {
+          problems.push({
+            err: `Unable to register embedded schema; ${err.message}`,
+            val: argSchemaPath,
+          });
+        }
+      } else {
+        problems.push({
+          err: 'Incorrectly formatted schema field; must be a path to a schema file or a schema object.',
+          val: argSchemaPath,
+        });
+      }
+    }
+    return problems;
+  }
+
+  /**
+   * @param {ExtManifest<ExtType>} extData
+   * @param {ExtName<ExtType>} extName
+   * @returns {Problem[]}
+   */
+  // eslint-disable-next-line no-unused-vars
+  getGenericConfigProblems (extData, extName) {
+    const {version, pkgName, installSpec, installType, mainClass} =
+      extData;
+    const problems = [];
+
+    if (!_.isString(version)) {
+      problems.push({err: 'Missing or incorrect version', val: version});
+    }
+
+    if (!_.isString(pkgName)) {
+      problems.push({
+        err: 'Missing or incorrect NPM package name',
+        val: pkgName,
+      });
+    }
+
+    if (!_.isString(installSpec)) {
+      problems.push({
+        err: 'Missing or incorrect installation spec',
+        val: installSpec,
+      });
+    }
+
+    if (!INSTALL_TYPES.has(installType)) {
+      problems.push({
+        err: 'Missing or incorrect install type',
+        val: installType,
+      });
+    }
+
+    if (!_.isString(mainClass)) {
+      problems.push({
+        err: 'Missing or incorrect driver class name',
+        val: mainClass,
+      });
+    }
+
+    return problems;
+  }
+
+  /**
+   * @abstract
+   * @param {ExtManifest<ExtType>} extData
+   * @returns {Problem[]}
+   */
+  // eslint-disable-next-line no-unused-vars
+  getConfigProblems (extData) {
+    // shoud override this method if special validation is necessary for this extension type
+    return [];
+  }
+
+  /**
+   * @param {string} extName
+   * @param {ExtManifest<ExtType>} extData
+   * @param {ExtensionConfigMutationOpts} [opts]
+   * @returns {Promise<void>}
+   */
+  async addExtension (extName, extData, {write = true} = {}) {
+    this.manifest.addExtension(this.extensionType, extName, extData);
+    if (write) {
+      await this.manifest.write();
+    }
+  }
+
+  /**
+   * @param {ExtName<ExtType>} extName
+   * @param {ExtManifest<ExtType>|import('../cli/extension-command').ExtensionFields<ExtType>} extData
+   * @param {ExtensionConfigMutationOpts} [opts]
+   * @returns {Promise<void>}
+   */
+  async updateExtension (extName, extData, {write = true} = {}) {
+    this.installedExtensions[extName] = {
+      ...this.installedExtensions[extName],
+      ...extData,
+    };
+    if (write) {
+      await this.manifest.write();
+    }
+  }
+
+  /**
+   * @param {ExtName<ExtType>} extName
+   * @param {ExtensionConfigMutationOpts} [opts]
+   * @returns {Promise<void>}
+   */
+  async removeExtension (extName, {write = true} = {}) {
+    delete this.installedExtensions[extName];
+    if (write) {
+      await this.manifest.write();
+    }
+  }
+
+  /**
+   * @param {ExtName<ExtType>[]} [activeNames]
+   * @returns {void}
+   */
+  // eslint-disable-next-line no-unused-vars
+  print (activeNames) {
+    if (_.isEmpty(this.installedExtensions)) {
+      log.info(
+        `No ${this.configKey} have been installed in ${this.appiumHome}. Use the "appium ${this.extensionType}" ` +
+          'command to install the one(s) you want to use.',
+      );
+      return;
+    }
+
+    log.info(`Available ${this.configKey}:`);
+    for (const [
+      extName,
+      extData,
+    ] of /** @type {[string, ExtManifest<ExtType>][]} */ (
+        _.toPairs(this.installedExtensions)
+      )) {
+      log.info(`  - ${this.extensionDesc(extName, extData)}`);
+    }
+  }
+
+  /**
+   * Returns a string describing the extension. Subclasses must implement.
+   * @param {ExtName<ExtType>} extName - Extension name
+   * @param {ExtManifest<ExtType>} extData - Extension data
+   * @returns {string}
+   * @abstract
+   */
+  // eslint-disable-next-line no-unused-vars
+  extensionDesc (extName, extData) {
+    throw new Error('This must be implemented in a subclass');
+  }
+
+  /**
+   * @param {string} extName
+   * @returns {string}
+   */
+  getInstallPath (extName) {
+    return path.join(this.appiumHome, 'node_modules', this.installedExtensions[extName].pkgName);
+  }
+
+  /**
+   * Loads extension and returns its main class (constructor)
+   * @param {ExtName<ExtType>} extName
+   * @returns {ExtClass<ExtType>}
+   */
+  require (extName) {
+    const {mainClass} = this.installedExtensions[extName];
+    const reqPath = this.getInstallPath(extName);
+    const reqResolved = require.resolve(reqPath);
+    // note: this will only reload the entry point
+    if (process.env.APPIUM_RELOAD_EXTENSIONS && require.cache[reqResolved]) {
+      log.debug(`Removing ${reqResolved} from require cache`);
+      delete require.cache[reqResolved];
+    }
+    log.debug(`Requiring ${this.extensionType} at ${reqPath}`);
+    return require(reqPath)[mainClass];
+  }
+
+  /**
+   * @param {string} extName
+   * @returns {boolean}
+   */
+  isInstalled (extName) {
+    return _.includes(Object.keys(this.installedExtensions), extName);
+  }
+
+  /**
+   * Intended to be called by corresponding instance methods of subclass.
+   * @private
+   * @template {ExtensionType} ExtType
+   * @param {string} appiumHome
+   * @param {ExtType} extType
+   * @param {ExtName<ExtType>} extName - Extension name (unique to its type)
+   * @param {ExtManifestWithSchema<ExtType>} extData - Extension config
+   * @returns {import('ajv').SchemaObject|undefined}
+   */
+  static _readExtensionSchema (appiumHome, extType, extName, extData) {
+    const {pkgName, schema: argSchemaPath} = extData;
+    if (!argSchemaPath) {
+      throw new TypeError(
+        `No \`schema\` property found in config for ${extType} ${pkgName} -- why is this function being called?`,
+      );
+    }
+    let moduleObject;
+    if (_.isString(argSchemaPath)) {
+      const schemaPath = resolveFrom(appiumHome, path.join(pkgName, argSchemaPath));
+      moduleObject = require(schemaPath);
+    } else {
+      moduleObject = argSchemaPath;
+    }
+    // this sucks. default exports should be destroyed
+    const schema = moduleObject.__esModule
+      ? moduleObject.default
+      : moduleObject;
+    registerSchema(extType, extName, schema);
+    return schema;
+  }
+
+  /**
+   * Returns `true` if a specific {@link ExtManifest} object has a `schema` prop.
+   * The {@link ExtManifest} object becomes a {@link ExtManifestWithSchema} object.
+   * @template {ExtensionType} ExtType
+   * @param {ExtManifest<ExtType>} extData
+   * @returns {extData is ExtManifestWithSchema<ExtType>}
+   */
+  static extDataHasSchema (extData) {
+    return _.isString(extData?.schema) || _.isObject(extData?.schema);
+  }
+
+  /**
+   * If an extension provides a schema, this will load the schema and attempt to
+   * register it with the schema registrar.
+   * @param {ExtName<ExtType>} extName - Name of extension
+   * @param {ExtManifestWithSchema<ExtType>} extData - Extension data
+   * @returns {import('ajv').SchemaObject|undefined}
+   */
+  readExtensionSchema (extName, extData) {
+    return ExtensionConfig._readExtensionSchema(
+      this.appiumHome,
+      this.extensionType,
+      extName,
+      extData,
+    );
+  }
+}
+
+export {
+  INSTALL_TYPE_NPM,
+  INSTALL_TYPE_GIT,
+  INSTALL_TYPE_LOCAL,
+  INSTALL_TYPE_GITHUB,
+  INSTALL_TYPES,
+};
+
+/**
+ * Config problem
+ * @typedef Problem
+ * @property {string} err - Error message
+ * @property {any} val - Associated value
+ */
+
+/**
+ * An optional logging function provided to an {@link ExtensionConfig} subclass.
+ * @callback ExtensionLogFn
+ * @param {...any} args
+ * @returns {void}
+ */
+
+/**
+ * @typedef {import('../../types').ExtensionType} ExtensionType
+ * @typedef {import('./manifest').Manifest} Manifest
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types/appium-manifest').ExtManifest<T>} ExtManifest
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types/appium-manifest').ExtManifestWithSchema<T>} ExtManifestWithSchema
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types/appium-manifest').ExtName<T>} ExtName
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types/extension').ExtClass<T>} ExtClass
+ */
+
+/**
+ * @template T
+ * @typedef {import('../../types/appium-manifest').ExtRecord<T>} ExtRecord
+ */
+
+/**
+ * Options for various methods in {@link ExtensionConfig}
+ * @typedef ExtensionConfigMutationOpts
+ * @property {boolean} [write=true] Whether or not to write the manifest to disk after a mutation operation
+ */
+
+/**
+ * A valid install type
+ * @typedef {typeof INSTALL_TYPE_NPM | typeof INSTALL_TYPE_GIT | typeof INSTALL_TYPE_LOCAL | typeof INSTALL_TYPE_GITHUB} InstallType
+ */