@appium/base-driver 10.5.2 → 10.7.0

package/lib/basedriver/driver.ts

@@ -1,3 +1,4 @@
+import type AsyncLock from 'async-lock';
 import {util} from '@appium/support';
 import {
   BASE_DESIRED_CAP_CONSTRAINTS,
@@ -17,8 +18,6 @@ import {
   type SingularSessionData,
   type SessionCapabilities,
 } from '@appium/types';
-import B from 'bluebird';
-import _ from 'lodash';
 import {fixCaps, isW3cCaps} from '../helpers/capabilities';
 import {getLevenshteinSuggestion} from '../helpers/levenshtein-match';
 import {calcSignature} from '../helpers/session';
@@ -26,8 +25,12 @@ import {DELETE_SESSION_COMMAND, determineProtocol, errors} from '../protocol';
 import {processCapabilities, validateCaps} from './capabilities';
 import {DriverCore} from './core';
 import * as helpers from './helpers';
+import {mergePlainObjects} from '../utils';
 import {resolveExecuteExtensionName} from '../helpers/extension-command-name';
 
+type CommandInvoker<C extends Constraints> = BaseDriver<C> &
+  Record<string, ((...args: any[]) => any) | undefined>;
+
 const EVENT_SESSION_INIT = 'newSessionRequested';
 const EVENT_SESSION_START = 'newSessionStarted';
 const EVENT_SESSION_QUIT_START = 'quitSessionRequested';
@@ -35,20 +38,20 @@ const EVENT_SESSION_QUIT_DONE = 'quitSessionFinished';
 const ON_UNEXPECTED_SHUTDOWN_EVENT = 'onUnexpectedShutdown';
 
 export class BaseDriver<
-    const C extends Constraints,
-    CArgs extends StringRecord = StringRecord,
-    Settings extends StringRecord = StringRecord,
-    CreateResult = DefaultCreateSessionResult<C>,
-    DeleteResult = DefaultDeleteSessionResult,
-    SessionData extends StringRecord = StringRecord,
-  >
+  const C extends Constraints,
+  CArgs extends StringRecord = StringRecord,
+  Settings extends StringRecord = StringRecord,
+  CreateResult = DefaultCreateSessionResult<C>,
+  DeleteResult = DefaultDeleteSessionResult,
+  SessionData extends StringRecord = StringRecord,
+>
   extends DriverCore<C, Settings>
   implements Driver<C, CArgs, Settings, CreateResult, DeleteResult, SessionData>
 {
   cliArgs: CArgs & ServerArgs;
   caps: DriverCaps<C>;
-  originalCaps: W3CDriverCaps<C>;
-  desiredCapConstraints: C;
+  originalCaps!: W3CDriverCaps<C>;
+  desiredCapConstraints!: C;
   server?: AppiumServer;
   serverHost?: string;
   serverPort?: number;
@@ -69,7 +72,13 @@ export class BaseDriver<
    * @see {@link https://github.com/appium/appium/issues/new}
    */
   protected get _desiredCapConstraints(): Readonly<BaseDriverCapConstraints & C> {
-    return Object.freeze(_.merge({}, BASE_DESIRED_CAP_CONSTRAINTS, this.desiredCapConstraints));
+    return Object.freeze(
+      mergePlainObjects(
+        {},
+        BASE_DESIRED_CAP_CONSTRAINTS,
+        this.desiredCapConstraints,
+      ) as BaseDriverCapConstraints & C,
+    );
   }
 
   /**
@@ -98,8 +107,10 @@ export class BaseDriver<
       throw new errors.NoSuchDriverError('The driver was unexpectedly shut down!');
     }
 
+    const invoker = this as unknown as CommandInvoker<C>;
+    const command = invoker[cmd];
     // If we don't have this command, it must not be implemented
-    if (!this[cmd]) {
+    if (!command) {
       await this.startNewCommandTimeout();
       throw new errors.NotYetImplementedError();
     }
@@ -113,15 +124,15 @@ export class BaseDriver<
         unexpectedShutdownRejecter?.(e);
       };
       try {
-        return await B.race([
-          this[cmd](...args),
+        return await Promise.race([
+          command.call(this, ...args),
           // This promise is needed to monitor if the session has been
           // shut down unexpectedly while the command was running
-          new B((resolve, reject) => {
+          new Promise((resolve, reject) => {
             unexpectedShutdownResolver = resolve;
             unexpectedShutdownRejecter = reject;
             this.eventEmitter.once(ON_UNEXPECTED_SHUTDOWN_EVENT, onUnexpectedShutdown);
-          })
+          }),
         ]);
       } finally {
         if (unexpectedShutdownRejecter && unexpectedShutdownResolver) {
@@ -138,7 +149,11 @@ export class BaseDriver<
         // automatic session deletion in this.onCommandTimeout. Of course we don't
         // want to trigger the timer when the user is shutting down the session
         // intentionally
-        if (!wasSessionShutdownUnexpectedly && this.isCommandsQueueEnabled && cmd !== DELETE_SESSION_COMMAND) {
+        if (
+          !wasSessionShutdownUnexpectedly &&
+          this.isCommandsQueueEnabled &&
+          cmd !== DELETE_SESSION_COMMAND
+        ) {
           // resetting existing timeout
           await this.startNewCommandTimeout();
         }
@@ -146,13 +161,15 @@ export class BaseDriver<
     };
 
     const synchronizationKey = BaseDriver.name;
-    // eslint-disable-next-line dot-notation
-    const commandsQueueLen: number = this.commandsQueueGuard['queues']?.[synchronizationKey]?.length ?? 0;
+    const commandsQueueGuard = this.commandsQueueGuard as AsyncLock & {
+      queues?: Record<string, unknown[]>;
+    };
+    const commandsQueueLen: number = commandsQueueGuard.queues?.[synchronizationKey]?.length ?? 0;
     if (this.isCommandsQueueEnabled && commandsQueueLen > 0) {
       this.log.debug(
         `Scheduling the '${cmd}' command to the ${this.constructor.name} commands queue. ` +
-        `${util.pluralize('queue item', commandsQueueLen, true)} ${commandsQueueLen === 1 ? 'is' : 'are'} ` +
-        `already waiting for execution.`
+          `${util.pluralize('queue item', commandsQueueLen, true)} ${commandsQueueLen === 1 ? 'is' : 'are'} ` +
+          `already waiting for execution.`,
       );
     }
 
@@ -180,8 +197,8 @@ export class BaseDriver<
   clarifyCommandName(cmd: string, args: string[]): string {
     if (cmd === 'execute') {
       const firstArg = args?.[0];
-      if (_.isString(firstArg) && firstArg.trim().length > 0) {
-        return resolveExecuteExtensionName.call(this, firstArg);
+      if (typeof firstArg === 'string' && firstArg.trim().length > 0) {
+        return resolveExecuteExtensionName.call(this as BaseDriver<Constraints>, firstArg);
       }
     }
 
@@ -239,15 +256,12 @@ export class BaseDriver<
     this.log.debug('Running generic full reset');
 
     // preserving state
-    const currentConfig = {};
-    for (const property of [
-      'implicitWaitMs',
-      'newCommandTimeoutMs',
-      'sessionId',
-      'resetOnUnexpectedShutdown',
-    ]) {
-      currentConfig[property] = this[property];
-    }
+    const currentConfig = {
+      implicitWaitMs: this.implicitWaitMs,
+      newCommandTimeoutMs: this.newCommandTimeoutMs,
+      sessionId: this.sessionId,
+      shutdownUnexpectedly: this.shutdownUnexpectedly,
+    };
 
     try {
       if (this.sessionId !== null) {
@@ -257,9 +271,7 @@ export class BaseDriver<
       await this.createSession(this.originalCaps);
     } finally {
       // always restore state.
-      for (const [key, value] of _.toPairs(currentConfig)) {
-        this[key] = value;
-      }
+      Object.assign(this, currentConfig);
     }
     await this.clearNewCommandTimeout();
   }
@@ -286,7 +298,7 @@ export class BaseDriver<
 
     this.log.debug();
 
-    const originalCaps = _.cloneDeep(
+    const originalCaps = structuredClone(
       [w3cCapabilities, w3cCapabilities1, w3cCapabilities2].find(isW3cCaps),
     );
     if (!originalCaps) {
@@ -312,7 +324,8 @@ export class BaseDriver<
       ) as DriverCaps<C>;
       caps = fixCaps(caps, this._desiredCapConstraints, this.log) as DriverCaps<C>;
     } catch (e) {
-      throw new errors.SessionNotCreatedError(e.message);
+      const message = e instanceof Error ? e.message : String(e);
+      throw new errors.SessionNotCreatedError(message);
     }
 
     this.validateDesiredCaps(caps);
@@ -321,7 +334,7 @@ export class BaseDriver<
     this.sessionCreationTimestampMs = Date.now();
     this.caps = caps;
     // merge caps onto opts so we don't need to worry about what's where
-    this.opts = {..._.cloneDeep(this.initialOpts), ...this.caps};
+    this.opts = {...structuredClone(this.initialOpts), ...this.caps};
 
     // deal with resets
     // some people like to do weird things by setting noReset and fullReset
@@ -347,7 +360,7 @@ export class BaseDriver<
       delete this.opts.app;
     }
 
-    if (!_.isUndefined(this.caps.newCommandTimeout)) {
+    if (this.caps.newCommandTimeout !== undefined) {
       this.newCommandTimeoutMs = (this.caps.newCommandTimeout as number) * 1000;
     }
 
@@ -388,7 +401,7 @@ export class BaseDriver<
       // simple hack to release pending commands if they exist
       // @ts-expect-error private API
       const queues = this.commandsQueueGuard.queues;
-      for (const key of _.keys(queues)) {
+      for (const key of Object.keys(queues)) {
         queues[key] = [];
       }
     }
@@ -396,17 +409,14 @@ export class BaseDriver<
   }
 
   logExtraCaps(caps: Capabilities<C>) {
-    const knownCaps = _.keys(this._desiredCapConstraints);
-    const extraCaps = _.difference(_.keys(caps), knownCaps);
+    const knownCaps = Object.keys(this._desiredCapConstraints);
+    const knownCapsSet = new Set(knownCaps);
+    const extraCaps = Object.keys(caps).filter((cap) => !knownCapsSet.has(cap));
     if (extraCaps.length) {
       this.log.warn(`The following provided capabilities were not recognized by this driver:`);
       for (const cap of extraCaps) {
         const suggestion = getLevenshteinSuggestion(cap, knownCaps);
-        this.log.warn(
-          suggestion
-            ? `  ${cap} (did you mean '${suggestion}'?)`
-            : `  ${cap}`,
-        );
+        this.log.warn(suggestion ? `  ${cap} (did you mean '${suggestion}'?)` : `  ${cap}`);
       }
     }
   }
@@ -419,11 +429,13 @@ export class BaseDriver<
     try {
       validateCaps(caps, this._desiredCapConstraints);
     } catch (e) {
+      const capError = e instanceof Error ? e : new Error(String(e));
       throw this.log.errorWithException(
         new errors.SessionNotCreatedError(
           `Session capabilities were not valid for the ` +
-          `following reason(s): ${e.message}`, e
-        )
+            `following reason(s): ${capError.message}`,
+          capError,
+        ),
       );
     }
 

package/lib/basedriver/extension-core.ts

@@ -1,17 +1,17 @@
-import {logger} from '@appium/support';
+import {logger, util} from '@appium/support';
 import {EventEmitter} from 'node:events';
 import type {
   AppiumLogger,
   BidiModuleMap,
   BiDiResultData,
+  IAppiumIpc,
+  IIpcSubscription,
+  IpcData,
   StringRecord,
 } from '@appium/types';
-import {
-  MAX_LOG_BODY_LENGTH,
-} from '../constants';
+import {MAX_LOG_BODY_LENGTH} from '../constants';
 import {errors} from '../protocol';
 import {BIDI_COMMANDS} from '../protocol/bidi-commands';
-import _ from 'lodash';
 import {generateDriverLogPrefix} from './helpers';
 
 export class ExtensionCore {
@@ -20,8 +20,8 @@ export class ExtensionCore {
   _logPrefix?: string;
   // used to handle driver events
   readonly eventEmitter: NodeJS.EventEmitter;
-  protected _log: AppiumLogger;
-
+  protected _log!: AppiumLogger;
+  private ipc?: IAppiumIpc;
 
   constructor(logPrefix?: string) {
     this._logPrefix = logPrefix;
@@ -41,9 +41,11 @@ export class ExtensionCore {
   }
 
   updateBidiCommands(cmds: BidiModuleMap): void {
-    const overlappingKeys = _.intersection(Object.keys(cmds), Object.keys(this.bidiCommands));
+    const overlappingKeys = Object.keys(cmds).filter((key) => key in this.bidiCommands);
     if (overlappingKeys.length) {
-      this.log.warn(`Overwriting existing bidi modules: ${JSON.stringify(overlappingKeys)}. This may not be intended!`);
+      this.log.warn(
+        `Overwriting existing bidi modules: ${JSON.stringify(overlappingKeys)}. This may not be intended!`,
+      );
     }
     this.bidiCommands = {
       ...this.bidiCommands,
@@ -71,7 +73,7 @@ export class ExtensionCore {
     }
 
     // if the command module or method isn't part of our spec, reject
-    if (!(this.bidiCommands[moduleName]?.[methodName])) {
+    if (!this.bidiCommands[moduleName]?.[methodName]) {
       throw new errors.UnknownCommandError();
     }
 
@@ -82,13 +84,19 @@ export class ExtensionCore {
     }
 
     // If the driver doesn't have this command, it must not be implemented
-    if (!this[command]) {
+    const handler = (this as ExtensionCore & Record<string, unknown>)[command];
+    if (typeof handler !== 'function') {
       throw new errors.NotYetImplementedError();
     }
   }
 
-  async executeBidiCommand(bidiCmd: string, bidiParams: StringRecord, next?: () => Promise<any>, driver?: ExtensionCore): Promise<BiDiResultData> {
-    const handlerType = (next && driver) ? 'plugin' : 'driver';
+  async executeBidiCommand(
+    bidiCmd: string,
+    bidiParams: StringRecord,
+    next?: () => Promise<any>,
+    driver?: ExtensionCore,
+  ): Promise<BiDiResultData> {
+    const handlerType = next && driver ? 'plugin' : 'driver';
     const [moduleName, methodName] = bidiCmd.split('.');
     this.ensureBidiCommandExists(moduleName, methodName);
     const {command, params} = this.bidiCommands[moduleName][methodName];
@@ -98,7 +106,7 @@ export class ExtensionCore {
     const args: any[] = [];
     if (params?.required?.length) {
       for (const requiredParam of params.required) {
-        if (_.isUndefined(bidiParams[requiredParam])) {
+        if (bidiParams[requiredParam] === undefined) {
           throw new errors.InvalidArgumentError(
             `The ${requiredParam} parameter was required but you omitted it`,
           );
@@ -111,18 +119,52 @@ export class ExtensionCore {
         args.push(bidiParams[optionalParam]);
       }
     }
-    const logParams = _.truncate(JSON.stringify(bidiParams), {length: MAX_LOG_BODY_LENGTH});
+    const logParams = util.truncateString(JSON.stringify(bidiParams), {
+      length: MAX_LOG_BODY_LENGTH,
+    });
     this.log.debug(
       `Executing bidi command '${bidiCmd}' with params ${logParams} by passing to ${handlerType} ` +
         `method '${command}'`,
     );
     // call the handler with the signature appropriate to extension type (plugin or driver)
-    const response = (next && driver) ? await this[command](next, driver, ...args) : await this[command](...args);
-    const finalResponse = _.isUndefined(response) ? {} : response;
+    const commandHandler = (
+      this as unknown as Record<string, (...handlerArgs: any[]) => Promise<unknown>>
+    )[command];
+    const response =
+      next && driver
+        ? await commandHandler.call(this, next, driver, ...args)
+        : await commandHandler.call(this, ...args);
+    const finalResponse: BiDiResultData =
+      response === undefined ? {} : (response as BiDiResultData);
     this.log.debug(
       `Responding to bidi command '${bidiCmd}' with ` +
-      `${_.truncate(JSON.stringify(finalResponse), {length: MAX_LOG_BODY_LENGTH})}`
+        `${util.truncateString(JSON.stringify(finalResponse), {length: MAX_LOG_BODY_LENGTH})}`,
     );
     return finalResponse;
   }
+
+  /**
+   * @internal Used by AppiumDriver to wire session IPC; extension authors should use {@link onIpcInit} instead.
+   */
+  async assignIpc(ipc: IAppiumIpc): Promise<void> {
+    this.ipc = ipc;
+    try {
+      await this.onIpcInit();
+    } catch (e) {
+      this.log.error(`Error running onIpcInit: `, e);
+    }
+  }
+
+  async onIpcInit(): Promise<void> {}
+
+  ipcSubscribe<T extends IpcData>(topic: string): IIpcSubscription<T> {
+    if (!this.ipc) {
+      throw new Error(
+        `Cannot subscribe to an IPC topic without an IPC object assigned. ` +
+          `This is likely a programming error. ipcSubscribe should be called in the ` +
+          `onIpcInit handler or after you are certain that createSession has completed successfully.`,
+      );
+    }
+    return this.ipc.subscribe<T>(topic, generateDriverLogPrefix(this));
+  }
 }