@appium/base-driver 9.3.2 → 9.3.3

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,9 +29,6 @@ class DriverCore {
    */
   static baseVersion = BASEDRIVER_VER;
 
-  /** @type {import('@appium/types').ExecuteMethodMap<DriverCore>} */
-  static executeMethodMap = {};
-
   /**
    * @type {string?}
    */

package/lib/basedriver/driver.js

@@ -8,7 +8,6 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/base-driver",
-  "version": "9.3.2",
+  "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.6",
-    "@appium/types": "^0.10.0",
+    "@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",
@@ -60,12 +60,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.6.1",
     "validate.js": "0.13.1"
   },
   "engines": {
@@ -75,7 +75,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7b4935632222123a4fa7422461f6312f1f0dfbe4",
+  "gitHead": "872b924a97c13142bdb8bf4218a4db324f309ce4",
   "typedoc": {
     "entryPoint": "./lib/index.js"
   }

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
- */