appium 2.0.0-beta.57 → 2.0.0-beta.58

package/lib/extension/manifest.js

@@ -10,7 +10,7 @@ import path from 'path';
 import YAML from 'yaml';
 import {CURRENT_SCHEMA_REV, DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
 import log from '../logger';
-import {INSTALL_TYPE_NPM} from './extension-config';
+import {INSTALL_TYPE_NPM, INSTALL_TYPE_DEV} from './extension-config';
 import {packageDidChange} from './package-changed';
 import {migrate} from './manifest-migrations';
 
@@ -148,27 +148,33 @@ export class Manifest {
    * Returns a new or existing {@link Manifest} instance, based on the value of `appiumHome`.
    *
    * Maintains one instance per value of `appiumHome`.
-   * @param {string} appiumHome - Path to `APPIUM_HOME`
-   * @returns {Manifest}
    */
-  static getInstance = _.memoize(function _getInstance(appiumHome) {
-    return new Manifest(appiumHome);
-  });
+  static getInstance = _.memoize(
+    /**
+     * @param {string} appiumHome - Path to `APPIUM_HOME`
+     * @returns {Manifest}
+     */
+    function _getInstance(appiumHome) {
+      return new Manifest(appiumHome);
+    }
+  );
 
   /**
    * Searches `APPIUM_HOME` for installed extensions and adds them to the manifest.
+   * @param {boolean} hasAppiumDependency - This affects whether or not the "dev" `InstallType` is used
    * @returns {Promise<boolean>} `true` if any extensions were added, `false` otherwise.
    */
-  async syncWithInstalledExtensions() {
+  async syncWithInstalledExtensions(hasAppiumDependency = false) {
     // this could be parallelized, but we can't use fs.walk as an async iterator
     let didChange = false;
 
     /**
      * Listener for the `match` event of a `glob` instance
      * @param {string} filepath - Path to a `package.json`
+     * @param {boolean} [devType] - If `true`, this is an extension in "dev mode"
      * @returns {Promise<void>}
      */
-    const onMatch = async (filepath) => {
+    const onMatch = async (filepath, devType = false) => {
       try {
         const pkg = JSON.parse(await fs.readFile(filepath, 'utf8'));
         if (isExtension(pkg)) {
@@ -188,7 +194,8 @@ export class Manifest {
           ) {
             log.info(`Discovered installed ${extType} "${name}"`);
           }
-          const changed = this.addExtensionFromPackage(pkg, filepath);
+          const installType = devType && hasAppiumDependency ? INSTALL_TYPE_DEV : INSTALL_TYPE_NPM;
+          const changed = this.addExtensionFromPackage(pkg, filepath, installType);
           didChange = didChange || changed;
         }
       } catch {}
@@ -199,8 +206,9 @@ export class Manifest {
      * @type {Promise<void>[]}
      */
     const queue = [
-      // look at `package.json` in `APPIUM_HOME` only
-      onMatch(path.join(this.#appiumHome, 'package.json')),
+      // look at `package.json` in `APPIUM_HOME` only.
+      // this causes extensions in "dev mode" to be automatically found
+      onMatch(path.join(this.#appiumHome, 'package.json'), true),
     ];
 
     // add dependencies to the queue
@@ -252,9 +260,10 @@ export class Manifest {
    * @template {ExtensionType} ExtType
    * @param {ExtPackageJson<ExtType>} pkgJson
    * @param {string} pkgPath
+   * @param {typeof INSTALL_TYPE_NPM | typeof INSTALL_TYPE_DEV} [installType]
    * @returns {boolean} - `true` if this method did anything.
    */
-  addExtensionFromPackage(pkgJson, pkgPath) {
+  addExtensionFromPackage(pkgJson, pkgPath, installType = INSTALL_TYPE_NPM) {
     const extensionPath = path.dirname(pkgPath);
 
     /**
@@ -264,7 +273,7 @@ export class Manifest {
       pkgName: pkgJson.name,
       version: pkgJson.version,
       appiumVersion: pkgJson.peerDependencies?.appium,
-      installType: INSTALL_TYPE_NPM,
+      installType,
       installSpec: `${pkgJson.name}@${pkgJson.version}`,
       installPath: extensionPath,
     };
@@ -434,6 +443,8 @@ export class Manifest {
         shouldWrite = await migrate(this);
       }
 
+      const hasAppiumDependency = await env.hasAppiumDependency(this.appiumHome);
+
       /**
        * 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:
@@ -445,13 +456,9 @@ export class Manifest {
        * 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)))
-      ) {
+      if (shouldWrite || (hasAppiumDependency && (await packageDidChange(this.appiumHome)))) {
         log.debug('Discovering newly installed extensions...');
-        shouldWrite = (await this.syncWithInstalledExtensions()) || shouldWrite;
+        shouldWrite = (await this.syncWithInstalledExtensions(hasAppiumDependency)) || shouldWrite;
       }
 
       if (shouldWrite) {

package/lib/main.js

@@ -2,7 +2,6 @@
 
 import {init as logsinkInit} from './logsink'; // this import needs to come first since it sets up global npmlog
 import logger from './logger'; // logger needs to remain second
-// @ts-ignore
 import {routeConfiguringFunction as makeRouter, server as baseServer} from '@appium/base-driver';
 import {logger as logFactory, util, env} from '@appium/support';
 import {asyncify} from 'asyncbox';
@@ -23,7 +22,7 @@ import {
 } from './config';
 import {readConfigFile} from './config-file';
 import {loadExtensions, getActivePlugins, getActiveDrivers} from './extension';
-import {SERVER_SUBCOMMAND} from './constants';
+import {SERVER_SUBCOMMAND, LONG_STACKTRACE_LIMIT} from './constants';
 import registerNode from './grid-register';
 import {getDefaultsForSchema, validate} from './schema/schema';
 import {
@@ -47,7 +46,7 @@ async function preflightChecks(args, throwInsteadOfExit = false) {
     checkNodeOk();
     await checkNpmOk();
     if (args.longStacktrace) {
-      require('longjohn').async_trace_limit = -1;
+      Error.stackTraceLimit = LONG_STACKTRACE_LIMIT;
     }
     if (args.showBuildInfo) {
       await showBuildInfo();
@@ -245,7 +244,11 @@ async function init(args) {
       }
     }
 
-    const appiumDriver = new AppiumDriver(serverArgs);
+    const appiumDriver = new AppiumDriver(
+      /** @type {import('@appium/types').DriverOpts<import('./appium').AppiumDriverConstraints>} */ (
+        serverArgs
+      )
+    );
     // set the config on the umbrella driver so it can match drivers to caps
     appiumDriver.driverConfig = driverConfig;
     await preflightChecks(serverArgs, throwInsteadOfExit);

package/lib/schema/cli-args.js

@@ -224,7 +224,7 @@ export function toParserArgs() {
 }
 
 /**
- * @template T
+ * @template {string|number} T
  * @typedef {import('ajv/dist/types').FormatValidator<T>} FormatValidator<T>
  */
 

package/lib/utils.js

@@ -223,7 +223,8 @@ function adjustNodePath() {
       // ! statements in client modules. It uses a private API though,
       // ! so it could break (maybe, eventually).
       // See https://gist.github.com/branneman/8048520#7-the-hack
-      // @ts-ignore
+      // @ts-ignore see above comment
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
       require('module').Module._initPaths();
       return true;
     } catch (e) {
@@ -368,21 +369,18 @@ export {
  */
 
 /**
- * @template {Constraints} [C=BaseDriverCapConstraints]
- * @template {StringRecord|void} [Extra=void]
- * @typedef {import('@appium/types').Capabilities<C, Extra>} Capabilities
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').Capabilities<C>} Capabilities
  */
 
 /**
- * @template {Constraints} [C=BaseDriverCapConstraints]
- * @template {StringRecord|void} [Extra=void]
- * @typedef {import('@appium/types').W3CCapabilities<C, Extra>} W3CCapabilities
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').W3CCapabilities<C>} W3CCapabilities
  */
 
 /**
- * @template {Constraints} [C=BaseDriverCapConstraints]
- * @template {StringRecord|void} [Extra=void]
- * @typedef {import('@appium/types').NSCapabilities<C, Extra>} NSCapabilities
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').NSCapabilities<C>} NSCapabilities
  */
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.0.0-beta.57",
+  "version": "2.0.0-beta.58",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -44,6 +44,7 @@
   ],
   "scripts": {
     "build:docs": "node docs/scripts/build-docs.js",
+    "build:docs:preview": "cross-env APPIUM_DOCS_PREVIEW=1 npm run build:docs",
     "build:docs:assets": "node docs/scripts/copy-assets.js",
     "build:docs:cli": "node docs/scripts/gen-cli-args-docs.js",
     "build:docs:reference": "node docs/scripts/build-reference.js",
@@ -59,12 +60,12 @@
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/base-driver": "^9.3.3",
-    "@appium/base-plugin": "^2.2.3",
-    "@appium/docutils": "^0.3.0",
+    "@appium/base-driver": "^9.3.4",
+    "@appium/base-plugin": "^2.2.4",
+    "@appium/docutils": "^0.3.1",
     "@appium/schema": "^0.2.6",
-    "@appium/support": "^3.1.7",
-    "@appium/types": "^0.10.1",
+    "@appium/support": "^3.1.8",
+    "@appium/types": "^0.10.2",
     "@sidvind/better-ajv-errors": "2.1.0",
     "@types/argparse": "2.0.10",
     "@types/bluebird": "3.5.38",
@@ -84,7 +85,6 @@
     "glob": "8.1.0",
     "lilconfig": "2.1.0",
     "lodash": "4.17.21",
-    "longjohn": "0.2.12",
     "npmlog": "7.0.1",
     "ora": "5.4.1",
     "package-changed": "2.0.0",
@@ -92,7 +92,7 @@
     "semver": "7.3.8",
     "source-map-support": "0.5.21",
     "teen_process": "2.0.2",
-    "type-fest": "3.6.1",
+    "type-fest": "3.7.1",
     "winston": "3.8.2",
     "wrap-ansi": "7.0.0",
     "yaml": "2.2.1"
@@ -105,7 +105,7 @@
     "access": "public",
     "tag": "next"
   },
-  "gitHead": "872b924a97c13142bdb8bf4218a4db324f309ce4",
+  "gitHead": "d514ebdd7ebd27bb236509d0a3d580f0f18a34e5",
   "typedoc": {
     "entryPoint": "./lib/main.js"
   }

package/types/manifest/index.ts

@@ -5,17 +5,18 @@
 
 import * as ManifestV2 from './base';
 import * as ManifestV3 from './v3';
-
+import * as ManifestV4 from './v4';
 // add `import * as ManifestV<new-version> from './v<new-version>';` above
 
-export * from './v3';
+export * from './v4';
 // replace above line with `export * from './v<new-version>';`
 
-export {ManifestV2, ManifestV3};
+export {ManifestV2, ManifestV3, ManifestV4};
 
 export interface ManifestDataVersions {
   2: ManifestV2.ManifestData;
   3: ManifestV3.ManifestData;
+  4: ManifestV4.ManifestData;
 }
 // append to this interface your new version of `ManifestData`
 

package/types/manifest/v4.ts

@@ -0,0 +1,161 @@
+import {DriverType, ExtensionType, PluginType} from '@appium/types';
+import {SchemaObject} from 'ajv';
+import {PackageJson, SetRequired} from 'type-fest';
+
+/**
+ * One of the possible extension installation stratgies
+ */
+export type InstallType = 'npm' | 'git' | 'local' | 'github' | 'dev';
+
+export interface InternalMetadata {
+  /**
+   * Package name of extension
+   *
+   * `name` from its `package.json`
+   */
+  pkgName: string;
+  /**
+   * Version of extension
+   *
+   * `version` from its `package.json`
+   */
+  version: string;
+  /**
+   * The method in which the user installed the extension (the `source` CLI arg)
+   */
+  installType: InstallType;
+  /**
+   * Whatever the user typed as the extension to install. May be derived from `package.json`
+   */
+  installSpec: string;
+  /**
+   * Maximum version of Appium that this extension is compatible with.
+   *
+   * If `undefined`, we'll try anyway.
+   */
+  appiumVersion?: string;
+  /**
+   * Path to the extension's root directory
+   */
+  installPath: string;
+}
+
+/**
+ * Shape of the `appium.schema` property in an extension's `package.json` (if it exists)
+ */
+export type ExtSchemaMetadata = string | (SchemaObject & {[key: number]: never});
+
+/**
+ * Manifest data shared by all extensions, as contained in `package.json`
+ */
+export interface CommonExtMetadata {
+  /**
+   * The main class of the extension.
+   *
+   * The extension must export this class by name.
+   */
+  mainClass: string;
+
+  /**
+   * Lookup table of scripts to run via `appium <driver|plugin> run <script>` keyed by name.
+   */
+  scripts?: Record<string, string>;
+
+  /**
+   * Schema describing configuration options (and CLI args) for the extension.
+   *
+   * Can also just be a path (relative to the extension root) to an external JSON schema file.
+   */
+  schema?: ExtSchemaMetadata;
+}
+
+/**
+ * Driver-specific manifest data as stored in a driver's `package.json`
+ */
+export interface DriverMetadata {
+  /**
+   * Automation name of the driver
+   */
+  automationName: string;
+  /**
+   * Platforms the driver supports
+   */
+  platformNames: string[];
+  /**
+   * Short name of the driver (displayed in `appium list`, etc.)
+   */
+  driverName: string;
+}
+
+/**
+ * Plugin-specific manifest data as stored in a plugin's `package.json`
+ */
+export interface PluginMetadata {
+  /**
+   * Short name of the plugin (displayed in `appium list`, etc.)
+   */
+  pluginName: string;
+}
+
+/**
+ * Generic extension metadata as stored in the `appium` prop of an extension's `package.json`.
+ */
+export type ExtMetadata<ExtType extends ExtensionType> = (ExtType extends DriverType
+  ? DriverMetadata
+  : ExtType extends PluginType
+  ? PluginMetadata
+  : never) &
+  CommonExtMetadata;
+
+/**
+ * Combination of external + internal extension data with `driverName`/`pluginName` removed (it becomes a key in an {@linkcode ExtRecord} object).
+ * Part of `extensions.yaml`.
+ */
+export type ExtManifest<ExtType extends ExtensionType> = Omit<
+  ExtMetadata<ExtType>,
+  'driverName' | 'pluginName'
+> &
+  InternalMetadata;
+
+/**
+ * Lookup of extension name to {@linkcode ExtManifest}.
+ * @see {ManifestData}
+ */
+export type ExtRecord<ExtType extends ExtensionType> = Record<string, ExtManifest<ExtType>>;
+
+/**
+ * The shape of the `extensions.yaml` file
+ */
+export interface ManifestData {
+  drivers: ExtRecord<DriverType>;
+  plugins: ExtRecord<PluginType>;
+  schemaRev: number;
+}
+
+/**
+ * The name of an installed extension, as it appears in `extensions.yaml`
+ * (as a property name under `drivers` or `plugins`)
+ */
+export type ExtName<ExtType extends ExtensionType> = keyof ExtRecord<ExtType>;
+
+/**
+ * A `package.json` containing extension metadata.
+ * Must have the following properties:
+ * - `name`: the name of the extension
+ * - `version`: the version of the extension
+ * - `appium`: the metadata for the extension
+ * - `peerDependencies.appium`: the maximum compatible version of Appium
+ */
+export type ExtPackageJson<ExtType extends ExtensionType> = SetRequired<
+  PackageJson,
+  'name' | 'version'
+> & {
+  appium: ExtMetadata<ExtType>;
+  peerDependencies: {appium: string; [key: string]: string};
+};
+
+/**
+ * A transient format between installation and insertion of extension metadata into the manifest.
+ */
+export type ExtInstallReceipt<ExtType extends ExtensionType> = ExtMetadata<ExtType> &
+  InternalMetadata;