@appium/base-driver 9.3.1 → 9.3.3

package/lib/basedriver/commands/find.ts

@@ -0,0 +1,79 @@
+import {Constraints, IFindCommands} from '@appium/types';
+import {errors} from '../../protocol';
+import {BaseDriver} from '../driver';
+import {mixin} from './mixin';
+
+declare module '../driver' {
+  interface BaseDriver<C extends Constraints> extends IFindCommands {}
+}
+
+const FindCommands: IFindCommands = {
+  async findElement<C extends Constraints>(this: BaseDriver<C>, strategy, selector) {
+    return await this.findElOrElsWithProcessing(strategy, selector, false);
+  },
+
+  async findElements<C extends Constraints>(this: BaseDriver<C>, strategy, selector) {
+    return await this.findElOrElsWithProcessing(strategy, selector, true);
+  },
+
+  async findElementFromElement<C extends Constraints>(
+    this: BaseDriver<C>,
+    strategy: string,
+    selector: string,
+    elementId: string
+  ) {
+    return await this.findElOrElsWithProcessing(strategy, selector, false, elementId);
+  },
+
+  async findElementsFromElement<C extends Constraints>(
+    this: BaseDriver<C>,
+    strategy: string,
+    selector: string,
+    elementId: string
+  ) {
+    return await this.findElOrElsWithProcessing(strategy, selector, true, elementId);
+  },
+
+  /**
+   * Returns an object which adheres to the way the JSON Wire Protocol represents elements:
+   *
+   * Override this for your own driver!
+   */
+  async findElOrEls<C extends Constraints, Mult extends boolean, Ctx = any>(
+    this: BaseDriver<C>,
+    strategy: string,
+    selector: string,
+    mult: Mult,
+    context: Ctx
+  ) {
+    throw new errors.NotImplementedError('Not implemented yet for find.');
+  },
+
+  async getPageSource<C extends Constraints>(this: BaseDriver<C>) {
+    throw new errors.NotImplementedError('Not implemented yet for find.');
+  },
+
+  async findElOrElsWithProcessing<C extends Constraints, Mult extends boolean, Ctx = any>(
+    this: BaseDriver<C>,
+    strategy: string,
+    selector: string,
+    mult: Mult,
+    context?: Ctx
+  ) {
+    this.validateLocatorStrategy(strategy);
+    try {
+      return await this.findElOrEls(strategy, selector, mult, context);
+    } catch (err) {
+      if (this.opts.printPageSourceOnFindFailure) {
+        const src = await this.getPageSource();
+        this.log.debug(`Error finding element${mult ? 's' : ''}: ${err.message}`);
+        this.log.debug(`Page source requested through 'printPageSourceOnFindFailure':`);
+        this.log.debug(src);
+      }
+      // still want the error to occur
+      throw err;
+    }
+  },
+};
+
+mixin(FindCommands);

package/lib/basedriver/commands/index.ts

@@ -0,0 +1,7 @@
+export * from './event';
+export * from './find';
+export * from './log';
+export * from './session';
+export * from './settings';
+export * from './timeout';
+export * from './execute';

package/lib/basedriver/commands/log.ts

@@ -0,0 +1,36 @@
+import {Constraints, Driver, ILogCommands, LogDefRecord} from '@appium/types';
+import _ from 'lodash';
+import {BaseDriver} from '../driver';
+import {mixin} from './mixin';
+
+declare module '../driver' {
+  interface BaseDriver<C extends Constraints> extends ILogCommands {}
+}
+
+const LogCommands: ILogCommands = {
+  supportedLogTypes: <LogDefRecord>{},
+
+  async getLogTypes<C extends Constraints>(this: BaseDriver<C>) {
+    this.log.debug('Retrieving supported log types');
+    return Object.keys(this.supportedLogTypes);
+  },
+
+  async getLog<C extends Constraints>(
+    this: Driver<C>,
+    logType: keyof ILogCommands['supportedLogTypes']
+  ) {
+    this.log.debug(`Retrieving '${String(logType)}' logs`);
+
+    if (!(logType in this.supportedLogTypes)) {
+      const logsTypesWithDescriptions = _.mapValues(this.supportedLogTypes, 'description');
+      throw new Error(
+        `Unsupported log type '${String(logType)}'. ` +
+          `Supported types: ${JSON.stringify(logsTypesWithDescriptions)}`
+      );
+    }
+
+    return await this.supportedLogTypes[logType].getter(this);
+  },
+};
+
+mixin(LogCommands);

package/lib/basedriver/commands/mixin.ts

@@ -0,0 +1,14 @@
+import {Constraints} from '@appium/types';
+import {BaseDriver} from '../driver';
+
+/**
+ * This function assigns a mixin `T` to the `FakeDriver` class' prototype.
+ * While each mixin has its own interface which is (in isolation) unrelated to `FakeDriver`, the constraint
+ * on this generic type `T` is that it must be a partial of `FakeDriver`'s interface. This enforces
+ * that it does not conflict with the existing interface of `FakeDriver`.  In that way, you can
+ * think of it as a type guard.
+ * @param mixin Mixin implementation
+ */
+export function mixin<C extends Constraints, T extends Partial<BaseDriver<C>>>(mixin: T): void {
+  Object.assign(BaseDriver.prototype, mixin);
+}

package/lib/basedriver/commands/session.ts

@@ -0,0 +1,34 @@
+import {Constraints, ISessionCommands, MultiSessionData} from '@appium/types';
+import {BaseDriver} from '../driver';
+import {mixin} from './mixin';
+
+declare module '../driver' {
+  interface BaseDriver<C extends Constraints> extends ISessionCommands {}
+}
+
+const SessionCommands: ISessionCommands = {
+  async getSessions<C extends Constraints>(this: BaseDriver<C>) {
+    const ret: MultiSessionData[] = [];
+
+    if (this.sessionId) {
+      ret.push({
+        id: this.sessionId,
+        capabilities: this.caps,
+      });
+    }
+
+    return ret;
+  },
+
+  /**
+   * Returns capabilities for the session and event history (if applicable)
+   */
+  async getSession<C extends Constraints>(this: BaseDriver<C>) {
+    if (this.caps.eventTimings) {
+      return {...this.caps, events: this.eventHistory};
+    }
+    return this.caps;
+  },
+};
+
+mixin(SessionCommands);

package/lib/basedriver/commands/settings.ts

@@ -0,0 +1,25 @@
+import {BaseDriver} from '../driver';
+import {Constraints, ISettingsCommands, StringRecord} from '@appium/types';
+import {mixin} from './mixin';
+
+declare module '../driver' {
+  interface BaseDriver<C extends Constraints> extends ISettingsCommands {}
+}
+
+const SettingsCommands: ISettingsCommands = {
+  async updateSettings<C extends Constraints>(this: BaseDriver<C>, newSettings: StringRecord) {
+    if (!this.settings) {
+      this.log.errorAndThrow('Cannot update settings; settings object not found');
+    }
+    return await this.settings.update(newSettings);
+  },
+
+  async getSettings<C extends Constraints>(this: BaseDriver<C>) {
+    if (!this.settings) {
+      this.log.errorAndThrow('Cannot get settings; settings object not found');
+    }
+    return this.settings.getSettings();
+  },
+};
+
+mixin(SettingsCommands);

package/lib/basedriver/commands/timeout.ts

@@ -0,0 +1,155 @@
+// @ts-check
+
+/* eslint-disable no-unused-vars */
+/* eslint-disable require-await */
+import {waitForCondition} from 'asyncbox';
+import _ from 'lodash';
+import {util} from '@appium/support';
+import {errors} from '../../protocol';
+import {BaseDriver} from '../driver';
+import {Constraints, ITimeoutCommands} from '@appium/types';
+import {mixin} from './mixin';
+
+declare module '../driver' {
+  interface BaseDriver<C extends Constraints> extends ITimeoutCommands {}
+}
+
+const MIN_TIMEOUT = 0;
+
+const TimeoutCommands: ITimeoutCommands = {
+  async timeouts(type, ms, script, pageLoad, implicit) {
+    if (util.hasValue(type) && util.hasValue(ms)) {
+      this.log.debug(`MJSONWP timeout arguments: ${JSON.stringify({type, ms})}}`);
+
+      switch (type) {
+        case 'command':
+          await this.newCommandTimeout(ms);
+          return;
+        case 'implicit':
+          await this.implicitWaitMJSONWP(ms);
+          return;
+        case 'page load':
+          await this.pageLoadTimeoutMJSONWP(ms);
+          return;
+        case 'script':
+          await this.scriptTimeoutMJSONWP(ms);
+          return;
+        default:
+          throw new Error(`'${type}' type is not supported for MJSONWP timeout`);
+      }
+    }
+
+    // Otherwise assume it is W3C protocol
+    this.log.debug(
+      `W3C timeout argument: ${JSON.stringify({
+        script,
+        pageLoad,
+        implicit,
+      })}}`
+    );
+    if (util.hasValue(script)) {
+      await this.scriptTimeoutW3C(script);
+    }
+    if (util.hasValue(pageLoad)) {
+      await this.pageLoadTimeoutW3C(pageLoad);
+    }
+    if (util.hasValue(implicit)) {
+      await this.implicitWaitW3C(implicit);
+    }
+  },
+
+  async getTimeouts() {
+    return {
+      command: this.newCommandTimeoutMs,
+      implicit: this.implicitWaitMs,
+    };
+  },
+
+  // implicit
+  async implicitWaitW3C(ms) {
+    await this.implicitWait(ms);
+  },
+
+  async implicitWaitMJSONWP(ms) {
+    await this.implicitWait(ms);
+  },
+
+  async implicitWait(ms) {
+    await this.setImplicitWait(this.parseTimeoutArgument(ms));
+  },
+
+  // pageLoad
+  async pageLoadTimeoutW3C(ms) {
+    throw new errors.NotImplementedError('Not implemented yet for pageLoad.');
+  },
+
+  async pageLoadTimeoutMJSONWP(ms) {
+    throw new errors.NotImplementedError('Not implemented yet for pageLoad.');
+  },
+
+  // script
+  async scriptTimeoutW3C(ms) {
+    throw new errors.NotImplementedError('Not implemented yet for script.');
+  },
+
+  async scriptTimeoutMJSONWP(ms) {
+    throw new errors.NotImplementedError('Not implemented yet for script.');
+  },
+
+  // command
+  async newCommandTimeout(ms) {
+    this.setNewCommandTimeout(this.parseTimeoutArgument(ms));
+  },
+
+  setImplicitWait(ms) {
+    // eslint-disable-line require-await
+    this.implicitWaitMs = ms;
+    this.log.debug(`Set implicit wait to ${ms}ms`);
+    if (this.managedDrivers && this.managedDrivers.length) {
+      this.log.debug('Setting implicit wait on managed drivers');
+      for (const driver of this.managedDrivers) {
+        if (_.isFunction(driver.setImplicitWait)) {
+          driver.setImplicitWait(ms);
+        }
+      }
+    }
+  },
+
+  setNewCommandTimeout(ms) {
+    this.newCommandTimeoutMs = ms;
+    this.log.debug(`Set new command timeout to ${ms}ms`);
+    if (this.managedDrivers && this.managedDrivers.length) {
+      this.log.debug('Setting new command timeout on managed drivers');
+      for (const driver of this.managedDrivers) {
+        if (_.isFunction(driver.setNewCommandTimeout)) {
+          driver.setNewCommandTimeout(ms);
+        }
+      }
+    }
+  },
+
+  async implicitWaitForCondition(condFn) {
+    this.log.debug(`Waiting up to ${this.implicitWaitMs} ms for condition`);
+    const wrappedCondFn = async (...args: any[]) => {
+      // reset command timeout
+      await this.clearNewCommandTimeout();
+
+      return await condFn(...args);
+    };
+    return await waitForCondition(wrappedCondFn, {
+      waitMs: this.implicitWaitMs,
+      intervalMs: 500,
+      logger: this.log,
+    });
+  },
+
+  parseTimeoutArgument<C extends Constraints>(this: BaseDriver<C>, ms: number | string) {
+    const duration = parseInt(String(ms), 10);
+    if (_.isNaN(duration) || duration < MIN_TIMEOUT) {
+      throw new errors.UnknownError(`Invalid timeout value '${ms}'`);
+    }
+    return duration;
+  },
+};
+
+mixin(TimeoutCommands);

package/lib/basedriver/core.js

@@ -29,13 +29,10 @@ class DriverCore {
    */
   static baseVersion = BASEDRIVER_VER;
 
-  /** @type {import('@appium/types').ExecuteMethodMap<DriverCore>} */
-  static executeMethodMap = {};
-
   /**
    * @type {string?}
    */
-  sessionId = null;
+  sessionId;
 
   /**
    * @type {import('@appium/types').DriverOpts<C>}
@@ -47,7 +44,8 @@ class DriverCore {
    */
   initialOpts;
 
-  helpers = helpers;
+  /** @type {typeof helpers} */
+  helpers;
 
   /**
    * basePath is used for several purposes, for example in setting up
@@ -56,39 +54,43 @@ class DriverCore {
    * initially but it is automatically updated during any actual program
    * execution by the routeConfiguringFunction, which is necessarily run as
    * the entrypoint for any Appium server
+   * @type {string}
    */
-  basePath = DEFAULT_BASE_PATH;
+  basePath;
 
-  relaxedSecurityEnabled = false;
+  /** @type {boolean} */
+  relaxedSecurityEnabled;
 
   /** @type {string[]} */
-  allowInsecure = [];
+  allowInsecure;
 
   /** @type {string[]} */
-  denyInsecure = [];
+  denyInsecure;
 
-  newCommandTimeoutMs = NEW_COMMAND_TIMEOUT_MS;
+  /** @type {number} */
+  newCommandTimeoutMs;
 
-  implicitWaitMs = 0;
+  /** @type {number} */
+  implicitWaitMs;
 
   /** @type {string[]} */
-  locatorStrategies = [];
+  locatorStrategies;
 
   /** @type {string[]} */
-  webLocatorStrategies = [];
+  webLocatorStrategies;
 
   /** @type {Driver[]} */
-  managedDrivers = [];
+  managedDrivers;
 
   /** @type {NodeJS.Timeout?} */
-  noCommandTimer = null;
+  noCommandTimer;
 
   /** @type {EventHistory} */
-  _eventHistory = {commands: []};
+  _eventHistory;
 
   // used to handle driver events
   /** @type {NodeJS.EventEmitter} */
-  eventEmitter = new EventEmitter();
+  eventEmitter;
 
   /**
    * @type {AppiumLogger}
@@ -97,8 +99,9 @@ class DriverCore {
 
   /**
    * @protected
+   * @type {boolean}
    */
-  shutdownUnexpectedly = false;
+  shutdownUnexpectedly;
 
   /**
    * @type {boolean}
@@ -107,16 +110,18 @@ class DriverCore {
 
   /**
    * @protected
+   * @type {AsyncLock}
    */
-  commandsQueueGuard = new AsyncLock();
+  commandsQueueGuard;
 
   /**
    * settings should be instantiated by drivers which extend BaseDriver, but
    * we set it to an empty DeviceSettings instance here to make sure that the
    * default settings are applied even if an extending driver doesn't utilize
    * the settings functionality itself
+   * @type {DeviceSettings}
    */
-  settings = new DeviceSettings();
+  settings;
 
   /**
    * @param {DriverOpts<C>} opts
@@ -139,6 +144,22 @@ class DriverCore {
     this.initialOpts = _.cloneDeep(opts);
 
     this.sessionId = null;
+    this.helpers = helpers;
+    this.basePath = DEFAULT_BASE_PATH;
+    this.relaxedSecurityEnabled = false;
+    this.allowInsecure = [];
+    this.denyInsecure = [];
+    this.newCommandTimeoutMs = NEW_COMMAND_TIMEOUT_MS;
+    this.implicitWaitMs = 0;
+    this.locatorStrategies = [];
+    this.webLocatorStrategies = [];
+    this.managedDrivers = [];
+    this.noCommandTimer = null;
+    this._eventHistory = {commands: []};
+    this.eventEmitter = new EventEmitter();
+    this.shutdownUnexpectedly = false;
+    this.commandsQueueGuard = new AsyncLock();
+    this.settings = new DeviceSettings();
   }
 
   get log() {

package/lib/basedriver/driver.js

@@ -1,14 +1,13 @@
 /* eslint-disable require-await */
 /* eslint-disable no-unused-vars */
 
-import {validateCaps, PREFIXED_APPIUM_OPTS_CAP, processCapabilities} from './capabilities';
+import {validateCaps, processCapabilities} from './capabilities';
 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 {BASE_DESIRED_CAP_CONSTRAINTS} from '@appium/types';
 
@@ -22,9 +21,10 @@ const ON_UNEXPECTED_SHUTDOWN_EVENT = 'onUnexpectedShutdown';
  * @implements {SessionHandler<C>}
  * @template {Constraints} C
  * @template {StringRecord} [CArgs=StringRecord]
+ * @implements {Driver<C, CArgs>}
  * @extends {DriverCore<C>}
  */
-export class BaseDriverCore extends DriverCore {
+export class BaseDriver extends DriverCore {
   /**
    * @type {CArgs & ServerArgs}
    */
@@ -59,7 +59,7 @@ export class BaseDriverCore extends DriverCore {
     super(opts, shouldValidateCaps);
 
     /**
-     * This must be assigned here because the declaration of {@linkcode BaseDriverCore.opts} above
+     * This must be assigned here because the declaration of {@linkcode BaseDriver.opts} above
      * blows away {@linkcode DriverCore.opts}.
      */
     this.opts = opts;
@@ -407,12 +407,9 @@ export class BaseDriverCore extends DriverCore {
   }
 }
 
-/**
- * This ensures that all of the mixins correctly implement the interface described in {@linkcode Driver}.
- * @template {Constraints} [C={}]
- * @implements {Driver<C>}
- */
-export class BaseDriver extends createBaseDriverClass(BaseDriverCore) {}
+// eslint-disable-next-line import/no-unresolved
+export * from './commands';
+
 export default BaseDriver;
 
 /**
@@ -433,11 +430,11 @@ export default BaseDriver;
  */
 
 /**
- * This is used to extend {@linkcode BaseDriverCore} by the mixins and also external drivers.
+ * This is used to extend {@linkcode BaseDriver} by the mixins and also external drivers.
  * @template {Constraints} C
  * @template [Proto={}]
  * @template [Static={}]
- * @typedef {import('@appium/types').Class<BaseDriverCore<C> & Proto,import('@appium/types').DriverStatic & Static>} BaseDriverBase
+ * @typedef {import('@appium/types').Class<BaseDriver<C> & Proto,import('@appium/types').DriverStatic & Static>} BaseDriverBase
  */
 
 /**

package/lib/basedriver/helpers.js

@@ -52,17 +52,22 @@ process.on('exit', () => {
   }
 });
 
-async function retrieveHeaders(link) {
+/**
+ *
+ * @param {string} url
+ * @returns {Promise<import('axios').AxiosResponse['headers']>}
+ */
+async function retrieveHeaders(url) {
   try {
     return (
       await axios({
-        url: link,
+        url,
         method: 'HEAD',
         timeout: 5000,
       })
     ).headers;
   } catch (e) {
-    logger.info(`Cannot send HEAD request to '${link}'. Original error: ${e.message}`);
+    logger.info(`Cannot send HEAD request to '${url}'. Original error: ${e.message}`);
   }
   return {};
 }
@@ -228,6 +233,7 @@ async function configureApp(app, options = /** @type {ConfigureAppOptions} */ ({
   let newApp = app;
   let shouldUnzipApp = false;
   let packageHash = null;
+  /** @type {import('axios').AxiosResponse['headers']?} */
   let headers = null;
   /** @type {RemoteAppProps} */
   const remoteAppProps = {

package/lib/index.js

@@ -35,6 +35,7 @@ export {
   isStandardCap,
   validateCaps,
   promoteAppiumOptions,
+  promoteAppiumOptionsForObject,
 } from './basedriver/capabilities';
 
 // Web socket helpers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/base-driver",
-  "version": "9.3.1",
+  "version": "9.3.3",
   "description": "Base driver class for Appium drivers",
   "keywords": [
     "automation",
@@ -43,8 +43,8 @@
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/support": "^3.1.5",
-    "@appium/types": "^0.9.1",
+    "@appium/support": "^3.1.7",
+    "@appium/types": "^0.10.1",
     "@colors/colors": "1.5.0",
     "@types/async-lock": "1.4.0",
     "@types/bluebird": "3.5.38",
@@ -53,19 +53,19 @@
     "@types/serve-favicon": "2.5.3",
     "async-lock": "1.4.0",
     "asyncbox": "2.9.4",
-    "axios": "1.2.3",
+    "axios": "1.3.4",
     "bluebird": "3.7.2",
-    "body-parser": "1.20.1",
+    "body-parser": "1.20.2",
     "es6-error": "4.1.1",
     "express": "4.18.2",
     "http-status-codes": "2.2.0",
     "lodash": "4.17.21",
-    "lru-cache": "7.14.1",
+    "lru-cache": "7.18.3",
     "method-override": "3.0.0",
     "morgan": "1.10.0",
     "serve-favicon": "2.5.0",
     "source-map-support": "0.5.21",
-    "type-fest": "3.5.6",
+    "type-fest": "3.6.1",
     "validate.js": "0.13.1"
   },
   "engines": {
@@ -75,7 +75,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "322363b8876a7ea7b630d538e22965f7bab0ea06",
+  "gitHead": "872b924a97c13142bdb8bf4218a4db324f309ce4",
   "typedoc": {
     "entryPoint": "./lib/index.js"
   }