@appium/base-driver 8.3.1 → 8.4.2

package/lib/basedriver/commands/event.js

@@ -1,40 +1,58 @@
+/* eslint-disable require-await */
+// @ts-check
 import _ from 'lodash';
 
-const commands = {};
-
 /**
- * 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
+ * @param {TimeoutBase} Base
+ * @returns {EventBase}
  */
-commands.logCustomEvent = function (vendor, event) {
-  this.logEvent(`${vendor}:${event}`);
-};
+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|Array<string>} type - the event type to filter with.
- * It returns all events if the type is not provided or empty string/array.
- * @returns {object} - the event history log object
- */
-commands.getLogEvents = function (type = null) {
-  if (_.isEmpty(type)) {
-    return this._eventHistory;
-  }
+    /**
+     * 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;
+      }
 
-  if (!_.isArray(type)) {
-    type = [type];
-  }
+      const typeList = _.castArray(type);
 
-  return _.reduce(this._eventHistory, (acc, eventTimes, eventType) => {
-    if (type.includes(eventType)) {
-      acc[eventType] = eventTimes;
+      return _.reduce(
+        this.eventHistory,
+        (acc, eventTimes, eventType) => {
+          if (typeList.includes(eventType)) {
+            acc[eventType] = eventTimes;
+          }
+          return acc;
+        },
+        {},
+      );
     }
-    return acc;
-  }, {});
-};
+  }
+
+  return EventCommands;
+}
 
-export default commands;
+/**
+ * @typedef {import('@appium/types').EventCommands} IEventCommands
+ * @typedef {import('./timeout').TimeoutBase} TimeoutBase
+ * @typedef {import('../driver').BaseDriverBase<import('@appium/types').TimeoutCommands & IEventCommands>} EventBase
+ */

package/lib/basedriver/commands/find.js

@@ -1,51 +1,116 @@
-const commands = {}, helpers = {}, extensions = {};
+/* eslint-disable no-unused-vars */
+/* eslint-disable require-await */
+// @ts-check
+import {errors} from '../../protocol';
 
-
-// Override the following function for your own driver, and the rest is taken
-// care of!
-
-// helpers.findElOrEls = async function (strategy, selector, mult, context) {}
-//   strategy: locator strategy
-//   selector: the actual selector for finding an element
-//   mult: multiple elements or just one?
-//   context: finding an element from the root context? or starting from another element
-//
-// Returns an object which adheres to the way the JSON Wire Protocol represents elements:
-// { ELEMENT: # }    eg: { ELEMENT: 3 }  or { ELEMENT: 1.023 }
-
-helpers.findElOrElsWithProcessing = async function 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);
+/**
+ *
+ * @param {EventBase} Base
+ * @returns {FindBase}
+ */
+export function FindMixin (Base) {
+  /**
+   * @implements {IFindCommands}
+   */
+  class FindCommands extends Base {
+    /**
+     *
+     * @returns {Promise<Element>}
+     */
+    async findElement (strategy, selector) {
+      return await this.findElOrElsWithProcessing(strategy, selector, false);
     }
-    // still want the error to occur
-    throw err;
-  }
-};
 
-commands.findElement = async function findElement (strategy, selector) {
-  return await this.findElOrElsWithProcessing(strategy, selector, false);
-};
+    /**
+     *
+     * @returns {Promise<Element[]>}
+     */
+    async findElements (strategy, selector) {
+      return await this.findElOrElsWithProcessing(strategy, selector, true);
+    }
 
-commands.findElements = async function 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,
+      );
+    }
 
-commands.findElementFromElement = async function 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,
+      );
+    }
+    // Override the following function for your own driver, and the rest is taken
+    // care of!
+    // Returns an object which adheres to the way the JSON Wire Protocol represents elements:
+    // { ELEMENT: # }    eg: { ELEMENT: 3 }  or { ELEMENT: 1.023 }
+    /**
+     * @template {boolean} Mult
+     * @param {string} strategy
+     * @param {string} selector
+     * @param {Mult} mult
+     * @param {string} [context]
+     * @returns {Promise<Mult extends true ? Element[] : Element>}
+     */
+    async findElOrEls (strategy, selector, mult, context) {
+      throw new errors.NotImplementedError('Not implemented yet for find.');
+    }
 
-commands.findElementsFromElement = async function findElementsFromElement (strategy, selector, elementId) {
-  return await this.findElOrElsWithProcessing(strategy, selector, true, elementId);
-};
+    /**
+     * @returns {Promise<string>}
+     */
+    async getPageSource () {
+      throw new errors.NotImplementedError('Not implemented yet for find.');
+    }
+    /**
+     * @template {boolean} Mult
+     * @param {string} strategy
+     * @param {string} selector
+     * @param {Mult} mult
+     * @param {string} [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;
+}
 
-Object.assign(extensions, commands, helpers);
-export { commands, helpers };
-export default extensions;
+/**
+ * @typedef {import('@appium/types').Element} Element
+ * @typedef {import('@appium/types').FindCommands} IFindCommands
+ * @typedef {import('./event').EventBase} EventBase
+ * @typedef {import('../driver').BaseDriverBase<import('@appium/types').TimeoutCommands & import('@appium/types').EventCommands & IFindCommands>} FindBase
+ */

package/lib/basedriver/commands/index.js

@@ -1,22 +1,28 @@
-import sessionCmds from './session';
-import settingsCmds from './settings';
-import timeoutCmds from './timeout';
-import findCmds from './find';
-import logCmds from './log';
-import eventCmds from './event';
+// @ts-check
 
+import { EventMixin } from './event';
+import { FindMixin } from './find';
+import { LogMixin } from './log';
+import { SessionMixin } from './session';
+import { SettingsMixin } from './settings';
+import { TimeoutMixin } from './timeout';
 
-let commands = {};
+/**
+ * Applies all the mixins to the `BaseDriverBase` class.
+ * Returns a `BaseDriver` class.
+ * @param {BaseDriverBase} Base
+ */
+export function createBaseDriverClass (Base) {
+  const WithTimeoutCommands = TimeoutMixin(Base);
+  const WithEventCommands = EventMixin(WithTimeoutCommands);
+  const WithFindCommands = FindMixin(WithEventCommands);
+  const WithLogCommands = LogMixin(WithFindCommands);
+  const WithSettingsCommands = SettingsMixin(WithLogCommands);
+  const WithSessionCommands = SessionMixin(WithSettingsCommands);
+  return WithSessionCommands;
+}
 
-Object.assign(
-  commands,
-  sessionCmds,
-  settingsCmds,
-  timeoutCmds,
-  findCmds,
-  logCmds,
-  eventCmds,
-  // add other command types here
-);
-
-export default commands;
+/**
+ * @template [T={}]
+ * @typedef {import('../driver').BaseDriverBase<T>} BaseDriverBase
+ */

package/lib/basedriver/commands/log.js

@@ -1,38 +1,65 @@
+/* eslint-disable require-await */
+// @ts-check
+
 import _ from 'lodash';
 
-const commands = {}, helpers = {}, extensions = {};
-
-// override in sub-classes, with appropriate logs
-// in the form of
-//   {
-//     type: {
-//       description: 'some useful text',
-//       getter: () => {}, // some function that will be called to get the logs
-//     }
-//   }
-extensions.supportedLogTypes = {};
-
-// eslint-disable-next-line require-await
-commands.getLogTypes = async function getLogTypes () {
-  this.log.debug('Retrieving supported log types');
-  return _.keys(this.supportedLogTypes);
-};
-
-commands.getLog = async function getLog (logType) {
-  this.log.debug(`Retrieving '${logType}' logs`);
-
-  if (!(await this.getLogTypes()).includes(logType)) {
-    const logsTypesWithDescriptions = _.reduce(this.supportedLogTypes, (acc, value, key) => {
-      acc[key] = value.description;
-      return acc;
-    }, {});
-    throw new Error(`Unsupported log type '${logType}'. ` +
-      `Supported types: ${JSON.stringify(logsTypesWithDescriptions)}`);
+/**
+ *
+ * @param {FindBase} Base
+ * @returns {LogBase}
+ */
+export function LogMixin (Base) {
+  /**
+   * @implements {ILogCommands}
+   */
+  class LogCommands extends Base {
+    /**
+     * XXX: dubious
+     * @type {Record<string,LogType<Driver>>}
+     */
+    supportedLogTypes;
+
+    async getLogTypes () {
+      this.log.debug('Retrieving supported log types');
+      return _.keys(this.supportedLogTypes);
+    }
+
+    /**
+     * @this {Driver}
+     */
+    async getLog (logType) {
+      this.log.debug(`Retrieving '${logType}' logs`);
+
+      if (!(await this.getLogTypes()).includes(logType)) {
+        const logsTypesWithDescriptions = _.reduce(
+          this.supportedLogTypes,
+          (acc, value, key) => {
+            acc[key] = value.description;
+            return acc;
+          },
+          {},
+        );
+        throw new Error(
+          `Unsupported log type '${logType}'. ` +
+            `Supported types: ${JSON.stringify(logsTypesWithDescriptions)}`,
+        );
+      }
+
+      return await this.supportedLogTypes[logType].getter(this);
+    }
   }
+  return LogCommands;
+}
+
 
-  return await this.supportedLogTypes[logType].getter(this);
-};
+/**
+ * @typedef {import('@appium/types').LogCommands} ILogCommands
+ * @typedef {import('@appium/types').Driver} Driver
+ * @typedef {import('./find').FindBase} FindBase
+ * @typedef {import('../driver').BaseDriverBase<import('@appium/types').TimeoutCommands & import('@appium/types').EventCommands & import('@appium/types').FindCommands & ILogCommands>} LogBase
+ */
 
-Object.assign(extensions, commands, helpers);
-export { commands, helpers};
-export default extensions;
+/**
+ * @template T
+ * @typedef {import('@appium/types').LogType<T>} LogType
+ */

package/lib/basedriver/commands/session.js

@@ -1,153 +1,51 @@
+/* eslint-disable no-unused-vars */
 /* eslint-disable require-await */
+// @ts-check
 import _ from 'lodash';
-import { errors } from '../../protocol';
-import { util } from '@appium/support';
-import {
-  processCapabilities, promoteAppiumOptions, APPIUM_OPTS_CAP, PREFIXED_APPIUM_OPTS_CAP,
-} from '../capabilities';
-import { isW3cCaps } from '../../helpers/capabilities';
 
-const commands = {};
-
-commands.createSession = async function createSession (w3cCapabilities1, w3cCapabilities2, w3cCapabilities) {
-  if (this.sessionId !== null) {
-    throw new errors.SessionNotCreatedError('Cannot create a new session while one is in progress');
-  }
-
-  this.log.debug();
-
-  // 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.
-  const originalCaps = [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.');
-  }
-
-  this.setProtocolW3C();
-
-  this.originalCaps = _.cloneDeep(originalCaps);
-  this.log.debug(`Creating session with W3C capabilities: ${JSON.stringify(originalCaps, null, 2)}`);
-
-  let caps;
-  try {
-    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);
-  } catch (e) {
-    throw new errors.SessionNotCreatedError(e.message);
-  }
-
-  this.validateDesiredCaps(caps);
-
-  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);
-
-  // deal with resets
-  // some people like to do weird things by setting noReset and fullReset
-  // 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");
-  }
-  if (this.opts.noReset === true) {
-    this.opts.fullReset = false;
-  }
-  if (this.opts.fullReset === true) {
-    this.opts.noReset = false;
-  }
-  this.opts.fastReset = !this.opts.fullReset && !this.opts.noReset;
-  this.opts.skipUninstall = this.opts.fastReset || this.opts.noReset;
-
-  // Prevents empty string caps so we don't need to test it everywhere
-  if (typeof this.opts.app === 'string' && this.opts.app.trim() === '') {
-    this.opts.app = null;
-  }
-
-  if (!_.isUndefined(this.caps.newCommandTimeout)) {
-    this.newCommandTimeoutMs = (this.caps.newCommandTimeout * 1000);
-  }
-
-  this.log.info(`Session created with session id: ${this.sessionId}`);
-
-  return [this.sessionId, caps];
-};
-
-commands.getSessions = async function getSessions () {
-  let ret = [];
-
-  if (this.sessionId) {
-    ret.push({
-      id: this.sessionId,
-      capabilities: this.caps
-    });
-  }
-
-  return ret;
-};
-
-commands.getSession = async function getSession () {
-  if (this.caps.eventTimings) {
-    return Object.assign({}, this.caps, {events: this.eventHistory});
-  }
-  return this.caps;
-};
-
-commands.deleteSession = async function deleteSession (/* sessionId */) {
-  this.clearNewCommandTimeout();
-  if (this.isCommandsQueueEnabled && this.commandsQueueGuard.isBusy()) {
-    // simple hack to release pending commands if they exist
-    for (const key of _.keys(this.commandsQueueGuard.queues)) {
-      this.commandsQueueGuard.queues[key] = [];
-    }
-  }
-  this.sessionId = null;
-};
-
-function fixCaps (originalCaps, desiredCapConstraints = {}, log) {
-  let caps = _.clone(originalCaps);
-
-  // 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];
-    if (_.isString(value)) {
-      value = value.toLowerCase();
-      if (value === 'true' || value === 'false') {
-        log.warn(`Capability '${cap}' changed from string to boolean. This may cause unexpected behavior`);
-        caps[cap] = (value === 'true');
+/**
+ * @param {SettingsBase} Base
+ * @returns {SessionBase}
+ */
+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;
     }
-  }
 
-  // int capabilities are often sent in as strings by frameworks
-  let intCaps = _.keys(_.pickBy(desiredCapConstraints, (k) => k.isNumber === true));
-  for (let cap of intCaps) {
-    let value = originalCaps[cap];
-    if (_.isString(value) && !isNaN(value)) {
-      value = value.trim();
-      let newValue = parseInt(value, 10);
-      if (value !== `${newValue}`) {
-        newValue = parseFloat(value);
+    /**
+     * @returns {Promise<SingularSessionData>}
+     */
+    async getSession () {
+      if (this.caps.eventTimings) {
+        return {...this.caps, events: this.eventHistory};
       }
-      log.warn(`Capability '${cap}' changed from string ('${value}') to integer (${newValue}). This may cause unexpected behavior`);
-      caps[cap] = newValue;
+      return this.caps;
     }
   }
 
-  return caps;
+  return SessionCommands;
 }
 
-export default commands;
-export { promoteAppiumOptions };
+/**
+ * @typedef {import('@appium/types').SessionCommands} ISessionCommands
+ * @typedef {import('@appium/types').SingularSessionData} SingularSessionData
+ * @typedef {import('@appium/types').MultiSessionData} MultiSessionData
+ * @typedef {import('./settings').SettingsBase} SettingsBase
+ * @typedef {import('../driver').BaseDriverBase<import('@appium/types').TimeoutCommands & import('@appium/types').EventCommands & import('@appium/types').FindCommands & import('@appium/types').LogCommands & import('@appium/types').SettingsCommands & ISessionCommands>} SessionBase
+ */

package/lib/basedriver/commands/settings.js

@@ -1,17 +1,37 @@
-const commands = {};
+// @ts-check
 
-commands.updateSettings = async function updateSettings (newSettings) {
-  if (!this.settings) {
-    this.log.errorAndThrow('Cannot update settings; settings object not found');
-  }
-  return await this.settings.update(newSettings);
-};
+/**
+ *
+ * @param {ReturnType<import('./log').LogMixin>} Base
+ * @returns {SettingsBase}
+ */
+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();
+    }
 
-commands.getSettings = async function getSettings () {
-  if (!this.settings) {
-    this.log.errorAndThrow('Cannot get settings; settings object not found');
   }
-  return await this.settings.getSettings();
-};
 
-export default commands;
+  return SettingsCommands;
+}
+
+/**
+ * @typedef {import('@appium/types').SettingsCommands} ISettingsCommands
+ * @typedef {import('./log').LogBase} LogBase
+ * @typedef {import('../driver').BaseDriverBase<import('@appium/types').TimeoutCommands & import('@appium/types').EventCommands & import('@appium/types').FindCommands & import('@appium/types').LogCommands & ISettingsCommands>} SettingsBase
+ */