appium 2.14.1 → 2.16.0

package/lib/appium.js

@@ -8,8 +8,11 @@ import {
   CREATE_SESSION_COMMAND,
   DELETE_SESSION_COMMAND,
   GET_STATUS_COMMAND,
+  LIST_DRIVER_COMMANDS_COMMAND,
+  LIST_DRIVER_EXTENSIONS_COMMAND,
   promoteAppiumOptions,
   promoteAppiumOptionsForObject,
+  generateDriverLogPrefix,
 } from '@appium/base-driver';
 import AsyncLock from 'async-lock';
 import {
@@ -18,10 +21,11 @@ import {
   makeNonW3cCapsError,
   validateFeatures,
 } from './utils';
-import {util, node, logger} from '@appium/support';
+import {util} from '@appium/support';
 import {getDefaultsForExtension} from './schema';
 import {DRIVER_TYPE, BIDI_BASE_PATH} from './constants';
-import * as bidiHelpers from './bidi';
+import * as bidiCommands from './bidi-commands';
+import * as inspectorCommands from './inspector-commands';
 
 const desiredCapabilityConstraints = /** @type {const} */ ({
   automationName: {
@@ -140,17 +144,6 @@ class AppiumDriver extends DriverCore {
     })();
   }
 
-  /**
-   * Retrieves logger instance for the current umbrella driver instance
-   */
-  get log() {
-    if (!this._log) {
-      const instanceName = `${this.constructor.name}@${node.getObjectId(this).substring(0, 4)}`;
-      this._log = logger.getLogger(instanceName);
-    }
-    return this._log;
-  }
-
   /**
    * Cancel commands queueing for the umbrella Appium driver
    */
@@ -202,6 +195,11 @@ class AppiumDriver extends DriverCore {
     }));
   }
 
+  async getAppiumSessions () {
+    throw new errors.NotImplementedError('Not implemented yet. ' +
+      'Please check https://github.com/appium/appium/issues/20880 for more details.');
+  }
+
   printNewSessionAnnouncement(driverName, driverVersion, driverBaseVersion) {
     this.log.info(
       driverVersion
@@ -343,7 +341,8 @@ class AppiumDriver extends DriverCore {
       }
 
       // We also want to assign any new Bidi Commands that the driver has specified, including all
-      // the standard bidi commands
+      // 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)) {
         driverInstance.updateBidiCommands(InnerDriver.newBidiCommands ?? {});
       }
@@ -412,7 +411,7 @@ class AppiumDriver extends DriverCore {
       );
 
       // set the New Command Timeout for the inner driver
-      driverInstance.startNewCommandTimeout();
+      await driverInstance.startNewCommandTimeout();
 
       // apply initial values to Appium settings (if provided)
       if (driverInstance.isW3CProtocol() && !_.isEmpty(w3cSettings)) {
@@ -429,14 +428,13 @@ class AppiumDriver extends DriverCore {
         await driverInstance.updateSettings(jwpSettings);
       }
 
-      // if the user has asked for bidi support, and the driver says that it supports bidi,
-      // send our bidi url back to the user. The inner driver will need to have already saved any
-      // internal bidi urls it might want to proxy to, cause we are going to overwrite that
-      // information here!
-      if (dCaps.webSocketUrl && driverInstance.doesSupportBidi) {
+      // if the user has asked for bidi support, send our bidi url back to the user. The inner
+      // driver will need to have already saved any internal bidi urls it might want to proxy to,
+      // cause we are going to overwrite that information here!
+      if (dCaps.webSocketUrl) {
         const {address, port, basePath} = this.args;
         const scheme = `ws${this.server.isSecure() ? 's' : ''}`;
-        const host = bidiHelpers.determineBiDiHost(address);
+        const host = bidiCommands.determineBiDiHost(address);
         const bidiUrl = `${scheme}://${host}:${port}${basePath}${BIDI_BASE_PATH}/${innerSessionId}`;
         this.log.info(
           `Upstream driver responded with webSocketUrl ${dCaps.webSocketUrl}, will rewrite to ` +
@@ -575,32 +573,6 @@ class AppiumDriver extends DriverCore {
     }
   }
 
-  /**
-   * @param {string} sessionId
-   */
-  cleanupBidiSockets(sessionId) {
-    // clean up any bidi sockets associated with session
-    if (this.bidiSockets[sessionId]) {
-      try {
-        this.log.debug(`Closing bidi socket(s) associated with session ${sessionId}`);
-        for (const ws of this.bidiSockets[sessionId]) {
-          // 1001 means server is going away
-          ws.close(1001, 'Appium session is closing');
-        }
-      } catch {}
-      delete this.bidiSockets[sessionId];
-      const proxyClient = this.bidiProxyClients[sessionId];
-      if (proxyClient) {
-        this.log.debug(`Also closing proxy connection to upstream bidi server`);
-        try {
-          // 1000 means normal closure, which seems correct when Appium is acting as the client
-          proxyClient.close(1000);
-        } catch {}
-        delete this.bidiProxyClients[sessionId];
-      }
-    }
-  }
-
   async deleteAllSessions(opts = {}) {
     const sessionsCount = _.size(this.sessions);
     if (0 === sessionsCount) {
@@ -628,12 +600,13 @@ class AppiumDriver extends DriverCore {
    * Get the appropriate plugins for a session (or sessionless plugins)
    *
    * @param {?string} sessionId - the sessionId (or null) to use to find plugins
-   * @returns {Array} - array of plugin instances
+   * @returns {Array<import('@appium/types').Plugin>} - array of plugin instances
    */
   pluginsForSession(sessionId = null) {
     if (sessionId) {
       if (!this.sessionPlugins[sessionId]) {
-        this.sessionPlugins[sessionId] = this.createPluginInstances();
+        const driverId = generateDriverLogPrefix(this.sessions[sessionId]);
+        this.sessionPlugins[sessionId] = this.createPluginInstances(driverId || null);
       }
       return this.sessionPlugins[sessionId];
     }
@@ -664,14 +637,19 @@ class AppiumDriver extends DriverCore {
 
   /**
    * Creates instances of all of the enabled Plugin classes
+   * @param {string|null} driverId - ID to use for linking a driver to a plugin in logs
    * @returns {Plugin[]}
    */
-  createPluginInstances() {
+  createPluginInstances(driverId = null) {
     /** @type {Plugin[]} */
     const pluginInstances = [];
     for (const [PluginClass, name] of this.pluginClasses.entries()) {
       const cliArgs = this.getCliArgsForPlugin(name);
-      const plugin = new PluginClass(name, cliArgs);
+      const plugin = new PluginClass(name, cliArgs, driverId);
+      if (_.isFunction(/** @type {Plugin & ExtensionCore} */(plugin).updateBidiCommands)) {
+        // some old plugin classes don't have `updateBidiCommands`
+        /** @type {Plugin & ExtensionCore} */(plugin).updateBidiCommands(PluginClass.newBidiCommands ?? {});
+      }
       pluginInstances.push(plugin);
     }
     return pluginInstances;
@@ -832,6 +810,12 @@ class AppiumDriver extends DriverCore {
           `to session ID ${sessionId}`,
       );
       this.sessionPlugins[sessionId] = this.sessionlessPlugins;
+      for (const p of /** @type {(Plugin & ExtensionCore)[]} */(this.sessionPlugins[sessionId])) {
+        if (_.isFunction(p.updateLogPrefix)) {
+          // some old plugin classes don't have `updateLogPrefix` yet
+          p.updateLogPrefix(`${generateDriverLogPrefix(p)} <${generateDriverLogPrefix(this.sessions[sessionId])}>`);
+        }
+      }
       this.sessionlessPlugins = [];
     }
 
@@ -933,15 +917,28 @@ class AppiumDriver extends DriverCore {
     return dstSession && dstSession.canProxy(sessionId);
   }
 
-  onBidiConnection = bidiHelpers.onBidiConnection;
-  onBidiMessage = bidiHelpers.onBidiMessage;
-  onBidiServerError = bidiHelpers.onBidiServerError;
+  onBidiConnection = bidiCommands.onBidiConnection;
+  onBidiMessage = bidiCommands.onBidiMessage;
+  onBidiServerError = bidiCommands.onBidiServerError;
+  cleanupBidiSockets = bidiCommands.cleanupBidiSockets;
+
+  listCommands = inspectorCommands.listCommands;
+  listExtensions = inspectorCommands.listExtensions;
 }
 
-// help decide which commands should be proxied to sub-drivers and which
-// should be handled by this, our umbrella driver
+/**
+ * Help decide which commands should be proxied to sub-drivers and which
+ * should be handled by this, our umbrella driver
+ * @param {string} cmd
+ * @returns {boolean}
+ */
 function isAppiumDriverCommand(cmd) {
-  return !isSessionCommand(cmd) || cmd === DELETE_SESSION_COMMAND;
+  return !isSessionCommand(cmd)
+    || _.includes([
+      DELETE_SESSION_COMMAND,
+      LIST_DRIVER_COMMANDS_COMMAND,
+      LIST_DRIVER_EXTENSIONS_COMMAND,
+    ], cmd);
 }
 
 /**
@@ -979,6 +976,7 @@ export {AppiumDriver};
  * @typedef {import('@appium/types').ExternalDriver} ExternalDriver
  * @typedef {import('@appium/types').PluginClass} PluginClass
  * @typedef {import('@appium/types').Plugin} Plugin
+ * @typedef {import('@appium/base-driver').ExtensionCore} ExtensionCore
  * @typedef {import('@appium/types').DriverClass<import('@appium/types').Driver>} DriverClass
  */
 

package/lib/{bidi.ts → bidi-commands.ts}

@@ -2,6 +2,7 @@ import _ from 'lodash';
 import B from 'bluebird';
 import {
   errors,
+  ExtensionCore,
 } from '@appium/base-driver';
 import {BIDI_BASE_PATH, BIDI_EVENT_NAME} from './constants';
 import WebSocket from 'ws';
@@ -17,14 +18,18 @@ import type {
   ErrorBiDiCommandResponse,
   SuccessBiDiCommandResponse,
   ExternalDriver,
-  StringRecord
+  StringRecord,
+  Plugin,
+  BiDiResultData
 } from '@appium/types';
 
+type ExtensionPlugin = Plugin & ExtensionCore
 type AnyDriver = ExternalDriver | AppiumDriver;
 type SendData = (data: string | Buffer) => Promise<void>;
 type LogSocketError = (err: Error) => void;
 interface InitBiDiSocketResult {
   bidiHandlerDriver: AnyDriver;
+  bidiHandlerPlugins: ExtensionPlugin[];
   proxyClient: WebSocket | null;
   send: SendData;
   sendToProxy: SendData | null;
@@ -64,7 +69,7 @@ export function determineBiDiHost(address: string): string {
 export function onBidiConnection(this: AppiumDriver, ws: WebSocket, req: IncomingMessage): void {
   try {
     const initBiDiSocketFunc: OmitThisParameter<typeof initBidiSocket> = initBidiSocket.bind(this);
-    const {bidiHandlerDriver, proxyClient, send, sendToProxy, logSocketErr} = initBiDiSocketFunc(
+    const {bidiHandlerDriver, bidiHandlerPlugins, proxyClient, send, sendToProxy, logSocketErr} = initBiDiSocketFunc(
       ws,
       req,
     );
@@ -77,6 +82,7 @@ export function onBidiConnection(this: AppiumDriver, ws: WebSocket, req: Incomin
       send,
       sendToProxy,
       bidiHandlerDriver,
+      bidiHandlerPlugins,
       logSocketErr,
     );
     if (proxyClient) {
@@ -86,7 +92,7 @@ export function onBidiConnection(this: AppiumDriver, ws: WebSocket, req: Incomin
     }
     const initBidiEventListenersFunc: OmitThisParameter<typeof initBidiEventListeners> = initBidiEventListeners
       .bind(this);
-    initBidiEventListenersFunc(ws, bidiHandlerDriver, send);
+    initBidiEventListenersFunc(ws, bidiHandlerDriver, bidiHandlerPlugins, send);
   } catch (err) {
     this.log.error(err);
     try {
@@ -95,14 +101,25 @@ export function onBidiConnection(this: AppiumDriver, ws: WebSocket, req: Incomin
   }
 }
 
+function wrapCommandWithPlugins(driver: ExtensionCore, plugins: ExtensionCore[], method: string, params: StringRecord): () => Promise<BiDiResultData> {
+    const [moduleName, methodName] = method.split('.');
+    let next = async () => await driver.executeBidiCommand(method, params);
+    for (const plugin of plugins.filter((p) => p.doesBidiCommandExist(moduleName, methodName))) {
+      next = ((_next) => async () => await plugin.executeBidiCommand(method, params, _next, driver))(next);
+    }
+    return next;
+}
+
 /**
  * @param data
  * @param driver
+ * @param plugins
  */
 export async function onBidiMessage(
   this: AppiumDriver,
   data: Buffer,
-  driver: AnyDriver
+  driver: AnyDriver,
+  plugins: ExtensionPlugin[]
 ): Promise<SuccessBiDiCommandResponse | ErrorBiDiCommandResponse> {
   let resMessage: SuccessBiDiCommandResponse | ErrorBiDiCommandResponse;
   let id: number = 0;
@@ -129,7 +146,8 @@ export async function onBidiMessage(
         `Missing params for BiDi operation in '${dataTruncated}`,
       );
     }
-    const result = await driver.executeBidiCommand(method, params);
+    const executeWrappedCommand = wrapCommandWithPlugins(driver as ExtensionCore, plugins, method, params);
+    const result = await executeWrappedCommand();
     resMessage = {
       id,
       type: 'success',
@@ -158,6 +176,38 @@ export function onBidiServerError(this: AppiumDriver, err: Error): void {
   this.log.warn(`Error from bidi websocket server: ${err}`);
 }
 
+/**
+ * Clean up any bidi sockets associated with session
+ *
+ * @param sessionId
+ */
+export function cleanupBidiSockets(this: AppiumDriver, sessionId: string): void {
+  if (!this.bidiSockets[sessionId]) {
+    return;
+  }
+  try {
+    this.log.debug(`Closing bidi socket(s) associated with session ${sessionId}`);
+    for (const ws of this.bidiSockets[sessionId]) {
+      // 1001 means server is going away
+      ws.close(1001, 'Appium session is closing');
+    }
+  } catch {}
+  delete this.bidiSockets[sessionId];
+
+  const proxyClient = this.bidiProxyClients[sessionId];
+  if (!proxyClient) {
+    return;
+  }
+  this.log.debug(`Also closing proxy connection to upstream bidi server`);
+  try {
+    // 1000 means normal closure, which seems correct when Appium is acting as the client
+    proxyClient.close(1000);
+  } catch {}
+  delete this.bidiProxyClients[sessionId];
+}
+
+// #region Private functions
+
 /**
  * Initialize a new bidi connection
  * @param ws The websocket connection object
@@ -186,6 +236,7 @@ function initBidiSocket(this: AppiumDriver, ws: WebSocket, req: IncomingMessage)
 
   let bidiHandlerDriver: AnyDriver;
   let proxyClient: WebSocket | null = null;
+  const bidiHandlerPlugins: ExtensionPlugin[] = [];
   if (sessionMatch) {
     // If we found a session id, see if it matches an active session
     const sessionId = sessionMatch[1];
@@ -217,15 +268,19 @@ function initBidiSocket(this: AppiumDriver, ws: WebSocket, req: IncomingMessage)
             `url ${bidiProxyUrl}, but this was not a valid url`,
         );
       }
-      this.log.info(`Bidi connection for ${driverName} will be proxied to ${bidiProxyUrl}`);
+      this.log.info(`Bidi connection for ${driverName} will be proxied to ${bidiProxyUrl}. ` +
+                    `Plugins will not handle bidi commands`);
       proxyClient = new WebSocket(bidiProxyUrl);
       this.bidiProxyClients[sessionId] = proxyClient;
+    } else {
+      bidiHandlerPlugins.push(...this.pluginsForSession(sessionId) as ExtensionPlugin[]);
     }
   } else {
     this.log.info('Bidi websocket connection made to main server');
     // no need to store the socket connection if it's to the main server since it will just
     // stay open as long as the server itself is and will close when the server closes.
     bidiHandlerDriver = this; // eslint-disable-line @typescript-eslint/no-this-alias
+    bidiHandlerPlugins.push(...this.pluginsForSession() as ExtensionPlugin[]);
   }
 
   const driverLog = bidiHandlerDriver.log;
@@ -240,6 +295,7 @@ function initBidiSocket(this: AppiumDriver, ws: WebSocket, req: IncomingMessage)
     const socketSend = B.promisify(socket.send, {context: socket});
     return async (data: string | Buffer) => {
       try {
+        await assertIsOpen(socket);
         await socketSend(data);
       } catch (err) {
         logSocketErr(err);
@@ -254,7 +310,7 @@ function initBidiSocket(this: AppiumDriver, ws: WebSocket, req: IncomingMessage)
   // bidi socket server (e.g. on a browser)
   const sendToProxy: SendData | null = proxyClient ? sendFactory(proxyClient) : null;
 
-  return {bidiHandlerDriver, proxyClient, send, sendToProxy, logSocketErr};
+  return {bidiHandlerDriver, bidiHandlerPlugins, proxyClient, send, sendToProxy, logSocketErr};
 }
 
 /**
@@ -315,6 +371,7 @@ function initBidiProxyHandlers(
  * upstream socket
  * @param bidiHandlerDriver - the driver
  * handling the bidi commands
+ * @param bidiHandlerPlugins - plugins that might also handle bidi commands
  * @param logSocketErr - a special prefixed logger
  */
 function initBidiSocketHandlers(
@@ -324,6 +381,7 @@ function initBidiSocketHandlers(
   send: SendData,
   sendToProxy: SendData | null,
   bidiHandlerDriver: AnyDriver,
+  bidiHandlerPlugins: ExtensionPlugin[],
   logSocketErr: LogSocketError,
 ): void {
   const driverLog = bidiHandlerDriver.log;
@@ -340,9 +398,11 @@ function initBidiSocketHandlers(
   ws.on('message', async (data: Buffer) => {
     if (proxyClient && sendToProxy) {
       // if we're meant to proxy to an upstream bidi socket, just do that
+      // TODO trying to determine how this proxying behaviour would interface with plugins is too
+      // complex for now, so just ignore plugins in this case
       await sendToProxy(data.toString('utf8'));
     } else {
-      const res = await this.onBidiMessage(data, bidiHandlerDriver);
+      const res = await this.onBidiMessage(data, bidiHandlerDriver, bidiHandlerPlugins);
       await send(JSON.stringify(res));
     }
   });
@@ -381,56 +441,103 @@ function initBidiEventListeners(
   this: AppiumDriver,
   ws: WebSocket,
   bidiHandlerDriver: AnyDriver,
+  bidiHandlerPlugins: ExtensionPlugin[],
   send: SendData,
 ): void {
   // If the driver emits a bidi event that should maybe get sent to the client, check to make
   // sure the client is subscribed and then pass it on
-  const driverLog = bidiHandlerDriver.log;
-  const driverEe = bidiHandlerDriver.eventEmitter;
   const eventLogCounts: Record<string, number> = BIDI_EVENTS_MAP.get(bidiHandlerDriver) ?? {};
   BIDI_EVENTS_MAP.set(bidiHandlerDriver, eventLogCounts);
-  const eventListener = async ({context, method, params = {}}) => {
-    // if the driver didn't specify a context, use the empty context
-    if (!context) {
-      context = '';
-    }
-    if (!method || !params) {
-      driverLog.warn(
-        `Driver emitted a bidi event that was malformed. Require method and params keys ` +
-          `(with optional context). But instead received: ${_.truncate(JSON.stringify({
-            context,
-            method,
-            params,
-          }), {length: MAX_LOGGED_DATA_LENGTH})}`,
-      );
-      return;
-    }
-    if (ws.readyState !== WebSocket.OPEN) {
-      // if the websocket is not still 'open', then we can ignore sending these events
-      if (ws.readyState > WebSocket.OPEN) {
-        // if the websocket is closed or closing, we can remove this listener as well to avoid
-        // leaks
-        driverEe.removeListener(BIDI_EVENT_NAME, eventListener);
+  const eventListenerFactory = (extType: 'driver'|'plugin', ext: ExtensionCore) => {
+    const eventListener = async ({context, method, params = {}}) => {
+      // if the driver didn't specify a context, use the empty context
+      if (!context) {
+        context = '';
       }
-      return;
-    }
-
-    const eventSubs = bidiHandlerDriver.bidiEventSubs[method];
-    if (_.isArray(eventSubs) && eventSubs.includes(context)) {
-      if (method in eventLogCounts) {
-        ++eventLogCounts[method];
-      } else {
-        driverLog.info(
-          `<-- BIDI EVENT ${method} (context: '${context}', ` +
-          `params: ${_.truncate(JSON.stringify(params), {length: MAX_LOGGED_DATA_LENGTH})}). ` +
-          `All further similar events won't be logged.`,
+      if (!method || !params) {
+        ext.log?.warn( // some old plugins might not have the `log` property
+          `${_.capitalize(extType)} emitted a bidi event that was malformed. Require method and params keys ` +
+            `(with optional context). But instead received: ${_.truncate(JSON.stringify({
+              context,
+              method,
+              params,
+            }), {length: MAX_LOGGED_DATA_LENGTH})}`,
         );
-        eventLogCounts[method] = 1;
+        return;
       }
-      // now we can send the event onto the socket
-      const ev = {type: 'event', context, method, params};
-      await send(JSON.stringify(ev));
-    }
+      if (ws.readyState !== WebSocket.OPEN) {
+        // if the websocket is not still 'open', then we can ignore sending these events
+        if (ws.readyState > WebSocket.OPEN) {
+          // if the websocket is closed or closing, we can remove this listener as well to avoid
+          // leaks. Some old plugin classes might not have the `eventEmitter` property, so use an
+          // existence guard for now.
+          ext.eventEmitter?.removeListener(BIDI_EVENT_NAME, eventListener);
+        }
+        return;
+      }
+
+      const eventSubs = bidiHandlerDriver.bidiEventSubs[method];
+      if (_.isArray(eventSubs) && eventSubs.includes(context)) {
+        if (method in eventLogCounts) {
+          ++eventLogCounts[method];
+        } else {
+          ext.log?.info( // some old plugins might not have the `log` property
+            `<-- BIDI EVENT ${method} (context: '${context}', ` +
+            `params: ${_.truncate(JSON.stringify(params), {length: MAX_LOGGED_DATA_LENGTH})}). ` +
+            `All further similar events won't be logged.`,
+          );
+          eventLogCounts[method] = 1;
+        }
+        // now we can send the event onto the socket
+        const ev = {type: 'event', context, method, params};
+        await send(JSON.stringify(ev));
+      }
+    };
+    return eventListener;
   };
-  driverEe.on(BIDI_EVENT_NAME, eventListener);
+  bidiHandlerDriver.eventEmitter.on(BIDI_EVENT_NAME, eventListenerFactory('driver', bidiHandlerDriver as ExtensionCore));
+  for (const plugin of bidiHandlerPlugins) {
+    // some old plugins might not have the eventEmitter property
+    plugin.eventEmitter?.on(BIDI_EVENT_NAME, eventListenerFactory('plugin', plugin));
+  }
+}
+
+async function assertIsOpen(
+  ws: WebSocket,
+  timeoutMs: number = 5000,
+): Promise<WebSocket> {
+  if (ws.readyState === ws.OPEN) {
+    return ws;
+  }
+  if (ws.readyState > ws.OPEN) {
+    throw new Error(`The BiDi web socket at ${ws.url} is not open`);
+  }
+
+  let errorListener;
+  let openListener;
+  // The socket is in CONNECTING state. Wait up to `timeoutMs` until it is open
+  try {
+    await new Promise((resolve, reject) => {
+      setTimeout(() => reject(
+        new Error(
+          `The BiDi web socket at ${ws.url} did not ` +
+          `open after ${timeoutMs}ms timeout`
+        )
+      ), timeoutMs);
+      ws.once('error', reject);
+      errorListener = reject;
+      ws.once('open', resolve);
+      openListener = resolve;
+    });
+  } finally {
+    if (errorListener) {
+      ws.off('error', errorListener);
+    }
+    if (openListener) {
+      ws.off('open', openListener);
+    }
+  }
+  return ws;
 }
+
+// #endregion