appium 2.0.0-beta.2 → 2.0.0-beta.23

package/lib/extension-config.js

@@ -1,15 +1,15 @@
+// @ts-check
+
 import _ from 'lodash';
-import log from './logger';
-import { fs, mkdirp } from 'appium-support';
+import os from 'os';
 import path from 'path';
-import YAML from 'yaml';
-
-const DRIVER_TYPE = 'driver';
-const PLUGIN_TYPE = 'plugin';
-const DEFAULT_APPIUM_HOME = path.resolve(process.env.HOME, '.appium');
+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 CONFIG_FILE_NAME = 'extensions.yaml';
-const CONFIG_SCHEMA_REV = 2;
+const DEFAULT_APPIUM_HOME = path.resolve(os.homedir(), '.appium');
+const APPIUM_HOME = process.env.APPIUM_HOME || DEFAULT_APPIUM_HOME;
 
 const INSTALL_TYPE_NPM = 'npm';
 const INSTALL_TYPE_LOCAL = 'local';
@@ -22,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)
       ];
     }
 
@@ -63,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);
       }
@@ -72,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)) {
@@ -103,62 +164,60 @@ 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],
+      ...extData,
+    };
+    await this.write();
+  }
+
+  /**
+   * @param {string} extName
+   * @returns {Promise<void>}
+   */
   async removeExtension (extName) {
     delete this.installedExtensions[extName];
     await this.write();
@@ -178,31 +237,130 @@ 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];
-    return require(this.getExtensionRequirePath(extName))[mainClass];
+    const reqPath = this.getExtensionRequirePath(extName);
+    const reqResolved = require.resolve(reqPath);
+    if (process.env.APPIUM_RELOAD_EXTENSIONS && require.cache[reqResolved]) {
+      log.debug(`Removing ${reqResolved} from require cache`);
+      delete require.cache[reqResolved];
+    }
+    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

@@ -1,5 +1,5 @@
 import axios from 'axios';
-import { fs } from 'appium-support';
+import { fs } from '@appium/support';
 import logger from './logger';
 import _ from 'lodash';
 
@@ -9,21 +9,32 @@ const hubUri = (config) => {
   return `${protocol}://${config.hubHost}:${config.hubPort}`;
 };
 
-async function registerNode (configFile, addr, port) {
-  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);
+  postRequest(data, addr, port, basePath);
 }
 
 async function registerToGrid (postOptions, configHolder) {
@@ -39,15 +50,7 @@ async function registerToGrid (postOptions, configHolder) {
   }
 }
 
-function postRequest (data, addr, port) {
-  // 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 = {};
@@ -66,7 +69,7 @@ function postRequest (data, addr, port) {
   // because we will always set localhost/127.0.0.1. this won't work if your
   // node and grid aren't in the same place
   if (!configHolder.configuration.url || !configHolder.configuration.host || !configHolder.configuration.port) {
-    configHolder.configuration.url = `http://${addr}:${port}/wd/hub`;
+    configHolder.configuration.url = `http://${addr}:${port}${basePath}`;
     configHolder.configuration.host = addr;
     configHolder.configuration.port = port;
   }

package/lib/logger.js

@@ -1,4 +1,4 @@
-import { logger } from 'appium-support';
+import { logger } from '@appium/support';
 
 
 let log = logger.getLogger('Appium');

package/lib/logsink.js

@@ -1,7 +1,6 @@
 import npmlog from 'npmlog';
 import { createLogger, format, transports } from 'winston';
-import { fs, logger } from 'appium-support';
-import dateformat from 'dateformat';
+import { fs, logger } from '@appium/support';
 import _ from 'lodash';
 
 
@@ -36,16 +35,20 @@ const npmToWinstonLevels = {
 };
 
 let log = null;
-let timeZone = null;
+let useLocalTimeZone = false;
 
 // add the timestamp in the correct format to the log info object
 const timestampFormat = format.timestamp({
   format () {
     let date = new Date();
-    if (!timeZone) {
-      date = new Date(date.valueOf() + date.getTimezoneOffset() * 60000);
+    if (useLocalTimeZone) {
+      date = new Date(date.valueOf() - date.getTimezoneOffset() * 60000);
     }
-    return dateformat(date, 'yyyy-mm-dd HH:MM:ss:l');
+    // '2012-11-04T14:51:06.157Z' -> '2012-11-04 14:51:06:157'
+    return date.toISOString()
+      .replace(/[TZ]/g, ' ')
+      .replace(/\./g, ':')
+      .trim();
   },
 });
 
@@ -182,7 +185,7 @@ async function createTransports (args) {
 
 async function init (args) {
   // set de facto param passed to timestamp function
-  timeZone = args.localTimezone;
+  useLocalTimeZone = args.localTimezone;
 
   // clean up in case we have initiated before since npmlog is a global object
   clear();