appium 2.0.0-beta.17 → 2.0.0-beta.20

package/lib/appium.js

@@ -2,10 +2,10 @@ import _ from 'lodash';
 import log from './logger';
 import { getBuildInfo, updateBuildInfo, APPIUM_VER } from './config';
 import { findMatchingDriver } from './drivers';
-import { BaseDriver, errors, isSessionCommand } from '@appium/base-driver';
-import B from 'bluebird';
+import { BaseDriver, errors, isSessionCommand,
+         CREATE_SESSION_COMMAND } from '@appium/base-driver';
 import AsyncLock from 'async-lock';
-import { getExtensionArgs, parseCapsForInnerDriver, pullSettings, validateExtensionArgs } from './utils';
+import { parseCapsForInnerDriver, pullSettings } from './utils';
 import { util } from '@appium/support';
 
 const desiredCapabilityConstraints = {
@@ -39,7 +39,7 @@ class AppiumDriver extends BaseDriver {
     // the main Appium Driver has no new command timeout
     this.newCommandTimeoutMs = 0;
 
-    this.args = Object.assign({}, args);
+    this.args = {...args};
 
     // Access to sessions list must be guarded with a Semaphore, because
     // it might be changed by other async calls at any time
@@ -59,6 +59,9 @@ class AppiumDriver extends BaseDriver {
     updateBuildInfo();
   }
 
+  /** @type {DriverConfig|undefined} */
+  driverConfig;
+
   /**
    * Cancel commands queueing for the umbrella Appium driver
    */
@@ -113,21 +116,16 @@ class AppiumDriver extends BaseDriver {
 
   /**
    * Validate and assign CLI args for a driver or plugin
-   * @param {string} extType 'driver' or 'plugin'
+   *
+   * If the extension has provided a schema, validation has already happened.
+   * @param {import('./ext-config-io').ExtensionType} extType 'driver' or 'plugin'
    * @param {string} extName the name of the extension
-   * @param {ObjectConstructor} extClass the class of the extension
    * @param {Object} extInstance the driver or plugin instance
    */
-  assignCliArgsToExtension (extType, extName, extClass, extInstance) {
-    const cliArgs = getExtensionArgs(this.args[`${extType}Args`], extName);
+  assignCliArgsToExtension (extType, extName, extInstance) {
+    const cliArgs = this.args[extType]?.[extName];
     if (!_.isEmpty(cliArgs)) {
-      if (!_.has(extClass, 'argsConstraints')) {
-        throw new Error(`You sent in CLI args for the ${extName} ${extType}, but it ` +
-                        `does not define any`);
-      }
-      validateExtensionArgs(cliArgs, extClass.argsConstraints);
       extInstance.cliArgs = cliArgs;
-      log.debug(`Set CLI arguments on ${extName} ${extType} instance: ${JSON.stringify(cliArgs)}`);
     }
   }
 
@@ -213,7 +211,7 @@ class AppiumDriver extends BaseDriver {
 
       // 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
-      this.assignCliArgsToExtension('driver', driverName, InnerDriver, driverInstance);
+      this.assignCliArgsToExtension('driver', driverName, driverInstance);
 
 
       // This assignment is required for correct web sockets functionality inside the driver
@@ -278,34 +276,31 @@ class AppiumDriver extends BaseDriver {
   }
 
   attachUnexpectedShutdownHandler (driver, innerSessionId) {
-    const removeSessionFromMasterList = (cause = new Error('Unknown error')) => {
-      log.warn(`Closing session, cause was '${cause.message}'`);
+    const onShutdown = (cause = new Error('Unknown error')) => {
+      log.warn(`Ending session, cause was '${cause.message}'`);
+
+      if (this.sessionPlugins[innerSessionId]) {
+        for (const plugin of this.sessionPlugins[innerSessionId]) {
+          if (_.isFunction(plugin.onUnexpectedShutdown)) {
+            log.debug(`Plugin ${plugin.name} defines an unexpected shutdown handler; calling it now`);
+            try {
+              plugin.onUnexpectedShutdown(driver, cause);
+            } catch (e) {
+              log.warn(`Got an error when running plugin ${plugin.name} shutdown handler: ${e}`);
+            }
+          } else {
+            log.debug(`Plugin ${plugin.name} does not define an unexpected shutdown handler`);
+          }
+        }
+      }
+
       log.info(`Removing session '${innerSessionId}' from our master session list`);
       delete this.sessions[innerSessionId];
       delete this.sessionPlugins[innerSessionId];
     };
 
-    // eslint-disable-next-line promise/prefer-await-to-then
-    if (_.isFunction((driver.onUnexpectedShutdown || {}).then)) {
-      // TODO: Remove this block after all the drivers use base driver above v 5.0.0
-      // Remove the session on unexpected shutdown, so that we are in a position
-      // to open another session later on.
-      driver.onUnexpectedShutdown
-        // eslint-disable-next-line promise/prefer-await-to-then
-        .then(() => {
-          // if we get here, we've had an unexpected shutdown, so error
-          throw new Error('Unexpected shutdown');
-        })
-        .catch((e) => {
-          // if we cancelled the unexpected shutdown promise, that means we
-          // no longer care about it, and can safely ignore it
-          if (!(e instanceof B.CancellationError)) {
-            removeSessionFromMasterList(e);
-          }
-        }); // this is a cancellable promise
-    } else if (_.isFunction(driver.onUnexpectedShutdown)) {
-      // since base driver v 5.0.0
-      driver.onUnexpectedShutdown(removeSessionFromMasterList);
+    if (_.isFunction(driver.onUnexpectedShutdown)) {
+      driver.onUnexpectedShutdown(onShutdown);
     } else {
       log.warn(`Failed to attach the unexpected shutdown listener. ` +
         `Is 'onUnexpectedShutdown' method available for '${driver.constructor.name}'?`);
@@ -393,19 +388,17 @@ class AppiumDriver extends BaseDriver {
    * @returns {Array} - array of plugin instances
    */
   pluginsForSession (sessionId = null) {
-    let plugins = [];
     if (sessionId) {
       if (!this.sessionPlugins[sessionId]) {
         this.sessionPlugins[sessionId] = this.createPluginInstances();
       }
-      plugins = this.sessionPlugins[sessionId];
-    } else {
-      if (_.isEmpty(this.sessionlessPlugins)) {
-        this.sessionlessPlugins = this.createPluginInstances();
-      }
-      plugins = this.sessionlessPlugins;
+      return this.sessionPlugins[sessionId];
+    }
+
+    if (_.isEmpty(this.sessionlessPlugins)) {
+      this.sessionlessPlugins = this.createPluginInstances();
     }
-    return plugins;
+    return this.sessionlessPlugins;
   }
 
   /**
@@ -425,16 +418,11 @@ class AppiumDriver extends BaseDriver {
       .filter((p) => _.isFunction(p[cmd]) || _.isFunction(p.handle));
   }
 
-  createPluginInstances (sessionId) {
-    if (!sessionId) {
-      sessionId = 'sessionless';
-    }
-    sessionId = _.truncate(sessionId, {length: 11});
+  createPluginInstances () {
     return this.pluginClasses.map((PluginClass) => {
-      const generalName = PluginClass.pluginName;
-      const name = `${generalName} (${sessionId})`;
+      const name = PluginClass.pluginName;
       const plugin = new PluginClass(name);
-      this.assignCliArgsToExtension('plugin', generalName, PluginClass, plugin);
+      this.assignCliArgsToExtension('plugin', name, plugin);
       return plugin;
     });
   }
@@ -453,6 +441,15 @@ class AppiumDriver extends BaseDriver {
     const isUmbrellaCmd = !isGetStatus && isAppiumDriverCommand(cmd);
     const isSessionCmd = !isGetStatus && !isUmbrellaCmd;
 
+    // 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;
+    if (reqForProxy) {
+      args.pop();
+    }
+
+
     // first do some error checking. If we're requesting a session command execution, then make
     // sure that session actually exists on the session driver, and set the session driver itself
     let sessionId = null;
@@ -494,6 +491,18 @@ class AppiumDriver extends BaseDriver {
       // if we make it here, we know that the default behavior is handled
       cmdHandledBy.default = true;
 
+      if (reqForProxy) {
+        // we would have proxied this command had a plugin not handled it, so the default behavior
+        // is to do the proxy and retrieve the result internally so it can be passed to the plugin
+        // in case it calls 'await next()'. This requires that the driver have defined
+        // 'proxyCommand' and not just 'proxyReqRes'.
+        if (!dstSession.proxyCommand) {
+          throw new NoDriverProxyCommandError();
+        }
+        return await dstSession.proxyCommand(reqForProxy.originalUrl, reqForProxy.method,
+          reqForProxy.body);
+      }
+
       if (isGetStatus) {
         return await this.getStatus();
       }
@@ -516,7 +525,18 @@ class AppiumDriver extends BaseDriver {
 
     // if we had plugins, make sure to log out the helpful report about which plugins ended up
     // handling the command and which didn't
-    plugins.length && this.logPluginHandlerReport({cmd, cmdHandledBy});
+    this.logPluginHandlerReport(plugins, {cmd, cmdHandledBy});
+
+    // And finally, if the command was createSession, we want to migrate any plugins which were
+    // 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 sessionId = _.first(res.value);
+      log.info(`Promoting ${this.sessionlessPlugins.length} sessionless plugins to be attached ` +
+               `to session ID ${sessionId}`);
+      this.sessionPlugins[sessionId] = this.sessionlessPlugins;
+      this.sessionlessPlugins = [];
+    }
 
     return res;
   }
@@ -546,7 +566,11 @@ class AppiumDriver extends BaseDriver {
     return next;
   }
 
-  logPluginHandlerReport ({cmd, cmdHandledBy}) {
+  logPluginHandlerReport (plugins, {cmd, cmdHandledBy}) {
+    if (!plugins.length) {
+      return;
+    }
+
     // at the end of the day, we have an object representing which plugins ended up getting
     // their code run as part of handling this command. Because plugins can choose *not* to
     // pass control to other plugins or to the default driver behavior, this is information
@@ -556,7 +580,7 @@ class AppiumDriver extends BaseDriver {
     const didHandle = Object.keys(cmdHandledBy).filter((k) => cmdHandledBy[k]);
     const didntHandle = Object.keys(cmdHandledBy).filter((k) => !cmdHandledBy[k]);
     if (didntHandle.length > 0) {
-      log.info(`Command '${cmd}' was not handled by the following beahviors or plugins, even ` +
+      log.info(`Command '${cmd}' was *not* handled by the following behaviours or plugins, even ` +
                `though they were registered to handle it: ${JSON.stringify(didntHandle)}. The ` +
                `command *was* handled by these: ${JSON.stringify(didHandle)}.`);
     }
@@ -586,24 +610,6 @@ class AppiumDriver extends BaseDriver {
     return res;
   }
 
-  // We want to override basedriver's proxy avoidance detection since plugins might want to avoid
-  // proxying in order to handle a command, so we use this function to make an extra check whether
-  // plugins might want to do this.
-  proxyRouteIsAvoided (sessionId, method, url, body) {
-    if (super.proxyRouteIsAvoided(sessionId, method, url, body)) {
-      return true;
-    }
-    // if even just one plugin needs to avoid proxying, do so
-    for (const plugin of this.pluginsForSession(sessionId)) {
-      if (plugin.shouldAvoidProxy?.(method, url, body)) {
-        log.info(`Request to ${url} would normally be proxied, but plugin ${plugin.name} wants ` +
-                 `to handle it internally. We'll avoid proxying in this case.`);
-        return true;
-      }
-    }
-    return false;
-  }
-
   proxyActive (sessionId) {
     const dstSession = this.sessions[sessionId];
     return dstSession && _.isFunction(dstSession.proxyActive) && dstSession.proxyActive(sessionId);
@@ -626,4 +632,22 @@ function isAppiumDriverCommand (cmd) {
   return !isSessionCommand(cmd) || cmd === 'deleteSession';
 }
 
+/**
+ * Thrown when Appium tried to proxy a command using a driver's `proxyCommand` method but the
+ * method did not exist
+ */
+export class NoDriverProxyCommandError extends Error {
+  /**
+   * @type {Readonly<string>}
+   */
+  code = 'APPIUMERR_NO_DRIVER_PROXYCOMMAND';
+
+  constructor () {
+    super(`The default behavior for this command was to proxy, but the driver ` +
+          `did not have the 'proxyCommand' method defined. To fully support ` +
+          `plugins, drivers should have 'proxyCommand' set to a jwpProxy object's ` +
+          `'command()' method, in addition to the normal 'proxyReqRes'`);
+  }
+}
+
 export { AppiumDriver };