appium 2.0.0-beta.43 → 2.0.0-beta.45

package/lib/appium.js

@@ -14,13 +14,9 @@ import AsyncLock from 'async-lock';
 import {parseCapsForInnerDriver, pullSettings} from './utils';
 import {util, node, logger} from '@appium/support';
 import {getDefaultsForExtension} from './schema';
-import {DRIVER_TYPE, PLUGIN_TYPE} from './constants';
+import {DRIVER_TYPE} from './constants';
 
-/**
- * Invariant set of base constraints
- * @type {Readonly<Constraints>}
- */
-const desiredCapabilityConstraints = Object.freeze({
+const desiredCapabilityConstraints = /** @type {const} */ ({
   automationName: {
     presence: true,
     isString: true,
@@ -30,6 +26,9 @@ const desiredCapabilityConstraints = Object.freeze({
     isString: true,
   },
 });
+/**
+ * @typedef {typeof desiredCapabilityConstraints} AppiumDriverConstraints
+ */
 
 const sessionsListGuard = new AsyncLock();
 const pendingDriversGuard = new AsyncLock();
@@ -181,10 +180,10 @@ class AppiumDriver extends DriverCore {
   /**
    * Retrieves all CLI arguments for a specific plugin.
    * @param {string} extName - Plugin name
-   * @returns {Record<string,unknown>} Arguments object. If none, an empty object.
+   * @returns {StringRecord} Arguments object. If none, an empty object.
    */
   getCliArgsForPlugin(extName) {
-    return /** @type {Record<string,unknown>} */ (this.args.plugin?.[extName] ?? {});
+    return /** @type {StringRecord} */ (this.args.plugin?.[extName] ?? {});
   }
 
   /**
@@ -194,12 +193,10 @@ class AppiumDriver extends DriverCore {
    *
    * _Note that this behavior currently (May 18 2022) differs from how plugins are handled_ (see {@linkcode AppiumDriver.getCliArgsForPlugin}).
    * @param {string} extName - Driver name
-   * @returns {Record<string,unknown>|undefined} Arguments object. If none, `undefined`
+   * @returns {StringRecord|undefined} Arguments object. If none, `undefined`
    */
   getCliArgsForDriver(extName) {
-    const allCliArgsForExt = /** @type {Record<string,unknown>|undefined} */ (
-      this.args.driver?.[extName]
-    );
+    const allCliArgsForExt = /** @type {StringRecord|undefined} */ (this.args.driver?.[extName]);
 
     if (!_.isEmpty(allCliArgsForExt)) {
       const defaults = getDefaultsForExtension(DRIVER_TYPE, extName);
@@ -214,9 +211,9 @@ class AppiumDriver extends DriverCore {
 
   /**
    * Create a new session
-   * @param {W3CCapabilities} jsonwpCaps JSONWP formatted desired capabilities
-   * @param {W3CCapabilities} reqCaps Required capabilities (JSONWP standard)
-   * @param {W3CCapabilities} w3cCapabilities W3C capabilities
+   * @param {W3CCapabilities<AppiumDriverConstraints>} jsonwpCaps JSONWP formatted desired capabilities
+   * @param {W3CCapabilities<AppiumDriverConstraints>} reqCaps Required capabilities (JSONWP standard)
+   * @param {W3CCapabilities<AppiumDriverConstraints>} w3cCapabilities W3C capabilities
    * @param {DriverData[]} [driverData]
    */
   async createSession(jsonwpCaps, reqCaps, w3cCapabilities, driverData) {
@@ -249,9 +246,11 @@ class AppiumDriver extends DriverCore {
       );
 
       const {desiredCaps, processedJsonwpCapabilities, processedW3CCapabilities} =
-        /** @type {import('./utils').ParsedDriverCaps} */ (parsedCaps);
+        /** @type {import('./utils').ParsedDriverCaps<AppiumDriverConstraints>} */ (parsedCaps);
       protocol = parsedCaps.protocol;
-      const error = /** @type {import('./utils').InvalidCaps} */ (parsedCaps).error;
+      const error = /** @type {import('./utils').InvalidCaps<AppiumDriverConstraints>} */ (
+        parsedCaps
+      ).error;
       // If the parsing of the caps produced an error, throw it in here
       if (error) {
         throw error;
@@ -783,6 +782,11 @@ class AppiumDriver extends DriverCore {
     return dstSession && _.isFunction(dstSession.proxyActive) && dstSession.proxyActive(sessionId);
   }
 
+  /**
+   *
+   * @param {string} sessionId
+   * @returns {import('@appium/types').RouteMatcher[]}
+   */
   getProxyAvoidList(sessionId) {
     const dstSession = this.sessions[sessionId];
     return dstSession ? dstSession.getProxyAvoidList() : [];
@@ -826,7 +830,6 @@ export {AppiumDriver};
  * @typedef {import('@appium/types').ExternalDriver} ExternalDriver
  * @typedef {import('@appium/types').Driver} Driver
  * @typedef {import('@appium/types').DriverClass} DriverClass
- * @typedef {import('@appium/types').W3CCapabilities} W3CCapabilities
  * @typedef {import('@appium/types').DriverData} DriverData
  * @typedef {import('@appium/types').ServerArgs} DriverOpts
  * @typedef {import('@appium/types').Constraints} Constraints
@@ -837,6 +840,7 @@ export {AppiumDriver};
  * @typedef {import('@appium/types').PluginClass} PluginClass
  * @typedef {import('@appium/types').PluginType} PluginType
  * @typedef {import('@appium/types').DriverType} DriverType
+ * @typedef {import('@appium/types').StringRecord} StringRecord
  * @typedef {import('@appium/types').SessionHandler<SessionHandlerResult<any[]>,SessionHandlerResult<void>>} SessionHandler
  */
 
@@ -849,3 +853,13 @@ export {AppiumDriver};
  * @property {Error} [error]
  * @property {string} [protocol]
  */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').W3CCapabilities<C>} W3CCapabilities
+ */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').Capabilities<C>} Capabilities
+ */

package/lib/cli/extension-command.js

@@ -576,13 +576,14 @@ class ExtensionCommand {
     // this is a helper method, 'ext' is assumed to already be installed here, and of the npm
     // install type
     const {version, pkgName} = this.config.installedExtensions[ext];
+    /** @type {string?} */
     let unsafeUpdate = await npm.getLatestVersion(this.config.appiumHome, pkgName);
     let safeUpdate = await npm.getLatestSafeUpgradeVersion(
       this.config.appiumHome,
       pkgName,
       version
     );
-    if (!util.compareVersions(unsafeUpdate, '>', version)) {
+    if (unsafeUpdate !== null && !util.compareVersions(unsafeUpdate, '>', version)) {
       // the latest version is not greater than the current version, so there's no possible update
       unsafeUpdate = null;
       safeUpdate = null;

package/lib/extension/driver-config.js

@@ -133,7 +133,8 @@ export class DriverConfig extends ExtensionConfig {
 
   /**
    * Given capabilities, find a matching driver within the config. Load its class and return it along with version and driver name.
-   * @param {Capabilities} caps
+   * @template {import('@appium/types').StringRecord} C
+   * @param {C} caps
    * @returns {MatchedDriver}
    */
   findMatchingDriver({automationName, platformName}) {

package/lib/extension/manifest.js

@@ -2,6 +2,8 @@
  * Module containing {@link Manifest} which handles reading & writing of extension config files.
  */
 
+import B from 'bluebird';
+import glob from 'glob';
 import {env, fs} from '@appium/support';
 import _ from 'lodash';
 import path from 'path';
@@ -11,23 +13,6 @@ import log from '../logger';
 import {INSTALL_TYPE_NPM} from './extension-config';
 import {packageDidChange} from './package-changed';
 
-/**
- * Default depth to search in directory tree for whatever it is we're looking for.
- *
- * It's 4 because smaller numbers didn't work.
- */
-const DEFAULT_SEARCH_DEPTH = 4;
-
-/**
- * Default options for {@link findExtensions}.
- * @type {Readonly<import('klaw').Options>}
- */
-const DEFAULT_FIND_EXTENSIONS_OPTS = Object.freeze({
-  depthLimit: DEFAULT_SEARCH_DEPTH,
-  /* istanbul ignore next */
-  filter: (filepath) => !path.basename(filepath).startsWith('.'),
-});
-
 /**
  * Current configuration schema revision!
  */
@@ -175,26 +160,58 @@ export class Manifest {
 
   /**
    * Searches `APPIUM_HOME` for installed extensions and adds them to the manifest.
-   * @param {SyncWithInstalledExtensionsOpts} opts
    * @returns {Promise<boolean>} `true` if any extensions were added, `false` otherwise.
    */
-  async syncWithInstalledExtensions({depthLimit = DEFAULT_SEARCH_DEPTH} = {}) {
-    const walkOpts = _.defaults({depthLimit}, DEFAULT_FIND_EXTENSIONS_OPTS);
+  async syncWithInstalledExtensions() {
     // this could be parallelized, but we can't use fs.walk as an async iterator
     let didChange = false;
-    for await (const {stats, path: filepath} of fs.walk(this._appiumHome, walkOpts)) {
-      if (filepath !== this._appiumHome && stats.isDirectory()) {
-        try {
-          const pkg = await env.readPackageInDir(filepath);
-          if (pkg && isExtension(pkg)) {
-            // it's possible that this extension already exists in the manifest,
-            // so only update `didChange` if it's new.
-            const added = this.addExtensionFromPackage(pkg, path.join(filepath, 'package.json'));
-            didChange = didChange || added;
+
+    /**
+     * Listener for the `match` event of a `glob` instance
+     * @param {string} filepath - Path to a `package.json`
+     * @returns {Promise<void>}
+     */
+    const onMatch = async (filepath) => {
+      try {
+        const pkg = JSON.parse(await fs.readFile(filepath, 'utf8'));
+        if (isDriver(pkg) || isPlugin(pkg)) {
+          const changed = this.addExtensionFromPackage(pkg, filepath);
+          didChange = didChange || changed;
+        }
+      } catch {}
+    };
+
+    /**
+     * A list of `Promise`s which read `package.json` files looking for Appium extensions.
+     * @type {Promise<void>[]}
+     */
+    const queue = [
+      // look at `package.json` in `APPIUM_HOME` only
+      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},
+        // eslint-disable-next-line promise/prefer-await-to-callbacks
+        (err) => {
+          if (err) {
+            reject(err);
           }
-        } catch {}
-      }
-    }
+          resolve();
+        }
+      )
+        .on('error', reject)
+        .on('match', (filepath) => {
+          queue.push(onMatch(filepath));
+        });
+    });
+
+    // wait for everything to finish
+    await B.all(queue);
+
     return didChange;
   }
 

package/lib/main.js

@@ -26,7 +26,7 @@ import {loadExtensions, getActivePlugins, getActiveDrivers} from './extension';
 import {DRIVER_TYPE, PLUGIN_TYPE, SERVER_SUBCOMMAND} from './constants';
 import registerNode from './grid-register';
 import {getDefaultsForSchema, validate} from './schema/schema';
-import {inspect} from './utils';
+import {inspect, adjustNodePath} from './utils';
 
 const {resolveAppiumHome} = env;
 
@@ -172,6 +172,8 @@ function areServerCommandArgs(args) {
 async function init(args) {
   const appiumHome = args?.appiumHome ?? (await resolveAppiumHome());
 
+  adjustNodePath();
+
   const {driverConfig, pluginConfig} = await loadExtensions(appiumHome);
 
   const parser = getParser();

package/lib/schema/cli-transformers.js

@@ -1,5 +1,5 @@
 import {ArgumentTypeError} from 'argparse';
-import {readFileSync} from 'fs';
+import {readFileSync, existsSync} from 'fs';
 import _ from 'lodash';
 
 /**
@@ -55,25 +55,30 @@ export const transformers = {
   /**
    * Given a CSV-style string or pathname, parse it into an array.
    * The file can also be split on newlines.
-   * @param {string} value
+   * @param {string} csvOrPath
    * @returns {string[]}
    */
-  csv: (value) => {
-    let body;
+  csv: (csvOrPath) => {
+    let csv = csvOrPath;
+    let loadedFromFile = false;
     // since this value could be a single string (no commas) _or_ a pathname, we will need
     // to attempt to parse it as a file _first_.
-    try {
-      body = readFileSync(value, 'utf8');
-    } catch (err) {
-      if (err.code !== 'ENOENT') {
-        throw new ArgumentTypeError(`Could not read file ${body}: ${err.message}`);
+    if (existsSync(csvOrPath)) {
+      try {
+        csv = readFileSync(csvOrPath, 'utf8');
+      } catch (err) {
+        throw new ArgumentTypeError(`Could not read file '${csvOrPath}': ${err.message}`);
       }
+      loadedFromFile = true;
     }
 
     try {
-      return body ? parseCsvFile(body) : parseCsvLine(value);
+      return loadedFromFile ? parseCsvFile(csv) : parseCsvLine(csv);
     } catch (err) {
-      throw new ArgumentTypeError('Must be a comma-delimited string, e.g., "foo,bar,baz"');
+      const msg = loadedFromFile
+        ? `The provided value of '${csvOrPath}' must be a valid CSV`
+        : `Must be a comma-delimited string, e.g., "foo,bar,baz"`;
+      throw new TypeError(`${msg}. Original error: ${err.message}`);
     }
   },
 
@@ -85,19 +90,18 @@ export const transformers = {
   json: (jsonOrPath) => {
     let json = jsonOrPath;
     let loadedFromFile = false;
-    try {
-      // use synchronous file access, as `argparse` provides no way of either
-      // awaiting or using callbacks. This step happens in startup, in what is
-      // effectively command-line code, so nothing is blocked in terms of
-      // sessions, so holding up the event loop does not incur the usual
-      // drawbacks.
-      json = readFileSync(jsonOrPath, 'utf8');
-      loadedFromFile = true;
-    } catch (err) {
-      // unreadable files don't count... but other problems do.
-      if (err.code !== 'ENOENT') {
-        throw err;
+    if (existsSync(jsonOrPath)) {
+      try {
+        // use synchronous file access, as `argparse` provides no way of either
+        // awaiting or using callbacks. This step happens in startup, in what is
+        // effectively command-line code, so nothing is blocked in terms of
+        // sessions, so holding up the event loop does not incur the usual
+        // drawbacks.
+        json = readFileSync(jsonOrPath, 'utf8');
+      } catch (err) {
+        throw new ArgumentTypeError(`Could not read file '${jsonOrPath}': ${err.message}`);
       }
+      loadedFromFile = true;
     }
     try {
       const result = JSON.parse(json);

package/lib/utils.js

@@ -1,9 +1,12 @@
 import _ from 'lodash';
 import logger from './logger';
-import {processCapabilities, PROTOCOLS} from '@appium/base-driver';
+import {processCapabilities, PROTOCOLS, STANDARD_CAPS} from '@appium/base-driver';
 import {inspect as dump} from 'util';
+import {node} from '@appium/support';
+import path from 'path';
 
 const W3C_APPIUM_PREFIX = 'appium';
+const STANDARD_CAPS_LOWERCASE = new Set([...STANDARD_CAPS].map((cap) => cap.toLowerCase()));
 
 /**
  *
@@ -33,16 +36,18 @@ const inspect = _.flow(
  * Takes the caps that were provided in the request and translates them
  * into caps that can be used by the inner drivers.
  *
- * @param {any} jsonwpCapabilities
- * @param {W3CCapabilities} w3cCapabilities
- * @param {import('@appium/types').Constraints} constraints
- * @param {import('@appium/types').DefaultCapabilitiesConfig} [defaultCapabilities]
- * @returns {ParsedDriverCaps|InvalidCaps}
+ * @template {Constraints} C
+ * @template [J=any]
+ * @param {J} jsonwpCapabilities
+ * @param {W3CCapabilities<C>} w3cCapabilities
+ * @param {C} constraints
+ * @param {NSCapabilities<C>} [defaultCapabilities]
+ * @returns {ParsedDriverCaps<C,J>|InvalidCaps<C,J>}
  */
 function parseCapsForInnerDriver(
   jsonwpCapabilities,
   w3cCapabilities,
-  constraints = {},
+  constraints = /** @type {C} */ ({}),
   defaultCapabilities = {}
 ) {
   // Check if the caller sent JSONWP caps, W3C caps, or both
@@ -50,14 +55,14 @@ function parseCapsForInnerDriver(
     _.isPlainObject(w3cCapabilities) &&
     (_.has(w3cCapabilities, 'alwaysMatch') || _.has(w3cCapabilities, 'firstMatch'));
   const hasJSONWPCaps = _.isPlainObject(jsonwpCapabilities);
-  let desiredCaps = /** @type {ParsedDriverCaps['desiredCaps']} */ ({});
-  /** @type {ParsedDriverCaps['processedW3CCapabilities']} */
+  let desiredCaps = /** @type {ParsedDriverCaps<C>['desiredCaps']} */ ({});
+  /** @type {ParsedDriverCaps<C>['processedW3CCapabilities']} */
   let processedW3CCapabilities;
-  /** @type {ParsedDriverCaps['processedJsonwpCapabilities']} */
+  /** @type {ParsedDriverCaps<C>['processedJsonwpCapabilities']} */
   let processedJsonwpCapabilities;
 
   if (!hasW3CCaps) {
-    return /** @type {InvalidCaps} */ ({
+    return /** @type {InvalidCaps<C>} */ ({
       protocol: PROTOCOLS.W3C,
       error: new Error('W3C capabilities should be provided'),
     });
@@ -76,7 +81,7 @@ function parseCapsForInnerDriver(
       for (const [defaultCapKey, defaultCapValue] of _.toPairs(defaultCapabilities)) {
         let isCapAlreadySet = false;
         // Check if the key is already present in firstMatch entries
-        for (const firstMatchEntry of w3cCapabilities.firstMatch || []) {
+        for (const firstMatchEntry of w3cCapabilities.firstMatch ?? []) {
           if (
             _.isPlainObject(firstMatchEntry) &&
             _.has(removeAppiumPrefixes(firstMatchEntry), removeAppiumPrefix(defaultCapKey))
@@ -100,7 +105,9 @@ function parseCapsForInnerDriver(
 
         // Only add the default capability if it is not overridden
         if (_.isEmpty(w3cCapabilities.firstMatch)) {
-          w3cCapabilities.firstMatch = [{[defaultCapKey]: defaultCapValue}];
+          w3cCapabilities.firstMatch = /** @type {W3CCapabilities<C>['firstMatch']} */ ([
+            {[defaultCapKey]: defaultCapValue},
+          ]);
         } else {
           w3cCapabilities.firstMatch[0][defaultCapKey] = defaultCapValue;
         }
@@ -127,7 +134,7 @@ function parseCapsForInnerDriver(
       desiredCaps = processCapabilities(w3cCapabilities, constraints, true);
     } catch (error) {
       logger.info(`Could not parse W3C capabilities: ${error.message}`);
-      return /** @type {InvalidCaps} */ ({
+      return /** @type {InvalidCaps<C,J>} */ ({
         desiredCaps,
         processedJsonwpCapabilities,
         processedW3CCapabilities,
@@ -143,7 +150,7 @@ function parseCapsForInnerDriver(
     };
   }
 
-  return /** @type {ParsedDriverCaps} */ ({
+  return /** @type {ParsedDriverCaps<C,J>} */ ({
     desiredCaps,
     processedJsonwpCapabilities,
     processedW3CCapabilities,
@@ -153,62 +160,101 @@ function parseCapsForInnerDriver(
 
 /**
  * Takes a capabilities objects and prefixes capabilities with `appium:`
- * @param {Capabilities} caps Desired capabilities object
- * @returns {AppiumW3CCapabilities}
+ * @template {Constraints} [C={}]
+ * @param {Capabilities<C>} caps - Desired capabilities object
+ * @returns {NSCapabilities<C>}
  */
 function insertAppiumPrefixes(caps) {
-  // Standard, non-prefixed capabilities (see https://www.w3.org/TR/webdriver/#dfn-table-of-standard-capabilities)
-  const STANDARD_CAPS = [
-    'browserName',
-    'browserVersion',
-    'platformName',
-    'acceptInsecureCerts',
-    'pageLoadStrategy',
-    'proxy',
-    'setWindowRect',
-    'timeouts',
-    'unhandledPromptBehavior',
-  ];
-
-  let prefixedCaps = {};
-  for (let [name, value] of _.toPairs(caps)) {
-    if (STANDARD_CAPS.includes(name) || name.includes(':')) {
-      prefixedCaps[name] = value;
-    } else {
-      prefixedCaps[`${W3C_APPIUM_PREFIX}:${name}`] = value;
-    }
-  }
-  return prefixedCaps;
+  return /** @type {NSCapabilities<C>} */ (
+    _.mapKeys(caps, (_, key) =>
+      STANDARD_CAPS_LOWERCASE.has(key.toLowerCase()) || key.includes(':')
+        ? key
+        : `${W3C_APPIUM_PREFIX}:${key}`
+    )
+  );
 }
 
 /**
- *
- * @param {AppiumW3CCapabilities} caps
- * @returns {Capabilities}
+ * @template {Constraints} [C={}]
+ * @param {NSCapabilities<C>} caps
+ * @returns {Capabilities<C>}
  */
 function removeAppiumPrefixes(caps) {
-  if (!_.isPlainObject(caps)) {
-    return caps;
-  }
-
-  /** @type {Capabilities} */
-  const fixedCaps = {};
-  for (let [name, value] of _.toPairs(caps)) {
-    fixedCaps[removeAppiumPrefix(name)] = value;
-  }
-  return fixedCaps;
+  return /** @type {Capabilities<C>} */ (_.mapKeys(caps, (_, key) => removeAppiumPrefix(key)));
 }
 
+/**
+ * @param {string} key
+ * @returns {string}
+ */
 function removeAppiumPrefix(key) {
   const prefix = `${W3C_APPIUM_PREFIX}:`;
   return _.startsWith(key, prefix) ? key.substring(prefix.length) : key;
 }
 
+/**
+ *
+ * @param {string} pkgName
+ * @returns {string|undefined}
+ */
 function getPackageVersion(pkgName) {
   const pkgInfo = require(`${pkgName}/package.json`) || {};
   return pkgInfo.version;
 }
 
+/**
+ * Adjusts NODE_PATH environment variable,
+ * so drivers and plugins could load their peer dependencies.
+ * Read https://nodejs.org/api/modules.html#loading-from-the-global-folders
+ * for more details.
+ * @returns {void}
+ */
+function adjustNodePath() {
+  const selfRoot = node.getModuleRootSync('appium', __filename);
+  if (!selfRoot || path.dirname(selfRoot).length >= selfRoot.length) {
+    return;
+  }
+  const nodeModulesRoot = path.dirname(selfRoot);
+
+  const refreshRequirePaths = () => {
+    try {
+      // ! This hack allows us to avoid modification of import
+      // ! 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
+      require('module').Module._initPaths();
+      return true;
+    } catch (e) {
+      return false;
+    }
+  };
+
+  if (!process.env.NODE_PATH) {
+    process.env.NODE_PATH = nodeModulesRoot;
+    if (refreshRequirePaths()) {
+      process.env.APPIUM_OMIT_PEER_DEPS = '1';
+    } else {
+      delete process.env.NODE_PATH;
+    }
+    return;
+  }
+
+  const nodePathParts = process.env.NODE_PATH.split(path.delimiter);
+  if (nodePathParts.includes(nodeModulesRoot)) {
+    process.env.APPIUM_OMIT_PEER_DEPS = '1';
+    return;
+  }
+
+  nodePathParts.push(nodeModulesRoot);
+  process.env.NODE_PATH = nodePathParts.join(path.delimiter);
+  if (refreshRequirePaths()) {
+    process.env.APPIUM_OMIT_PEER_DEPS = '1';
+  } else {
+    process.env.NODE_PATH = _.without(nodePathParts, nodeModulesRoot).join(path.delimiter);
+  }
+}
+
 /**
  * Pulls the initial values of Appium settings from the given capabilities argument.
  * Each setting item must satisfy the following format:
@@ -250,29 +296,64 @@ export {
   getPackageVersion,
   pullSettings,
   removeAppiumPrefixes,
+  adjustNodePath,
 };
 
 /**
- * @todo protocol is more specific
+ * @typedef {import('@appium/types').StringRecord} StringRecord
+ * @typedef {import('@appium/types').BaseDriverCapConstraints} BaseDriverCapConstraints
+ */
+
+/**
+ * @template {Constraints} [C=BaseDriverCapConstraints]
+ * @template [J=any]
  * @typedef ParsedDriverCaps
- * @property {Capabilities} desiredCaps
+ * @property {Capabilities<C>} desiredCaps
  * @property {string} protocol
- * @property {any} [processedJsonwpCapabilities]
- * @property {W3CCapabilities} [processedW3CCapabilities]
+ * @property {J} [processedJsonwpCapabilities]
+ * @property {W3CCapabilities<C>} [processedW3CCapabilities]
  */
 
 /**
  * @todo protocol is more specific
+ * @template {Constraints} [C=BaseDriverCapConstraints]
+ * @template [J=any]
  * @typedef InvalidCaps
  * @property {Error} error
  * @property {string} protocol
- * @property {Capabilities} [desiredCaps]
- * @property {any} [processedJsonwpCapabilities]
- * @property {W3CCapabilities} [processedW3CCapabilities]
+ * @property {Capabilities<C>} [desiredCaps]
+ * @property {J} [processedJsonwpCapabilities]
+ * @property {W3CCapabilities<C>} [processedW3CCapabilities]
+ */
+
+/**
+ * @template {Constraints} [C=BaseDriverCapConstraints]
+ * @template {StringRecord|void} [Extra=void]
+ * @typedef {import('@appium/types').Capabilities<C, Extra>} Capabilities
+ */
+
+/**
+ * @template {Constraints} [C=BaseDriverCapConstraints]
+ * @template {StringRecord|void} [Extra=void]
+ * @typedef {import('@appium/types').W3CCapabilities<C, Extra>} 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').ConstraintsToCaps<C>} ConstraintsToCaps
+ */
+
+/**
+ * @template T
+ * @typedef {import('type-fest').StringKeyOf<T>} StringKeyOf
  */
 
 /**
- * @typedef {import('@appium/types').W3CCapabilities} W3CCapabilities
- * @typedef {import('@appium/types').Capabilities} Capabilities
- * @typedef {import('@appium/types').AppiumW3CCapabilities} AppiumW3CCapabilities
+ * @typedef {import('@appium/types').Constraints} Constraints
  */