@appium/base-driver 8.3.1 → 8.4.0

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/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/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
 };

package/lib/protocol/protocol.js

@@ -16,8 +16,6 @@ const CREATE_SESSION_COMMAND = 'createSession';
 const DELETE_SESSION_COMMAND = 'deleteSession';
 const GET_STATUS_COMMAND = 'getStatus';
 
-class Protocol {}
-
 function determineProtocol (createSessionArgs) {
   return _.some(createSessionArgs, isW3cCaps) ? PROTOCOLS.W3C : PROTOCOLS.MJSONWP;
 }
@@ -456,7 +454,7 @@ async function doJwpProxy (driver, req, res) {
 
 
 export {
-  Protocol, routeConfiguringFunction, isSessionCommand,
+  routeConfiguringFunction, isSessionCommand,
   driverShouldDoJwpProxy, determineProtocol, CREATE_SESSION_COMMAND,
   DELETE_SESSION_COMMAND, GET_STATUS_COMMAND,
 };

package/lib/protocol/routes.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 import _ from 'lodash';
 import { util } from '@appium/support';
 import { PROTOCOLS, DEFAULT_BASE_PATH } from '../constants';
@@ -14,6 +16,7 @@ const SET_ALERT_TEXT_PAYLOAD_PARAMS = {
 // define the routes, mapping of HTTP methods to particular driver commands,
 // and any parameters that are expected in a request
 // parameters can be `required` or `optional`
+/** @type {import('@appium/types').MethodMap} */
 const METHOD_MAP = {
   '/status': {
     GET: {command: 'getStatus'}
@@ -240,6 +243,12 @@ const METHOD_MAP = {
   '/session/:sessionId/element/:elementId/shadow': {
     GET: {command: 'elementShadowRoot'}
   },
+  '/session/:sessionId/shadow/:shadowId/element': {
+    POST: {command: 'findElementFromShadowRoot', payloadParams: {required: ['using', 'value']}}
+  },
+  '/session/:sessionId/shadow/:shadowId/elements': {
+    POST: {command: 'findElementsFromShadowRoot', payloadParams: {required: ['using', 'value']}}
+  },
   '/session/:sessionId/element/:elementId/css/:propertyName': {
     GET: {command: 'getCssProperty'}
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/base-driver",
-  "version": "8.3.1",
+  "version": "8.4.0",
   "description": "Base driver class for Appium drivers",
   "keywords": [
     "automation",
@@ -37,10 +37,10 @@
     "!build/test/e2e/fixtures"
   ],
   "scripts": {
-    "build": "npm run build:sources && npm run build:test",
-    "build:sources": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build": "npm run build:distfiles && npm run build:test",
+    "build:distfiles": "babel lib --root-mode=upward --out-dir=build/lib",
     "build:test": "babel test --root-mode=upward --out-dir=build/test --copy-files",
-    "dev": "npm run build -- --watch",
+    "dev": "run-p \"build:distfiles -- --watch\" \"build:test -- --watch\"",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
     "test": "npm run test:unit",
@@ -48,19 +48,19 @@
     "test:unit": "mocha --require ../../test/setup-babel.js \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/support": "^2.56.1",
-    "@babel/runtime": "7.17.8",
+    "@appium/support": "^2.57.0",
+    "@babel/runtime": "7.17.9",
     "@colors/colors": "1.5.0",
     "async-lock": "1.3.1",
     "asyncbox": "2.9.2",
     "axios": "0.26.1",
     "bluebird": "3.7.2",
-    "body-parser": "1.19.2",
+    "body-parser": "1.20.0",
     "es6-error": "4.1.1",
     "express": "4.17.3",
     "http-status-codes": "2.2.0",
     "lodash": "4.17.21",
-    "lru-cache": "7.7.1",
+    "lru-cache": "7.7.3",
     "method-override": "3.0.0",
     "morgan": "1.10.0",
     "serve-favicon": "2.5.0",
@@ -75,5 +75,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6d35def9ed754121fee691cdaf7b30e3a7ac3e8b"
+  "types": "./build/lib/index.d.ts",
+  "gitHead": "3ec3a0efa590e22e264ffbd23316ee5714a12081"
 }

package/test/basedriver/driver-tests.js

@@ -10,6 +10,35 @@ function baseDriverUnitTests (DriverClass, defaultCaps = {}) {
   // to display the driver under test in report
   const className = DriverClass.name || '(unknown driver)';
 
+  describe('static property', function () {
+    describe('baseVersion', function () {
+      it('should exist', function () {
+        DriverClass.baseVersion.should.exist;
+      });
+    });
+  });
+
+  describe('Log prefix', function () {
+
+    it('should setup log prefix', async function () {
+      const d = new DriverClass();
+      const previousPrefix = d.log.prefix;
+      await d.createSession({
+        alwaysMatch: Object.assign({}, defaultCaps, {
+          platformName: 'Fake',
+          'appium:deviceName': 'Commodore 64',
+        }),
+        firstMatch: [{}],
+      });
+      try {
+        previousPrefix.should.not.eql(d.log.prefix);
+      } finally {
+        await d.deleteSession();
+        previousPrefix.should.eql(d.log.prefix);
+      }
+    });
+
+  });
 
   describe(`BaseDriver (as ${className})`, function () {
     let d, w3cCaps;
@@ -183,8 +212,8 @@ function baseDriverUnitTests (DriverClass, defaultCaps = {}) {
         throw new Error('multipass');
       }.bind(d);
 
-      afterEach(function () {
-        d.clearNewCommandTimeout();
+      afterEach(async function () {
+        await d.clearNewCommandTimeout();
       });
 
       it('should queue commands and.executeCommand/respond in the order received', async function () {