appium 3.4.2 → 3.5.1

package/lib/appium.ts

@@ -1,4 +1,3 @@
-import _ from 'lodash';
 import type WebSocket from 'ws';
 import type {
   AppiumServer,
@@ -11,6 +10,7 @@ import type {
   PluginCommand,
   Protocol,
   RouteMatcher,
+  IAppiumIpc,
   StringRecord,
   TimestampedMultiSessionData,
   W3CDriverCaps,
@@ -46,6 +46,8 @@ import * as bidiCommands from './bidi-commands';
 import * as insecureFeatures from './insecure-features';
 import * as inspectorCommands from './inspector-commands';
 import type {DriverConfig} from './extension/driver-config';
+import {AppiumIpc} from '@appium/base-driver';
+import {compact, pickBy, pull} from './utils';
 
 const desiredCapabilityConstraints = {
   automationName: {
@@ -74,6 +76,11 @@ type SessionHandlerCreateResult = SessionHandlerResult<
 
 type SessionHandlerDeleteResult = SessionHandlerResult<void>;
 
+/** @internal Not part of {@link ExternalDriver}; used only when wiring session IPC. */
+type IpcAssignable = {
+  assignIpc?: (ipc: IAppiumIpc) => Promise<void>;
+};
+
 /**
  * Umbrella driver: owns the session table, loads platform drivers and plugins, and routes
  * commands to the right session driver or plugin chain.
@@ -93,6 +100,8 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
 
   readonly sessionPlugins: Record<string, Plugin[]> = {};
 
+  readonly sessionIpcs: Record<string, AppiumIpc> = {};
+
   sessionlessPlugins: Plugin[] = [];
 
   /** Set during server init before listen; tests may assign a mock after construction. */
@@ -182,7 +191,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
         };
     return {
       ...statusObj,
-      build: _.clone(getBuildInfo()),
+      build: structuredClone(getBuildInfo()),
     };
   }
 
@@ -201,7 +210,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
    */
   async getAppiumSessions(): Promise<TimestampedMultiSessionData[]> {
     this.assertFeatureEnabled(SESSION_DISCOVERY_FEATURE);
-    return _.toPairs(this.sessions).map(([id, driver]) => ({
+    return Object.entries(this.sessions).map(([id, driver]) => ({
       id,
       created: driver.sessionCreationTimestampMs,
       capabilities: driver.caps as DriverCaps<AppiumDriverConstraints>,
@@ -212,7 +221,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
   printNewSessionAnnouncement(
     driverName: string,
     driverVersion?: string,
-    driverBaseVersion?: string
+    driverBaseVersion?: string,
   ): void {
     this.log.info(
       driverVersion
@@ -246,15 +255,18 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
    */
   getCliArgsForDriver(extName: string): StringRecord | undefined {
     const allCliArgsForExt = this.args.driver?.[extName] as StringRecord | undefined;
-    if (_.isEmpty(allCliArgsForExt)) {
+    if (util.isEmpty(allCliArgsForExt)) {
       return undefined;
     }
 
     const defaults = getDefaultsForExtension(DRIVER_TYPE, extName);
-    const cliArgs = _.isEmpty(defaults)
+    const cliArgs = util.isEmpty(defaults)
       ? allCliArgsForExt
-      : _.omitBy(allCliArgsForExt, (value, key) => _.isEqual(defaults[key], value));
-    return _.isEmpty(cliArgs) ? undefined : cliArgs;
+      : pickBy(
+          allCliArgsForExt as Record<string, unknown>,
+          (value, key) => !util.isEqual(defaults[key as string], value),
+        );
+    return util.isEmpty(cliArgs) ? undefined : (cliArgs as StringRecord);
   }
 
   /**
@@ -265,12 +277,12 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
   async createSession(
     w3cCapabilities1: W3CAppiumDriverCaps,
     w3cCapabilities2?: W3CAppiumDriverCaps,
-    w3cCapabilities3?: W3CAppiumDriverCaps
+    w3cCapabilities3?: W3CAppiumDriverCaps,
   ): Promise<SessionHandlerCreateResult> {
-    const defaultCapabilities = _.cloneDeep(this.args.defaultCapabilities);
+    const defaultCapabilities = structuredClone(this.args.defaultCapabilities);
     const defaultSettings = pullSettings((defaultCapabilities ?? {}) as StringRecord);
-    const w3cCapabilities = _.cloneDeep(
-      [w3cCapabilities3, w3cCapabilities2, w3cCapabilities1].find(isW3cCaps)
+    const w3cCapabilities = structuredClone(
+      [w3cCapabilities3, w3cCapabilities2, w3cCapabilities1].find(isW3cCaps),
     );
     if (!w3cCapabilities) {
       throw makeNonW3cCapsError();
@@ -291,7 +303,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
       const parsedCaps = parseCapsForInnerDriver<AppiumDriverConstraints>(
         promoteAppiumOptions(w3cCapabilities),
         this.desiredCapConstraints,
-        defaultCapabilities ? promoteAppiumOptionsForObject(defaultCapabilities) : undefined
+        defaultCapabilities ? promoteAppiumOptionsForObject(defaultCapabilities) : undefined,
       );
 
       if ('error' in parsedCaps && parsedCaps.error) {
@@ -321,14 +333,14 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
       // We also want to assign any new Bidi Commands that the driver has specified, including all
       // the standard bidi commands. But add a method existence guard since some old driver class
       // instances might not have this method
-      if (_.isFunction(driverInstance.updateBidiCommands)) {
+      if (typeof driverInstance.updateBidiCommands === 'function') {
         driverInstance.updateBidiCommands(InnerDriver.newBidiCommands ?? {});
       }
 
       // Likewise, any driver-specific CLI args that were passed in should be assigned directly to
       // the driver so that they cannot be mimicked by a malicious user sending in capabilities
       const cliArgs = this.getCliArgsForDriver(driverName);
-      if (!_.isUndefined(cliArgs)) {
+      if (cliArgs !== undefined) {
         (driverInstance as ExternalDriver & {cliArgs?: StringRecord}).cliArgs = cliArgs;
       }
 
@@ -348,7 +360,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
         throw new errors.SessionNotCreatedError(msg);
       }
       this.pendingDrivers[InnerDriver.name] = this.pendingDrivers[InnerDriver.name] || [];
-      otherPendingDriversData = _.compact(
+      otherPendingDriversData = compact(
         this.pendingDrivers[InnerDriver.name].map((drv) => drv.driverData),
       );
       this.pendingDrivers[InnerDriver.name].push(driverInstance);
@@ -358,11 +370,22 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
           processedW3CCapabilities as never,
           processedW3CCapabilities,
           processedW3CCapabilities,
-          [...runningDriversData, ...otherPendingDriversData]
+          [...runningDriversData, ...otherPendingDriversData],
         )) as [string, DriverCaps<AppiumDriverConstraints> & {webSocketUrl?: string | boolean}];
         this.sessions[innerSessionId] = driverInstance;
+        // create an IPC channel for the driver and all plugins on this session
+        this.sessionIpcs[innerSessionId] = new AppiumIpc({
+          maxObjSize: this.args.maxIpcDataSize,
+          maxTopics: this.args.maxIpcTopics,
+          log: driverInstance.log,
+        });
+        const extDriver = driverInstance as unknown as IpcAssignable;
+        if (typeof extDriver.assignIpc === 'function') {
+          // TODO remove this existence guard as a breaking change in Appium 3
+          await extDriver.assignIpc(this.sessionIpcs[innerSessionId]);
+        }
       } finally {
-        _.pull(this.pendingDrivers[InnerDriver.name], driverInstance);
+        pull(this.pendingDrivers[InnerDriver.name], driverInstance);
       }
 
       this.attachUnexpectedShutdownHandler(driverInstance, innerSessionId);
@@ -376,7 +399,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
       await driverInstance.startNewCommandTimeout();
 
       // apply initial values to Appium settings (if provided)
-      if (driverInstance.isW3CProtocol() && !_.isEmpty(w3cSettings)) {
+      if (driverInstance.isW3CProtocol() && !util.isEmpty(w3cSettings)) {
         this.log.info(
           `Applying the initial values to Appium settings parsed from W3C caps: ` +
             JSON.stringify(w3cSettings),
@@ -394,7 +417,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
         const bidiUrl = `${scheme}://${host}:${port}${basePath}${BIDI_BASE_PATH}/${innerSessionId}`;
         this.log.info(
           `Upstream driver responded with webSocketUrl ${dCaps.webSocketUrl}, will rewrite to ` +
-          `${bidiUrl} for response to client`
+            `${bidiUrl} for response to client`,
         );
         // @ts-ignore webSocketUrl gets sent by the client as a boolean, but then it is supposed
         // to come back from the server as a string. TODO figure out how to express this in our
@@ -424,7 +447,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
 
       if (this.sessionPlugins[innerSessionId]) {
         for (const plugin of this.sessionPlugins[innerSessionId]) {
-          if (_.isFunction(plugin.onUnexpectedShutdown)) {
+          if (typeof plugin.onUnexpectedShutdown === 'function') {
             this.log.debug(
               `Plugin ${plugin.name} defines an unexpected shutdown handler; calling it now`,
             );
@@ -442,11 +465,10 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
       }
 
       this.log.info(`Removing session '${innerSessionId}' from our master session list`);
-      delete this.sessions[innerSessionId];
-      delete this.sessionPlugins[innerSessionId];
+      this.deleteLinkedSessionObjects(innerSessionId);
     };
 
-    if (_.isFunction(driver.onUnexpectedShutdown)) {
+    if (typeof driver.onUnexpectedShutdown === 'function') {
       driver.onUnexpectedShutdown(onShutdown);
     } else {
       this.log.warn(
@@ -462,8 +484,8 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
    * @remarks `InnerDriver` is expected to be the driver class; only `.name` is read.
    */
   async curSessionDataForDriver(InnerDriver: {name: string}): Promise<DriverData[]> {
-    const data = _.compact(
-      _.values(this.sessions)
+    const data = compact(
+      Object.values(this.sessions)
         .filter((s) => s.constructor.name === InnerDriver.name)
         .map((s) => s.driverData),
     );
@@ -489,20 +511,13 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
       let dstSession: ExternalDriver | undefined;
       if (this.sessions[sessionId]) {
         const curConstructorName = this.sessions[sessionId].constructor.name;
-        otherSessionsData = _.toPairs(this.sessions)
+        otherSessionsData = Object.entries(this.sessions)
           .filter(
             ([key, value]) => value.constructor.name === curConstructorName && key !== sessionId,
           )
           .map(([, value]) => value.driverData);
         dstSession = this.sessions[sessionId];
         protocol = dstSession.protocol;
-        this.log.info(`Removing session ${sessionId} from our master session list`);
-        // regardless of whether the deleteSession completes successfully or not
-        // make the session unavailable, because who knows what state it might
-        // be in otherwise
-        delete this.sessions[sessionId];
-        delete this.sessionPlugins[sessionId];
-
         this.cleanupBidiSockets(sessionId);
       }
       // this may not be correct, but if `dstSession` was falsy, the call to `deleteSession()` would
@@ -510,6 +525,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
       if (!dstSession) {
         throw new Error('Session not found');
       }
+
       return {
         protocol,
         value: await dstSession.deleteSession(sessionId, otherSessionsData),
@@ -521,6 +537,12 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
         protocol,
         error: e instanceof Error ? e : new Error(msg),
       };
+    } finally {
+      // regardless of whether the deleteSession completes successfully or not
+      // make the session unavailable, because who knows what state it might
+      // be in otherwise
+      this.log.info(`Removing session ${sessionId} from our master session list`);
+      this.deleteLinkedSessionObjects(sessionId);
     }
   }
 
@@ -529,7 +551,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
    * when `force` is true.
    */
   async deleteAllSessions(opts: {force?: boolean; reason?: string} = {}): Promise<void> {
-    const sessionsCount = _.size(this.sessions);
+    const sessionsCount = Object.keys(this.sessions).length;
     if (0 === sessionsCount) {
       this.log.debug('There are no active sessions for cleanup');
       return;
@@ -538,10 +560,10 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
     const {force = false, reason} = opts;
     this.log.debug(`Cleaning up ${util.pluralize('active session', sessionsCount, true)}`);
     const cleanupPromises = force
-      ? _.values(this.sessions).map((drv) =>
+      ? Object.values(this.sessions).map((drv) =>
           drv.startUnexpectedShutdown(reason ? new Error(reason) : undefined),
         )
-      : _.keys(this.sessions).map((id) => this.deleteSession(id));
+      : Object.keys(this.sessions).map((id) => this.deleteSession(id));
     for (const cleanupPromise of cleanupPromises) {
       try {
         await cleanupPromise;
@@ -570,7 +592,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
       ));
     }
 
-    if (_.isEmpty(this.sessionlessPlugins)) {
+    if (util.isEmpty(this.sessionlessPlugins)) {
       this.sessionlessPlugins = this.createPluginInstances();
     }
     return this.sessionlessPlugins;
@@ -583,9 +605,10 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
   pluginsToHandleCmd(cmd: string, sessionId: string | null = null): Plugin[] {
     // to handle a given command, a plugin should either implement that command as a plugin
     // instance method or it should implement a generic 'handle' method
-    return this.pluginsForSession(sessionId).filter(
-      (p) => _.isFunction(p[cmd]) || _.isFunction(p.handle),
-    );
+    return this.pluginsForSession(sessionId).filter((p) => {
+      const pluginMethod = (p as Plugin & Record<string, unknown>)[cmd];
+      return typeof pluginMethod === 'function' || typeof p.handle === 'function';
+    });
   }
 
   /**
@@ -598,7 +621,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
       const cliArgs = this.getCliArgsForPlugin(name);
       const plugin = new PluginClass(name, cliArgs, driverId);
       const extPlugin = plugin as Plugin & ExtensionCore;
-      if (_.isFunction(extPlugin.updateBidiCommands)) {
+      if (typeof extPlugin.updateBidiCommands === 'function') {
         extPlugin.updateBidiCommands(PluginClass.newBidiCommands ?? {});
       }
       pluginInstances.push(plugin);
@@ -627,7 +650,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
     // if a plugin override proxying for this command and that is why we are here instead of just
     // letting the protocol proxy the command entirely, determine that, get the request object for
     // use later on, then clean up the args
-    const reqForProxy = _.last(args)?.reqForProxy;
+    const reqForProxy = args.at(-1)?.reqForProxy;
     if (reqForProxy) {
       args.pop();
     }
@@ -640,7 +663,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     let driver: this | ExternalDriver = this;
     if (isSessionCmd) {
-      sessionId = _.last(args) as string;
+      sessionId = args.at(-1) as string;
       dstSession = this.sessions[sessionId] ?? null;
       if (!dstSession) {
         throw new Error(`The session with id '${sessionId}' does not exist`);
@@ -754,7 +777,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
     // previously sessionless to use the new sessionId, so that plugins can share state between
     // their createSession method and other instance methods
     if (cmd === CREATE_SESSION_COMMAND && this.sessionlessPlugins.length && !res.error) {
-      const newSessionId = _.first(res.value as unknown[]) as string;
+      const newSessionId = (res.value as unknown[])[0] as string;
       this.log.info(
         `Promoting ${this.sessionlessPlugins.length} sessionless plugins to be attached ` +
           `to session ID ${newSessionId}`,
@@ -762,11 +785,17 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
       this.sessionPlugins[newSessionId] = this.sessionlessPlugins;
       const promoted = this.sessionPlugins[newSessionId] as (Plugin & ExtensionCore)[];
       for (const p of promoted) {
-        if (_.isFunction(p.updateLogPrefix)) {
+        if (typeof p.updateLogPrefix === 'function') {
           p.updateLogPrefix(
-            `${generateDriverLogPrefix(p)} <${generateDriverLogPrefix(this.sessions[newSessionId])}>`
+            `${generateDriverLogPrefix(p)} <${generateDriverLogPrefix(this.sessions[newSessionId])}>`,
           );
         }
+        // we also want to assign the IPC channel for this session to the plugins
+        const extPlugin = p as unknown as IpcAssignable;
+        if (typeof extPlugin.assignIpc === 'function') {
+          // TODO remove this existence guard as a breaking change in Appium 4
+          await extPlugin.assignIpc(this.sessionIpcs[newSessionId]);
+        }
       }
       this.sessionlessPlugins = [];
     }
@@ -806,7 +835,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
         cmdHandledBy[plugin.name] = true; // if we make it here, this plugin has attempted to handle cmd
         // first attempt to handle the command via a command-specific handler on the plugin
         const cmdHandler = (plugin as Plugin & Record<string, unknown>)[cmd];
-        if (_.isFunction(cmdHandler)) {
+        if (typeof cmdHandler === 'function') {
           // Command methods must run with plugin as `this` (detached property access drops binding).
           return await (cmdHandler as PluginCommand).call(
             plugin,
@@ -815,7 +844,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
             ...args,
           );
         }
-        if (!_.isFunction(plugin.handle)) {
+        if (typeof plugin.handle !== 'function') {
           throw new Error(`Plugin ${plugin.name} cannot handle command '${cmd}'`);
         }
         return await plugin.handle(_next, driver as ExternalDriver, cmd, ...args);
@@ -828,7 +857,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
   /** After a command with plugins, logs which handlers ran vs. were skipped (debugging aid). */
   logPluginHandlerReport(
     plugins: Plugin[],
-    {cmd, cmdHandledBy}: {cmd: string; cmdHandledBy: Record<string, boolean>}
+    {cmd, cmdHandledBy}: {cmd: string; cmdHandledBy: Record<string, boolean>},
   ): void {
     if (!plugins.length) {
       return;
@@ -874,7 +903,7 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
     // Sadly, we don't know exactly what kind of object will be returned. It will either be a bare
     // object, or a protocol-aware object with protocol and error/value keys. So we need to sniff
     // it and make sure we don't double-wrap it if it's the latter kind.
-    if (_.isPlainObject(cmdRes) && _.has(cmdRes, 'protocol')) {
+    if (util.isPlainObject(cmdRes) && 'protocol' in cmdRes) {
       Object.assign(res, cmdRes);
     } else {
       res.value = cmdRes;
@@ -887,21 +916,28 @@ export class AppiumDriver extends DriverCore<AppiumDriverConstraints> {
   /** Whether the inner session driver is actively proxying for this session id. */
   override proxyActive(sessionId: string): boolean {
     const dstSession = this.sessions[sessionId];
-    return _.isFunction(dstSession?.proxyActive) && dstSession.proxyActive(sessionId);
+    return typeof dstSession?.proxyActive === 'function' && dstSession.proxyActive(sessionId);
   }
 
   /** URL patterns the session driver does not want proxied; empty if no session or no list. */
   override getProxyAvoidList(sessionId: string): RouteMatcher[] {
     const dstSession = this.sessions[sessionId];
-    return _.isFunction(dstSession?.getProxyAvoidList) ? dstSession.getProxyAvoidList() : [];
+    return typeof dstSession?.getProxyAvoidList === 'function'
+      ? dstSession.getProxyAvoidList()
+      : [];
   }
 
   /** Whether the session driver supports proxying for this session. */
   override canProxy(sessionId: string): boolean {
     const dstSession = this.sessions[sessionId];
-    return _.isFunction(dstSession?.canProxy) && dstSession.canProxy(sessionId);
+    return typeof dstSession?.canProxy === 'function' && dstSession.canProxy(sessionId);
   }
 
+  private deleteLinkedSessionObjects(sessionId: string): void {
+    delete this.sessions[sessionId];
+    delete this.sessionPlugins[sessionId];
+    delete this.sessionIpcs[sessionId];
+  }
 }
 
 /**
@@ -923,11 +959,10 @@ export class NoDriverProxyCommandError extends Error {
 
 /** True if `cmd` should run on the umbrella driver instead of only on the session’s inner driver. */
 function isAppiumDriverCommand(cmd: string): boolean {
-  return !isSessionCommand(cmd)
-    || _.includes([
-      DELETE_SESSION_COMMAND,
-      LIST_DRIVER_COMMANDS_COMMAND,
-      LIST_DRIVER_EXTENSIONS_COMMAND,
-    ], cmd);
+  return (
+    !isSessionCommand(cmd) ||
+    [DELETE_SESSION_COMMAND, LIST_DRIVER_COMMANDS_COMMAND, LIST_DRIVER_EXTENSIONS_COMMAND].includes(
+      cmd,
+    )
+  );
 }
-