appium 2.0.0-beta.47 → 2.0.0-beta.48

package/lib/constants.js

@@ -45,6 +45,7 @@ export const KNOWN_DRIVERS = Object.freeze(
     espresso: 'appium-espresso-driver',
     safari: 'appium-safari-driver',
     gecko: 'appium-geckodriver',
+    chromium: 'appium-chromium-driver',
   })
 );
 

package/lib/extension/extension-config.js

@@ -33,13 +33,18 @@ const INSTALL_TYPES = new Set([
  * @template {ExtensionType} ExtType
  */
 export class ExtensionConfig {
-  /** @type {ExtType} */
+  /**
+   * The type of extension this class is responsible for.
+   * @type {ExtType}
+   */
   extensionType;
 
-  /** @type {`${ExtType}s`} */
-  configKey;
-
-  /** @type {ExtRecord<ExtType>} */
+  /**
+   * Manifest data for the extensions of this type.
+   *
+   * This data should _not_ be written to by anything but {@linkcode Manifest}.
+   * @type {Readonly<ExtRecord<ExtType>>}
+   */
   installedExtensions;
 
   /** @type {import('@appium/types').AppiumLogger} */
@@ -49,9 +54,9 @@ export class ExtensionConfig {
   manifest;
 
   /**
-   * @type {ExtensionListData}
+   * @type {ExtensionListData|undefined}
    */
-  _listDataCache;
+  #listDataCache;
 
   /**
    * @protected
@@ -60,7 +65,6 @@ export class ExtensionConfig {
    */
   constructor(extensionType, manifest) {
     this.extensionType = extensionType;
-    this.configKey = `${extensionType}s`;
     this.installedExtensions = manifest.getExtensionData(extensionType);
     this.manifest = manifest;
   }
@@ -204,8 +208,8 @@ export class ExtensionConfig {
     if (!_.isEmpty(errorSummaries)) {
       log.error(
         `Appium encountered ${util.pluralize('error', errorMap.size, true)} while validating ${
-          this.configKey
-        } found in manifest ${this.manifestPath}`
+          this.extensionType
+        }s found in manifest ${this.manifestPath}`
       );
       for (const summary of errorSummaries) {
         log.error(summary);
@@ -219,7 +223,7 @@ export class ExtensionConfig {
             'warning',
             warningMap.size,
             true
-          )} while validating ${this.configKey} found in manifest ${this.manifestPath}`
+          )} while validating ${this.extensionType}s found in manifest ${this.manifestPath}`
         );
         for (const summary of warningSummaries) {
           log.warn(summary);
@@ -231,18 +235,20 @@ export class ExtensionConfig {
 
   /**
    * Retrieves listing data for extensions via command class.
-   * Caches the result in {@linkcode ExtensionConfig._listDataCache}
+   *
+   * This is an expensive operation, so the result is cached.  Currently, there is no
+   * use case for invalidating the cache.
    * @protected
    * @returns {Promise<ExtensionListData>}
    */
   async getListData() {
-    if (this._listDataCache) {
-      return this._listDataCache;
+    if (this.#listDataCache) {
+      return this.#listDataCache;
     }
     const CommandClass = /** @type {ExtCommand<ExtType>} */ (commandClasses[this.extensionType]);
     const cmd = new CommandClass({config: this, json: true});
     const listData = await cmd.list({showInstalled: true, showUpdates: true});
-    this._listDataCache = listData;
+    this.#listDataCache = listData;
     return listData;
   }
 
@@ -433,7 +439,7 @@ export class ExtensionConfig {
    * @returns {Promise<void>}
    */
   async addExtension(extName, extManifest, {write = true} = {}) {
-    this.manifest.addExtension(this.extensionType, extName, extManifest);
+    this.manifest.setExtension(this.extensionType, extName, extManifest);
     if (write) {
       await this.manifest.write();
     }
@@ -446,10 +452,10 @@ export class ExtensionConfig {
    * @returns {Promise<void>}
    */
   async updateExtension(extName, extManifest, {write = true} = {}) {
-    this.installedExtensions[extName] = {
+    this.manifest.setExtension(this.extensionType, extName, {
       ...this.installedExtensions[extName],
       ...extManifest,
-    };
+    });
     if (write) {
       await this.manifest.write();
     }
@@ -463,7 +469,7 @@ export class ExtensionConfig {
    * @returns {Promise<void>}
    */
   async removeExtension(extName, {write = true} = {}) {
-    delete this.installedExtensions[extName];
+    this.manifest.deleteExtension(this.extensionType, extName);
     if (write) {
       await this.manifest.write();
     }
@@ -477,13 +483,13 @@ export class ExtensionConfig {
   print(activeNames) {
     if (_.isEmpty(this.installedExtensions)) {
       log.info(
-        `No ${this.configKey} have been installed in ${this.appiumHome}. Use the "appium ${this.extensionType}" ` +
+        `No ${this.extensionType}s 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}:`);
+    log.info(`Available ${this.extensionType}s:`);
     for (const [extName, extManifest] of /** @type {[string, ExtManifest<ExtType>][]} */ (
       _.toPairs(this.installedExtensions)
     )) {
@@ -552,7 +558,7 @@ export class ExtensionConfig {
    * @returns {boolean}
    */
   isInstalled(extName) {
-    return _.includes(Object.keys(this.installedExtensions), extName);
+    return extName in this.installedExtensions;
   }
 
   /**

package/lib/extension/manifest-migrations.js

@@ -1,3 +1,4 @@
+import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
 import log from '../logger';
 
 /**
@@ -12,7 +13,13 @@ import log from '../logger';
 const SCHEMA_REV_3 = 3;
 
 /**
- * Collection of functions to migrate from one version to another
+ * Collection of functions to migrate from one version to another.
+ *
+ * These functions _should not actually perform the migration_; rather, they
+ * should return `true` if the migration should be performed.  The migration
+ * itself will happen within {@linkcode Manifest.syncWithInstalledExtensions}; the extensions
+ * will be checked and the manifest file updated per the state of the filesystem.
+ *
  * @type {{[P in keyof ManifestDataVersions]?: Migration}}
  */
 const Migrations = {
@@ -24,9 +31,13 @@ const Migrations = {
    *
    * @type {Migration}
    */
-  [SCHEMA_REV_3]: (data) => {
+  [SCHEMA_REV_3]: (manifest) => {
     let shouldSync = false;
-    const allExtData = [...Object.values(data.drivers), ...Object.values(data.plugins)];
+    /** @type {Array<ExtManifest<PluginType>|ExtManifest<DriverType>>} */
+    const allExtData = [
+      ...Object.values(manifest.getExtensionData(DRIVER_TYPE)),
+      ...Object.values(manifest.getExtensionData(PLUGIN_TYPE)),
+    ];
     for (const metadata of allExtData) {
       if (!('installPath' in metadata)) {
         shouldSync = true;
@@ -38,14 +49,20 @@ const Migrations = {
 };
 
 /**
- * Set `schemaRev` to a specific version
- * @param {AnyManifestDataVersion} data
+ * Set `schemaRev` to a specific version.
+ *
+ * This _does_ mutate `data` in-place, unlike functions in
+ * {@linkcode Migrations}.
+ *
+ * Again, returning `true` means that the manifest should be--at
+ * minimum--persisted to disk, since we changed it.
+ * @param {Readonly<Manifest>} manifest
  * @param {keyof ManifestDataVersions} version
  * @returns {boolean} Whether the data was modified
  */
-function setSchemaRev(data, version) {
-  if (data.schemaRev ?? 0 < version) {
-    data.schemaRev = version;
+function setSchemaRev(manifest, version) {
+  if (manifest.schemaRev ?? 0 < version) {
+    manifest.setSchemaRev(version);
     return true;
   }
   return false;
@@ -56,44 +73,48 @@ function setSchemaRev(data, version) {
  *
  * `data` is modified in-place.
  *
- * @param {Manifest} manifest
- * @param {AnyManifestDataVersion} data
+ * @param {Readonly<Manifest>} manifest
  * @returns {Promise<boolean>} If `true` existing packages should be synced from disk and the manifest should be persisted.
  */
-export async function migrate(manifest, data) {
+export async function migrate(manifest) {
   let didChange = false;
   for await (const [v, migration] of Object.entries(Migrations)) {
     const version = /** @type {keyof ManifestDataVersions} */ (Number(v));
-    didChange = (await migration(data, manifest)) || didChange;
-    didChange = setSchemaRev(data, version) || didChange;
+    didChange = (await migration(manifest)) || didChange;
+    didChange = setSchemaRev(manifest, version) || didChange;
   }
 
   if (didChange) {
     // this is not _technically_ true, since we don't actually write the file here.
-    log.info(`Upgraded extension manifest to schema v${data.schemaRev}`);
+    log.info(`Upgraded extension manifest to schema v${manifest.schemaRev}`);
   }
+
   return didChange;
 }
 
 /**
- * Migration functions take a {@linkcode Manifest} and its data and **mutates `data` in-place**.
+ * A migration function. It will return `true` if a change _should be made_.
  *
  * A migration function should not modify `schemaRev`, as this is done automatically.
  *
- * A migration function can also call out to, say, {@linkcode Manifest.syncWithInstalledExtensions}, which
- * may apply the mutation itself.
- *
  * Note that at the time of writing, we're not able to determine the version of the _current_ manifest file if there is no `schemaRev` prop present (and we may not want to trust it anyway).
  * @callback Migration
- * @param {AnyManifestDataVersion} data - The raw data from `Manifest`
- * @param {Manifest} manifest - The `Manifest` instance
+ * @param {Readonly<Manifest>} manifest - The `Manifest` instance
  * @returns {boolean|Promise<boolean>} If `true`, then something changed
  */
 
 /**
  * @typedef {import('appium/types').ManifestData} ManifestData
+ * @typedef {import('@appium/types').DriverType} DriverType
+ * @typedef {import('@appium/types').PluginType} PluginType
  * @typedef {import('appium/types').AnyManifestDataVersion} AnyManifestDataVersion
  * @typedef {import('appium/types').ManifestDataVersions} ManifestDataVersions
+ * @typedef {import('@appium/types').ExtensionType} ExtensionType
  * @typedef {import('appium/types').ManifestV2.ManifestData} ManifestDataV2
  * @typedef {import('./manifest').Manifest} Manifest
  */
+
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtManifest<ExtType>} ExtManifest
+ */

package/lib/extension/manifest.js

@@ -38,6 +38,8 @@ const INITIAL_MANIFEST_DATA = Object.freeze({
 /**
  * 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>}
@@ -50,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);
 }
 
 /**
@@ -166,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;
         }
@@ -228,11 +249,10 @@ export class Manifest {
   /**
    * 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);
@@ -250,26 +270,28 @@ export class Manifest {
     };
 
     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}.`
       );
     }
   }
@@ -285,12 +307,29 @@ 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);
+  setExtension(extType, extName, extData) {
+    const data = _.cloneDeep(extData);
     this.#data[`${extType}s`][extName] = data;
     return data;
   }
 
+  /**
+   * 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
    */
@@ -305,12 +344,19 @@ export class Manifest {
     return this.#manifestPath;
   }
 
+  /**
+   * Returns the schema rev of this manifest
+   */
+  get schemaRev() {
+    return this.#data.schemaRev;
+  }
+
   /**
    * Returns extension data for a particular type.
    *
    * @template {ExtensionType} ExtType
    * @param {ExtType} extType
-   * @returns {ExtRecord<ExtType>}
+   * @returns {Readonly<ExtRecord<ExtType>>}
    */
   getExtensionData(extType) {
     return this.#data[/** @type {string} */ (`${extType}s`)];
@@ -319,11 +365,18 @@ export class Manifest {
   /**
    * 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.
    *
-   * 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.
+   * 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.
+   *
+   * Only one read operation can happen at a time.
    *
-   * Only one read operation should happen at a time.
    * @returns {Promise<ManifestData>} The data
    */
   async read() {
@@ -335,17 +388,23 @@ export class Manifest {
     this.#reading = (async () => {
       /** @type {ManifestData} */
       let data;
-      let isNewFile = false;
+      /**
+       * 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');
         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) {
             throw new Error(
@@ -364,27 +423,42 @@ export class Manifest {
 
       this.#data = data;
 
-      let shouldWrite = false;
-
-      if ((data.schemaRev ?? 0) < CURRENT_SCHEMA_REV) {
+      /**
+       * 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, this.#data);
+        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 (
         shouldWrite ||
         ((await env.hasAppiumDependency(this.appiumHome)) &&
           (await packageDidChange(this.appiumHome)))
       ) {
-        shouldWrite = await this.syncWithInstalledExtensions();
+        log.debug('Discovering newly installed extensions...');
+        shouldWrite = (await this.syncWithInstalledExtensions()) || shouldWrite;
       }
 
-      if (isNewFile || shouldWrite) {
+      if (shouldWrite) {
         await this.write();
       }
     })();
+
     try {
       await this.#reading;
       return this.#data;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.0.0-beta.47",
+  "version": "2.0.0-beta.48",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -52,17 +52,17 @@
     "postinstall": "node ./scripts/autoinstall-extensions.js",
     "publish:docs": "cross-env APPIUM_DOCS_PUBLISH=1 npm run build:docs",
     "test": "npm run test:unit",
-    "test:e2e": "mocha --timeout 1m --slow 30s \"./test/e2e/**/*.spec.js\"",
+    "test:e2e": "mocha -p --timeout 1m --slow 30s \"./test/e2e/**/*.spec.js\"",
     "test:smoke": "cross-env APPIUM_HOME=./local_appium_home node ./index.js driver install uiautomator2 && cross-env APPIUM_HOME=./local_appium_home node ./index.js driver list",
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/base-driver": "^9.0.0",
-    "@appium/base-plugin": "^2.0.0",
-    "@appium/docutils": "^0.1.0",
+    "@appium/base-driver": "^9.1.0",
+    "@appium/base-plugin": "^2.0.1",
+    "@appium/docutils": "^0.1.1",
     "@appium/schema": "^0.1.0",
-    "@appium/support": "^3.0.0",
-    "@appium/types": "^0.6.0",
+    "@appium/support": "^3.0.1",
+    "@appium/types": "^0.7.0",
     "@sidvind/better-ajv-errors": "2.1.0",
     "@types/argparse": "2.0.10",
     "@types/bluebird": "3.5.38",
@@ -90,7 +90,7 @@
     "semver": "7.3.8",
     "source-map-support": "0.5.21",
     "teen_process": "2.0.2",
-    "type-fest": "3.3.0",
+    "type-fest": "3.4.0",
     "winston": "3.8.2",
     "wrap-ansi": "7.0.0",
     "yaml": "2.1.3"
@@ -103,7 +103,7 @@
     "access": "public",
     "tag": "next"
   },
-  "gitHead": "0823f0b60e40395cd1dc3b72cfa3c0092bc81302",
+  "gitHead": "2e76ba9607729f59ca967e47c2cba738e90a57b8",
   "typedoc": {
     "entryPoint": "./build/lib/main.js"
   }