@appium/base-driver 8.5.2 → 8.5.5

package/lib/basedriver/desired-caps.js

@@ -1,7 +1,12 @@
 import log from './logger';
-import validator from 'validate.js';
+import _validator from 'validate.js';
 import B from 'bluebird';
 
+const validator =
+  /** @type {import('validate.js').ValidateJS & {promise: typeof import('bluebird')}} */ (
+    _validator
+  );
+
 /** @type {import('@appium/types').Constraints} */
 let desiredCapabilityConstraints = {
   platformName: {
@@ -9,53 +14,50 @@ let desiredCapabilityConstraints = {
     isString: true,
   },
   deviceName: {
-    isString: true
+    isString: true,
   },
   platformVersion: {
-    isString: true
+    isString: true,
   },
   newCommandTimeout: {
-    isNumber: true
+    isNumber: true,
   },
   automationName: {
-    isString: true
+    isString: true,
   },
   autoLaunch: {
-    isBoolean: true
+    isBoolean: true,
   },
   udid: {
-    isString: true
+    isString: true,
   },
   orientation: {
-    inclusion: [
-      'LANDSCAPE',
-      'PORTRAIT'
-    ]
+    inclusion: ['LANDSCAPE', 'PORTRAIT'],
   },
   autoWebview: {
-    isBoolean: true
+    isBoolean: true,
   },
   noReset: {
-    isBoolean: true
+    isBoolean: true,
   },
   fullReset: {
-    isBoolean: true
+    isBoolean: true,
   },
   language: {
-    isString: true
+    isString: true,
   },
   locale: {
-    isString: true
+    isString: true,
   },
   eventTimings: {
-    isBoolean: true
+    isBoolean: true,
   },
   printPageSourceOnFindFailure: {
-    isBoolean: true
+    isBoolean: true,
   },
 };
 
-validator.validators.isString = function isString (value) {
+validator.validators.isString = function isString(value) {
   if (typeof value === 'string') {
     return null;
   }
@@ -66,7 +68,7 @@ validator.validators.isString = function isString (value) {
 
   return 'must be of type string';
 };
-validator.validators.isNumber = function isNumber (value) {
+validator.validators.isNumber = function isNumber(value) {
   if (typeof value === 'number') {
     return null;
   }
@@ -76,14 +78,14 @@ validator.validators.isNumber = function isNumber (value) {
   }
 
   // allow a string value
-  if (typeof value === 'string' && !isNaN(value)) {
+  if (typeof value === 'string' && !isNaN(Number(value))) {
     log.warn('Number capability passed in as string. Functionality may be compromised.');
     return null;
   }
 
   return 'must be of type number';
 };
-validator.validators.isBoolean = function isBoolean (value) {
+validator.validators.isBoolean = function isBoolean(value) {
   if (typeof value === 'boolean') {
     return null;
   }
@@ -99,7 +101,7 @@ validator.validators.isBoolean = function isBoolean (value) {
 
   return 'must be of type boolean';
 };
-validator.validators.isObject = function isObject (value) {
+validator.validators.isObject = function isObject(value) {
   if (typeof value === 'object') {
     return null;
   }
@@ -110,7 +112,7 @@ validator.validators.isObject = function isObject (value) {
 
   return 'must be of type object';
 };
-validator.validators.isArray = function isArray (value) {
+validator.validators.isArray = function isArray(value) {
   if (Array.isArray(value)) {
     return null;
   }
@@ -121,13 +123,13 @@ validator.validators.isArray = function isArray (value) {
 
   return 'must be of type array';
 };
-validator.validators.deprecated = function deprecated (value, options, key) {
+validator.validators.deprecated = function deprecated(value, options, key) {
   if (options) {
     log.warn(`${key} is a deprecated capability`);
   }
   return null;
 };
-validator.validators.inclusionCaseInsensitive = function inclusionCaseInsensitive (value, options) {
+validator.validators.inclusionCaseInsensitive = function inclusionCaseInsensitive(value, options) {
   if (typeof value === 'undefined') {
     return null;
   } else if (typeof value !== 'string') {
@@ -142,9 +144,8 @@ validator.validators.inclusionCaseInsensitive = function inclusionCaseInsensitiv
 };
 
 validator.promise = B;
-validator.prettify = function prettify (val) {
+validator.prettify = function prettify(val) {
   return val;
 };
 
-
-export { desiredCapabilityConstraints, validator };
+export {desiredCapabilityConstraints, validator};

package/lib/basedriver/device-settings.js

@@ -1,9 +1,7 @@
-// @ts-check
-
 import _ from 'lodash';
 import log from './logger';
-import { node, util } from '@appium/support';
-import { errors } from '../protocol/errors';
+import {node, util} from '@appium/support';
+import {errors} from '../protocol/errors';
 
 /**
  * Maximum size (in bytes) of a given driver's settings object (which is internal to {@linkcode DriverSettings}).
@@ -11,14 +9,13 @@ import { errors } from '../protocol/errors';
 export const MAX_SETTINGS_SIZE = 20 * 1024 * 1024; // 20 MB
 
 /**
- * @template {Record<string,unknown>} T
+ * @template T
  * @implements {IDeviceSettings<T>}
  */
 class DeviceSettings {
-
   /**
    * @protected
-   * @type {T}
+   * @type {Record<string,T>}
    */
   _settings;
 
@@ -30,30 +27,34 @@ class DeviceSettings {
 
   /**
    * Creates a _shallow copy_ of the `defaultSettings` parameter!
-   * @param {T} [defaultSettings]
+   * @param {Record<string,T>} [defaultSettings]
    * @param {import('@appium/types').SettingsUpdateListener<T>} [onSettingsUpdate]
    */
-  constructor (defaultSettings, onSettingsUpdate) {
-    this._settings = /** @type {T} */({...(defaultSettings ?? {})});
-    this._onSettingsUpdate = onSettingsUpdate ?? (async () => {});
+  constructor(defaultSettings = {}, onSettingsUpdate = async () => {}) {
+    this._settings = {...defaultSettings};
+    this._onSettingsUpdate = onSettingsUpdate;
   }
 
   /**
    * calls updateSettings from implementing driver every time a setting is changed.
-   * @param {T} newSettings
+   * @param {Record<string,T>} newSettings
    */
-  async update (newSettings) {
+  async update(newSettings) {
     if (!_.isPlainObject(newSettings)) {
-      throw new errors.InvalidArgumentError(`Settings update should be called with valid JSON. Got ` +
-        `${JSON.stringify(newSettings)} instead`);
+      throw new errors.InvalidArgumentError(
+        `Settings update should be called with valid JSON. Got ` +
+          `${JSON.stringify(newSettings)} instead`
+      );
     }
 
     if (node.getObjectSize({...this._settings, ...newSettings}) >= MAX_SETTINGS_SIZE) {
-      throw new errors.InvalidArgumentError(`New settings cannot be applied, because the overall ` +
-        `object size exceeds the allowed limit of ${util.toReadableSizeString(MAX_SETTINGS_SIZE)}`);
+      throw new errors.InvalidArgumentError(
+        `New settings cannot be applied, because the overall ` +
+          `object size exceeds the allowed limit of ${util.toReadableSizeString(MAX_SETTINGS_SIZE)}`
+      );
     }
 
-    const props = /** @type {(keyof T & string)[]} */(_.keys(newSettings));
+    const props = /** @type {(keyof T & string)[]} */ (_.keys(newSettings));
     for (const prop of props) {
       if (!_.isUndefined(this._settings[prop])) {
         if (this._settings[prop] === newSettings[prop]) {
@@ -66,13 +67,13 @@ class DeviceSettings {
     }
   }
 
-  getSettings () {
+  getSettings() {
     return this._settings;
   }
 }
 
 export default DeviceSettings;
-export { DeviceSettings };
+export {DeviceSettings};
 
 /**
  * @template T

package/lib/basedriver/driver.js

@@ -1,21 +1,22 @@
-// @ts-check
 /* eslint-disable require-await */
 /* eslint-disable no-unused-vars */
 
-import { DriverCore } from './core';
-import { util } from '@appium/support';
-import B from 'bluebird';
-import _ from 'lodash';
-import { fixCaps, isW3cCaps } from '../helpers/capabilities';
-import { DELETE_SESSION_COMMAND, determineProtocol, errors } from '../protocol';
 import {
+  validateCaps,
   APPIUM_OPTS_CAP,
   PREFIXED_APPIUM_OPTS_CAP,
   processCapabilities,
-  promoteAppiumOptions
+  promoteAppiumOptions,
 } from './capabilities';
-import { createBaseDriverClass } from './commands';
+import {DriverCore} from './core';
+import {util} from '@appium/support';
+import B from 'bluebird';
+import _ from 'lodash';
+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';
 
 const EVENT_SESSION_INIT = 'newSessionRequested';
 const EVENT_SESSION_START = 'newSessionStarted';
@@ -23,11 +24,11 @@ const EVENT_SESSION_QUIT_START = 'quitSessionRequested';
 const EVENT_SESSION_QUIT_DONE = 'quitSessionFinished';
 const ON_UNEXPECTED_SHUTDOWN_EVENT = 'onUnexpectedShutdown';
 
-
 /**
  * @implements {SessionHandler}
  */
 export class BaseDriverCore extends DriverCore {
+  _constraints = _.cloneDeep(desiredCapabilityConstraints);
 
   /** @type {Record<string,any>|undefined} */
   cliArgs;
@@ -37,11 +38,11 @@ export class BaseDriverCore extends DriverCore {
   // and ensuring that we execute commands one at a time. This method is called
   // by MJSONWP's express router.
   /**
-    * @param {string} cmd
-    * @param  {...any[]} args
-    * @returns {Promise<any>}
-    */
-  async executeCommand (cmd, ...args) {
+   * @param {string} cmd
+   * @param  {...any} args
+   * @returns {Promise<any>}
+   */
+  async executeCommand(cmd, ...args) {
     // get start time for this command, and log in special cases
     let startTime = Date.now();
 
@@ -58,9 +59,7 @@ export class BaseDriverCore extends DriverCore {
     await this.clearNewCommandTimeout();
 
     if (this.shutdownUnexpectedly) {
-      throw new errors.NoSuchDriverError(
-          'The driver was unexpectedly shut down!',
-      );
+      throw new errors.NoSuchDriverError('The driver was unexpectedly shut down!');
     }
 
     // If we don't have this command, it must not be implemented
@@ -74,17 +73,14 @@ export class BaseDriverCore extends DriverCore {
         this[cmd](...args),
         new B((resolve, reject) => {
           unexpectedShutdownListener = reject;
-          this.eventEmitter.on(
-              ON_UNEXPECTED_SHUTDOWN_EVENT,
-              unexpectedShutdownListener,
-          );
+          this.eventEmitter.on(ON_UNEXPECTED_SHUTDOWN_EVENT, unexpectedShutdownListener);
         }),
       ]).finally(() => {
         if (unexpectedShutdownListener) {
           // This is needed to prevent memory leaks
           this.eventEmitter.removeListener(
-              ON_UNEXPECTED_SHUTDOWN_EVENT,
-              unexpectedShutdownListener,
+            ON_UNEXPECTED_SHUTDOWN_EVENT,
+            unexpectedShutdownListener
           );
           unexpectedShutdownListener = null;
         }
@@ -117,13 +113,11 @@ export class BaseDriverCore extends DriverCore {
   }
 
   /**
-    *
-    * @param {Error} err
-    */
-  async startUnexpectedShutdown (
-    err = new errors.NoSuchDriverError(
-        'The driver was unexpectedly shut down!',
-    ),
+   *
+   * @param {Error} err
+   */
+  async startUnexpectedShutdown(
+    err = new errors.NoSuchDriverError('The driver was unexpectedly shut down!')
   ) {
     this.eventEmitter.emit(ON_UNEXPECTED_SHUTDOWN_EVENT, err); // allow others to listen for this
     this.shutdownUnexpectedly = true;
@@ -136,7 +130,7 @@ export class BaseDriverCore extends DriverCore {
     }
   }
 
-  async startNewCommandTimeout () {
+  async startNewCommandTimeout() {
     // make sure there are no rogue timeouts
     await this.clearNewCommandTimeout();
 
@@ -146,7 +140,7 @@ export class BaseDriverCore extends DriverCore {
     this.noCommandTimer = setTimeout(async () => {
       this.log.warn(
         `Shutting down because we waited ` +
-          `${this.newCommandTimeoutMs / 1000.0} seconds for a command`,
+          `${this.newCommandTimeoutMs / 1000.0} seconds for a command`
       );
       const errorMessage =
         `New Command Timeout of ` +
@@ -164,7 +158,7 @@ export class BaseDriverCore extends DriverCore {
    * @param {number} port
    * @param {string} path
    */
-  assignServer (server, host, port, path) {
+  assignServer(server, host, port, path) {
     this.server = server;
     this.serverHost = host;
     this.serverPort = port;
@@ -172,10 +166,10 @@ export class BaseDriverCore extends DriverCore {
   }
 
   /*
-    * Restart the session with the original caps,
-    * preserving the timeout config.
-    */
-  async reset () {
+   * Restart the session with the original caps,
+   * preserving the timeout config.
+   */
+  async reset() {
     this.log.debug('Resetting app mid-session');
     this.log.debug('Running generic full reset');
 
@@ -209,40 +203,33 @@ export class BaseDriverCore extends DriverCore {
   }
 
   /**
-     *
-     * Historically the first two arguments were reserved for JSONWP capabilities.
-     * 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 {DriverData[]} [driverData]
-     * @returns {Promise<[string,object]>}
-     */
-  async createSession (
-    w3cCapabilities1,
-    w3cCapabilities2,
-    w3cCapabilities,
-    driverData,
-  ) {
+   *
+   * Historically the first two arguments were reserved for JSONWP capabilities.
+   * 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 {DriverData[]} [driverData]
+   * @returns {Promise<[string,object]>}
+   */
+  async createSession(w3cCapabilities1, w3cCapabilities2, w3cCapabilities, driverData) {
     if (this.sessionId !== null) {
       throw new errors.SessionNotCreatedError(
-           'Cannot create a new session while one is in progress',
+        'Cannot create a new session while one is in progress'
       );
     }
 
     this.log.debug();
 
-    const originalCaps = _.cloneDeep([
-      w3cCapabilities,
-      w3cCapabilities1,
-      w3cCapabilities2,
-    ].find(isW3cCaps));
+    const originalCaps = _.cloneDeep(
+      [w3cCapabilities, w3cCapabilities1, w3cCapabilities2].find(isW3cCaps)
+    );
     if (!originalCaps) {
       throw new errors.SessionNotCreatedError(
-           'Appium only supports W3C-style capability objects. ' +
-             'Your client is sending an older capabilities format. Please update your client library.',
+        'Appium only supports W3C-style capability objects. ' +
+          'Your client is sending an older capabilities format. Please update your client library.'
       );
     }
 
@@ -250,23 +237,15 @@ export class BaseDriverCore extends DriverCore {
 
     this.originalCaps = _.cloneDeep(originalCaps);
     this.log.debug(
-      `Creating session with W3C capabilities: ${JSON.stringify(
-        originalCaps,
-        null,
-        2,
-      )}`,
+      `Creating session with W3C capabilities: ${JSON.stringify(originalCaps, null, 2)}`
     );
 
     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`,
+          `Found ${PREFIXED_APPIUM_OPTS_CAP} capability present; will promote items inside to caps`
         );
         caps = promoteAppiumOptions(caps);
       }
@@ -289,9 +268,9 @@ export class BaseDriverCore extends DriverCore {
     // both to true, but this is misguided and strange, so error here instead
     if (this.opts.noReset && this.opts.fullReset) {
       throw new Error(
-           "The 'noReset' and 'fullReset' capabilities are mutually " +
-             'exclusive and should not both be set to true. You ' +
-             "probably meant to just use 'fullReset' on its own",
+        "The 'noReset' and 'fullReset' capabilities are mutually " +
+          'exclusive and should not both be set to true. You ' +
+          "probably meant to just use 'fullReset' on its own"
       );
     }
     if (this.opts.noReset === true) {
@@ -320,12 +299,12 @@ export class BaseDriverCore extends DriverCore {
   }
 
   /**
-    *
-    * @param {string} [sessionId]
-    * @param {DriverData[]} [driverData]
-    * @returns {Promise<void>}
-    */
-  async deleteSession (sessionId, driverData) {
+   *
+   * @param {string} [sessionId]
+   * @param {DriverData[]} [driverData]
+   * @returns {Promise<void>}
+   */
+  async deleteSession(sessionId, driverData) {
     await this.clearNewCommandTimeout();
     if (this.isCommandsQueueEnabled && this.commandsQueueGuard.isBusy()) {
       // simple hack to release pending commands if they exist
@@ -338,14 +317,80 @@ export class BaseDriverCore extends DriverCore {
     this.sessionId = null;
     this._log.prefix = helpers.generateDriverLogPrefix(this);
   }
+
+  /**
+   *
+   * @param {Capabilities} caps
+   */
+  logExtraCaps(caps) {
+    let extraCaps = _.difference(_.keys(caps), _.keys(this._constraints));
+    if (extraCaps.length) {
+      this.log.warn(
+        `The following capabilities were provided, but are not ` + `recognized by Appium:`
+      );
+      for (const cap of extraCaps) {
+        this.log.warn(`  ${cap}`);
+      }
+    }
+  }
+
+  /**
+   *
+   * @param {Capabilities} caps
+   * @returns {boolean}
+   */
+  validateDesiredCaps(caps) {
+    if (!this.shouldValidateCaps) {
+      return true;
+    }
+
+    try {
+      validateCaps(caps, this._constraints);
+    } catch (e) {
+      this.log.errorAndThrow(
+        new errors.SessionNotCreatedError(
+          `The desiredCapabilities object was not valid for the ` +
+            `following reason(s): ${e.message}`
+        )
+      );
+    }
+
+    this.logExtraCaps(caps);
+
+    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) {}
-export { BaseDriver };
+class _BaseDriver extends createBaseDriverClass(BaseDriverCore) {}
+
+/**
+ * @type {import('@appium/types').DriverClass<Driver>}
+ */
+const BaseDriver = _BaseDriver;
+
+export {BaseDriver};
 export default BaseDriver;
 
 /**
@@ -357,7 +402,6 @@ export default BaseDriver;
  * @typedef {import('@appium/types').DriverData} DriverData
  */
 
-
 /**
  * @callback UpdateServerCallback
  * @param {import('express').Express} app - Express app
@@ -369,16 +413,7 @@ export default BaseDriver;
  * This is used to extend {@linkcode BaseDriverCore} by the mixins and also external drivers.
  * @template [Proto={}]
  * @template [Static={}]
- * @typedef {import('@appium/types').Class<BaseDriverCore & Proto,BaseDriverStatic & Static>} BaseDriverBase
- */
-
-/**
- * Static properties of `BaseDriver` and optional properties for subclasses.
- * @template {ExternalDriver} [T=ExternalDriver]
- * @typedef BaseDriverStatic
- * @property {string} baseVersion
- * @property {UpdateServerCallback} [updateServer]
- * @property {import('@appium/types').MethodMap<T>} [newMethodMap]
+ * @typedef {import('@appium/types').Class<BaseDriverCore & Proto,import('@appium/types').DriverStatic & Static>} BaseDriverBase
  */
 
 /**