appium 2.0.0-beta.56 → 2.0.0-beta.58

package/lib/extension/extension-config.js

@@ -1,9 +1,9 @@
-import _ from 'lodash';
+import {util} from '@appium/support';
 import B from 'bluebird';
+import _ from 'lodash';
 import path from 'path';
 import resolveFrom from 'resolve-from';
 import {satisfies} from 'semver';
-import {util} from '@appium/support';
 import {commandClasses} from '../cli/extension';
 import {APPIUM_VER} from '../config';
 import log from '../logger';
@@ -13,17 +13,41 @@ import {
   registerSchema,
 } from '../schema/schema';
 
-const INSTALL_TYPE_NPM = 'npm';
-const INSTALL_TYPE_LOCAL = 'local';
-const INSTALL_TYPE_GITHUB = 'github';
-const INSTALL_TYPE_GIT = 'git';
+/**
+ * "npm" install type
+ * Used when extension was installed by npm package name
+ * @remarks _All_ extensions are installed _by_ `npm`, but only this one means the package name was
+ * used to specify it
+ */
+export const INSTALL_TYPE_NPM = 'npm';
+/**
+ * "local" install type
+ * Used when extension was installed from a local path
+ */
+export const INSTALL_TYPE_LOCAL = 'local';
+/**
+ * "github" install type
+ * Used when extension was installed via GitHub URL
+ */
+export const INSTALL_TYPE_GITHUB = 'github';
+/**
+ * "git" install type
+ * Used when extensions was installed via Git URL
+ */
+export const INSTALL_TYPE_GIT = 'git';
+/**
+ * "dev" install type
+ * Used when automatically detected as a working copy
+ */
+export const INSTALL_TYPE_DEV = 'dev';
 
 /** @type {Set<InstallType>} */
-const INSTALL_TYPES = new Set([
+export const INSTALL_TYPES = new Set([
   INSTALL_TYPE_GIT,
   INSTALL_TYPE_GITHUB,
   INSTALL_TYPE_LOCAL,
   INSTALL_TYPE_NPM,
+  INSTALL_TYPE_DEV,
 ]);
 
 /**
@@ -54,7 +78,7 @@ export class ExtensionConfig {
   manifest;
 
   /**
-   * @type {ExtensionListData|undefined}
+   * @type {import('../cli/extension-command').ExtensionList<ExtType>|undefined}
    */
   #listDataCache;
 
@@ -239,7 +263,7 @@ export class ExtensionConfig {
    * This is an expensive operation, so the result is cached.  Currently, there is no
    * use case for invalidating the cache.
    * @protected
-   * @returns {Promise<ExtensionListData>}
+   * @returns {Promise<import('../cli/extension-command').ExtensionList<ExtType>>}
    */
   async getListData() {
     if (this.#listDataCache) {
@@ -300,7 +324,10 @@ export class ExtensionConfig {
 
     if (_.isString(appiumVersion) && !satisfies(APPIUM_VER, appiumVersion)) {
       const listData = await this.getListData();
-      const extListData = /** @type {InstalledExtensionListData} */ (listData[extName]);
+      const extListData =
+        /** @type {import('../cli/extension-command').ExtensionListData<ExtType>} */ (
+          listData[extName]
+        );
       if (extListData?.installed) {
         const {updateVersion, upToDate} = extListData;
         if (!upToDate) {
@@ -319,7 +346,10 @@ export class ExtensionConfig {
       }
     } else if (!_.isString(appiumVersion)) {
       const listData = await this.getListData();
-      const extListData = /** @type {InstalledExtensionListData} */ (listData[extName]);
+      const extListData =
+        /** @type {import('../cli/extension-command').InstalledExtensionListData<ExtType>} */ (
+          listData[extName]
+        );
       if (!extListData?.upToDate && extListData?.updateVersion) {
         warnings.push(
           createPeerWarning(
@@ -544,6 +574,7 @@ export class ExtensionConfig {
       delete require.cache[reqResolved];
     }
     log.debug(`Requiring ${this.extensionType} at ${reqPath}`);
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
     const MainClass = require(reqPath)[mainClass];
     if (!MainClass) {
       throw new ReferenceError(
@@ -619,8 +650,6 @@ export class ExtensionConfig {
   }
 }
 
-export {INSTALL_TYPE_NPM, INSTALL_TYPE_GIT, INSTALL_TYPE_LOCAL, INSTALL_TYPE_GITHUB, INSTALL_TYPES};
-
 /**
  * An issue with the {@linkcode ExtManifest} for a particular extension.
  *
@@ -640,8 +669,6 @@ export {INSTALL_TYPE_NPM, INSTALL_TYPE_GIT, INSTALL_TYPE_LOCAL, INSTALL_TYPE_GIT
 /**
  * @typedef {import('@appium/types').ExtensionType} ExtensionType
  * @typedef {import('./manifest').Manifest} Manifest
- * @typedef {import('../cli/extension-command').ExtensionListData} ExtensionListData
- * @typedef {import('../cli/extension-command').InstalledExtensionListData} InstalledExtensionListData
  * @typedef {import('appium/types').InstallType} InstallType
  */
 

package/lib/extension/manifest-migrations.js

@@ -1,4 +1,4 @@
-import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
+import {CURRENT_SCHEMA_REV, DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
 import log from '../logger';
 
 /**
@@ -12,6 +12,11 @@ import log from '../logger';
  */
 const SCHEMA_REV_3 = 3;
 
+/**
+ * Constant for v4 of the schema rev.
+ */
+const SCHEMA_REV_4 = 4;
+
 /**
  * Collection of functions to migrate from one version to another.
  *
@@ -20,7 +25,7 @@ const SCHEMA_REV_3 = 3;
  * 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}}
+ * @type { {[P in keyof ManifestDataVersions]?: Migration} }
  */
 const Migrations = {
   /**
@@ -32,19 +37,32 @@ const Migrations = {
    * @type {Migration}
    */
   [SCHEMA_REV_3]: (manifest) => {
-    let shouldSync = false;
     /** @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;
-        break;
-      }
+    return allExtData.some((metadata) => !('installPath' in metadata));
+  },
+  /**
+   * Updates installed extensions to use `InstallType` of `dev` if appropriate.
+   *
+   * Previously, these types of extensions (automatically discovered) would use the default `InstallType` of `npm`, so we need
+   * to refresh any with this install type.
+   *
+   * This should only happen once; we do not want to re-check everything with `npm` install type
+   * every time.
+   * @type {Migration}
+   */
+  [SCHEMA_REV_4]: (manifest) => {
+    if (manifest.schemaRev < SCHEMA_REV_4) {
+      const allExtData = [
+        ...Object.values(manifest.getExtensionData(DRIVER_TYPE)),
+        ...Object.values(manifest.getExtensionData(PLUGIN_TYPE)),
+      ];
+      return allExtData.some((metadata) => metadata.installType === 'npm');
     }
-    return shouldSync;
+    return false;
   },
 };
 
@@ -61,7 +79,7 @@ const Migrations = {
  * @returns {boolean} Whether the data was modified
  */
 function setSchemaRev(manifest, version) {
-  if (manifest.schemaRev ?? 0 < version) {
+  if ((manifest.schemaRev ?? 0) < version) {
     manifest.setSchemaRev(version);
     return true;
   }
@@ -78,15 +96,13 @@ function setSchemaRev(manifest, version) {
  */
 export async function migrate(manifest) {
   let didChange = false;
-  for await (const [v, migration] of Object.entries(Migrations)) {
-    const version = /** @type {keyof ManifestDataVersions} */ (Number(v));
+  for await (const migration of Object.values(Migrations)) {
     didChange = (await migration(manifest)) || didChange;
-    didChange = setSchemaRev(manifest, version) || didChange;
   }
-
+  didChange = setSchemaRev(manifest, CURRENT_SCHEMA_REV) || 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${manifest.schemaRev}`);
+    log.debug(`Upgraded extension manifest to schema v${manifest.schemaRev}`);
   }
 
   return didChange;

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.56",
+  "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.2",
-    "@appium/base-plugin": "^2.2.2",
-    "@appium/docutils": "^0.2.2",
-    "@appium/schema": "^0.2.5",
-    "@appium/support": "^3.1.6",
-    "@appium/types": "^0.10.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.8",
+    "@appium/types": "^0.10.2",
     "@sidvind/better-ajv-errors": "2.1.0",
     "@types/argparse": "2.0.10",
     "@types/bluebird": "3.5.38",
@@ -82,9 +83,8 @@
     "cross-env": "7.0.3",
     "find-up": "5.0.0",
     "glob": "8.1.0",
-    "lilconfig": "2.0.6",
+    "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.0",
+    "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": "7b4935632222123a4fa7422461f6312f1f0dfbe4",
+  "gitHead": "d514ebdd7ebd27bb236509d0a3d580f0f18a34e5",
   "typedoc": {
     "entryPoint": "./lib/main.js"
   }

package/scripts/autoinstall-extensions.js

@@ -22,6 +22,8 @@
  */
 
 const B = require('bluebird');
+const path = require('node:path');
+const {realpath} = require('node:fs/promises');
 
 B.config({
   cancellation: true,
@@ -55,11 +57,32 @@ function log(message) {
   console.error(wrap(`[Appium] ${message}`));
 }
 
+/**
+ * This is a naive attempt at determining whether or not we are in a dev environment; in other
+ * words, is `postinstall` being run from within the `appium` monorepo?
+ *
+ * When we're in the monorepo, `npm_config_local_prefix` will be set to the root of the monorepo root
+ * dir when running this lifecycle script from an `npm install` in the monorepo root.
+ *
+ * `realpath` is necessary due to macOS omitting `/private` from paths
+ */
+async function isDevEnvironment() {
+  return (
+    process.env.npm_config_local_prefix &&
+    path.join(process.env.npm_config_local_prefix, 'packages', 'appium') ===
+      (await realpath(path.join(__dirname, '..')))
+  );
+}
+
 /**
  * Setup / check environment if we should do anything here
  * @returns {Promise<boolean>} `true` if Appium is built and ready to go
  */
 async function init() {
+  if (await isDevEnvironment()) {
+    log('Dev environment likely; skipping automatic installation of extensions');
+    return false;
+  }
   try {
     ({env, util, logger} = require('@appium/support'));
     // @ts-ignore

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`