@appium/base-driver 8.2.4 → 8.3.0

package/lib/protocol/protocol.js

@@ -1,5 +1,5 @@
 import _ from 'lodash';
-import { util } from '@appium/support';
+import { util, logger, node } from '@appium/support';
 import { validators } from './validators';
 import {
   errors, isErrorType, getResponseForW3CError,
@@ -7,11 +7,9 @@ import {
 } from './errors';
 import { METHOD_MAP, NO_SESSION_ID_COMMANDS } from './routes';
 import B from 'bluebird';
-import {
-  formatResponseValue, formatStatus,
-} from './helpers';
+import { formatResponseValue, formatStatus } from './helpers';
 import { MAX_LOG_BODY_LENGTH, PROTOCOLS, DEFAULT_BASE_PATH } from '../constants';
-import SESSIONS_CACHE from './sessions-cache';
+import { isW3cCaps } from '../helpers/capabilities';
 
 
 const CREATE_SESSION_COMMAND = 'createSession';
@@ -20,10 +18,8 @@ const GET_STATUS_COMMAND = 'getStatus';
 
 class Protocol {}
 
-function determineProtocol (desiredCapabilities, requiredCapabilities, capabilities) {
-  return _.isPlainObject(capabilities) ?
-    PROTOCOLS.W3C :
-    PROTOCOLS.MJSONWP;
+function determineProtocol (createSessionArgs) {
+  return _.some(createSessionArgs, isW3cCaps) ? PROTOCOLS.W3C : PROTOCOLS.MJSONWP;
 }
 
 function extractProtocol (driver, sessionId = null) {
@@ -38,13 +34,30 @@ function extractProtocol (driver, sessionId = null) {
   }
 
   // Extract the protocol for the current session if the given driver is the umbrella one
-  return dstDriver ? dstDriver.protocol : SESSIONS_CACHE.getProtocol(sessionId);
+  return dstDriver?.protocol ?? PROTOCOLS.W3C;
 }
 
 function isSessionCommand (command) {
   return !_.includes(NO_SESSION_ID_COMMANDS, command);
 }
 
+function getLogger (driver, sessionId = null) {
+  const dstDriver = sessionId && _.isFunction(driver.driverForSession)
+    ? (driver.driverForSession(sessionId) ?? driver)
+    : driver;
+  if (_.isFunction(dstDriver.log?.info)) {
+    return dstDriver.log;
+  }
+
+  let logPrefix = dstDriver.constructor
+    ? `${dstDriver.constructor.name}@${node.getObjectId(dstDriver).substring(0, 8)}`
+    : 'AppiumDriver';
+  if (sessionId) {
+    logPrefix += ` (${sessionId.substring(0, 8)})`;
+  }
+  return logger.getLogger(logPrefix);
+}
+
 function wrapParams (paramSets, jsonObj) {
   /* There are commands like performTouch which take a single parameter (primitive type or array).
    * Some drivers choose to pass this parameter as a value (eg. [action1, action2...]) while others to
@@ -192,11 +205,11 @@ function makeArgs (requestParams, jsonObj, payloadParams, protocol) {
 
 function routeConfiguringFunction (driver) {
   if (!driver.sessionExists) {
-    throw new Error('Drivers used with MJSONWP must implement `sessionExists`');
+    throw new Error('Drivers must implement `sessionExists` property');
   }
 
   if (!(driver.executeCommand || driver.execute)) {
-    throw new Error('Drivers used with MJSONWP must implement `executeCommand` or `execute`');
+    throw new Error('Drivers must implement `executeCommand` or `execute` method');
   }
 
   // return a function which will add all the routes to the driver. Here extraMethods might be
@@ -247,7 +260,7 @@ function buildHandler (app, method, path, spec, driver, isSessCmd) {
           await doJwpProxy(driver, req, res);
           return;
         }
-        SESSIONS_CACHE.getLogger(req.params.sessionId, currentProtocol).debug(`Would have proxied ` +
+        getLogger(driver, req.params.sessionId).debug(`Would have proxied ` +
           `command directly, but a plugin exists which might require its value, so will let ` +
           `its value be collected internally and made part of plugin chain`);
         didPluginOverrideProxy = true;
@@ -272,7 +285,7 @@ function buildHandler (app, method, path, spec, driver, isSessCmd) {
       if (spec.command === CREATE_SESSION_COMMAND) {
         // try to determine protocol by session creation args, so we can throw a
         // properly formatted error if arguments validation fails
-        currentProtocol = determineProtocol(...makeArgs(req.params, jsonObj, spec.payloadParams || {}));
+        currentProtocol = determineProtocol(makeArgs(req.params, jsonObj, spec.payloadParams || {}));
       }
 
       // ensure that the json payload conforms to the spec
@@ -288,7 +301,7 @@ function buildHandler (app, method, path, spec, driver, isSessCmd) {
       }
 
       // run the driver command wrapped inside the argument validators
-      SESSIONS_CACHE.getLogger(req.params.sessionId, currentProtocol).debug(`Calling ` +
+      getLogger(driver, req.params.sessionId).debug(`Calling ` +
         `${driver.constructor.name}.${spec.command}() with args: ` +
         _.truncate(JSON.stringify(args), {length: MAX_LOG_BODY_LENGTH}));
 
@@ -317,8 +330,7 @@ function buildHandler (app, method, path, spec, driver, isSessCmd) {
       // unpack createSession response
       if (spec.command === CREATE_SESSION_COMMAND) {
         newSessionId = driverRes[0];
-        SESSIONS_CACHE.putSession(newSessionId, currentProtocol);
-        SESSIONS_CACHE.getLogger(newSessionId, currentProtocol)
+        getLogger(driver, newSessionId)
           .debug(`Cached the protocol value '${currentProtocol}' for the new session ${newSessionId}`);
         if (currentProtocol === PROTOCOLS.MJSONWP) {
           driverRes = driverRes[1];
@@ -333,9 +345,9 @@ function buildHandler (app, method, path, spec, driver, isSessCmd) {
 
       // delete should not return anything even if successful
       if (spec.command === DELETE_SESSION_COMMAND) {
-        SESSIONS_CACHE.getLogger(req.params.sessionId, currentProtocol)
+        getLogger(driver, req.params.sessionId)
           .debug(`Received response: ${_.truncate(JSON.stringify(driverRes), {length: MAX_LOG_BODY_LENGTH})}`);
-        SESSIONS_CACHE.getLogger(req.params.sessionId, currentProtocol).debug('But deleting session, so not returning');
+        getLogger(driver, req.params.sessionId).debug('But deleting session, so not returning');
         driverRes = null;
       }
 
@@ -349,15 +361,8 @@ function buildHandler (app, method, path, spec, driver, isSessCmd) {
       }
 
       httpResBody.value = driverRes;
-      SESSIONS_CACHE.getLogger(req.params.sessionId || newSessionId, currentProtocol).debug(`Responding ` +
+      getLogger(driver, req.params.sessionId || newSessionId).debug(`Responding ` +
         `to client with driver.${spec.command}() result: ${_.truncate(JSON.stringify(driverRes), {length: MAX_LOG_BODY_LENGTH})}`);
-
-      if (spec.command === DELETE_SESSION_COMMAND) {
-        // We don't want to keep the logger instance in the cache
-        // after the session is deleted, because it contains the logging history
-        // and consumes the memory
-        SESSIONS_CACHE.resetLogger(req.params.sessionId);
-      }
     } catch (err) {
       // if anything goes wrong, figure out what our response should be
       // based on the type of error that we encountered
@@ -374,7 +379,7 @@ function buildHandler (app, method, path, spec, driver, isSessCmd) {
       if (isErrorType(err, errors.ProxyRequestError)) {
         actualErr = err.getActualError();
       } else {
-        SESSIONS_CACHE.getLogger(req.params.sessionId || newSessionId, currentProtocol)
+        getLogger(driver, req.params.sessionId || newSessionId)
           .debug(`Encountered internal error running command: ${errMsg}`);
       }
 
@@ -431,7 +436,7 @@ function driverShouldDoJwpProxy (driver, req, command) {
 }
 
 async function doJwpProxy (driver, req, res) {
-  SESSIONS_CACHE.getLogger(req.params.sessionId, extractProtocol(driver, req.params.sessionId))
+  getLogger(driver, req.params.sessionId)
     .info('Driver proxy active, passing request on via HTTP proxy');
 
   // check that the inner driver has a proxy function

package/lib/protocol/routes.js

@@ -1,6 +1,6 @@
 import _ from 'lodash';
 import { util } from '@appium/support';
-import { DEFAULT_BASE_PATH } from '../constants';
+import { PROTOCOLS, DEFAULT_BASE_PATH } from '../constants';
 
 
 const SET_ALERT_TEXT_PAYLOAD_PARAMS = {
@@ -33,6 +33,18 @@ const METHOD_MAP = {
   '/session/:sessionId/timeouts': {
     GET: {command: 'getTimeouts'}, // W3C route
     POST: {command: 'timeouts', payloadParams: {
+      validate: (jsonObj, protocolName) => {
+        if (protocolName === PROTOCOLS.W3C) {
+          if (!util.hasValue(jsonObj.script) && !util.hasValue(jsonObj.pageLoad) && !util.hasValue(jsonObj.implicit)) {
+            return 'W3C protocol expects any of script, pageLoad or implicit to be set';
+          }
+        } else {
+          // MJSONWP
+          if (!util.hasValue(jsonObj.type) || !util.hasValue(jsonObj.ms)) {
+            return 'MJSONWP protocol requires type and ms';
+          }
+        }
+      },
       optional: ['type', 'ms', 'script', 'pageLoad', 'implicit'],
     }}
   },
@@ -42,9 +54,19 @@ const METHOD_MAP = {
   '/session/:sessionId/timeouts/implicit_wait': {
     POST: {command: 'implicitWait', payloadParams: {required: ['ms']}}
   },
+  // JSONWP
+  '/session/:sessionId/window_handle': {
+    GET: {command: 'getWindowHandle'}
+  },
+  // W3C
   '/session/:sessionId/window/handle': {
     GET: {command: 'getWindowHandle'}
   },
+  // JSONWP
+  '/session/:sessionId/window_handles': {
+    GET: {command: 'getWindowHandles'}
+  },
+  // W3C
   '/session/:sessionId/window/handles': {
     GET: {command: 'getWindowHandles'}
   },
@@ -61,6 +83,14 @@ const METHOD_MAP = {
   '/session/:sessionId/refresh': {
     POST: {command: 'refresh'}
   },
+  // MJSONWP
+  '/session/:sessionId/execute': {
+    POST: {command: 'execute', payloadParams: {required: ['script', 'args']}}
+  },
+  // MJSONWP
+  '/session/:sessionId/execute_async': {
+    POST: {command: 'executeAsync', payloadParams: {required: ['script', 'args']}}
+  },
   '/session/:sessionId/screenshot': {
     GET: {command: 'getScreenshot'}
   },
@@ -207,6 +237,9 @@ const METHOD_MAP = {
   '/session/:sessionId/element/:elementId/size': {
     GET: {command: 'getSize'}
   },
+  '/session/:sessionId/element/:elementId/shadow': {
+    GET: {command: 'elementShadowRoot'}
+  },
   '/session/:sessionId/element/:elementId/css/:propertyName': {
     GET: {command: 'getCssProperty'}
   },
@@ -582,6 +615,28 @@ const METHOD_MAP = {
     POST: {command: 'logCustomEvent', payloadParams: {required: ['vendor', 'event']}}
   },
 
+  /*
+   * The W3C spec has some changes to the wire protocol.
+   * https://w3c.github.io/webdriver/webdriver-spec.html
+   * Begin to add those changes here, keeping the old version
+   * since clients still implement them.
+   */
+  // MJSONWP
+  '/session/:sessionId/alert_text': {
+    GET: {command: 'getAlertText'},
+    POST: {
+      command: 'setAlertText',
+      payloadParams: SET_ALERT_TEXT_PAYLOAD_PARAMS,
+    }
+  },
+  // MJSONWP
+  '/session/:sessionId/accept_alert': {
+    POST: {command: 'postAcceptAlert'}
+  },
+  // MJSONWP
+  '/session/:sessionId/dismiss_alert': {
+    POST: {command: 'postDismissAlert'}
+  },
   // https://w3c.github.io/webdriver/webdriver-spec.html#user-prompts
   '/session/:sessionId/alert/text': {
     GET: {command: 'getAlertText'},
@@ -606,6 +661,10 @@ const METHOD_MAP = {
   '/session/:sessionId/execute/async': {
     POST: {command: 'executeAsync', payloadParams: {required: ['script', 'args']}}
   },
+  // Pre-W3C endpoint for element screenshot
+  '/session/:sessionId/screenshot/:elementId': {
+    GET: {command: 'getElementScreenshot'}
+  },
   '/session/:sessionId/element/:elementId/screenshot': {
     GET: {command: 'getElementScreenshot'}
   },

package/package.json

@@ -1,5 +1,6 @@
 {
   "name": "@appium/base-driver",
+  "version": "8.3.0",
   "description": "Base driver class for Appium drivers",
   "keywords": [
     "automation",
@@ -11,20 +12,17 @@
     "firefoxos",
     "testing"
   ],
-  "version": "8.2.4",
-  "author": "https://github.com/appium",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/appium/appium.git"
-  },
+  "homepage": "https://appium.io",
   "bugs": {
     "url": "https://github.com/appium/appium/issues"
   },
-  "engines": {
-    "node": ">=12",
-    "npm": ">=6"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/appium/appium.git",
+    "directory": "packages/base-driver"
   },
+  "license": "Apache-2.0",
+  "author": "https://github.com/appium",
   "directories": {
     "lib": "lib"
   },
@@ -38,30 +36,39 @@
     "build",
     "!build/test/basedriver/fixtures"
   ],
+  "scripts": {
+    "dev": "gulp dev --no-notif",
+    "build": "gulp transpile",
+    "test": "gulp unit-test:run",
+    "test:e2e": "gulp e2e-test:run"
+  },
   "dependencies": {
-    "@appium/support": "^2.55.4",
-    "@babel/runtime": "7.16.3",
-    "@dabh/colors": "1.4.0",
-    "async-lock": "1.3.0",
+    "@appium/support": "^2.56.0",
+    "@babel/runtime": "7.17.8",
+    "@colors/colors": "1.5.0",
+    "async-lock": "1.3.1",
     "asyncbox": "2.9.2",
-    "axios": "0.24.0",
+    "axios": "0.26.1",
     "bluebird": "3.7.2",
-    "body-parser": "1.19.0",
+    "body-parser": "1.19.2",
     "es6-error": "4.1.1",
-    "express": "4.17.1",
-    "http-status-codes": "2.1.4",
+    "express": "4.17.3",
+    "http-status-codes": "2.2.0",
     "lodash": "4.17.21",
-    "lru-cache": "6.0.0",
+    "lru-cache": "7.7.1",
     "method-override": "3.0.0",
     "morgan": "1.10.0",
     "serve-favicon": "2.5.0",
     "source-map-support": "0.5.21",
     "validate.js": "0.13.1",
-    "ws": "7.5.6"
+    "ws": "7.5.7"
+  },
+  "engines": {
+    "node": ">=12",
+    "npm": ">=6"
   },
   "publishConfig": {
     "access": "public"
   },
-  "homepage": "https://appium.io",
-  "gitHead": "42f4a2de2d763d57cf0bdb6fb6c9a3bc9c3d232f"
+  "gitHead": "f5cce0f29d31699decea63ed94c4506f7af469df"
 }

package/test/basedriver/capabilities-specs.js

@@ -1,7 +1,10 @@
-import { parseCaps, validateCaps, mergeCaps, processCapabilities, findNonPrefixedCaps,
-         promoteAppiumOptions, APPIUM_OPTS_CAP, stripAppiumPrefixes } from '../../lib/basedriver/capabilities';
+import {
+  parseCaps, validateCaps, mergeCaps, processCapabilities, findNonPrefixedCaps,
+  promoteAppiumOptions, APPIUM_OPTS_CAP, stripAppiumPrefixes
+} from '../../lib/basedriver/capabilities';
 import _ from 'lodash';
 import { desiredCapabilityConstraints } from '../../lib/basedriver/desired-caps';
+import { isW3cCaps } from '../../lib/helpers/capabilities';
 
 
 describe('caps', function () {
@@ -502,4 +505,33 @@ describe('caps', function () {
       });
     });
   });
+
+  describe('#isW3cCaps', function () {
+    it('should drop invalid W3C capabilities', function () {
+      for (const invalidCaps of [
+        null, undefined, [], {},
+        {firstMatch: null},
+        {firtMatch: [{}]},
+        {alwaysMatch: null},
+        {firstMatch: [{}], alwaysMatch: null},
+        {firstMatch: [], alwaysMatch: {}},
+        {firstMatch: []},
+        {firstMatch: {}},
+        {alwaysMatch: []},
+      ]) {
+        isW3cCaps(invalidCaps).should.be.false;
+      }
+    });
+
+    it('should accept valid W3C capabilities', function () {
+      for (const validCaps of [
+        {firstMatch: [{}]},
+        {firstMatch: [{}], alaysMatch: {}},
+        {firtMatch: [{}], alwaysMatch: {}},
+        {alwaysMatch: {}},
+      ]) {
+        isW3cCaps(validCaps).should.be.true;
+      }
+    });
+  });
 });