appium 2.0.0-beta.24 → 2.0.0-beta.27

package/lib/extension/extension-config.js

@@ -0,0 +1,459 @@
+// @ts-check
+
+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>, ExtData<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 {ExtData<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 {ExtData<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 {ExtData<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 {ExtData<ExtType>} extData
+   * @param {ExtensionConfigMutationOpts} [opts]
+   * @returns {Promise<void>}
+   */
+  async addExtension (extName, extData, {write = true} = {}) {
+    await this.manifest.addExtension(this.extensionType, extName, extData);
+    if (write) {
+      await this.manifest.write();
+    }
+  }
+
+  /**
+   * @param {ExtName<ExtType>} extName
+   * @param {ExtData<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, ExtData<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 {ExtData<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 {ExtDataWithSchema<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 ExtData} object has a `schema` prop.
+   * The {@link ExtData} object becomes a {@link ExtDataWithSchema} object.
+   * @template {ExtensionType} ExtType
+   * @param {ExtData<ExtType>} extData
+   * @returns {extData is ExtDataWithSchema<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 {ExtDataWithSchema<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('./manifest').ExtensionType} ExtensionType
+ * @typedef {import('./manifest').Manifest} Manifest
+ */
+
+/**
+ * @template T
+ * @typedef {import('./manifest').ExtData<T>} ExtData
+ */
+
+/**
+ * @template T
+ * @typedef {import('./manifest').ExtDataWithSchema<T>} ExtDataWithSchema
+ */
+
+/**
+ * @template T
+ * @typedef {import('./manifest').ExtName<T>} ExtName
+ */
+
+/**
+ * @template T
+ * @typedef {import('./manifest').ExtClass<T>} ExtClass
+ */
+
+/**
+ * @template T
+ * @typedef {import('./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
+ */

package/lib/extension/index.js

@@ -0,0 +1,103 @@
+// @ts-check
+
+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';
+
+/**
+ * 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);
+  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});
+  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 {import('./manifest').PluginClass[]}
+ */
+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);
+        }
+      }),
+  );
+}
+
+/**
+ * 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
+ */
+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);
+        }
+      }),
+  );
+}
+
+/**
+ * @typedef ExtensionConfigs
+ * @property {DriverConfig} driverConfig
+ * @property {PluginConfig} pluginConfig
+ */