appium 2.0.0-beta.2 → 2.0.0-beta.23

package/lib/appium.js

@@ -2,11 +2,11 @@ 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 { parseCapsForInnerDriver, pullSettings } from './utils';
-import { util } from 'appium-support';
+import { util } from '@appium/support';
 
 const desiredCapabilityConstraints = {
   automationName: {
@@ -27,7 +27,7 @@ class AppiumDriver extends BaseDriver {
     // It is necessary to set `--tmp` here since it should be set to
     // process.env.APPIUM_TMP_DIR once at an initial point in the Appium lifecycle.
     // The process argument will be referenced by BaseDriver.
-    // Please call appium-support.tempDir module to apply this benefit.
+    // Please call @appium/support.tempDir module to apply this benefit.
     if (args.tmpDir) {
       process.env.APPIUM_TMP_DIR = args.tmpDir;
     }
@@ -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
@@ -51,12 +51,17 @@ class AppiumDriver extends BaseDriver {
     // It is not recommended to access this property directly from the outside
     this.pendingDrivers = {};
 
-    this.plugins = [];
+    this.pluginClasses = []; // list of which plugins are active
+    this.sessionPlugins = {}; // map of sessions to actual plugin instances per session
+    this.sessionlessPlugins = []; // some commands are sessionless, so we need a set of plugins for them
 
     // allow this to happen in the background, so no `await`
     updateBuildInfo();
   }
 
+  /** @type {DriverConfig|undefined} */
+  driverConfig;
+
   /**
    * Cancel commands queueing for the umbrella Appium driver
    */
@@ -85,11 +90,20 @@ class AppiumDriver extends BaseDriver {
       .map(([id, driver]) => ({id, capabilities: driver.caps}));
   }
 
-  printNewSessionAnnouncement (driverName, driverVersion) {
-    const introString = driverVersion
+  printNewSessionAnnouncement (driverName, driverVersion, driverBaseVersion) {
+    log.info(driverVersion
       ? `Appium v${APPIUM_VER} creating new ${driverName} (v${driverVersion}) session`
-      : `Appium v${APPIUM_VER} creating new ${driverName} session`;
-    log.info(introString);
+      : `Appium v${APPIUM_VER} creating new ${driverName} session`
+    );
+    log.info(`Checking BaseDriver versions for Appium and ${driverName}`);
+    log.info(AppiumDriver.baseVersion
+      ? `Appium's BaseDriver version is ${AppiumDriver.baseVersion}`
+      : `Could not determine Appium's BaseDriver version`
+    );
+    log.info(driverBaseVersion
+      ? `${driverName}'s BaseDriver version is ${driverBaseVersion}`
+      : `Could not determine ${driverName}'s BaseDriver version`
+    );
   }
 
   /**
@@ -100,6 +114,21 @@ class AppiumDriver extends BaseDriver {
     return findMatchingDriver(...args);
   }
 
+  /**
+   * Validate and assign CLI args for a 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 {Object} extInstance the driver or plugin instance
+   */
+  assignCliArgsToExtension (extType, extName, extInstance) {
+    const cliArgs = this.args[extType]?.[extName];
+    if (!_.isEmpty(cliArgs)) {
+      extInstance.cliArgs = cliArgs;
+    }
+  }
+
   /**
    * Create a new session
    * @param {Object} jsonwpCaps JSONWP formatted desired capabilities
@@ -144,16 +173,18 @@ class AppiumDriver extends BaseDriver {
 
       const {
         driver: InnerDriver,
-        version: driverVersion
+        version: driverVersion,
+        driverName
       } = this._findMatchingDriver(this.driverConfig, desiredCaps);
-      this.printNewSessionAnnouncement(InnerDriver.name, driverVersion);
+      this.printNewSessionAnnouncement(InnerDriver.name, driverVersion, InnerDriver.baseVersion);
 
       if (this.args.sessionOverride) {
         await this.deleteAllSessions();
       }
 
       let runningDriversData, otherPendingDriversData;
-      const d = new InnerDriver(this.args);
+
+      const driverInstance = new InnerDriver(this.args, true);
 
       // We want to assign security values directly on the driver. The driver
       // should not read security values from `this.opts` because those values
@@ -163,23 +194,34 @@ class AppiumDriver extends BaseDriver {
         log.info(`Applying relaxed security to '${InnerDriver.name}' as per ` +
                  `server command line argument. All insecure features will be ` +
                  `enabled unless explicitly disabled by --deny-insecure`);
-        d.relaxedSecurityEnabled = true;
+        driverInstance.relaxedSecurityEnabled = true;
       }
 
       if (!_.isEmpty(this.args.denyInsecure)) {
         log.info('Explicitly preventing use of insecure features:');
         this.args.denyInsecure.map((a) => log.info(`    ${a}`));
-        d.denyInsecure = this.args.denyInsecure;
+        driverInstance.denyInsecure = this.args.denyInsecure;
       }
 
       if (!_.isEmpty(this.args.allowInsecure)) {
         log.info('Explicitly enabling use of insecure features:');
         this.args.allowInsecure.map((a) => log.info(`    ${a}`));
-        d.allowInsecure = this.args.allowInsecure;
+        driverInstance.allowInsecure = this.args.allowInsecure;
       }
 
+      // 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, driverInstance);
+
+
       // This assignment is required for correct web sockets functionality inside the driver
-      d.server = this.server;
+      driverInstance.server = this.server;
+
+      // Drivers/plugins might also want to know where they are hosted
+      driverInstance.serverHost = this.args.address;
+      driverInstance.serverPort = this.args.port;
+      driverInstance.serverPath = this.args.basePath;
+
       try {
         runningDriversData = await this.curSessionDataForDriver(InnerDriver);
       } catch (e) {
@@ -188,43 +230,43 @@ class AppiumDriver extends BaseDriver {
       await pendingDriversGuard.acquire(AppiumDriver.name, () => {
         this.pendingDrivers[InnerDriver.name] = this.pendingDrivers[InnerDriver.name] || [];
         otherPendingDriversData = this.pendingDrivers[InnerDriver.name].map((drv) => drv.driverData);
-        this.pendingDrivers[InnerDriver.name].push(d);
+        this.pendingDrivers[InnerDriver.name].push(driverInstance);
       });
 
       try {
-        [innerSessionId, dCaps] = await d.createSession(
+        [innerSessionId, dCaps] = await driverInstance.createSession(
           processedJsonwpCapabilities,
           reqCaps,
           processedW3CCapabilities,
           [...runningDriversData, ...otherPendingDriversData]
         );
-        protocol = d.protocol;
+        protocol = driverInstance.protocol;
         await sessionsListGuard.acquire(AppiumDriver.name, () => {
-          this.sessions[innerSessionId] = d;
+          this.sessions[innerSessionId] = driverInstance;
         });
       } finally {
         await pendingDriversGuard.acquire(AppiumDriver.name, () => {
-          _.pull(this.pendingDrivers[InnerDriver.name], d);
+          _.pull(this.pendingDrivers[InnerDriver.name], driverInstance);
         });
       }
 
-      this.attachUnexpectedShutdownHandler(d, innerSessionId);
+      this.attachUnexpectedShutdownHandler(driverInstance, innerSessionId);
 
       log.info(`New ${InnerDriver.name} session created successfully, session ` +
               `${innerSessionId} added to master session list`);
 
       // set the New Command Timeout for the inner driver
-      d.startNewCommandTimeout();
+      driverInstance.startNewCommandTimeout();
 
       // apply initial values to Appium settings (if provided)
-      if (d.isW3CProtocol() && !_.isEmpty(w3cSettings)) {
+      if (driverInstance.isW3CProtocol() && !_.isEmpty(w3cSettings)) {
         log.info(`Applying the initial values to Appium settings parsed from W3C caps: ` +
           JSON.stringify(w3cSettings));
-        await d.updateSettings(w3cSettings);
-      } else if (d.isMjsonwpProtocol() && !_.isEmpty(jwpSettings)) {
+        await driverInstance.updateSettings(w3cSettings);
+      } else if (driverInstance.isMjsonwpProtocol() && !_.isEmpty(jwpSettings)) {
         log.info(`Applying the initial values to Appium settings parsed from MJSONWP caps: ` +
           JSON.stringify(jwpSettings));
-        await d.updateSettings(jwpSettings);
+        await driverInstance.updateSettings(jwpSettings);
       }
     } catch (error) {
       return {
@@ -240,33 +282,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}'?`);
@@ -308,6 +348,7 @@ class AppiumDriver extends BaseDriver {
         // make the session unavailable, because who knows what state it might
         // be in otherwise
         delete this.sessions[sessionId];
+        delete this.sessionPlugins[sessionId];
       });
       return {
         protocol,
@@ -346,11 +387,50 @@ class AppiumDriver extends BaseDriver {
     }
   }
 
-  pluginsToHandleCmd (cmd) {
-    return this.plugins.filter((p) =>
-      p.commands === true ||
-      (_.isArray(p.commands) && _.includes(p.commands, cmd))
-    );
+  /**
+   * 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
+   */
+  pluginsForSession (sessionId = null) {
+    if (sessionId) {
+      if (!this.sessionPlugins[sessionId]) {
+        this.sessionPlugins[sessionId] = this.createPluginInstances();
+      }
+      return this.sessionPlugins[sessionId];
+    }
+
+    if (_.isEmpty(this.sessionlessPlugins)) {
+      this.sessionlessPlugins = this.createPluginInstances();
+    }
+    return this.sessionlessPlugins;
+  }
+
+  /**
+   * To get plugins for a command, we either get the plugin instances associated with the
+   * particular command's session, or in the case of sessionless plugins, pull from the set of
+   * plugin instances reserved for sessionless commands (and we lazily create plugin instances on
+   * first use)
+   *
+   * @param {string} cmd - the name of the command to find a plugin to handle
+   * @param {?string} sessionId - the particular session for which to find a plugin, or null if
+   * sessionless
+   */
+  pluginsToHandleCmd (cmd, sessionId = null) {
+    // 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));
+  }
+
+  createPluginInstances () {
+    return this.pluginClasses.map((PluginClass) => {
+      const name = PluginClass.pluginName;
+      const plugin = new PluginClass(name);
+      this.assignCliArgsToExtension('plugin', name, plugin);
+      return plugin;
+    });
   }
 
   async executeCommand (cmd, ...args) {
@@ -367,14 +447,21 @@ class AppiumDriver extends BaseDriver {
     const isUmbrellaCmd = !isGetStatus && isAppiumDriverCommand(cmd);
     const isSessionCmd = !isGetStatus && !isUmbrellaCmd;
 
-    // get any plugins which are registered as handling this command
-    const plugins = this.pluginsToHandleCmd(cmd);
+    // 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;
     let dstSession = null;
     let protocol = null;
+    let driver = this;
     if (isSessionCmd) {
       sessionId = _.last(args);
       dstSession = await sessionsListGuard.acquire(AppiumDriver.name, () => this.sessions[sessionId]);
@@ -383,8 +470,12 @@ class AppiumDriver extends BaseDriver {
       }
       // now save the response protocol given that the session driver's protocol might differ
       protocol = dstSession.protocol;
+      driver = dstSession;
     }
 
+    // get any plugins which are registered as handling this command
+    const plugins = this.pluginsToHandleCmd(cmd, sessionId);
+
     // now we define a 'cmdHandledBy' object which will keep track of which plugins have handled this
     // command. we care about this because (a) multiple plugins can handle the same command, and
     // (b) there's no guarantee that a plugin will actually call the next() method which runs the
@@ -406,6 +497,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();
       }
@@ -421,17 +524,30 @@ class AppiumDriver extends BaseDriver {
     };
 
     // now take our default behavior, wrap it with any number of plugin behaviors, and run it
-    const wrappedCmd = this.wrapCommandWithPlugins({cmd, args, plugins, cmdHandledBy, next: defaultBehavior});
+    const wrappedCmd = this.wrapCommandWithPlugins({
+      driver, cmd, args, plugins, cmdHandledBy, next: defaultBehavior
+    });
     const res = await this.executeWrappedCommand({wrappedCmd, protocol});
 
     // 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;
   }
 
-  wrapCommandWithPlugins ({cmd, args, next, cmdHandledBy, plugins}) {
+  wrapCommandWithPlugins ({driver, cmd, args, next, cmdHandledBy, plugins}) {
     plugins.length && log.info(`Plugins which can handle cmd '${cmd}': ${plugins.map((p) => p.name)}`);
 
     // now we can go through each plugin and wrap `next` around its own handler, passing the *old*
@@ -444,14 +560,23 @@ class AppiumDriver extends BaseDriver {
       next = ((_next) => async () => {
         log.info(`Plugin ${plugin.name} is now handling cmd '${cmd}'`);
         cmdHandledBy[plugin.name] = true; // if we make it here, this plugin has attempted to handle cmd
-        return await plugin.handle(_next, this, cmd, ...args);
+        // first attempt to handle the command via a command-specific handler on the plugin
+        if (plugin[cmd]) {
+          return await plugin[cmd](_next, driver, ...args);
+        }
+        // otherwise, call the generic 'handle' method
+        return await plugin.handle(_next, driver, cmd, ...args);
       })(next);
     }
 
     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
@@ -461,7 +586,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)}.`);
     }
@@ -491,7 +616,6 @@ class AppiumDriver extends BaseDriver {
     return res;
   }
 
-
   proxyActive (sessionId) {
     const dstSession = this.sessions[sessionId];
     return dstSession && _.isFunction(dstSession.proxyActive) && dstSession.proxyActive(sessionId);
@@ -514,4 +638,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 };