@appium/base-driver 9.3.2 → 9.3.4

package/lib/protocol/routes.js

@@ -18,6 +18,7 @@ const SET_ALERT_TEXT_PAYLOAD_PARAMS = {
  * define the routes, mapping of HTTP methods to particular driver commands, and
  * any parameters that are expected in a request parameters can be `required` or
  * `optional`
+ * @satisfies {import('@appium/types').MethodMap<import('../basedriver/driver').BaseDriver>}
  */
 const METHOD_MAP = /** @type {const} */ ({
   '/status': {
@@ -129,7 +130,11 @@ const METHOD_MAP = /** @type {const} */ ({
     POST: {command: 'deactivateIMEEngine', deprecated: true},
   },
   '/session/:sessionId/ime/activate': {
-    POST: {command: 'activateIMEEngine', payloadParams: {required: ['engine']}, deprecated: true},
+    POST: {
+      command: 'activateIMEEngine',
+      payloadParams: {required: ['engine']},
+      deprecated: true,
+    },
   },
   '/session/:sessionId/frame': {
     POST: {command: 'setFrame', payloadParams: {required: ['id']}},
@@ -356,7 +361,11 @@ const METHOD_MAP = /** @type {const} */ ({
     DELETE: {command: 'releaseActions'},
   },
   '/session/:sessionId/touch/longclick': {
-    POST: {command: 'touchLongClick', payloadParams: {required: ['elements']}, deprecated: true},
+    POST: {
+      command: 'touchLongClick',
+      payloadParams: {required: ['elements']},
+      deprecated: true,
+    },
   },
   '/session/:sessionId/touch/flick': {
     POST: {
@@ -922,7 +931,7 @@ const METHOD_MAP = /** @type {const} */ ({
 let ALL_COMMANDS = [];
 for (let v of _.values(METHOD_MAP)) {
   for (let m of _.values(v)) {
-    if (m.command) {
+    if ('command' in m && m.command) {
       ALL_COMMANDS.push(m.command);
     }
   }
@@ -1006,13 +1015,3 @@ function routeToCommandName(endpoint, method, basePath = DEFAULT_BASE_PATH) {
 const NO_SESSION_ID_COMMANDS = ['createSession', 'getStatus', 'getSessions'];
 
 export {METHOD_MAP, ALL_COMMANDS, NO_SESSION_ID_COMMANDS, routeToCommandName};
-
-/**
- * This checks compat with the `MethodMap` interface.
- * @ignore
- */
-// eslint-disable-next-line no-unused-vars
-const _validMethodMap =
-  /** @type {import('@appium/types').MethodMap<import('@appium/types').ExternalDriver<import('@appium/types').BaseDriverCapConstraints>>} */ (
-    METHOD_MAP
-  );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/base-driver",
-  "version": "9.3.2",
+  "version": "9.3.4",
   "description": "Base driver class for Appium drivers",
   "keywords": [
     "automation",
@@ -40,11 +40,12 @@
     "test": "npm run test:unit",
     "test:e2e": "mocha -p --timeout 20s --slow 10s \"./test/e2e/**/*.spec.js\"",
     "test:smoke": "node ./index.js",
-    "test:unit": "mocha \"./test/unit/**/*.spec.js\""
+    "test:unit": "mocha \"./test/unit/**/*.spec.js\"",
+    "test:types": "tsd"
   },
   "dependencies": {
-    "@appium/support": "^3.1.6",
-    "@appium/types": "^0.10.0",
+    "@appium/support": "^3.1.8",
+    "@appium/types": "^0.10.2",
     "@colors/colors": "1.5.0",
     "@types/async-lock": "1.4.0",
     "@types/bluebird": "3.5.38",
@@ -60,12 +61,12 @@
     "express": "4.18.2",
     "http-status-codes": "2.2.0",
     "lodash": "4.17.21",
-    "lru-cache": "7.17.0",
+    "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.6.0",
+    "type-fest": "3.7.1",
     "validate.js": "0.13.1"
   },
   "engines": {
@@ -75,8 +76,11 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7b4935632222123a4fa7422461f6312f1f0dfbe4",
+  "gitHead": "d514ebdd7ebd27bb236509d0a3d580f0f18a34e5",
   "typedoc": {
     "entryPoint": "./lib/index.js"
+  },
+  "tsd": {
+    "directory": "test/types"
   }
 }

package/lib/basedriver/commands/event.js

@@ -1,63 +0,0 @@
-/* eslint-disable require-await */
-// @ts-check
-import _ from 'lodash';
-
-/**
- * @template {Constraints} C
- * @param {import('./timeout').TimeoutBase<C>} Base
- * @returns {EventBase<C>}
- */
-export function EventMixin(Base) {
-  /**
-   * @implements {IEventCommands}
-   */
-  class EventCommands extends Base {
-    /**
-     * Log a user-defined event in the event log.
-     *
-     * @param {string} vendor - a vendor prefix for the user, to ensure namespace
-     * separation
-     * @param {string} event - the event name
-     */
-    async logCustomEvent(vendor, event) {
-      this.logEvent(`${vendor}:${event}`);
-    }
-
-    /**
-     * Get the event log
-     * @param {string|string[]} [type] - the event type to filter with.
-     * It returns all events if the type is not provided or empty string/array.
-     * @returns {Promise<import('@appium/types').EventHistory|Record<string,number>>} - the event history log object
-     */
-    async getLogEvents(type) {
-      if (_.isEmpty(type)) {
-        return this.eventHistory;
-      }
-
-      const typeList = _.castArray(type);
-
-      return _.reduce(
-        this.eventHistory,
-        (acc, eventTimes, eventType) => {
-          if (typeList.includes(eventType)) {
-            acc[eventType] = eventTimes;
-          }
-          return acc;
-        },
-        {}
-      );
-    }
-  }
-
-  return EventCommands;
-}
-
-/**
- * @typedef {import('@appium/types').Constraints} Constraints
- * @typedef {import('@appium/types').IEventCommands} IEventCommands
- */
-
-/**
- * @template {Constraints} C
- * @typedef {import('../driver').BaseDriverBase<C, import('@appium/types').ITimeoutCommands & IEventCommands>} EventBase
- */

package/lib/basedriver/commands/execute.js

@@ -1,45 +0,0 @@
-import _ from 'lodash';
-import {errors, validateExecuteMethodParams} from '../../protocol';
-
-/**
- * @template {Constraints} C
- * @param {import('./session').SessionBase<C>} Base
- * @returns {ExecuteBase<C>}
- */
-export function ExecuteMixin(Base) {
-  /**
-   * @implements {IExecuteCommands}
-   */
-  class ExecuteCommands extends Base {
-    /**
-     * @param {string} script
-     * @param {[Record<string, any>]|[]} protoArgs
-     */
-    async executeMethod(script, protoArgs) {
-      const Driver = /** @type {DriverClass} */ (this.constructor);
-      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(', ')}`
-        );
-      }
-      const args = validateExecuteMethodParams(protoArgs, commandMetadata.params);
-      return await this[commandMetadata.command](...args);
-    }
-  }
-  return ExecuteCommands;
-}
-
-/**
- * @typedef {import('@appium/types').IExecuteCommands} IExecuteCommands
- * @typedef {import('@appium/types').Driver} Driver
- * @typedef {import('@appium/types').DriverClass} DriverClass
- * @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

@@ -1,108 +0,0 @@
-/* eslint-disable no-unused-vars */
-/* eslint-disable require-await */
-// @ts-check
-import {errors} from '../../protocol';
-
-/**
- * @template {Constraints} C
- * @param {import('./event').EventBase<C>} Base
- * @returns {FindBase<C>}
- */
-export function FindMixin(Base) {
-  /**
-   * @implements {IFindCommands}
-   */
-  class FindCommands extends Base {
-    /**
-     *
-     * @returns {Promise<Element>}
-     */
-    async findElement(strategy, selector) {
-      return await this.findElOrElsWithProcessing(strategy, selector, false);
-    }
-
-    /**
-     *
-     * @returns {Promise<Element[]>}
-     */
-    async findElements(strategy, selector) {
-      return await this.findElOrElsWithProcessing(strategy, selector, true);
-    }
-
-    /**
-     *
-     * @returns {Promise<Element>}
-     */
-    async findElementFromElement(strategy, selector, elementId) {
-      return await this.findElOrElsWithProcessing(strategy, selector, false, elementId);
-    }
-
-    /**
-     *
-     * @returns {Promise<Element[]>}
-     */
-    async findElementsFromElement(strategy, selector, elementId) {
-      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!
-     * @template {boolean} Mult
-     * @template [Ctx=any]
-     * @param {string} strategy
-     * @param {string} selector
-     * @param {Mult} mult
-     * @param {Ctx} [context]
-     * @returns {Promise<Mult extends true ? Element[] : Element>}
-     */
-    async findElOrEls(strategy, selector, mult, context) {
-      throw new errors.NotImplementedError('Not implemented yet for find.');
-    }
-
-    /**
-     * @returns {Promise<string>}
-     */
-    async getPageSource() {
-      throw new errors.NotImplementedError('Not implemented yet for find.');
-    }
-    /**
-     * @template {boolean} Mult
-     * @template [Ctx=any]
-     * @param {string} strategy
-     * @param {string} selector
-     * @param {Mult} mult
-     * @param {Ctx} [context]
-     * @returns {Promise<Mult extends true ? Element[] : Element>}
-     */
-    async findElOrElsWithProcessing(strategy, selector, mult, context) {
-      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;
-      }
-    }
-  }
-
-  return FindCommands;
-}
-
-/**
- * @typedef {import('@appium/types').Element} Element
- * @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,35 +0,0 @@
-// @ts-check
-import _ from 'lodash';
-import {EventMixin} from './event';
-import {FindMixin} from './find';
-import {LogMixin} from './log';
-import {SessionMixin} from './session';
-import {SettingsMixin} from './settings';
-import {TimeoutMixin} from './timeout';
-import {ExecuteMixin} from './execute';
-
-/**
- * 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
- */
-
-/**
- * @typedef {import('@appium/types').Constraints} Constraints
- */

package/lib/basedriver/commands/log.js

@@ -1,64 +0,0 @@
-/* eslint-disable require-await */
-// @ts-check
-
-import _ from 'lodash';
-
-/**
- * @template {Constraints} C
- * @param {import('./find').FindBase<C>} Base
- * @returns {LogBase<C>}
- */
-export function LogMixin(Base) {
-  /**
-   * @implements {ILogCommands<C>}
-   */
-  class LogCommands extends Base {
-    /** @type {Readonly<import('@appium/types').LogDefRecord<C>>} */
-    supportedLogTypes;
-
-    constructor(...args) {
-      super(...args);
-      this.supportedLogTypes ??= {};
-    }
-
-    async getLogTypes() {
-      this.log.debug('Retrieving supported log types');
-      return Object.keys(this.supportedLogTypes);
-    }
-
-    /**
-     * @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 '${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);
-    }
-  }
-  return LogCommands;
-}
-
-/**
- * @typedef {import('@appium/types').Constraints} Constraints
- * @typedef {import('@appium/types').StringRecord} StringRecord
- */
-
-/**
- * @template {Constraints} C
- * @typedef {import('@appium/types').ILogCommands<C>} ILogCommands
- */
-
-/**
- * @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

@@ -1,57 +0,0 @@
-/* eslint-disable no-unused-vars */
-/* eslint-disable require-await */
-// @ts-check
-import _ from 'lodash';
-
-/**
- * @template {Constraints} C
- * @param {import('./settings').SettingsBase<C>} Base
- * @returns {SessionBase<C>}
- */
-export function SessionMixin(Base) {
-  /**
-   * @implements {ISessionCommands}
-   */
-  class SessionCommands extends Base {
-    /**
-     * @returns {Promise<MultiSessionData[]>}
-     */
-    async getSessions() {
-      let ret = [];
-
-      if (this.sessionId) {
-        ret.push({
-          id: this.sessionId,
-          capabilities: this.caps,
-        });
-      }
-
-      return ret;
-    }
-
-    /**
-     * Returns capabilities for the session and event history (if applicable)
-     * @returns {Promise<SingularSessionData>}
-     */
-    async getSession() {
-      if (this.caps.eventTimings) {
-        return {...this.caps, events: this.eventHistory};
-      }
-      return this.caps;
-    }
-  }
-
-  return SessionCommands;
-}
-
-/**
- * @typedef {import('@appium/types').ISessionCommands} ISessionCommands
- * @typedef {import('@appium/types').SingularSessionData} SingularSessionData
- * @typedef {import('@appium/types').MultiSessionData} MultiSessionData
- * @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,38 +0,0 @@
-// @ts-check
-
-/**
- * @template {Constraints} C
- * @param {import('./log').LogBase<C>} Base
- * @returns {SettingsBase<C>}
- */
-export function SettingsMixin(Base) {
-  /**
-   * @implements {ISettingsCommands}
-   */
-  class SettingsCommands extends Base {
-    async updateSettings(newSettings) {
-      if (!this.settings) {
-        this.log.errorAndThrow('Cannot update settings; settings object not found');
-      }
-      return await this.settings.update(newSettings);
-    }
-
-    async getSettings() {
-      if (!this.settings) {
-        this.log.errorAndThrow('Cannot get settings; settings object not found');
-      }
-      return await this.settings.getSettings();
-    }
-  }
-
-  return SettingsCommands;
-}
-
-/**
- * @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

@@ -1,168 +0,0 @@
-// @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';
-
-const MIN_TIMEOUT = 0;
-
-/**
- * @template {Constraints} C
- * @param {import('../driver').BaseDriverBase<C>} Base
- * @returns {TimeoutBase<C>}
- */
-export function TimeoutMixin(Base) {
-  /**
-   * @implements {ITimeoutCommands}
-   */
-  class TimeoutCommands extends Base {
-    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 (let 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 (let 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`);
-      let wrappedCondFn = async (...args) => {
-        // reset command timeout
-        await this.clearNewCommandTimeout();
-
-        return await condFn(...args);
-      };
-      return await waitForCondition(wrappedCondFn, {
-        waitMs: this.implicitWaitMs,
-        intervalMs: 500,
-        logger: this.log,
-      });
-    }
-
-    parseTimeoutArgument(ms) {
-      let duration = parseInt(ms, 10);
-      if (_.isNaN(duration) || duration < MIN_TIMEOUT) {
-        throw new errors.UnknownError(`Invalid timeout value '${ms}'`);
-      }
-      return duration;
-    }
-  }
-
-  return TimeoutCommands;
-}
-
-/**
- * @typedef {import('@appium/types').ITimeoutCommands} ITimeoutCommands
- * @typedef {import('@appium/types').Constraints} Constraints
- */
-
-/**
- * @template {Constraints} C
- * @typedef {import('../driver').BaseDriverBase<C, ITimeoutCommands>} TimeoutBase
- */