@appium/base-driver 8.4.0 → 8.5.0

package/lib/basedriver/commands/log.js

@@ -13,11 +13,12 @@ export function LogMixin (Base) {
    * @implements {ILogCommands}
    */
   class LogCommands extends Base {
-    /**
-     * XXX: dubious
-     * @type {Record<string,LogType<Driver>>}
-     */
-    supportedLogTypes;
+
+    constructor (...args) {
+      super(...args);
+      /** @type {Record<string, LogType<Driver>>} */
+      this.supportedLogTypes = this.supportedLogTypes ?? {};
+    }
 
     async getLogTypes () {
       this.log.debug('Retrieving supported log types');
@@ -26,19 +27,13 @@ export function LogMixin (Base) {
 
     /**
      * @this {Driver}
+     * @param {string} logType
      */
     async getLog (logType) {
       this.log.debug(`Retrieving '${logType}' logs`);
 
       if (!(await this.getLogTypes()).includes(logType)) {
-        const logsTypesWithDescriptions = _.reduce(
-          this.supportedLogTypes,
-          (acc, value, key) => {
-            acc[key] = value.description;
-            return acc;
-          },
-          {},
-        );
+        const logsTypesWithDescriptions = _.mapValues(this.supportedLogTypes, 'description');
         throw new Error(
           `Unsupported log type '${logType}'. ` +
             `Supported types: ${JSON.stringify(logsTypesWithDescriptions)}`,

package/lib/basedriver/core.js

@@ -491,7 +491,7 @@ export {DriverCore};
  * @typedef {import('@appium/types').W3CCapabilities} W3CCapabilities
  * @typedef {import('@appium/types').Driver} Driver
  * @typedef {import('@appium/types').Core} Core
- * @typedef {import('@appium/types').DriverOpts} DriverOpts
+ * @typedef {import('@appium/types').ServerArgs} DriverOpts
  * @typedef {import('@appium/types').EventHistory} EventHistory
  * @typedef {import('@appium/types').AppiumLogger} AppiumLogger
  */

package/lib/basedriver/device-settings.js

@@ -5,7 +5,10 @@ import log from './logger';
 import { node, util } from '@appium/support';
 import { errors } from '../protocol/errors';
 
-const MAX_SETTINGS_SIZE = 20 * 1024 * 1024; // 20 MB
+/**
+ * Maximum size (in bytes) of a given driver's settings object (which is internal to {@linkcode DriverSettings}).
+ */
+export const MAX_SETTINGS_SIZE = 20 * 1024 * 1024; // 20 MB
 
 /**
  * @template {Record<string,unknown>} T
@@ -21,19 +24,18 @@ class DeviceSettings {
 
   /**
    * @protected
-   * @type {import('@appium/types').SettingsUpdateListener<T>|undefined}
+   * @type {import('@appium/types').SettingsUpdateListener<T>}
    */
   _onSettingsUpdate;
 
   /**
-   * `onSettingsUpdate` is _required_ if settings will ever be updated; otherwise
-   * an error will occur at runtime.
+   * Creates a _shallow copy_ of the `defaultSettings` parameter!
    * @param {T} [defaultSettings]
    * @param {import('@appium/types').SettingsUpdateListener<T>} [onSettingsUpdate]
    */
   constructor (defaultSettings, onSettingsUpdate) {
     this._settings = /** @type {T} */({...(defaultSettings ?? {})});
-    this._onSettingsUpdate = onSettingsUpdate;
+    this._onSettingsUpdate = onSettingsUpdate ?? (async () => {});
   }
 
   /**
@@ -51,12 +53,6 @@ class DeviceSettings {
         `object size exceeds the allowed limit of ${util.toReadableSizeString(MAX_SETTINGS_SIZE)}`);
     }
 
-    if (!_.isFunction(this._onSettingsUpdate)) {
-      log.errorAndThrow(`Unable to update settings; ` +
-      `onSettingsUpdate method not found on '${this.constructor.name}'`);
-      return;
-    }
-
     const props = /** @type {(keyof T & string)[]} */(_.keys(newSettings));
     for (const prop of props) {
       if (!_.isUndefined(this._settings[prop])) {
@@ -65,7 +61,6 @@ class DeviceSettings {
           continue;
         }
       }
-      // update setting only when there is updateSettings defined.
       await this._onSettingsUpdate(prop, newSettings[prop], this._settings[prop]);
       this._settings[prop] = newSettings[prop];
     }

package/lib/basedriver/helpers.js

@@ -262,7 +262,7 @@ async function configureApp (app, options = {}) {
         }
         logger.info(`The application at '${cachedPath}' does not exist anymore ` +
           `or its integrity has been damaged. Deleting it from the internal cache`);
-        APPLICATIONS_CACHE.del(app);
+        APPLICATIONS_CACHE.delete(app);
       }
 
       let fileName = null;
@@ -347,7 +347,7 @@ async function configureApp (app, options = {}) {
         }
         logger.info(`The application at '${fullPath}' does not exist anymore ` +
           `or its integrity has been damaged. Deleting it from the cache`);
-        APPLICATIONS_CACHE.del(app);
+        APPLICATIONS_CACHE.delete(app);
       }
       const tmpRoot = await tempDir.openDir();
       try {

package/lib/express/idempotency.js

@@ -78,14 +78,14 @@ function cacheResponse (key, req, res) {
     }
     if (writeError) {
       log.info(`Could not cache the response identified by '${key}': ${writeError.message}`);
-      IDEMPOTENT_RESPONSES.del(key);
+      IDEMPOTENT_RESPONSES.delete(key);
       return responseStateListener.emit('ready', null);
     }
     if (!isResponseFullySent) {
       log.info(`Could not cache the response identified by '${key}', ` +
         `because it has not been completed`);
       log.info('Does the client terminate connections too early?');
-      IDEMPOTENT_RESPONSES.del(key);
+      IDEMPOTENT_RESPONSES.delete(key);
       return responseStateListener.emit('ready', null);
     }
 
@@ -125,7 +125,7 @@ async function handleIdempotency (req, res, next) {
 
   const rerouteCachedResponse = async (cachedResPath) => {
     if (!await fs.exists(cachedResPath)) {
-      IDEMPOTENT_RESPONSES.del(key);
+      IDEMPOTENT_RESPONSES.delete(key);
       log.warn(`Could not read the cached response identified by key '${key}'`);
       log.warn('The temporary storage is not accessible anymore');
       return next();

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/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/routes.js

@@ -690,6 +690,9 @@ const METHOD_MAP = {
   '/session/:sessionId/window/fullscreen': {
     POST: {command: 'fullScreenWindow'}
   },
+  '/session/:sessionId/window/new': {
+    POST: {command: 'createNewWindow', payloadParams: {optional: ['type']}}
+  },
   '/session/:sessionId/element/:elementId/property/:name': {
     GET: {command: 'getProperty'}
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/base-driver",
-  "version": "8.4.0",
+  "version": "8.5.0",
   "description": "Base driver class for Appium drivers",
   "keywords": [
     "automation",
@@ -37,18 +37,18 @@
     "!build/test/e2e/fixtures"
   ],
   "scripts": {
-    "build": "npm run build:distfiles && npm run build:test",
+    "build": "run-s build:*",
     "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": "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",
-    "test:e2e": "mocha --require ../../test/setup-babel.js --timeout 20s --slow 10s \"./test/e2e/**/*.spec.js\"",
-    "test:unit": "mocha --require ../../test/setup-babel.js \"./test/unit/**/*.spec.js\""
+    "test:e2e": "mocha --timeout 20s --slow 10s \"./test/e2e/**/*.spec.js\"",
+    "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/support": "^2.57.0",
+    "@appium/support": "^2.57.2",
     "@babel/runtime": "7.17.9",
     "@colors/colors": "1.5.0",
     "async-lock": "1.3.1",
@@ -60,13 +60,15 @@
     "express": "4.17.3",
     "http-status-codes": "2.2.0",
     "lodash": "4.17.21",
-    "lru-cache": "7.7.3",
+    "lru-cache": "7.8.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.7"
+    "validate.js": "0.13.1"
+  },
+  "devDependencies": {
+    "ws": "8.5.0"
   },
   "engines": {
     "node": ">=12",
@@ -76,5 +78,5 @@
     "access": "public"
   },
   "types": "./build/lib/index.d.ts",
-  "gitHead": "3ec3a0efa590e22e264ffbd23316ee5714a12081"
+  "gitHead": "8b7906f757f23b7abc09a0acf41a3daa6671c2ec"
 }

package/test/basedriver/driver-e2e-tests.js

@@ -279,11 +279,10 @@ function baseDriverE2ETests (DriverClass, defaultCaps = {}) {
       it('should be able to get settings object', function () {
         d.settings.getSettings().ignoreUnimportantViews.should.be.false;
       });
-      it('should throw error when updateSettings method is not defined', async function () {
-        await d.settings.update({ignoreUnimportantViews: true}).should.eventually
-                .be.rejectedWith('onSettingsUpdate');
+      it('should not reject when `updateSettings` method is not provided', async function () {
+        await d.settings.update({ignoreUnimportantViews: true}).should.not.be.rejected;
       });
-      it('should throw error for invalid update object', async function () {
+      it('should reject for invalid update object', async function () {
         await d.settings.update('invalid json').should.eventually
                 .be.rejectedWith('JSON');
       });