appium 2.0.0-beta.18 → 2.0.0-beta.21

package/lib/extension-config.js

@@ -1,16 +1,15 @@
+// @ts-check
+
 import _ from 'lodash';
-import log from './logger';
-import { fs, mkdirp } from '@appium/support';
-import path from 'path';
 import os from 'os';
-import YAML from 'yaml';
+import path from 'path';
+import resolveFrom from 'resolve-from';
+import { getExtConfigIOInstance } from './ext-config-io';
+import log from './logger';
+import { ALLOWED_SCHEMA_EXTENSIONS, isAllowedSchemaFileExtension, registerSchema } from './schema/schema';
 
-const DRIVER_TYPE = 'driver';
-const PLUGIN_TYPE = 'plugin';
 const DEFAULT_APPIUM_HOME = path.resolve(os.homedir(), '.appium');
-
-const CONFIG_FILE_NAME = 'extensions.yaml';
-const CONFIG_SCHEMA_REV = 2;
+const APPIUM_HOME = process.env.APPIUM_HOME || DEFAULT_APPIUM_HOME;
 
 const INSTALL_TYPE_NPM = 'npm';
 const INSTALL_TYPE_LOCAL = 'local';
@@ -23,27 +22,44 @@ const INSTALL_TYPES = [
   INSTALL_TYPE_NPM
 ];
 
-
 export default class ExtensionConfig {
-  constructor (appiumHome, extensionType, logFn = null) {
-    if (logFn === null) {
-      logFn = log.error.bind(log);
-    }
+  /**
+   *
+   * @param {string} appiumHome - `APPIUM_HOME`
+   * @param {ExtensionType} extensionType - Type of extension
+   * @param {(...args: any[]) => void} [logFn]
+   */
+  constructor (appiumHome, extensionType, logFn) {
+    const logger = _.isFunction(logFn) ? logFn : log.error.bind(log);
+    /** @type {string} */
     this.appiumHome = appiumHome;
-    this.configFile = path.resolve(this.appiumHome, CONFIG_FILE_NAME);
+    /** @type {Record<string,object>} */
     this.installedExtensions = {};
+    /** @type {import('./ext-config-io').ExtensionConfigIO} */
+    this.io = getExtConfigIOInstance(appiumHome);
+    /** @type {ExtensionType} */
     this.extensionType = extensionType;
-    this.configKey = `${extensionType}s`;
-    this.yamlData = {[`${DRIVER_TYPE}s`]: {}, [`${PLUGIN_TYPE}s`]: {}};
-    this.log = logFn;
+    /** @type {'drivers'|'plugins'} */
+    this.configKey = `${extensionType}s`; // todo use template type
+    /**
+     * @type {(...args: any[])=>void}
+     */
+    this.log = logger;
   }
 
+  /**
+   * Checks extensions for problems
+   * @template ExtData
+   * @param {ExtData[]} exts - Array of extData objects
+   * @returns {ExtData[]}
+   */
   validate (exts) {
     const foundProblems = {};
     for (const [extName, extData] of _.toPairs(exts)) {
       foundProblems[extName] = [
-        ...this.getGenericConfigProblems(extData),
-        ...this.getConfigProblems(extData)
+        ...this.getGenericConfigProblems(extData, extName),
+        ...this.getConfigProblems(extData, extName),
+        ...this.getSchemaProblems(extData, extName)
       ];
     }
 
@@ -64,7 +80,7 @@ export default class ExtensionConfig {
 
     if (!_.isEmpty(problemSummaries)) {
       this.log(`Appium encountered one or more errors while validating ` +
-               `the ${this.configKey} extension file (${this.configFile}):`);
+               `the ${this.configKey} extension file (${this.io.filepath}):`);
       for (const summary of problemSummaries) {
         this.log(summary);
       }
@@ -73,8 +89,52 @@ export default class ExtensionConfig {
     return exts;
   }
 
-  getGenericConfigProblems (ext) {
-    const {version, pkgName, installSpec, installType, installPath, mainClass} = ext;
+  /**
+   * @param {object} extData
+   * @param {string} extName
+   * @returns {Problem[]}
+   */
+  getSchemaProblems (extData, extName) {
+    const problems = [];
+    const {schema: argSchemaPath} = extData;
+    if (argSchemaPath) {
+      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 {object} extData
+   * @param {string} extName
+   * @returns {Problem[]}
+   */
+  // eslint-disable-next-line no-unused-vars
+  getGenericConfigProblems (extData, extName) {
+    const {version, pkgName, installSpec, installType, installPath, mainClass} = extData;
     const problems = [];
 
     if (!_.isString(version)) {
@@ -104,62 +164,48 @@ export default class ExtensionConfig {
     return problems;
   }
 
-  getConfigProblems (/*ext*/) {
+  /**
+   * @param {object} extData
+   * @param {string} extName
+   * @returns {Problem[]}
+   */
+  // eslint-disable-next-line no-unused-vars
+  getConfigProblems (extData, extName) {
     // shoud override this method if special validation is necessary for this extension type
     return [];
   }
 
-  applySchemaMigrations () {
-    if (this.yamlData.schemaRev < 2 && _.isUndefined(this.yamlData[PLUGIN_TYPE])) {
-      // at schema revision 2, we started including plugins as well as drivers in the file,
-      // so make sure we at least have an empty section for it
-      this.yamlData[PLUGIN_TYPE] = {};
-    }
-  }
-
+  /**
+   * @returns {Promise<typeof this.installedExtensions>}
+   */
   async read () {
-    await mkdirp(this.appiumHome); // ensure appium home exists
-    try {
-      this.yamlData = YAML.parse(await fs.readFile(this.configFile, 'utf8'));
-      this.applySchemaMigrations();
-
-      // set the list of drivers the user has installed
-      this.installedExtensions = this.validate(this.yamlData[this.configKey]);
-    } catch (err) {
-      if (await fs.exists(this.configFile)) {
-        // if the file exists and we couldn't parse it, that's a problem
-        throw new Error(`Appium had trouble loading the extension installation ` +
-                        `cache file (${this.configFile}). Ensure it exists and is ` +
-                        `readable. Specific error: ${err.message}`);
-      }
-
-      // if the config file doesn't exist, try to write an empty one, to make
-      // sure we actually have write privileges, and complain if we don't
-      try {
-        await this.write();
-      } catch {
-        throw new Error(`Appium could not read or write from the Appium Home directory ` +
-                        `(${this.appiumHome}). Please ensure it is writable.`);
-      }
-    }
+    const extensions = await this.io.read(this.extensionType);
+    this.installedExtensions = this.validate(extensions);
     return this.installedExtensions;
   }
 
-
+  /**
+   * @returns {Promise<boolean>}
+   */
   async write () {
-    const newYamlData = {
-      ...this.yamlData,
-      schemaRev: CONFIG_SCHEMA_REV,
-      [this.configKey]: this.installedExtensions
-    };
-    await fs.writeFile(this.configFile, YAML.stringify(newYamlData), 'utf8');
+    return await this.io.write();
   }
 
+  /**
+   * @param {string} extName
+   * @param {object} extData
+   * @returns {Promise<void>}
+   */
   async addExtension (extName, extData) {
     this.installedExtensions[extName] = extData;
     await this.write();
   }
 
+  /**
+   * @param {string} extName
+   * @param {object} extData
+   * @returns {Promise<void>}
+   */
   async updateExtension (extName, extData) {
     this.installedExtensions[extName] = {
       ...this.installedExtensions[extName],
@@ -168,6 +214,10 @@ export default class ExtensionConfig {
     await this.write();
   }
 
+  /**
+   * @param {string} extName
+   * @returns {Promise<void>}
+   */
   async removeExtension (extName) {
     delete this.installedExtensions[extName];
     await this.write();
@@ -187,20 +237,41 @@ export default class ExtensionConfig {
     }
   }
 
-  extensionDesc () {
-    throw new Error('This must be implemented in a final class');
+  /**
+   * Returns a string describing the extension. Subclasses must implement.
+   * @param {string} extName - Extension name
+   * @param {object} 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}
+   */
   getExtensionRequirePath (extName) {
     const {pkgName, installPath} = this.installedExtensions[extName];
     return path.resolve(this.appiumHome, installPath, 'node_modules', pkgName);
   }
 
+  /**
+   * @param {string} extName
+   * @returns {string}
+   */
   getInstallPath (extName) {
     const {installPath} = this.installedExtensions[extName];
     return path.resolve(this.appiumHome, installPath);
   }
 
+  /**
+   * Loads extension and returns its main class
+   * @param {string} extName
+   * @returns {(...args: any[]) => object }
+   */
   require (extName) {
     const {mainClass} = this.installedExtensions[extName];
     const reqPath = this.getExtensionRequirePath(extName);
@@ -212,12 +283,84 @@ export default class ExtensionConfig {
     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
+   * @param {string} appiumHome
+   * @param {ExtensionType} extType
+   * @param {string} extName - Extension name (unique to its type)
+   * @param {ExtData} extData - Extension config
+   * @returns {import('ajv').SchemaObject|undefined}
+   */
+  static _readExtensionSchema (appiumHome, extType, extName, extData) {
+    const {installPath, 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(
+        path.resolve(appiumHome, installPath),
+        // this path sep is fine because `resolveFrom` uses Node's module resolution
+        path.normalize(`${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;
+  }
+
+  /**
+   * If an extension provides a schema, this will load the schema and attempt to
+   * register it with the schema registrar.
+   * @param {string} extName - Name of extension
+   * @param {ExtData} extData - Extension data
+   * @returns {import('ajv').SchemaObject|undefined}
+   */
+  readExtensionSchema (extName, extData) {
+    return ExtensionConfig._readExtensionSchema(this.appiumHome, this.extensionType, extName, extData);
+  }
 }
 
+export { DRIVER_TYPE, PLUGIN_TYPE } from './ext-config-io';
 export {
   INSTALL_TYPE_NPM, INSTALL_TYPE_GIT, INSTALL_TYPE_LOCAL, INSTALL_TYPE_GITHUB,
-  INSTALL_TYPES, DEFAULT_APPIUM_HOME, DRIVER_TYPE, PLUGIN_TYPE,
+  INSTALL_TYPES, DEFAULT_APPIUM_HOME, APPIUM_HOME
 };
+
+/**
+ * Config problem
+ * @typedef {Object} Problem
+ * @property {string} err - Error message
+ * @property {any} val - Associated value
+ */
+
+/**
+ * Alias
+ * @typedef {import('./ext-config-io').ExtensionType} ExtensionType
+ */
+
+/**
+ * Extension data (pulled from config YAML)
+ * @typedef {Object} ExtData
+ * @property {string|import('ajv').SchemaObject} [schema] - Optional schema path if the ext defined it
+ * @property {string} pkgName - Package name
+ * @property {string} installPath - Actually looks more like a module identifier? Resolved from `APPIUM_HOME`
+ */
+

package/lib/grid-register.js

@@ -9,20 +9,31 @@ const hubUri = (config) => {
   return `${protocol}://${config.hubHost}:${config.hubPort}`;
 };
 
-async function registerNode (configFile, addr, port, basePath) {
-  let data;
-  try {
-    data = await fs.readFile(configFile, 'utf-8');
-  } catch (err) {
-    logger.error(`Unable to load node configuration file to register with grid: ${err.message}`);
-    return;
+/**
+ * Registers a new node with a selenium grid
+ * @param {string|object} data - Path or object representing selenium grid node config file
+ * @param {string} addr - Bind to this address
+ * @param {number} port - Bind to this port
+ * @param {string} basePath - Base path for the grid
+ */
+async function registerNode (data, addr, port, basePath) {
+  let configFilePath;
+  if (_.isString(data)) {
+    configFilePath = data;
+    try {
+      data = await fs.readFile(data, 'utf-8');
+    } catch (err) {
+      logger.error(`Unable to load node configuration file ${configFilePath} to register with grid: ${err.message}`);
+      return;
+    }
+    try {
+      data = JSON.parse(data);
+    } catch (err) {
+      logger.errorAndThrow(`Syntax error in node configuration file ${configFilePath}: ${err.message}`);
+      return;
+    }
   }
 
-  // Check presence of data before posting  it to the selenium grid
-  if (!data) {
-    logger.error('No data found in the node configuration file to send to the grid');
-    return;
-  }
   postRequest(data, addr, port, basePath);
 }
 
@@ -39,15 +50,7 @@ async function registerToGrid (postOptions, configHolder) {
   }
 }
 
-function postRequest (data, addr, port, basePath) {
-  // parse json to get hub host and port
-  let configHolder;
-  try {
-    configHolder = JSON.parse(data);
-  } catch (err) {
-    logger.errorAndThrow(`Syntax error in node configuration file: ${err.message}`);
-  }
-
+function postRequest (configHolder, addr, port, basePath) {
   // Move Selenium 3 configuration properties to configuration object
   if (!_.has(configHolder, 'configuration')) {
     let configuration = {};