@appium/base-driver 8.3.0 → 8.4.1

package/lib/basedriver/helpers.js

@@ -2,7 +2,7 @@ import _ from 'lodash';
 import path from 'path';
 import url from 'url';
 import logger from './logger';
-import { tempDir, fs, util, zip, net, timing } from '@appium/support';
+import { tempDir, fs, util, zip, net, timing, node } from '@appium/support';
 import LRU from 'lru-cache';
 import AsyncLock from 'async-lock';
 import axios from 'axios';
@@ -546,6 +546,22 @@ function parseCapsArray (cap) {
   throw new Error(`must provide a string or JSON Array; received ${cap}`);
 }
 
+/**
+ * Generate a string that uniquely describes driver instance
+ *
+ * @param {import('@appium/types').Core} obj driver instance
+ * @param {string?} sessionId session identifier (if exists)
+ * @returns {string}
+ */
+function generateDriverLogPrefix (obj, sessionId = null) {
+  const instanceName = `${obj.constructor.name}@${node.getObjectId(obj).substring(0, 4)}`;
+  return sessionId ? `${instanceName} (${sessionId.substring(0, 8)})` : instanceName;
+}
+
+/** @type {import('@appium/types').DriverHelpers} */
+export default {
+  configureApp, isPackageOrBundle, duplicateKeys, parseCapsArray, generateDriverLogPrefix
+};
 export {
-  configureApp, isPackageOrBundle, duplicateKeys, parseCapsArray
+  configureApp, isPackageOrBundle, duplicateKeys, parseCapsArray, generateDriverLogPrefix
 };

package/lib/express/websocket.js

@@ -1,5 +1,6 @@
 import _ from 'lodash';
-import url from 'url';
+import { URL } from 'url';
+import B from 'bluebird';
 
 const DEFAULT_WS_PATHNAME_PREFIX = '/ws';
 
@@ -18,29 +19,28 @@ const DEFAULT_WS_PATHNAME_PREFIX = '/ws';
  * on how to configure the handler properly.
  */
 async function addWebSocketHandler (handlerPathname, handlerServer) { // eslint-disable-line require-await
-  let isUpgradeListenerAssigned = true;
   if (_.isUndefined(this.webSocketsMapping)) {
     this.webSocketsMapping = {};
-    isUpgradeListenerAssigned = false;
+    // https://github.com/websockets/ws/pull/885
+    this.on('upgrade', (request, socket, head) => {
+      let currentPathname;
+      try {
+        currentPathname = (new URL(request.url)).pathname;
+      } catch (ign) {
+        currentPathname = request.url;
+      }
+      for (const [pathname, wsServer] of _.toPairs(this.webSocketsMapping)) {
+        if (currentPathname === pathname) {
+          wsServer.handleUpgrade(request, socket, head, (ws) => {
+            wsServer.emit('connection', ws, request);
+          });
+          return;
+        }
+      }
+      socket.destroy();
+    });
   }
   this.webSocketsMapping[handlerPathname] = handlerServer;
-  if (isUpgradeListenerAssigned) {
-    return;
-  }
-
-  // https://github.com/websockets/ws/pull/885
-  this.on('upgrade', (request, socket, head) => {
-    const currentPathname = url.parse(request.url).pathname;
-    for (const [pathname, wsServer] of _.toPairs(this.webSocketsMapping)) {
-      if (currentPathname === pathname) {
-        wsServer.handleUpgrade(request, socket, head, (ws) => {
-          wsServer.emit('connection', ws, request);
-        });
-        return;
-      }
-    }
-    socket.destroy();
-  });
 }
 
 /**
@@ -59,13 +59,12 @@ async function getWebSocketHandlers (keysFilter = null) { // eslint-disable-line
     return {};
   }
 
-  let result = {};
-  for (const [pathname, wsServer] of _.toPairs(this.webSocketsMapping)) {
+  return _.toPairs(this.webSocketsMapping).reduce((acc, [pathname, wsServer]) => {
     if (!_.isString(keysFilter) || pathname.includes(keysFilter)) {
-      result[pathname] = wsServer;
+      acc[pathname] = wsServer;
     }
-  }
-  return result;
+    return acc;
+  }, {});
 }
 
 /**
@@ -79,12 +78,16 @@ async function getWebSocketHandlers (keysFilter = null) { // eslint-disable-line
  * @returns {boolean} true if the handlerPathname was found and deleted
  */
 async function removeWebSocketHandler (handlerPathname) { // eslint-disable-line require-await
-  if (!this.webSocketsMapping || !this.webSocketsMapping[handlerPathname]) {
+  const wsServer = this.webSocketsMapping?.[handlerPathname];
+  if (!wsServer) {
     return false;
   }
 
   try {
-    this.webSocketsMapping[handlerPathname].close();
+    wsServer.close();
+    for (const client of (wsServer.clients || [])) {
+      client.terminate();
+    }
     return true;
   } catch (ign) {
     // ignore
@@ -106,11 +109,11 @@ async function removeAllWebSocketHandlers () {
     return false;
   }
 
-  let result = false;
-  for (const pathname of _.keys(this.webSocketsMapping)) {
-    result = result || await this.removeWebSocketHandler(pathname);
-  }
-  return result;
+  return _.some(
+    await B.all(
+      _.keys(this.webSocketsMapping).map((pathname) => this.removeWebSocketHandler(pathname))
+    )
+  );
 }
 
 export {

package/lib/helpers/capabilities.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import _ from 'lodash';
 
 function isW3cCaps (caps) {
@@ -20,6 +22,63 @@ function isW3cCaps (caps) {
   return false;
 }
 
+/**
+ *
+ * @param {Capabilities} originalCaps
+ * @param {Constraints} desiredCapConstraints
+ * @param {AppiumLogger} log
+ * @returns {Capabilities}
+ */
+function fixCaps (originalCaps, desiredCapConstraints, log) {
+  let caps = _.clone(originalCaps);
+
+  // boolean capabilities can be passed in as strings 'false' and 'true'
+  // which we want to translate into boolean values
+  let booleanCaps = _.keys(
+    _.pickBy(desiredCapConstraints, (k) => k.isBoolean === true),
+  );
+  for (let cap of booleanCaps) {
+    let value = originalCaps[cap];
+    if (_.isString(value)) {
+      value = value.toLowerCase();
+      if (value === 'true' || value === 'false') {
+        log.warn(
+          `Capability '${cap}' changed from string to boolean. This may cause unexpected behavior`,
+        );
+        caps[cap] = value === 'true';
+      }
+    }
+  }
+
+  // int capabilities are often sent in as strings by frameworks
+  let intCaps = _.keys(
+    _.pickBy(desiredCapConstraints, (k) => k.isNumber === true),
+  );
+  for (let cap of intCaps) {
+    let value = originalCaps[cap];
+    if (_.isString(value)) {
+      value = value.trim();
+      let newValue = parseInt(value, 10);
+      if (value !== `${newValue}`) {
+        newValue = parseFloat(value);
+      }
+      log.warn(
+        `Capability '${cap}' changed from string ('${value}') to integer (${newValue}). This may cause unexpected behavior`,
+      );
+      caps[cap] = newValue;
+    }
+  }
+
+  return caps;
+}
+
 export {
   isW3cCaps,
-};
+  fixCaps
+};
+
+/**
+ * @typedef {import('@appium/types').Capabilities} Capabilities
+ * @typedef {import('@appium/types').Constraints} Constraints
+ * @typedef {import('@appium/types').AppiumLogger} AppiumLogger
+ */

package/lib/index.js

@@ -1,11 +1,15 @@
-// transpile:main
+// @ts-check
 
-// BaseDriver exports
-import * as driver from './basedriver/driver';
-import * as deviceSettings from './basedriver/device-settings';
+import B from 'bluebird';
+
+B.config({
+  cancellation: true,
+});
 
-const { BaseDriver } = driver;
-const { DeviceSettings } = deviceSettings;
+// BaseDriver exports
+import { BaseDriver } from './basedriver/driver';
+export { DriverCore } from './basedriver/core';
+import { DeviceSettings } from './basedriver/device-settings';
 
 export { BaseDriver, DeviceSettings };
 export default BaseDriver;
@@ -18,19 +22,19 @@ import {
 } from './constants';
 
 const {
-  Protocol, routeConfiguringFunction, errors, isErrorType,
+  routeConfiguringFunction, errors, isErrorType,
   errorFromMJSONWPStatusCode, errorFromW3CJsonCode, ALL_COMMANDS, METHOD_MAP,
   routeToCommandName, NO_SESSION_ID_COMMANDS, isSessionCommand,
-  normalizeBasePath, determineProtocol, CREATE_SESSION_COMMAND,
+  determineProtocol, CREATE_SESSION_COMMAND,
   DELETE_SESSION_COMMAND, GET_STATUS_COMMAND,
 } = protocol;
 
 export {
-  Protocol, routeConfiguringFunction, errors, isErrorType, PROTOCOLS,
+  routeConfiguringFunction, errors, isErrorType, PROTOCOLS,
   errorFromMJSONWPStatusCode, errorFromW3CJsonCode, determineProtocol,
   errorFromMJSONWPStatusCode as errorFromCode, ALL_COMMANDS, METHOD_MAP,
   routeToCommandName, NO_SESSION_ID_COMMANDS, isSessionCommand,
-  DEFAULT_BASE_PATH, normalizeBasePath, CREATE_SESSION_COMMAND,
+  DEFAULT_BASE_PATH, CREATE_SESSION_COMMAND,
   DELETE_SESSION_COMMAND, GET_STATUS_COMMAND,
 };
 
@@ -40,8 +44,8 @@ const { STATIC_DIR } = staticIndex;
 export { STATIC_DIR };
 
 import * as serverIndex from './express/server';
-const { server } = serverIndex;
-export { server };
+const { server, normalizeBasePath } = serverIndex;
+export { server, normalizeBasePath };
 
 // jsonwp-proxy exports
 import * as proxyIndex from './jsonwp-proxy/proxy';

package/lib/jsonwp-proxy/proxy.js

@@ -3,7 +3,8 @@ import { logger, util } from '@appium/support';
 import axios from 'axios';
 import { getSummaryByCode } from '../jsonwp-status/status';
 import {
-  errors, isErrorType, errorFromMJSONWPStatusCode, errorFromW3CJsonCode
+  errors, isErrorType, errorFromMJSONWPStatusCode, errorFromW3CJsonCode,
+  getResponseForW3CError,
 } from '../protocol/errors';
 import { routeToCommandName } from '../protocol';
 import { MAX_LOG_BODY_LENGTH, DEFAULT_BASE_PATH, PROTOCOLS } from '../constants';
@@ -312,15 +313,34 @@ class JWProxy {
   }
 
   async proxyReqRes (req, res) {
-    const [response, resBodyObj] = await this.proxyCommand(req.originalUrl, req.method, req.body);
+    // ! this method must not throw any exceptions
+    // ! make sure to call res.send before return
+    let statusCode;
+    let resBodyObj;
+    try {
+      let response;
+      [response, resBodyObj] = await this.proxyCommand(req.originalUrl, req.method, req.body);
+      res.headers = response.headers;
+      statusCode = response.statusCode;
+    } catch (err) {
+      [statusCode, resBodyObj] = getResponseForW3CError(
+        isErrorType(err, errors.ProxyRequestError) ? err.getActualError() : err
+      );
+    }
+    res.set('content-type', 'application/json; charset=utf-8');
+    if (!_.isPlainObject(resBodyObj)) {
+      const error = new errors.UnknownError(
+        `The downstream server response with the status code ${statusCode} is not a valid JSON object: ` +
+        _.truncate(`${resBodyObj}`, {length: 300})
+      );
+      [statusCode, resBodyObj] = getResponseForW3CError(error);
+    }
 
-    res.headers = response.headers;
-    res.set('content-type', response.headers['content-type']);
     // if the proxied response contains a sessionId that the downstream
     // driver has generated, we don't want to return that to the client.
     // Instead, return the id from the request or from current session
-    const reqSessionId = this.getSessionIdFromUrl(req.originalUrl);
     if (_.has(resBodyObj, 'sessionId')) {
+      const reqSessionId = this.getSessionIdFromUrl(req.originalUrl);
       if (reqSessionId) {
         this.log.info(`Replacing sessionId ${resBodyObj.sessionId} with ${reqSessionId}`);
         resBodyObj.sessionId = reqSessionId;
@@ -330,7 +350,7 @@ class JWProxy {
       }
     }
     resBodyObj.value = formatResponseValue(resBodyObj.value);
-    res.status(response.statusCode).send(JSON.stringify(formatStatus(resBodyObj)));
+    res.status(statusCode).send(JSON.stringify(formatStatus(resBodyObj)));
   }
 }
 

package/lib/protocol/errors.js

@@ -9,7 +9,7 @@ const w3cLog = logger.getLogger('W3C');
 const W3C_UNKNOWN_ERROR = 'unknown error';
 
 // base error class for all of our errors
-class ProtocolError extends ES6Error {
+export class ProtocolError extends ES6Error {
   constructor (msg, jsonwpCode, w3cStatus, error) {
     super(msg);
     this.jsonwpCode = jsonwpCode;
@@ -34,7 +34,7 @@ class ProtocolError extends ES6Error {
 // https://github.com/SeleniumHQ/selenium/issues/5562#issuecomment-370379470
 // https://w3c.github.io/webdriver/webdriver-spec.html#dfn-error-code
 
-class NoSuchDriverError extends ProtocolError {
+export class NoSuchDriverError extends ProtocolError {
   static code () {
     return 6;
   }
@@ -51,7 +51,7 @@ class NoSuchDriverError extends ProtocolError {
   }
 }
 
-class NoSuchElementError extends ProtocolError {
+export class NoSuchElementError extends ProtocolError {
   static code () {
     return 7;
   }
@@ -68,7 +68,7 @@ class NoSuchElementError extends ProtocolError {
   }
 }
 
-class NoSuchFrameError extends ProtocolError {
+export class NoSuchFrameError extends ProtocolError {
   static code () {
     return 8;
   }
@@ -85,7 +85,7 @@ class NoSuchFrameError extends ProtocolError {
   }
 }
 
-class UnknownCommandError extends ProtocolError {
+export class UnknownCommandError extends ProtocolError {
   static code () {
     return 9;
   }
@@ -102,7 +102,7 @@ class UnknownCommandError extends ProtocolError {
   }
 }
 
-class StaleElementReferenceError extends ProtocolError {
+export class StaleElementReferenceError extends ProtocolError {
   static code () {
     return 10;
   }
@@ -119,7 +119,7 @@ class StaleElementReferenceError extends ProtocolError {
   }
 }
 
-class ElementNotVisibleError extends ProtocolError {
+export class ElementNotVisibleError extends ProtocolError {
   static code () {
     return 11;
   }
@@ -136,7 +136,7 @@ class ElementNotVisibleError extends ProtocolError {
   }
 }
 
-class InvalidElementStateError extends ProtocolError {
+export class InvalidElementStateError extends ProtocolError {
   static code () {
     return 12;
   }
@@ -154,7 +154,7 @@ class InvalidElementStateError extends ProtocolError {
   }
 }
 
-class UnknownError extends ProtocolError {
+export class UnknownError extends ProtocolError {
   static code () {
     return 13;
   }
@@ -174,7 +174,7 @@ class UnknownError extends ProtocolError {
   }
 }
 
-class UnknownMethodError extends ProtocolError {
+export class UnknownMethodError extends ProtocolError {
   static code () {
     return 405;
   }
@@ -190,7 +190,7 @@ class UnknownMethodError extends ProtocolError {
   }
 }
 
-class UnsupportedOperationError extends ProtocolError {
+export class UnsupportedOperationError extends ProtocolError {
   static code () {
     return 405;
   }
@@ -207,7 +207,7 @@ class UnsupportedOperationError extends ProtocolError {
   }
 }
 
-class ElementIsNotSelectableError extends ProtocolError {
+export class ElementIsNotSelectableError extends ProtocolError {
   static code () {
     return 15;
   }
@@ -224,7 +224,7 @@ class ElementIsNotSelectableError extends ProtocolError {
   }
 }
 
-class ElementClickInterceptedError extends ProtocolError {
+export class ElementClickInterceptedError extends ProtocolError {
   static code () {
     return 64;
   }
@@ -242,7 +242,7 @@ class ElementClickInterceptedError extends ProtocolError {
   }
 }
 
-class ElementNotInteractableError extends ProtocolError {
+export class ElementNotInteractableError extends ProtocolError {
   static code () {
     return 60;
   }
@@ -259,7 +259,7 @@ class ElementNotInteractableError extends ProtocolError {
   }
 }
 
-class InsecureCertificateError extends ProtocolError {
+export class InsecureCertificateError extends ProtocolError {
   static error () {
     return 'insecure certificate';
   }
@@ -269,7 +269,7 @@ class InsecureCertificateError extends ProtocolError {
   }
 }
 
-class JavaScriptError extends ProtocolError {
+export class JavaScriptError extends ProtocolError {
   static code () {
     return 17;
   }
@@ -285,7 +285,7 @@ class JavaScriptError extends ProtocolError {
   }
 }
 
-class XPathLookupError extends ProtocolError {
+export class XPathLookupError extends ProtocolError {
   static code () {
     return 19;
   }
@@ -301,7 +301,7 @@ class XPathLookupError extends ProtocolError {
   }
 }
 
-class TimeoutError extends ProtocolError {
+export class TimeoutError extends ProtocolError {
   static code () {
     return 21;
   }
@@ -317,7 +317,7 @@ class TimeoutError extends ProtocolError {
   }
 }
 
-class NoSuchWindowError extends ProtocolError {
+export class NoSuchWindowError extends ProtocolError {
   static code () {
     return 23;
   }
@@ -334,7 +334,7 @@ class NoSuchWindowError extends ProtocolError {
   }
 }
 
-class InvalidArgumentError extends ProtocolError {
+export class InvalidArgumentError extends ProtocolError {
   static code () {
     return 61;
   }
@@ -351,7 +351,7 @@ class InvalidArgumentError extends ProtocolError {
   }
 }
 
-class InvalidCookieDomainError extends ProtocolError {
+export class InvalidCookieDomainError extends ProtocolError {
   static code () {
     return 24;
   }
@@ -368,7 +368,7 @@ class InvalidCookieDomainError extends ProtocolError {
   }
 }
 
-class NoSuchCookieError extends ProtocolError {
+export class NoSuchCookieError extends ProtocolError {
   static code () {
     return 62;
   }
@@ -384,7 +384,7 @@ class NoSuchCookieError extends ProtocolError {
   }
 }
 
-class UnableToSetCookieError extends ProtocolError {
+export class UnableToSetCookieError extends ProtocolError {
   static code () {
     return 25;
   }
@@ -400,7 +400,7 @@ class UnableToSetCookieError extends ProtocolError {
   }
 }
 
-class UnexpectedAlertOpenError extends ProtocolError {
+export class UnexpectedAlertOpenError extends ProtocolError {
   static code () {
     return 26;
   }
@@ -416,7 +416,7 @@ class UnexpectedAlertOpenError extends ProtocolError {
   }
 }
 
-class NoAlertOpenError extends ProtocolError {
+export class NoAlertOpenError extends ProtocolError {
   static code () {
     return 27;
   }
@@ -432,9 +432,9 @@ class NoAlertOpenError extends ProtocolError {
   }
 }
 
-class NoSuchAlertError extends NoAlertOpenError {}
+export class NoSuchAlertError extends NoAlertOpenError {}
 
-class ScriptTimeoutError extends ProtocolError {
+export class ScriptTimeoutError extends ProtocolError {
   static code () {
     return 28;
   }
@@ -450,7 +450,7 @@ class ScriptTimeoutError extends ProtocolError {
   }
 }
 
-class InvalidElementCoordinatesError extends ProtocolError {
+export class InvalidElementCoordinatesError extends ProtocolError {
   static code () {
     return 29;
   }
@@ -467,9 +467,9 @@ class InvalidElementCoordinatesError extends ProtocolError {
   }
 }
 
-class InvalidCoordinatesError extends InvalidElementCoordinatesError {}
+export class InvalidCoordinatesError extends InvalidElementCoordinatesError {}
 
-class IMENotAvailableError extends ProtocolError {
+export class IMENotAvailableError extends ProtocolError {
   static code () {
     return 30;
   }
@@ -485,7 +485,7 @@ class IMENotAvailableError extends ProtocolError {
   }
 }
 
-class IMEEngineActivationFailedError extends ProtocolError {
+export class IMEEngineActivationFailedError extends ProtocolError {
   static code () {
     return 31;
   }
@@ -502,7 +502,7 @@ class IMEEngineActivationFailedError extends ProtocolError {
   }
 }
 
-class InvalidSelectorError extends ProtocolError {
+export class InvalidSelectorError extends ProtocolError {
   static code () {
     return 32;
   }
@@ -519,7 +519,7 @@ class InvalidSelectorError extends ProtocolError {
   }
 }
 
-class SessionNotCreatedError extends ProtocolError {
+export class SessionNotCreatedError extends ProtocolError {
   static code () {
     return 33;
   }
@@ -539,7 +539,7 @@ class SessionNotCreatedError extends ProtocolError {
   }
 }
 
-class MoveTargetOutOfBoundsError extends ProtocolError {
+export class MoveTargetOutOfBoundsError extends ProtocolError {
   static code () {
     return 34;
   }
@@ -555,7 +555,7 @@ class MoveTargetOutOfBoundsError extends ProtocolError {
   }
 }
 
-class NoSuchContextError extends ProtocolError {
+export class NoSuchContextError extends ProtocolError {
   static code () {
     return 35;
   }
@@ -564,7 +564,7 @@ class NoSuchContextError extends ProtocolError {
   }
 }
 
-class InvalidContextError extends ProtocolError {
+export class InvalidContextError extends ProtocolError {
   static code () {
     return 36;
   }
@@ -575,18 +575,18 @@ class InvalidContextError extends ProtocolError {
 }
 
 // These are aliases for UnknownMethodError
-class NotYetImplementedError extends UnknownMethodError {
+export class NotYetImplementedError extends UnknownMethodError {
   constructor (err) {
     super(err || 'Method has not yet been implemented');
   }
 }
-class NotImplementedError extends UnknownMethodError {
+export class NotImplementedError extends UnknownMethodError {
   constructor (err) {
     super(err || 'Method is not implemented');
   }
 }
 
-class UnableToCaptureScreen extends ProtocolError {
+export class UnableToCaptureScreen extends ProtocolError {
   static code () {
     return 63;
   }
@@ -604,7 +604,7 @@ class UnableToCaptureScreen extends ProtocolError {
 
 
 // Equivalent to W3C InvalidArgumentError
-class BadParametersError extends ES6Error {
+export class BadParametersError extends ES6Error {
   static error () {
     return 'invalid argument';
   }
@@ -628,7 +628,7 @@ class BadParametersError extends ES6Error {
  * In case of ProxyRequestError should fetch the actual error by calling `getActualError()`
  * for proxy failure to generate the client response.
  */
-class ProxyRequestError extends ES6Error {
+export class ProxyRequestError extends ES6Error {
   constructor (err, responseError, httpStatus) {
     let responseErrorObj = util.safeJsonParse(responseError);
     if (!_.isPlainObject(responseErrorObj)) {
@@ -864,7 +864,7 @@ function getResponseForJsonwpError (err) {
 }
 
 export {
-  ProtocolError, errors, isErrorType, isUnknownError,
+  errors, isErrorType, isUnknownError,
   errorFromMJSONWPStatusCode, errorFromW3CJsonCode,
   getResponseForW3CError, getResponseForJsonwpError,
 };

package/lib/protocol/index.js

@@ -1,8 +1,8 @@
 // transpile:main
 
 import {
-  Protocol, isSessionCommand, routeConfiguringFunction, determineProtocol,
-  CREATE_SESSION_COMMAND, DELETE_SESSION_COMMAND,
+  isSessionCommand, routeConfiguringFunction, determineProtocol,
+  CREATE_SESSION_COMMAND, DELETE_SESSION_COMMAND, GET_STATUS_COMMAND
 } from './protocol';
 import {
   NO_SESSION_ID_COMMANDS, ALL_COMMANDS, METHOD_MAP,
@@ -13,8 +13,8 @@ import {
 } from './errors';
 
 export {
-  Protocol, routeConfiguringFunction, errors, isErrorType,
+  routeConfiguringFunction, errors, isErrorType,
   errorFromMJSONWPStatusCode, errorFromW3CJsonCode, ALL_COMMANDS, METHOD_MAP,
   routeToCommandName, NO_SESSION_ID_COMMANDS, isSessionCommand, determineProtocol,
-  CREATE_SESSION_COMMAND, DELETE_SESSION_COMMAND,
+  CREATE_SESSION_COMMAND, DELETE_SESSION_COMMAND, GET_STATUS_COMMAND
 };