@appium/base-driver 8.7.1 → 8.7.3

package/lib/basedriver/driver.js

@@ -16,7 +16,7 @@ import {fixCaps, isW3cCaps} from '../helpers/capabilities';
 import {DELETE_SESSION_COMMAND, determineProtocol, errors} from '../protocol';
 import {createBaseDriverClass} from './commands';
 import helpers from './helpers';
-import {desiredCapabilityConstraints} from './desired-caps';
+import {BASE_DESIRED_CAP_CONSTRAINTS} from '@appium/types';
 
 const EVENT_SESSION_INIT = 'newSessionRequested';
 const EVENT_SESSION_START = 'newSessionStarted';
@@ -25,14 +25,67 @@ const EVENT_SESSION_QUIT_DONE = 'quitSessionFinished';
 const ON_UNEXPECTED_SHUTDOWN_EVENT = 'onUnexpectedShutdown';
 
 /**
- * @implements {SessionHandler}
+ * @implements {SessionHandler<C>}
+ * @template {Constraints} C
+ * @template {StringRecord} [CArgs=StringRecord]
+ * @extends {DriverCore<C>}
  */
 export class BaseDriverCore extends DriverCore {
-  _constraints = _.cloneDeep(desiredCapabilityConstraints);
-
-  /** @type {Record<string,any>|undefined} */
+  /**
+   * @type {CArgs & ServerArgs}
+   */
   cliArgs;
 
+  /**
+   * @type {Capabilities<C>}
+   */
+  caps;
+
+  /**
+   * @type {W3CCapabilities<C>}
+   */
+  originalCaps;
+
+  /**
+   * @type {C}
+   */
+  desiredCapConstraints;
+
+  /**
+   * @type {DriverOpts<C> & DriverOpts<BaseDriverCapConstraints>}
+   */
+  opts;
+
+  static BASE_DESIRED_CAP_CONSTRAINTS = BASE_DESIRED_CAP_CONSTRAINTS;
+
+  /**
+   *
+   * @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;
+  }
+
+  /**
+   * Contains the base constraints plus whatever the subclass wants to add.
+   *
+   * Subclasses _shouldn't_ need to use this. If you need to use this, please create
+   * an issue:
+   * @see https://github.com/appium/appium/issues/new
+   * @type {Readonly<BaseDriverCapConstraints & C>}
+   * @protected
+   */
+  get _desiredCapConstraints() {
+    return Object.freeze(_.merge({}, BASE_DESIRED_CAP_CONSTRAINTS, this.desiredCapConstraints));
+  }
+
   // 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
@@ -114,7 +167,7 @@ export class BaseDriverCore extends DriverCore {
 
   /**
    *
-   * @param {Error} err
+   * @param {Error|import('../protocol/errors').NoSuchDriverError} err
    */
   async startUnexpectedShutdown(
     err = new errors.NoSuchDriverError('The driver was unexpectedly shut down!')
@@ -208,11 +261,11 @@ export class BaseDriverCore extends DriverCore {
    * Appium 2 has dropped the support of these, so now we only accept capability
    * objects in W3C format and thus allow any of the three arguments to represent
    * the latter.
-   * @param {W3CCapabilities} w3cCapabilities1
-   * @param {W3CCapabilities} [w3cCapabilities2]
-   * @param {W3CCapabilities} [w3cCapabilities]
+   * @param {W3CCapabilities<C>} w3cCapabilities1
+   * @param {W3CCapabilities<C>} [w3cCapabilities2]
+   * @param {W3CCapabilities<C>} [w3cCapabilities]
    * @param {DriverData[]} [driverData]
-   * @returns {Promise<[string,object]>}
+   * @returns {Promise<[string,Capabilities<C>]>}
    */
   async createSession(w3cCapabilities1, w3cCapabilities2, w3cCapabilities, driverData) {
     if (this.sessionId !== null) {
@@ -235,21 +288,26 @@ export class BaseDriverCore extends DriverCore {
 
     this.setProtocolW3C();
 
-    this.originalCaps = _.cloneDeep(originalCaps);
+    this.originalCaps = originalCaps;
     this.log.debug(
       `Creating session with W3C capabilities: ${JSON.stringify(originalCaps, null, 2)}`
     );
 
+    /** @type {Capabilities<C>} */
     let caps;
     try {
-      caps = processCapabilities(originalCaps, this.desiredCapConstraints, this.shouldValidateCaps);
+      caps = processCapabilities(
+        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);
+      caps = fixCaps(caps, this._desiredCapConstraints, this.log);
     } catch (e) {
       throw new errors.SessionNotCreatedError(e.message);
     }
@@ -258,10 +316,8 @@ export class BaseDriverCore extends DriverCore {
 
     this.sessionId = util.uuidV4();
     this.caps = caps;
-    this.opts = _.cloneDeep(this.initialOpts);
-
     // merge caps onto opts so we don't need to worry about what's where
-    Object.assign(this.opts, this.caps);
+    this.opts = {..._.cloneDeep(this.initialOpts), ...this.caps};
 
     // deal with resets
     // some people like to do weird things by setting noReset and fullReset
@@ -288,7 +344,7 @@ export class BaseDriverCore extends DriverCore {
     }
 
     if (!_.isUndefined(this.caps.newCommandTimeout)) {
-      this.newCommandTimeoutMs = this.caps.newCommandTimeout * 1000;
+      this.newCommandTimeoutMs = /** @type {number} */ (this.caps.newCommandTimeout) * 1000;
     }
 
     this._log.prefix = helpers.generateDriverLogPrefix(this, this.sessionId);
@@ -323,7 +379,7 @@ export class BaseDriverCore extends DriverCore {
    * @param {Capabilities} caps
    */
   logExtraCaps(caps) {
-    let extraCaps = _.difference(_.keys(caps), _.keys(this._constraints));
+    let extraCaps = _.difference(_.keys(caps), _.keys(this._desiredCapConstraints));
     if (extraCaps.length) {
       this.log.warn(
         `The following capabilities were provided, but are not ` + `recognized by Appium:`
@@ -336,7 +392,7 @@ export class BaseDriverCore extends DriverCore {
 
   /**
    *
-   * @param {Capabilities} caps
+   * @param {Capabilities<C>} caps
    * @returns {boolean}
    */
   validateDesiredCaps(caps) {
@@ -345,7 +401,7 @@ export class BaseDriverCore extends DriverCore {
     }
 
     try {
-      validateCaps(caps, this._constraints);
+      validateCaps(caps, this._desiredCapConstraints);
     } catch (e) {
       this.log.errorAndThrow(
         new errors.SessionNotCreatedError(
@@ -359,47 +415,25 @@ export class BaseDriverCore extends DriverCore {
 
     return true;
   }
-
-  // we only want subclasses to ever extend the contraints
-  set desiredCapConstraints(constraints) {
-    this._constraints = Object.assign(this._constraints, constraints);
-    // 'presence' means different things in different versions of the validator,
-    // when we say 'true' we mean that it should not be able to be empty
-    for (const [, value] of _.toPairs(this._constraints)) {
-      if (value && value.presence === true) {
-        value.presence = {
-          allowEmpty: false,
-        };
-      }
-    }
-  }
-
-  get desiredCapConstraints() {
-    return this._constraints;
-  }
 }
 
 /**
  * This ensures that all of the mixins correctly implement the interface described in {@linkcode Driver}.
- * @implements {Driver}
- */
-class _BaseDriver extends createBaseDriverClass(BaseDriverCore) {}
-
-/**
- * @type {import('@appium/types').DriverClass<Driver>}
+ * @template {Constraints} [C={}]
+ * @implements {Driver<C>}
  */
-const BaseDriver = _BaseDriver;
-
-export {BaseDriver};
+export class BaseDriver extends createBaseDriverClass(BaseDriverCore) {}
 export default BaseDriver;
 
 /**
  * @typedef {import('@appium/types').HTTPMethod} HTTPMethod
- * @typedef {import('@appium/types').Driver} Driver
  * @typedef {import('@appium/types').ExternalDriver} ExternalDriver
- * @typedef {import('@appium/types').Capabilities} Capabilities
- * @typedef {import('@appium/types').W3CCapabilities} W3CCapabilities
  * @typedef {import('@appium/types').DriverData} DriverData
+ * @typedef {import('@appium/types').Constraints} Constraints
+ * @typedef {import('@appium/types').Constraint} Constraint
+ * @typedef {import('@appium/types').StringRecord} StringRecord
+ * @typedef {import('@appium/types').BaseDriverCapConstraints} BaseDriverCapConstraints
+ * @typedef {import('@appium/types').ServerArgs} ServerArgs
  */
 
 /**
@@ -417,5 +451,33 @@ export default BaseDriver;
  */
 
 /**
- * @typedef {import('@appium/types').SessionHandler<[string, object],void>} SessionHandler
+ * @template {Constraints} [C=BaseDriverCapConstraints]
+ * @typedef {import('@appium/types').SessionHandler<[string, object],void, C>} SessionHandler
+ */
+
+/**
+ * @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
+ * @typedef {import('@appium/types').ConstraintsToCaps<C>} ConstraintsToCaps
+ */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').Driver<C>} Driver
+ */
+
+/**
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').DriverOpts<C>} DriverOpts
  */

package/lib/helpers/capabilities.js

@@ -26,19 +26,20 @@ function isW3cCaps(caps) {
 
 /**
  *
- * @param {Capabilities} originalCaps
- * @param {Constraints} desiredCapConstraints
+ * @template {Constraints} C
+ * @param {any} oldCaps
+ * @param {C} desiredCapConstraints
  * @param {AppiumLogger} log
- * @returns {Capabilities}
+ * @returns {Capabilities<C>}
  */
-function fixCaps(originalCaps, desiredCapConstraints, log) {
-  let caps = _.clone(originalCaps);
+function fixCaps(oldCaps, desiredCapConstraints, log) {
+  let caps = _.clone(oldCaps);
 
   // boolean capabilities can be passed in as strings 'false' and 'true'
   // which we want to translate into boolean values
   let booleanCaps = _.keys(_.pickBy(desiredCapConstraints, (k) => k.isBoolean === true));
   for (let cap of booleanCaps) {
-    let value = originalCaps[cap];
+    let value = oldCaps[cap];
     if (_.isString(value)) {
       value = value.toLowerCase();
       if (value === 'true' || value === 'false') {
@@ -51,9 +52,11 @@ function fixCaps(originalCaps, desiredCapConstraints, log) {
   }
 
   // int capabilities are often sent in as strings by frameworks
-  let intCaps = _.keys(_.pickBy(desiredCapConstraints, (k) => k.isNumber === true));
+  let intCaps = /** @type {import('type-fest').StringKeyOf<typeof caps>[]} */ (
+    _.keys(_.pickBy(desiredCapConstraints, (k) => k.isNumber === true))
+  );
   for (let cap of intCaps) {
-    let value = originalCaps[cap];
+    let value = oldCaps[cap];
     if (_.isString(value)) {
       value = value.trim();
       let newValue = parseInt(value, 10);
@@ -73,7 +76,14 @@ function fixCaps(originalCaps, desiredCapConstraints, log) {
 export {isW3cCaps, fixCaps};
 
 /**
- * @typedef {import('@appium/types').Capabilities} Capabilities
  * @typedef {import('@appium/types').Constraints} Constraints
  * @typedef {import('@appium/types').AppiumLogger} AppiumLogger
+ * @typedef {import('@appium/types').StringRecord} StringRecord
+ * @typedef {import('@appium/types').BaseDriverCapConstraints} BaseDriverCapConstraints
+ */
+
+/**
+ * @template {Constraints} [C=BaseDriverCapConstraints]
+ * @template {StringRecord|void} [Extra=void]
+ * @typedef {import('@appium/types').Capabilities<C, Extra>} Capabilities
  */

package/lib/index.js

@@ -30,6 +30,7 @@ export {getSummaryByCode, codes as statusCodes} from './jsonwp-status/status';
 // W3C capabilities parser
 export {
   PREFIXED_APPIUM_OPTS_CAP,
+  STANDARD_CAPS,
   processCapabilities,
   isStandardCap,
   validateCaps,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/base-driver",
-  "version": "8.7.1",
+  "version": "8.7.3",
   "description": "Base driver class for Appium drivers",
   "keywords": [
     "automation",
@@ -45,21 +45,20 @@
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/support": "^2.60.0",
-    "@babel/runtime": "7.19.0",
+    "@appium/support": "^2.61.1",
     "@colors/colors": "1.5.0",
-    "@types/async-lock": "1.1.5",
-    "@types/bluebird": "3.5.36",
-    "@types/express": "4.17.13",
+    "@types/async-lock": "1.3.0",
+    "@types/bluebird": "3.5.37",
+    "@types/express": "4.17.14",
     "@types/method-override": "0.0.32",
     "@types/serve-favicon": "2.5.3",
     "async-lock": "1.3.2",
     "asyncbox": "2.9.2",
     "axios": "0.27.2",
     "bluebird": "3.7.2",
-    "body-parser": "1.20.0",
+    "body-parser": "1.20.1",
     "es6-error": "4.1.1",
-    "express": "4.18.1",
+    "express": "4.18.2",
     "http-status-codes": "2.2.0",
     "lodash": "4.17.21",
     "lru-cache": "7.14.0",
@@ -67,7 +66,7 @@
     "morgan": "1.10.0",
     "serve-favicon": "2.5.0",
     "source-map-support": "0.5.21",
-    "type-fest": "2.19.0",
+    "type-fest": "3.1.0",
     "validate.js": "0.13.1"
   },
   "engines": {
@@ -78,5 +77,5 @@
     "access": "public"
   },
   "types": "./build/lib/index.d.ts",
-  "gitHead": "c26af8f85230ac65cbc19f08f763942f74b0eb0c"
+  "gitHead": "6b3cc1a8743f78c1f50320364f25f3011d2b2136"
 }