appium 2.0.0-beta.46 → 2.0.0-beta.48

package/lib/extension/manifest.js

@@ -8,15 +8,11 @@ import {env, fs} from '@appium/support';
 import _ from 'lodash';
 import path from 'path';
 import YAML from 'yaml';
-import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
+import {CURRENT_SCHEMA_REV, DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
 import log from '../logger';
 import {INSTALL_TYPE_NPM} from './extension-config';
 import {packageDidChange} from './package-changed';
-
-/**
- * Current configuration schema revision!
- */
-const CONFIG_SCHEMA_REV = 2;
+import {migrate} from './manifest-migrations';
 
 /**
  * The name of the prop (`drivers`) used in `extensions.yaml` for drivers.
@@ -36,12 +32,14 @@ const CONFIG_DATA_PLUGIN_KEY = `${PLUGIN_TYPE}s`;
 const INITIAL_MANIFEST_DATA = Object.freeze({
   [CONFIG_DATA_DRIVER_KEY]: Object.freeze({}),
   [CONFIG_DATA_PLUGIN_KEY]: Object.freeze({}),
-  schemaRev: CONFIG_SCHEMA_REV,
+  schemaRev: CURRENT_SCHEMA_REV,
 });
 
 /**
  * Given a `package.json` return `true` if it represents an Appium Extension (either a driver or plugin).
  *
+ *  _This is a type guard; not a validator._
+ *
  * The `package.json` must have an `appium` property which is an object.
  * @param {any} value
  * @returns {value is ExtPackageJson<ExtensionType>}
@@ -54,32 +52,35 @@ function isExtension(value) {
     _.isString(value.version)
   );
 }
+
 /**
  * Given a `package.json`, return `true` if it represents an Appium Driver.
  *
- * To be considered a driver, a `package.json` must have a fields
- * `appium.driverName`, `appium.automationName` and `appium.platformNames`.
+ * _This is a type guard; not a validator._
+ *
+ * To be considered a driver, a `package.json` must have an `appium.driverName` field.
+ *
+ * Further validation of the `appium` property happens elsewhere.
  * @param {any} value - Value to test
  * @returns {value is ExtPackageJson<DriverType>}
  */
 function isDriver(value) {
-  return (
-    isExtension(value) &&
-    _.isString(_.get(value, 'appium.driverName')) &&
-    _.isString(_.get(value, 'appium.automationName')) &&
-    _.isArray(_.get(value, 'appium.platformNames'))
-  );
+  return isExtension(value) && 'driverName' in value.appium && _.isString(value.appium.driverName);
 }
 
 /**
  * Given a `package.json`, return `true` if it represents an Appium Plugin.
  *
+ * _This is a type guard; not a validator._
+ *
  * To be considered a plugin, a `package.json` must have an `appium.pluginName` field.
+ *
+ * Further validation of the `appium` property happens elsewhere.
  * @param {any} value - Value to test
  * @returns {value is ExtPackageJson<PluginType>}
  */
 function isPlugin(value) {
-  return isExtension(value) && _.isString(_.get(value, 'appium.pluginName'));
+  return isExtension(value) && 'pluginName' in value.appium && _.isString(value.appium.pluginName);
 }
 
 /**
@@ -93,23 +94,21 @@ export class Manifest {
    *
    * Contains proxies for automatic persistence on disk
    * @type {ManifestData}
-   * @private
    */
-  _data;
+  #data;
 
   /**
    * Path to `APPIUM_HOME`.
-   * @private
    * @type {Readonly<string>}
    */
-  _appiumHome;
+  #appiumHome;
 
   /**
    * Path to `extensions.yaml`
    * @type {string}
    * Not set until {@link Manifest.read} is called.
    */
-  _manifestPath;
+  #manifestPath;
 
   /**
    * Helps avoid writing multiple times.
@@ -118,10 +117,9 @@ export class Manifest {
    * set to a `Promise`. When the call to `write()` is complete, the `Promise`
    * will resolve and then this value will be set to `undefined`.  Concurrent calls
    * made while this value is a `Promise` will return the `Promise` itself.
-   * @private
    * @type {Promise<boolean>|undefined}
    */
-  _writing;
+  #writing;
 
   /**
    * Helps avoid reading multiple times.
@@ -130,10 +128,9 @@ export class Manifest {
    * set to a `Promise`. When the call to `read()` is complete, the `Promise`
    * will resolve and then this value will be set to `undefined`.  Concurrent calls
    * made while this value is a `Promise` will return the `Promise` itself.
-   * @private
    * @type {Promise<void>|undefined}
    */
-  _reading;
+  #reading;
 
   /**
    * Sets internal data to a fresh clone of {@link INITIAL_MANIFEST_DATA}
@@ -143,8 +140,8 @@ export class Manifest {
    * @private
    */
   constructor(appiumHome) {
-    this._appiumHome = appiumHome;
-    this._data = _.cloneDeep(INITIAL_MANIFEST_DATA);
+    this.#appiumHome = appiumHome;
+    this.#data = _.cloneDeep(INITIAL_MANIFEST_DATA);
   }
 
   /**
@@ -174,7 +171,23 @@ export class Manifest {
     const onMatch = async (filepath) => {
       try {
         const pkg = JSON.parse(await fs.readFile(filepath, 'utf8'));
-        if (isDriver(pkg) || isPlugin(pkg)) {
+        if (isExtension(pkg)) {
+          const extType = isDriver(pkg) ? DRIVER_TYPE : PLUGIN_TYPE;
+          /**
+           * this should only be 'unknown' if the extension's `package.json` is invalid
+           * @type {string}
+           */
+          const name = isDriver(pkg)
+            ? pkg.appium.driverName
+            : isPlugin(pkg)
+            ? pkg.appium.pluginName
+            : '(unknown)';
+          if (
+            (isDriver(pkg) && !this.hasDriver(name)) ||
+            (isPlugin(pkg) && !this.hasPlugin(name))
+          ) {
+            log.info(`Discovered installed ${extType} "${name}"`);
+          }
           const changed = this.addExtensionFromPackage(pkg, filepath);
           didChange = didChange || changed;
         }
@@ -187,14 +200,14 @@ export class Manifest {
      */
     const queue = [
       // look at `package.json` in `APPIUM_HOME` only
-      onMatch(path.join(this._appiumHome, 'package.json')),
+      onMatch(path.join(this.#appiumHome, 'package.json')),
     ];
 
     // add dependencies to the queue
     await new B((resolve, reject) => {
       glob(
         'node_modules/{*,@*/*}/package.json',
-        {cwd: this._appiumHome, silent: true, absolute: true},
+        {cwd: this.#appiumHome, silent: true, absolute: true},
         // eslint-disable-next-line promise/prefer-await-to-callbacks
         (err) => {
           if (err) {
@@ -221,7 +234,7 @@ export class Manifest {
    * @returns {boolean}
    */
   hasDriver(name) {
-    return Boolean(this._data.drivers[name]);
+    return Boolean(this.#data.drivers[name]);
   }
 
   /**
@@ -230,17 +243,16 @@ export class Manifest {
    * @returns {boolean}
    */
   hasPlugin(name) {
-    return Boolean(this._data.plugins[name]);
+    return Boolean(this.#data.plugins[name]);
   }
 
   /**
    * Given a path to a `package.json`, add it as either a driver or plugin to the manifest.
    *
-   * Will _not_ overwrite existing entries.
    * @template {ExtensionType} ExtType
    * @param {ExtPackageJson<ExtType>} pkgJson
    * @param {string} pkgPath
-   * @returns {boolean} - `true` upon success, `false` if the extension is already registered.
+   * @returns {boolean} - `true` if this method did anything.
    */
   addExtensionFromPackage(pkgJson, pkgPath) {
     const extensionPath = path.dirname(pkgPath);
@@ -254,29 +266,32 @@ export class Manifest {
       appiumVersion: pkgJson.peerDependencies?.appium,
       installType: INSTALL_TYPE_NPM,
       installSpec: `${pkgJson.name}@${pkgJson.version}`,
+      installPath: extensionPath,
     };
 
     if (isDriver(pkgJson)) {
-      if (!this.hasDriver(pkgJson.appium.driverName)) {
-        this.addExtension(DRIVER_TYPE, pkgJson.appium.driverName, {
-          ..._.omit(pkgJson.appium, 'driverName'),
-          ...internal,
-        });
+      const value = {
+        ..._.omit(pkgJson.appium, 'driverName'),
+        ...internal,
+      };
+      if (!_.isEqual(value, this.#data.drivers[pkgJson.appium.driverName])) {
+        this.setExtension(DRIVER_TYPE, pkgJson.appium.driverName, value);
         return true;
       }
       return false;
     } else if (isPlugin(pkgJson)) {
-      if (!this.hasPlugin(pkgJson.appium.pluginName)) {
-        this.addExtension(PLUGIN_TYPE, pkgJson.appium.pluginName, {
-          ..._.omit(pkgJson.appium, 'pluginName'),
-          ...internal,
-        });
+      const value = {
+        ..._.omit(pkgJson.appium, 'pluginName'),
+        ...internal,
+      };
+      if (!_.isEqual(value, this.#data.plugins[pkgJson.appium.pluginName])) {
+        this.setExtension(PLUGIN_TYPE, pkgJson.appium.pluginName, value);
         return true;
       }
       return false;
     } else {
       throw new TypeError(
-        `The extension in ${extensionPath} is neither a valid driver nor a valid plugin.`
+        `The extension in ${extensionPath} is neither a valid ${DRIVER_TYPE} nor a valid ${PLUGIN_TYPE}.`
       );
     }
   }
@@ -292,24 +307,48 @@ export class Manifest {
    * @param {ExtManifest<ExtType>} extData - Extension metadata
    * @returns {ExtManifest<ExtType>} A clone of `extData`, potentially with a mutated `appiumVersion` field
    */
-  addExtension(extType, extName, extData) {
-    const data = _.clone(extData);
-    this._data[`${extType}s`][extName] = data;
+  setExtension(extType, extName, extData) {
+    const data = _.cloneDeep(extData);
+    this.#data[`${extType}s`][extName] = data;
     return data;
   }
 
   /**
-   * Returns the APPIUM_HOME path
+   * Sets the schema revision
+   * @param {keyof import('./manifest-migrations').ManifestDataVersions} rev
+   */
+  setSchemaRev(rev) {
+    this.#data.schemaRev = rev;
+  }
+
+  /**
+   * Remove an extension from the manifest.
+   * @param {ExtensionType} extType
+   * @param {string} extName
+   */
+  deleteExtension(extType, extName) {
+    delete this.#data[`${extType}s`][extName];
+  }
+
+  /**
+   * Returns the `APPIUM_HOME` path
    */
   get appiumHome() {
-    return this._appiumHome;
+    return this.#appiumHome;
   }
 
   /**
-   * Returns the path to the manifest file
+   * Returns the path to the manifest file (`extensions.yaml`)
    */
   get manifestPath() {
-    return this._manifestPath;
+    return this.#manifestPath;
+  }
+
+  /**
+   * Returns the schema rev of this manifest
+   */
+  get schemaRev() {
+    return this.#data.schemaRev;
   }
 
   /**
@@ -317,47 +356,62 @@ export class Manifest {
    *
    * @template {ExtensionType} ExtType
    * @param {ExtType} extType
-   * @returns {ExtRecord<ExtType>}
+   * @returns {Readonly<ExtRecord<ExtType>>}
    */
   getExtensionData(extType) {
-    return this._data[/** @type {string} */ (`${extType}s`)];
+    return this.#data[/** @type {string} */ (`${extType}s`)];
   }
 
   /**
    * Reads manifest from disk and _overwrites_ the internal data.
    *
-   * If the manifest does not exist on disk, an {@link INITIAL_MANIFEST_DATA "empty"} manifest file will be created.
+   * If the manifest does not exist on disk, an
+   * {@link INITIAL_MANIFEST_DATA "empty"} manifest file will be created, as
+   * well as its directory if needed.
+   *
+   * This will also, if necessary:
+   * 1. perform a migration of the manifest data
+   * 2. sync the manifest with extensions on-disk (kind of like "auto
+   *    discovery")
+   * 3. write the manifest to disk.
    *
-   * If `APPIUM_HOME` contains a `package.json` with an `appium` dependency, then a hash of the `package.json` will be taken. If this hash differs from the last hash, the contents of `APPIUM_HOME/node_modules` will be scanned for extensions that may have been installed outside of the `appium` CLI.  Any found extensions will be added to the manifest file, and if so, the manifest file will be written to disk.
+   * Only one read operation can happen at a time.
    *
-   * Only one read operation should happen at a time.  This is controlled via the {@link Manifest._reading} property.
    * @returns {Promise<ManifestData>} The data
    */
   async read() {
-    if (this._reading) {
-      await this._reading;
-      return this._data;
+    if (this.#reading) {
+      await this.#reading;
+      return this.#data;
     }
 
-    this._reading = (async () => {
+    this.#reading = (async () => {
       /** @type {ManifestData} */
       let data;
-      let isNewFile = false;
-      await this._setManifestPath();
+      /**
+       * This will be `true` if, after reading, we need to update the manifest data
+       * and write it again to disk.
+       */
+      let shouldWrite = false;
+      await this.#setManifestPath();
       try {
-        log.debug(`Reading ${this._manifestPath}...`);
-        const yaml = await fs.readFile(this._manifestPath, 'utf8');
+        const yaml = await fs.readFile(this.#manifestPath, 'utf8');
         data = YAML.parse(yaml);
-        log.debug(`Parsed manifest file: ${JSON.stringify(data, null, 2)}`);
+        log.debug(
+          `Parsed manifest file at ${this.#manifestPath}: ${JSON.stringify(data, null, 2)}`
+        );
       } catch (err) {
         if (err.code === 'ENOENT') {
+          log.debug(`No manifest file found at ${this.#manifestPath}; creating`);
           data = _.cloneDeep(INITIAL_MANIFEST_DATA);
-          isNewFile = true;
+          shouldWrite = true;
         } else {
-          if (this._manifestPath) {
+          if (this.#manifestPath) {
             throw new Error(
               `Appium had trouble loading the extension installation ` +
-                `cache file (${this._manifestPath}). It may be invalid YAML. Specific error: ${err.message}`
+                `cache file (${this.#manifestPath}). It may be invalid YAML. Specific error: ${
+                  err.message
+                }`
             );
           } else {
             throw new Error(
@@ -367,47 +421,73 @@ export class Manifest {
         }
       }
 
-      this._data = data;
-      let installedExtensionsChanged = false;
+      this.#data = data;
+
+      /**
+       * the only way `shouldWrite` is `true` is if we have a new file.  a new
+       * file will get the latest schema revision, so we can skip the migration.
+       */
+      if (!shouldWrite && (data.schemaRev ?? 0) < CURRENT_SCHEMA_REV) {
+        log.debug(
+          `Updating manifest schema from rev ${data.schemaRev ?? '(none)'} to ${CURRENT_SCHEMA_REV}`
+        );
+        shouldWrite = await migrate(this);
+      }
+
+      /**
+       * we still may want to sync with installed extensions even if we have a
+       * new file. right now this is limited to the following cases:
+       * 1. we have a brand new manifest file
+       * 2. we have performed a migration on a manifest file
+       * 3. `appium` is a dependency within `package.json`, and `package.json`
+       *    has changed since last time we checked.
+       *
+       * It may also make sense to sync with the extensions in an arbitrary
+       * `APPIUM_HOME`, but we don't do that here.
+       */
       if (
-        (await env.hasAppiumDependency(this.appiumHome)) &&
-        (await packageDidChange(this.appiumHome))
+        shouldWrite ||
+        ((await env.hasAppiumDependency(this.appiumHome)) &&
+          (await packageDidChange(this.appiumHome)))
       ) {
-        installedExtensionsChanged = await this.syncWithInstalledExtensions();
+        log.debug('Discovering newly installed extensions...');
+        shouldWrite = (await this.syncWithInstalledExtensions()) || shouldWrite;
       }
 
-      if (isNewFile || installedExtensionsChanged) {
+      if (shouldWrite) {
         await this.write();
       }
     })();
+
     try {
-      await this._reading;
-      return this._data;
+      await this.#reading;
+      return this.#data;
     } finally {
-      this._reading = undefined;
+      this.#reading = undefined;
     }
   }
 
   /**
-   * Ensures {@link Manifest._manifestPath} is set.
+   * Ensures the internal manifest path is set.
    *
    * Creates the directory if necessary.
-   * @private
    * @returns {Promise<string>}
    */
-  async _setManifestPath() {
-    if (!this._manifestPath) {
-      this._manifestPath = await env.resolveManifestPath(this._appiumHome);
+  async #setManifestPath() {
+    if (!this.#manifestPath) {
+      this.#manifestPath = await env.resolveManifestPath(this.#appiumHome);
 
       /* istanbul ignore if */
-      if (path.relative(this._appiumHome, this._manifestPath).startsWith('.')) {
+      if (path.relative(this.#appiumHome, this.#manifestPath).startsWith('.')) {
         throw new Error(
-          `Mismatch between location of APPIUM_HOME and manifest file. APPIUM_HOME: ${this.appiumHome}, manifest file: ${this._manifestPath}`
+          `Mismatch between location of APPIUM_HOME and manifest file. APPIUM_HOME: ${
+            this.appiumHome
+          }, manifest file: ${this.#manifestPath}`
         );
       }
     }
 
-    return this._manifestPath;
+    return this.#manifestPath;
   }
 
   /**
@@ -419,34 +499,35 @@ export class Manifest {
    * @returns {Promise<boolean>} Whether the data was written
    */
   async write() {
-    if (this._writing) {
-      return this._writing;
+    if (this.#writing) {
+      return this.#writing;
     }
-    this._writing = (async () => {
-      await this._setManifestPath();
+    this.#writing = (async () => {
+      await this.#setManifestPath();
       try {
-        await fs.mkdirp(path.dirname(this._manifestPath));
+        await fs.mkdirp(path.dirname(this.#manifestPath));
       } catch (err) {
         throw new Error(
           `Appium could not create the directory for the manifest file: ${path.dirname(
-            this._manifestPath
+            this.#manifestPath
           )}. Original error: ${err.message}`
         );
       }
       try {
-        await fs.writeFile(this._manifestPath, YAML.stringify(this._data), 'utf8');
+        await fs.writeFile(this.#manifestPath, YAML.stringify(this.#data), 'utf8');
         return true;
       } catch (err) {
         throw new Error(
-          `Appium could not write to manifest at ${this._manifestPath} using APPIUM_HOME ${this._appiumHome}. ` +
-            `Please ensure it is writable. Original error: ${err.message}`
+          `Appium could not write to manifest at ${this.#manifestPath} using APPIUM_HOME ${
+            this.#appiumHome
+          }. Please ensure it is writable. Original error: ${err.message}`
         );
       }
     })();
     try {
-      return await this._writing;
+      return await this.#writing;
     } finally {
-      this._writing = undefined;
+      this.#writing = undefined;
     }
   }
 }
@@ -472,18 +553,18 @@ export class Manifest {
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtPackageJson<T>} ExtPackageJson
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtPackageJson<ExtType>} ExtPackageJson
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtManifest<T>} ExtManifest
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtManifest<ExtType>} ExtManifest
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtRecord<T>} ExtRecord
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtRecord<ExtType>} ExtRecord
  */
 
 /**

package/lib/extension/plugin-config.js

@@ -72,7 +72,7 @@ export class PluginConfig extends ExtensionConfig {
 
   /**
    *
-   * @param {(keyof PluginRecord)[]} activeNames
+   * @param {(keyof import('appium/types').ExtRecord<PluginType>)[]} activeNames
    * @returns {void}
    */
   print(activeNames) {
@@ -106,7 +106,6 @@ export class PluginConfig extends ExtensionConfig {
  */
 
 /**
- * @typedef {import('appium/types').PluginRecord} PluginRecord
  * @typedef {import('@appium/types').PluginType} PluginType
  * @typedef {import('appium/types').ExtMetadata<PluginType>} PluginMetadata
  * @typedef {import('./manifest').Manifest} Manifest

package/lib/logsink.js

@@ -33,6 +33,8 @@ const npmToWinstonLevels = {
   error: 'error',
 };
 
+const encounteredPrefixes = [];
+
 let log = null;
 let useLocalTimeZone = false;
 
@@ -186,8 +188,21 @@ async function createTransports(args) {
   return transports;
 }
 
+function getColorizedPrefix(prefix) {
+  let prefixId = prefix.split('@')[0].trim();
+  prefixId = prefixId.split(' (')[0].trim();
+  if (encounteredPrefixes.indexOf(prefixId) < 0) {
+    encounteredPrefixes.push(prefixId);
+  }
+  // using a multiple of 16 should cause 16 colors to be created
+  const colorNumber = encounteredPrefixes.indexOf(prefixId) * 16;
+  // use the modulus to cycle around color wheel
+  return `\x1b[38;5;${colorNumber % 256}m${prefix}\x1b[0m`;
+}
+
 async function init(args) {
   npmlog.level = 'silent';
+
   // set de facto param passed to timestamp function
   useLocalTimeZone = args.localTimezone;
 
@@ -205,11 +220,17 @@ async function init(args) {
     let msg = logObj.message;
     if (logObj.prefix) {
       const prefix = `[${logObj.prefix}]`;
-      msg = `${args.logNoColors ? prefix : prefix.magenta} ${msg}`;
-    }
-    log[winstonLevel](msg);
-    if (args.logHandler && _.isFunction(args.logHandler)) {
-      args.logHandler(logObj.level, msg);
+      if (args.logNoColors) {
+        msg = `${prefix} ${msg}`;
+      } if (prefix === '[Appium]') {
+        msg = `${prefix.magenta} ${msg}`;
+      } else {
+        msg = `${getColorizedPrefix(prefix)} ${msg}`;
+      }
+      log[winstonLevel](msg);
+      if (args.logHandler && _.isFunction(args.logHandler)) {
+        args.logHandler(logObj.level, msg);
+      }
     }
   });
 }