@appium/base-driver 8.7.2 → 9.0.0

package/lib/basedriver/commands/execute.js

@@ -2,8 +2,9 @@ import _ from 'lodash';
 import {errors, makeArgs, checkParams} from '../../protocol';
 
 /**
- * @param {SessionBase} Base
- * @returns {ExecuteBase}
+ * @template {Constraints} C
+ * @param {import('./session').SessionBase<C>} Base
+ * @returns {ExecuteBase<C>}
  */
 export function ExecuteMixin(Base) {
   /**
@@ -33,9 +34,9 @@ export function ExecuteMixin(Base) {
       }
 
       const Driver = /** @type {DriverClass} */ (this.constructor);
-      const availableScripts = _.keys(Driver.executeMethodMap);
-      const commandMetadata = Driver.executeMethodMap[script];
-      if (!commandMetadata) {
+      const commandMetadata = {...Driver.executeMethodMap?.[script]};
+      if (!commandMetadata.command) {
+        const availableScripts = _.keys(Driver.executeMethodMap);
         throw new errors.UnsupportedOperationError(
           `Unsupported execute method '${script}'. Available methods ` +
             `are: ${availableScripts.join(', ')}`
@@ -50,16 +51,20 @@ export function ExecuteMixin(Base) {
         checkParams(commandMetadata.params, args, null);
       }
       argsToApply = makeArgs({}, args, commandMetadata.params, null);
-      return await this[Driver.executeMethodMap[script].command](...argsToApply);
+      return await this[commandMetadata.command](...argsToApply);
     }
   }
   return ExecuteCommands;
 }
 
 /**
- * @typedef {import('@appium/types').ExecuteCommands} IExecuteCommands
+ * @typedef {import('@appium/types').IExecuteCommands} IExecuteCommands
  * @typedef {import('@appium/types').Driver} Driver
  * @typedef {import('@appium/types').DriverClass} DriverClass
- * @typedef {import('./session').SessionBase} SessionBase
- * @typedef {import('../driver').BaseDriverBase<import('@appium/types').TimeoutCommands & import('@appium/types').EventCommands & import('@appium/types').FindCommands & import('@appium/types').LogCommands & import('@appium/types').SettingsCommands & import('@appium/types').SessionCommands & IExecuteCommands>} ExecuteBase
+ * @typedef {import('@appium/types').Constraints} Constraints
+ */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('../driver').BaseDriverBase<C, import('@appium/types').ITimeoutCommands & import('@appium/types').IEventCommands & import('@appium/types').IFindCommands & import('@appium/types').ILogCommands<C> & import('@appium/types').ISettingsCommands & import('@appium/types').ISessionCommands & IExecuteCommands>} ExecuteBase
  */

package/lib/basedriver/commands/find.js

@@ -4,9 +4,9 @@
 import {errors} from '../../protocol';
 
 /**
- *
- * @param {EventBase} Base
- * @returns {FindBase}
+ * @template {Constraints} C
+ * @param {import('./event').EventBase<C>} Base
+ * @returns {FindBase<C>}
  */
 export function FindMixin(Base) {
   /**
@@ -44,16 +44,16 @@ export function FindMixin(Base) {
     async findElementsFromElement(strategy, selector, elementId) {
       return await this.findElOrElsWithProcessing(strategy, selector, true, elementId);
     }
-    // Override the following function for your own driver, and the rest is taken
-    // care of!
-    // Returns an object which adheres to the way the JSON Wire Protocol represents elements:
-    // { ELEMENT: # }    eg: { ELEMENT: 3 }  or { ELEMENT: 1.023 }
     /**
+     * Returns an object which adheres to the way the JSON Wire Protocol represents elements:
+     *
+     * Override this for your own driver!
      * @template {boolean} Mult
+     * @template [Ctx=any]
      * @param {string} strategy
      * @param {string} selector
      * @param {Mult} mult
-     * @param {string} [context]
+     * @param {Ctx} [context]
      * @returns {Promise<Mult extends true ? Element[] : Element>}
      */
     async findElOrEls(strategy, selector, mult, context) {
@@ -68,10 +68,11 @@ export function FindMixin(Base) {
     }
     /**
      * @template {boolean} Mult
+     * @template [Ctx=any]
      * @param {string} strategy
      * @param {string} selector
      * @param {Mult} mult
-     * @param {string} [context]
+     * @param {Ctx} [context]
      * @returns {Promise<Mult extends true ? Element[] : Element>}
      */
     async findElOrElsWithProcessing(strategy, selector, mult, context) {
@@ -96,7 +97,12 @@ export function FindMixin(Base) {
 
 /**
  * @typedef {import('@appium/types').Element} Element
- * @typedef {import('@appium/types').FindCommands} IFindCommands
- * @typedef {import('./event').EventBase} EventBase
- * @typedef {import('../driver').BaseDriverBase<import('@appium/types').TimeoutCommands & import('@appium/types').EventCommands & IFindCommands>} FindBase
+ * @typedef {import('@appium/types').Constraints} Constraints
+ * @typedef {import('@appium/types').IFindCommands} IFindCommands
+ * @typedef {import('@appium/types').ITimeoutCommands} ITimeoutCommands
+ * @typedef {import('@appium/types').IEventCommands} IEventCommands
+ */
+/**
+ * @template {Constraints} C
+ * @typedef {import('../driver').BaseDriverBase<C, ITimeoutCommands & IEventCommands & IFindCommands>} FindBase
  */

package/lib/basedriver/commands/index.js

@@ -1,5 +1,5 @@
 // @ts-check
-
+import _ from 'lodash';
 import {EventMixin} from './event';
 import {FindMixin} from './find';
 import {LogMixin} from './log';
@@ -9,22 +9,27 @@ import {TimeoutMixin} from './timeout';
 import {ExecuteMixin} from './execute';
 
 /**
- * Applies all the mixins to the `BaseDriverBase` class.
- * Returns a `BaseDriver` class.
- * @param {BaseDriverBase} Base
+ * Applies all the mixins to the `BaseDriverBase` class; returns a `BaseDriver` class definition.
+ * Each mixin is applied in the order it is listed here, and each type is a union with the previous.
+ *
+ * @template {Constraints} C
+ * @param {BaseDriverBase<C>} Base
+ */
+export const createBaseDriverClass = _.flow(
+  TimeoutMixin,
+  EventMixin,
+  FindMixin,
+  LogMixin,
+  SettingsMixin,
+  SessionMixin,
+  ExecuteMixin
+);
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('../driver').BaseDriverBase<C>} BaseDriverBase
  */
-export function createBaseDriverClass(Base) {
-  const WithTimeoutCommands = TimeoutMixin(Base);
-  const WithEventCommands = EventMixin(WithTimeoutCommands);
-  const WithFindCommands = FindMixin(WithEventCommands);
-  const WithLogCommands = LogMixin(WithFindCommands);
-  const WithSettingsCommands = SettingsMixin(WithLogCommands);
-  const WithSessionCommands = SessionMixin(WithSettingsCommands);
-  const WithExecuteCommands = ExecuteMixin(WithSessionCommands);
-  return WithExecuteCommands;
-}
 
 /**
- * @template [T={}]
- * @typedef {import('../driver').BaseDriverBase<T>} BaseDriverBase
+ * @typedef {import('@appium/types').Constraints} Constraints
  */

package/lib/basedriver/commands/log.js

@@ -4,37 +4,40 @@
 import _ from 'lodash';
 
 /**
- *
- * @param {FindBase} Base
- * @returns {LogBase}
+ * @template {Constraints} C
+ * @param {import('./find').FindBase<C>} Base
+ * @returns {LogBase<C>}
  */
 export function LogMixin(Base) {
   /**
-   * @implements {ILogCommands}
+   * @implements {ILogCommands<C>}
    */
   class LogCommands extends Base {
+    /** @type {Readonly<import('@appium/types').LogDefRecord<C>>} */
+    supportedLogTypes;
+
     constructor(...args) {
       super(...args);
-      /** @type {Record<string, LogType<Driver>>} */
-      this.supportedLogTypes = this.supportedLogTypes ?? {};
+      this.supportedLogTypes ??= {};
     }
 
     async getLogTypes() {
       this.log.debug('Retrieving supported log types');
-      return _.keys(this.supportedLogTypes);
+      return Object.keys(this.supportedLogTypes);
     }
 
     /**
-     * @this {Driver}
-     * @param {string} logType
+     * @this {import('@appium/types').Driver<C>}
+     * @param {keyof typeof this.supportedLogTypes} logType
+     * @returns {Promise<import('type-fest').AsyncReturnType<typeof this.supportedLogTypes[keyof typeof this.supportedLogTypes]['getter']>>}
      */
     async getLog(logType) {
-      this.log.debug(`Retrieving '${logType}' logs`);
+      this.log.debug(`Retrieving '${String(logType)}' logs`);
 
-      if (!(await this.getLogTypes()).includes(logType)) {
+      if (!(logType in this.supportedLogTypes)) {
         const logsTypesWithDescriptions = _.mapValues(this.supportedLogTypes, 'description');
         throw new Error(
-          `Unsupported log type '${logType}'. ` +
+          `Unsupported log type '${String(logType)}'. ` +
             `Supported types: ${JSON.stringify(logsTypesWithDescriptions)}`
         );
       }
@@ -46,13 +49,16 @@ export function LogMixin(Base) {
 }
 
 /**
- * @typedef {import('@appium/types').LogCommands} ILogCommands
- * @typedef {import('@appium/types').Driver} Driver
- * @typedef {import('./find').FindBase} FindBase
- * @typedef {import('../driver').BaseDriverBase<import('@appium/types').TimeoutCommands & import('@appium/types').EventCommands & import('@appium/types').FindCommands & ILogCommands>} LogBase
+ * @typedef {import('@appium/types').Constraints} Constraints
+ * @typedef {import('@appium/types').StringRecord} StringRecord
+ */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').ILogCommands<C>} ILogCommands
  */
 
 /**
- * @template T
- * @typedef {import('@appium/types').LogType<T>} LogType
+ * @template {Constraints} C
+ * @typedef {import('../driver').BaseDriverBase<C, import('@appium/types').ITimeoutCommands & import('@appium/types').IEventCommands & import('@appium/types').IFindCommands & ILogCommands<C>>} LogBase
  */

package/lib/basedriver/commands/session.js

@@ -4,8 +4,9 @@
 import _ from 'lodash';
 
 /**
- * @param {SettingsBase} Base
- * @returns {SessionBase}
+ * @template {Constraints} C
+ * @param {import('./settings').SettingsBase<C>} Base
+ * @returns {SessionBase<C>}
  */
 export function SessionMixin(Base) {
   /**
@@ -43,9 +44,13 @@ export function SessionMixin(Base) {
 }
 
 /**
- * @typedef {import('@appium/types').SessionCommands} ISessionCommands
+ * @typedef {import('@appium/types').ISessionCommands} ISessionCommands
  * @typedef {import('@appium/types').SingularSessionData} SingularSessionData
  * @typedef {import('@appium/types').MultiSessionData} MultiSessionData
- * @typedef {import('./settings').SettingsBase} SettingsBase
- * @typedef {import('../driver').BaseDriverBase<import('@appium/types').TimeoutCommands & import('@appium/types').EventCommands & import('@appium/types').FindCommands & import('@appium/types').LogCommands & import('@appium/types').SettingsCommands & ISessionCommands>} SessionBase
+ * @typedef {import('@appium/types').Constraints} Constraints
+ */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('../driver').BaseDriverBase<C, import('@appium/types').ITimeoutCommands & import('@appium/types').IEventCommands & import('@appium/types').IFindCommands & import('@appium/types').ILogCommands<C> & import('@appium/types').ISettingsCommands & ISessionCommands>} SessionBase
  */

package/lib/basedriver/commands/settings.js

@@ -1,9 +1,9 @@
 // @ts-check
 
 /**
- *
- * @param {ReturnType<import('./log').LogMixin>} Base
- * @returns {SettingsBase}
+ * @template {Constraints} C
+ * @param {import('./log').LogBase<C>} Base
+ * @returns {SettingsBase<C>}
  */
 export function SettingsMixin(Base) {
   /**
@@ -29,7 +29,10 @@ export function SettingsMixin(Base) {
 }
 
 /**
- * @typedef {import('@appium/types').SettingsCommands} ISettingsCommands
- * @typedef {import('./log').LogBase} LogBase
- * @typedef {import('../driver').BaseDriverBase<import('@appium/types').TimeoutCommands & import('@appium/types').EventCommands & import('@appium/types').FindCommands & import('@appium/types').LogCommands & ISettingsCommands>} SettingsBase
+ * @typedef {import('@appium/types').Constraints} Constraints
+ * @typedef {import('@appium/types').ISettingsCommands} ISettingsCommands
+ */
+/**
+ * @template {Constraints} C
+ * @typedef {import('../driver').BaseDriverBase<C, import('@appium/types').ITimeoutCommands & import('@appium/types').IEventCommands & import('@appium/types').IFindCommands & import('@appium/types').ILogCommands<C> & ISettingsCommands>} SettingsBase
  */

package/lib/basedriver/commands/timeout.js

@@ -10,8 +10,9 @@ import {errors} from '../../protocol';
 const MIN_TIMEOUT = 0;
 
 /**
- * @param {import('../driver').BaseDriverBase} Base
- * @returns {TimeoutBase}
+ * @template {Constraints} C
+ * @param {import('../driver').BaseDriverBase<C>} Base
+ * @returns {TimeoutBase<C>}
  */
 export function TimeoutMixin(Base) {
   /**
@@ -157,6 +158,11 @@ export function TimeoutMixin(Base) {
 }
 
 /**
- * @typedef {import('@appium/types').TimeoutCommands} ITimeoutCommands
- * @typedef {import('../driver').BaseDriverBase<ITimeoutCommands>} TimeoutBase
+ * @typedef {import('@appium/types').ITimeoutCommands} ITimeoutCommands
+ * @typedef {import('@appium/types').Constraints} Constraints
+ */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('../driver').BaseDriverBase<C, ITimeoutCommands>} TimeoutBase
  */

package/lib/basedriver/core.js

@@ -29,7 +29,7 @@ class DriverCore {
    */
   static baseVersion = BASEDRIVER_VER;
 
-  /** @type {ExecuteMethodMap} */
+  /** @type {import('@appium/types').ExecuteMethodMap<DriverCore>} */
   static executeMethodMap = {};
 
   /**
@@ -171,7 +171,7 @@ class DriverCore {
   }
 
   /**
-   * This property controls the way {#executeCommand} method
+   * This property controls the way the `executeCommand` method
    * handles new driver commands received from the client.
    * Override it for inherited classes only in special cases.
    *
@@ -420,7 +420,6 @@ export {DriverCore};
 /**
  * @typedef {import('@appium/types').Driver} Driver
  * @typedef {import('@appium/types').Constraints} Constraints
- * @typedef {import('@appium/types').ExecuteMethodMap} ExecuteMethodMap
  * @typedef {import('@appium/types').ServerArgs} ServerArgs
  * @typedef {import('@appium/types').EventHistory} EventHistory
  * @typedef {import('@appium/types').AppiumLogger} AppiumLogger

package/lib/basedriver/driver.js

@@ -3,7 +3,6 @@
 
 import {
   validateCaps,
-  APPIUM_OPTS_CAP,
   PREFIXED_APPIUM_OPTS_CAP,
   processCapabilities,
   promoteAppiumOptions,
@@ -27,12 +26,12 @@ const ON_UNEXPECTED_SHUTDOWN_EVENT = 'onUnexpectedShutdown';
 /**
  * @implements {SessionHandler<C>}
  * @template {Constraints} C
- * @template {StringRecord} [A=StringRecord]
+ * @template {StringRecord} [CArgs=StringRecord]
  * @extends {DriverCore<C>}
  */
 export class BaseDriverCore extends DriverCore {
   /**
-   * @type {A & ServerArgs}
+   * @type {CArgs & ServerArgs}
    */
   cliArgs;
 
@@ -56,6 +55,25 @@ export class BaseDriverCore extends DriverCore {
    */
   opts;
 
+  /**
+   *
+   * @param {DriverOpts<C>} opts
+   * @param {boolean} shouldValidateCaps
+   */
+  constructor(opts = /** @type {DriverOpts<C>} */ ({}), shouldValidateCaps = true) {
+    super(opts, shouldValidateCaps);
+
+    /**
+     * This must be assigned here because the declaration of {@linkcode BaseDriverCore.opts} above
+     * blows away {@linkcode DriverCore.opts}.
+     */
+    this.opts = opts;
+
+    this.caps = {};
+
+    this.cliArgs = /** @type {CArgs & ServerArgs} */ ({});
+  }
+
   /**
    * Contains the base constraints plus whatever the subclass wants to add.
    *
@@ -69,8 +87,6 @@ export class BaseDriverCore extends DriverCore {
     return Object.freeze(_.merge({}, BASE_DESIRED_CAP_CONSTRAINTS, this.desiredCapConstraints));
   }
 
-  static BASE_DESIRED_CAP_CONSTRAINTS = BASE_DESIRED_CAP_CONSTRAINTS;
-
   // This is the main command handler for the driver. It wraps command
   // execution with timeout logic, checking that we have a valid session,
   // and ensuring that we execute commands one at a time. This method is called
@@ -282,16 +298,10 @@ export class BaseDriverCore extends DriverCore {
     let caps;
     try {
       caps = processCapabilities(
-        originalCaps,
+        promoteAppiumOptions(originalCaps),
         this._desiredCapConstraints,
         this.shouldValidateCaps
       );
-      if (caps[APPIUM_OPTS_CAP]) {
-        this.log.debug(
-          `Found ${PREFIXED_APPIUM_OPTS_CAP} capability present; will promote items inside to caps`
-        );
-        caps = promoteAppiumOptions(caps);
-      }
       caps = fixCaps(caps, this._desiredCapConstraints, this.log);
     } catch (e) {
       throw new errors.SessionNotCreatedError(e.message);
@@ -361,7 +371,7 @@ export class BaseDriverCore extends DriverCore {
 
   /**
    *
-   * @param {Capabilities} caps
+   * @param {Capabilities<C>} caps
    */
   logExtraCaps(caps) {
     let extraCaps = _.difference(_.keys(caps), _.keys(this._desiredCapConstraints));
@@ -412,7 +422,6 @@ export default BaseDriver;
 
 /**
  * @typedef {import('@appium/types').HTTPMethod} HTTPMethod
- * @typedef {import('@appium/types').ExternalDriver} ExternalDriver
  * @typedef {import('@appium/types').DriverData} DriverData
  * @typedef {import('@appium/types').Constraints} Constraints
  * @typedef {import('@appium/types').Constraint} Constraint
@@ -430,9 +439,10 @@ export default BaseDriver;
 
 /**
  * This is used to extend {@linkcode BaseDriverCore} by the mixins and also external drivers.
+ * @template {Constraints} C
  * @template [Proto={}]
  * @template [Static={}]
- * @typedef {import('@appium/types').Class<BaseDriverCore & Proto,import('@appium/types').DriverStatic & Static>} BaseDriverBase
+ * @typedef {import('@appium/types').Class<BaseDriverCore<C> & Proto,import('@appium/types').DriverStatic & Static>} BaseDriverBase
  */
 
 /**
@@ -453,13 +463,14 @@ export default BaseDriver;
  */
 
 /**
- * @template {Constraints} C
- * @typedef {import('@appium/types').ConstraintsToCaps<C>} ConstraintsToCaps
+ * @template {Constraints} [C=BaseDriverCapConstraints]
+ * @template {StringRecord} [CArgs=StringRecord]
+ * @typedef {import('@appium/types').Driver<C, CArgs>} Driver
  */
 
 /**
  * @template {Constraints} C
- * @typedef {import('@appium/types').Driver<C>} Driver
+ * @typedef {import('@appium/types').ExternalDriver<C>} ExternalDriver
  */
 
 /**

package/lib/express/server.js

@@ -40,7 +40,7 @@ async function server(opts) {
     routeConfiguringFunction,
     port,
     hostname,
-    cliArgs,
+    cliArgs = {},
     allowCors = true,
     basePath = DEFAULT_BASE_PATH,
     extraMethodMap = {},
@@ -277,7 +277,10 @@ export {server, configureServer, normalizeBasePath};
 /**
  * @typedef {import('@appium/types').AppiumServer} AppiumServer
  * @typedef {import('@appium/types').AppiumServerSocket} AppiumServerSocket
- * @typedef {import('@appium/types').MethodMap} MethodMap
+ */
+
+/**
+ * @typedef {import('@appium/types').MethodMap<import('@appium/types').ExternalDriver>} MethodMap
  */
 
 /**
@@ -293,7 +296,7 @@ export {server, configureServer, normalizeBasePath};
  * @typedef ServerOpts
  * @property {RouteConfiguringFunction} routeConfiguringFunction
  * @property {number} port
- * @property {import('@appium/types').ServerArgs} cliArgs
+ * @property {import('@appium/types').ServerArgs} [cliArgs]
  * @property {string} [hostname]
  * @property {boolean} [allowCors]
  * @property {string} [basePath]