@appium/base-driver 8.5.3 → 8.5.4

package/lib/express/middleware.js

@@ -1,13 +1,16 @@
 import _ from 'lodash';
 import log from './logger';
-import { errors } from '../protocol';
-import { handleIdempotency } from './idempotency';
+import {errors} from '../protocol';
+import {handleIdempotency} from './idempotency';
 
-function allowCrossDomain (req, res, next) {
+function allowCrossDomain(req, res, next) {
   try {
     res.header('Access-Control-Allow-Origin', '*');
     res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, OPTIONS, DELETE');
-    res.header('Access-Control-Allow-Headers', 'Cache-Control, Pragma, Origin, X-Requested-With, Content-Type, Accept, User-Agent');
+    res.header(
+      'Access-Control-Allow-Headers',
+      'Cache-Control, Pragma, Origin, X-Requested-With, Content-Type, Accept, User-Agent'
+    );
 
     // need to respond 200 to OPTIONS
     if ('OPTIONS' === req.method) {
@@ -19,11 +22,13 @@ function allowCrossDomain (req, res, next) {
   next();
 }
 
-function allowCrossDomainAsyncExecute (basePath) {
+function allowCrossDomainAsyncExecute(basePath) {
   return (req, res, next) => {
     // there are two paths for async responses, so cover both
     // https://regex101.com/r/txYiEz/1
-    const receiveAsyncResponseRegExp = new RegExp(`${_.escapeRegExp(basePath)}/session/[a-f0-9-]+/(appium/)?receive_async_response`);
+    const receiveAsyncResponseRegExp = new RegExp(
+      `${_.escapeRegExp(basePath)}/session/[a-f0-9-]+/(appium/)?receive_async_response`
+    );
     if (!receiveAsyncResponseRegExp.test(req.url)) {
       return next();
     }
@@ -31,10 +36,13 @@ function allowCrossDomainAsyncExecute (basePath) {
   };
 }
 
-function fixPythonContentType (basePath) {
+function fixPythonContentType(basePath) {
   return (req, res, next) => {
     // hack because python client library gives us wrong content-type
-    if (new RegExp(`^${_.escapeRegExp(basePath)}`).test(req.path) && /^Python/.test(req.headers['user-agent'])) {
+    if (
+      new RegExp(`^${_.escapeRegExp(basePath)}`).test(req.path) &&
+      /^Python/.test(req.headers['user-agent'])
+    ) {
       if (req.headers['content-type'] === 'application/x-www-form-urlencoded') {
         req.headers['content-type'] = 'application/json; charset=utf-8';
       }
@@ -43,14 +51,14 @@ function fixPythonContentType (basePath) {
   };
 }
 
-function defaultToJSONContentType (req, res, next) {
+function defaultToJSONContentType(req, res, next) {
   if (!req.headers['content-type']) {
     req.headers['content-type'] = 'application/json; charset=utf-8';
   }
   next();
 }
 
-function catchAllHandler (err, req, res, next) {
+function catchAllHandler(err, req, res, next) {
   if (res.headersSent) {
     return next(err);
   }
@@ -58,36 +66,40 @@ function catchAllHandler (err, req, res, next) {
   log.error(`Uncaught error: ${err.message}`);
   log.error('Sending generic error response');
   const error = errors.UnknownError;
-  res.status(error.w3cStatus()).json(patchWithSessionId(req, {
-    status: error.code(),
-    value: {
-      error: error.error(),
-      message: `An unknown server-side error occurred while processing the command: ${err.message}`,
-      stacktrace: err.stack,
-    }
-  }));
+  res.status(error.w3cStatus()).json(
+    patchWithSessionId(req, {
+      status: error.code(),
+      value: {
+        error: error.error(),
+        message: `An unknown server-side error occurred while processing the command: ${err.message}`,
+        stacktrace: err.stack,
+      },
+    })
+  );
   log.error(err);
 }
 
-function catch404Handler (req, res) {
+function catch404Handler(req, res) {
   log.debug(`No route found for ${req.url}`);
   const error = errors.UnknownCommandError;
-  res.status(error.w3cStatus()).json(patchWithSessionId(req, {
-    status: error.code(),
-    value: {
-      error: error.error(),
-      message: 'The requested resource could not be found, or a request was ' +
-        'received using an HTTP method that is not supported by the mapped ' +
-        'resource',
-      stacktrace: '',
-    }
-  }));
+  res.status(error.w3cStatus()).json(
+    patchWithSessionId(req, {
+      status: error.code(),
+      value: {
+        error: error.error(),
+        message:
+          'The requested resource could not be found, or a request was ' +
+          'received using an HTTP method that is not supported by the mapped ' +
+          'resource',
+        stacktrace: '',
+      },
+    })
+  );
 }
 
-
 const SESSION_ID_PATTERN = /\/session\/([^/]+)/;
 
-function patchWithSessionId (req, body) {
+function patchWithSessionId(req, body) {
   const match = SESSION_ID_PATTERN.exec(req.url);
   if (match) {
     body.sessionId = match[1];
@@ -96,7 +108,11 @@ function patchWithSessionId (req, body) {
 }
 
 export {
-  allowCrossDomain, fixPythonContentType, defaultToJSONContentType,
-  catchAllHandler, allowCrossDomainAsyncExecute, handleIdempotency,
+  allowCrossDomain,
+  fixPythonContentType,
+  defaultToJSONContentType,
+  catchAllHandler,
+  allowCrossDomainAsyncExecute,
+  handleIdempotency,
   catch404Handler,
 };

package/lib/express/server.js

@@ -6,27 +6,31 @@ import favicon from 'serve-favicon';
 import bodyParser from 'body-parser';
 import methodOverride from 'method-override';
 import log from './logger';
-import { startLogFormatter, endLogFormatter } from './express-logging';
+import {startLogFormatter, endLogFormatter} from './express-logging';
 import {
-  allowCrossDomain, fixPythonContentType, defaultToJSONContentType,
-  catchAllHandler, allowCrossDomainAsyncExecute, handleIdempotency,
+  allowCrossDomain,
+  fixPythonContentType,
+  defaultToJSONContentType,
+  catchAllHandler,
+  allowCrossDomainAsyncExecute,
+  handleIdempotency,
   catch404Handler,
 } from './middleware';
-import { guineaPig, guineaPigScrollable, guineaPigAppBanner, welcome, STATIC_DIR } from './static';
-import { produceError, produceCrash } from './crash';
+import {guineaPig, guineaPigScrollable, guineaPigAppBanner, welcome, STATIC_DIR} from './static';
+import {produceError, produceCrash} from './crash';
 import {
-  addWebSocketHandler, removeWebSocketHandler, removeAllWebSocketHandlers,
-  getWebSocketHandlers
+  addWebSocketHandler,
+  removeWebSocketHandler,
+  removeAllWebSocketHandlers,
+  getWebSocketHandlers,
 } from './websocket';
 import B from 'bluebird';
-import { DEFAULT_BASE_PATH } from '../constants';
-import { EventEmitter } from 'events';
-
+import {DEFAULT_BASE_PATH} from '../constants';
+import {EventEmitter} from 'events';
 
 const KEEP_ALIVE_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
 
-
-async function server (opts = {}) {
+async function server(opts = {}) {
   const {
     routeConfiguringFunction,
     port,
@@ -49,7 +53,13 @@ async function server (opts = {}) {
     // try/catch so any errors can be passed to reject.
     try {
       configureHttp({httpServer, reject, keepAliveTimeout});
-      configureServer({app, addRoutes: routeConfiguringFunction, allowCors, basePath, extraMethodMap});
+      configureServer({
+        app,
+        addRoutes: routeConfiguringFunction,
+        allowCors,
+        basePath,
+        extraMethodMap,
+      });
       // allow extensions to update the app and http server objects
       for (const updater of serverUpdaters) {
         await updater(app, httpServer);
@@ -66,10 +76,9 @@ async function server (opts = {}) {
       reject(err);
     }
   });
-
 }
 
-function configureServer ({
+function configureServer({
   app,
   addRoutes,
   allowCors = true,
@@ -116,7 +125,7 @@ function configureServer ({
   app.all('/test/guinea-pig-app-banner', guineaPigAppBanner);
 }
 
-function configureHttp ({httpServer, reject, keepAliveTimeout}) {
+function configureHttp({httpServer, reject, keepAliveTimeout}) {
   const serverState = {
     notifier: new EventEmitter(),
     closed: false,
@@ -129,28 +138,32 @@ function configureHttp ({httpServer, reject, keepAliveTimeout}) {
   // http.Server.close() only stops new connections, but we need to wait until
   // all connections are closed and the `close` event is emitted
   const close = httpServer.close.bind(httpServer);
-  httpServer.close = async () => await new B((resolve, reject) => {
-    // https://github.com/nodejs/node-v0.x-archive/issues/9066#issuecomment-124210576
-    serverState.closed = true;
-    serverState.notifier.emit('shutdown');
-    log.info('Waiting until the server is closed');
-    httpServer.on('close', () => {
-      log.info('Received server close event');
-      resolve();
-    });
-    close((err) => {
-      if (err) reject(err); // eslint-disable-line curly
+  httpServer.close = async () =>
+    await new B((resolve, reject) => {
+      // https://github.com/nodejs/node-v0.x-archive/issues/9066#issuecomment-124210576
+      serverState.closed = true;
+      serverState.notifier.emit('shutdown');
+      log.info('Waiting until the server is closed');
+      httpServer.on('close', () => {
+        log.info('Received server close event');
+        resolve();
+      });
+      close((err) => {
+        if (err) reject(err); // eslint-disable-line curly
+      });
     });
-  });
 
   httpServer.on('error', (err) => {
     if (err.code === 'EADDRNOTAVAIL') {
-      log.error('Could not start REST http interface listener. ' +
-                'Requested address is not available.');
+      log.error(
+        'Could not start REST http interface listener. ' + 'Requested address is not available.'
+      );
     } else {
-      log.error('Could not start REST http interface listener. The requested ' +
-                'port may already be in use. Please make sure there is no ' +
-                'other instance of this server running already.');
+      log.error(
+        'Could not start REST http interface listener. The requested ' +
+          'port may already be in use. Please make sure there is no ' +
+          'other instance of this server running already.'
+      );
     }
     reject(err);
   });
@@ -159,7 +172,7 @@ function configureHttp ({httpServer, reject, keepAliveTimeout}) {
     socket.setTimeout(keepAliveTimeout);
     socket.on('error', reject);
 
-    function destroy () {
+    function destroy() {
       socket.destroy();
     }
     socket._openReqCount = 0;
@@ -179,21 +192,23 @@ function configureHttp ({httpServer, reject, keepAliveTimeout}) {
   });
 }
 
-async function startServer ({httpServer, port, hostname, keepAliveTimeout}) {
-  const serverArgs = [port];
-  if (hostname) {
-    // If the hostname is omitted, the server will accept
-    // connections on any IP address
-    serverArgs.push(hostname);
-  }
-  const startPromise = B.promisify(httpServer.listen, {context: httpServer})(...serverArgs);
+/**
+ *
+ * @param {StartServerOpts} opts
+ */
+async function startServer({httpServer, port, hostname, keepAliveTimeout}) {
+  // If the hostname is omitted, the server will accept
+  // connections on any IP address
+  /** @type {(port: number, hostname?: string) => B<http.Server>} */
+  const start = B.promisify(httpServer.listen, {context: httpServer});
+  const startPromise = start(port, hostname);
   httpServer.keepAliveTimeout = keepAliveTimeout;
   // headers timeout must be greater than keepAliveTimeout
   httpServer.headersTimeout = keepAliveTimeout + 5 * 1000;
   await startPromise;
 }
 
-function normalizeBasePath (basePath) {
+function normalizeBasePath(basePath) {
   if (!_.isString(basePath)) {
     throw new Error(`Invalid path prefix ${basePath}`);
   }
@@ -211,4 +226,13 @@ function normalizeBasePath (basePath) {
   return basePath;
 }
 
-export { server, configureServer, normalizeBasePath };
+export {server, configureServer, normalizeBasePath};
+
+/**
+ * Options for {@linkcode startServer}.
+ * @typedef StartServerOpts
+ * @property {import('http').Server} httpServer - HTTP server instance
+ * @property {number} port - Port to run on
+ * @property {number} keepAliveTimeout - Keep-alive timeout in milliseconds
+ * @property {string} [hostname] - Optional hostname
+ */

package/lib/express/static.js

@@ -1,10 +1,9 @@
 import path from 'path';
 import log from './logger';
 import _ from 'lodash';
-import { fs } from '@appium/support';
+import {fs} from '@appium/support';
 import B from 'bluebird';
 
-
 let STATIC_DIR = path.resolve(__dirname, '..', '..', '..', 'static');
 if (_.isNull(path.resolve(__dirname).match(/build[/\\]lib[/\\]express$/))) {
   // in some contexts we are not in the build directory,
@@ -12,14 +11,14 @@ if (_.isNull(path.resolve(__dirname).match(/build[/\\]lib[/\\]express$/))) {
   STATIC_DIR = path.resolve(__dirname, '..', '..', 'static');
 }
 
-async function guineaPigTemplate (req, res, page) {
+async function guineaPigTemplate(req, res, page) {
   const delay = parseInt(req.params.delay || req.query.delay || 0, 10);
   const throwError = req.params.throwError || req.query.throwError || '';
   let params = {
     throwError,
     serverTime: new Date(),
     userAgent: req.headers['user-agent'],
-    comment: 'None'
+    comment: 'None',
   };
   if (req.method === 'POST') {
     params.comment = req.body.comments || params.comment;
@@ -34,7 +33,7 @@ async function guineaPigTemplate (req, res, page) {
   res.cookie('guineacookie2', 'cookié2', {path: '/'});
   res.cookie('guineacookie3', 'cant access this', {
     domain: '.blargimarg.com',
-    path: '/'
+    path: '/',
   });
   res.send((await getTemplate(page))(params));
 }
@@ -42,36 +41,36 @@ async function guineaPigTemplate (req, res, page) {
 /*
  * Dynamic page mapped to /test/guinea-pig
  */
-async function guineaPig (req, res) {
+async function guineaPig(req, res) {
   return await guineaPigTemplate(req, res, 'guinea-pig.html');
 }
 
 /*
  * Dynamic page mapped to /test/guinea-pig-scrollable
  */
-async function guineaPigScrollable (req, res) {
+async function guineaPigScrollable(req, res) {
   return await guineaPigTemplate(req, res, 'guinea-pig-scrollable.html');
 }
 
 /*
  * Dynamic page mapped to /test/guinea-pig-app-banner
  */
-async function guineaPigAppBanner (req, res) {
+async function guineaPigAppBanner(req, res) {
   return await guineaPigTemplate(req, res, 'guinea-pig-app-banner.html');
 }
 
 /*
  * Dynamic page mapped to /welcome
  */
-async function welcome (req, res) {
-  let params = {message: 'Let\'s browse!'};
+async function welcome(req, res) {
+  let params = {message: "Let's browse!"};
   log.debug(`Sending welcome response with params: ${JSON.stringify(params)}`);
   res.send((await getTemplate('welcome.html'))(params));
 }
 
-async function getTemplate (templateName) {
+async function getTemplate(templateName) {
   let content = await fs.readFile(path.resolve(STATIC_DIR, 'test', templateName));
   return _.template(content.toString());
 }
 
-export { guineaPig, guineaPigScrollable, guineaPigAppBanner, welcome, STATIC_DIR };
+export {guineaPig, guineaPigScrollable, guineaPigAppBanner, welcome, STATIC_DIR};

package/lib/express/websocket.js

@@ -1,16 +1,15 @@
 import _ from 'lodash';
-import { URL } from 'url';
+import {URL} from 'url';
 import B from 'bluebird';
 
 const DEFAULT_WS_PATHNAME_PREFIX = '/ws';
 
-
 /**
  * Adds websocket handler to express server instance.
  * It is expected this function is called in Express
  * server instance context.
  *
- * @param {Object} server - An instance of express HTTP server.
+ * @this {WebSocketServer} - An instance of express HTTP server.
  * @param {string} handlerPathname - Web socket endpoint path starting with
  * a single slash character. It is recommended to always add
  * DEFAULT_WS_PATHNAME_PREFIX to all web socket pathnames.
@@ -18,15 +17,17 @@ const DEFAULT_WS_PATHNAME_PREFIX = '/ws';
  * https://github.com/websockets/ws/pull/885 for more details
  * on how to configure the handler properly.
  */
-async function addWebSocketHandler (handlerPathname, handlerServer) { // eslint-disable-line require-await
+// eslint-disable-next-line require-await
+async function addWebSocketHandler(handlerPathname, handlerServer) {
   if (_.isUndefined(this.webSocketsMapping)) {
     this.webSocketsMapping = {};
     // https://github.com/websockets/ws/pull/885
     this.on('upgrade', (request, socket, head) => {
       let currentPathname;
       try {
-        currentPathname = (new URL(request.url)).pathname;
-      } catch (ign) {
+        // @ts-expect-error
+        currentPathname = new URL(request.url).pathname;
+      } catch {
         currentPathname = request.url;
       }
       for (const [pathname, wsServer] of _.toPairs(this.webSocketsMapping)) {
@@ -49,12 +50,13 @@ async function addWebSocketHandler (handlerPathname, handlerServer) { // eslint-
  * It is expected this function is called in Express
  * server instance context.
  *
- * @param {?string} keysFilter [null]- Only include pathnames with given
+ * @param {string?} [keysFilter] - Only include pathnames with given
  * `keysFilter` value if set. All pairs will be included by default.
- * @returns {Object} pathnames to websocket server isntances mapping
+ * @returns {Promise<Object>} pathnames to websocket server isntances mapping
  * matching the search criteria or an empty object otherwise.
  */
-async function getWebSocketHandlers (keysFilter = null) { // eslint-disable-line require-await
+// eslint-disable-next-line require-await
+async function getWebSocketHandlers(keysFilter = null) {
   if (_.isEmpty(this.webSocketsMapping)) {
     return {};
   }
@@ -75,9 +77,10 @@ async function getWebSocketHandlers (keysFilter = null) { // eslint-disable-line
  * server instance context.
  *
  * @param {string} handlerPathname - Websocket endpoint path.
- * @returns {boolean} true if the handlerPathname was found and deleted
+ * @returns {Promise<boolean>} true if the handlerPathname was found and deleted
  */
-async function removeWebSocketHandler (handlerPathname) { // eslint-disable-line require-await
+// eslint-disable-next-line require-await
+async function removeWebSocketHandler(handlerPathname) {
   const wsServer = this.webSocketsMapping?.[handlerPathname];
   if (!wsServer) {
     return false;
@@ -85,7 +88,7 @@ async function removeWebSocketHandler (handlerPathname) { // eslint-disable-line
 
   try {
     wsServer.close();
-    for (const client of (wsServer.clients || [])) {
+    for (const client of wsServer.clients || []) {
       client.terminate();
     }
     return true;
@@ -102,9 +105,9 @@ async function removeWebSocketHandler (handlerPathname) { // eslint-disable-line
  * It is expected this function is called in Express
  * server instance context.
  *
- * @returns {boolean} true if at least one handler has been deleted
+ * @returns {Promise<boolean>} true if at least one handler has been deleted
  */
-async function removeAllWebSocketHandlers () {
+async function removeAllWebSocketHandlers() {
   if (_.isEmpty(this.webSocketsMapping)) {
     return false;
   }
@@ -117,6 +120,13 @@ async function removeAllWebSocketHandlers () {
 }
 
 export {
-  addWebSocketHandler, removeWebSocketHandler, removeAllWebSocketHandlers,
-  getWebSocketHandlers, DEFAULT_WS_PATHNAME_PREFIX,
+  addWebSocketHandler,
+  removeWebSocketHandler,
+  removeAllWebSocketHandlers,
+  getWebSocketHandlers,
+  DEFAULT_WS_PATHNAME_PREFIX,
 };
+
+/**
+ * @typedef {import('http').Server & {webSocketsMapping: Record<string,import('ws').Server>}} WebSocketServer
+ */

package/lib/helpers/capabilities.js

@@ -2,13 +2,15 @@
 
 import _ from 'lodash';
 
-function isW3cCaps (caps) {
+function isW3cCaps(caps) {
   if (!_.isPlainObject(caps)) {
     return false;
   }
 
-  const isFirstMatchValid = () => _.isArray(caps.firstMatch)
-    && !_.isEmpty(caps.firstMatch) && _.every(caps.firstMatch, _.isPlainObject);
+  const isFirstMatchValid = () =>
+    _.isArray(caps.firstMatch) &&
+    !_.isEmpty(caps.firstMatch) &&
+    _.every(caps.firstMatch, _.isPlainObject);
   const isAlwaysMatchValid = () => _.isPlainObject(caps.alwaysMatch);
   if (_.has(caps, 'firstMatch') && _.has(caps, 'alwaysMatch')) {
     return isFirstMatchValid() && isAlwaysMatchValid();
@@ -29,21 +31,19 @@ function isW3cCaps (caps) {
  * @param {AppiumLogger} log
  * @returns {Capabilities}
  */
-function fixCaps (originalCaps, desiredCapConstraints, log) {
+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),
-  );
+  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`,
+          `Capability '${cap}' changed from string to boolean. This may cause unexpected behavior`
         );
         caps[cap] = value === 'true';
       }
@@ -51,9 +51,7 @@ function fixCaps (originalCaps, desiredCapConstraints, log) {
   }
 
   // int capabilities are often sent in as strings by frameworks
-  let intCaps = _.keys(
-    _.pickBy(desiredCapConstraints, (k) => k.isNumber === true),
-  );
+  let intCaps = _.keys(_.pickBy(desiredCapConstraints, (k) => k.isNumber === true));
   for (let cap of intCaps) {
     let value = originalCaps[cap];
     if (_.isString(value)) {
@@ -63,7 +61,7 @@ function fixCaps (originalCaps, desiredCapConstraints, log) {
         newValue = parseFloat(value);
       }
       log.warn(
-        `Capability '${cap}' changed from string ('${value}') to integer (${newValue}). This may cause unexpected behavior`,
+        `Capability '${cap}' changed from string ('${value}') to integer (${newValue}). This may cause unexpected behavior`
       );
       caps[cap] = newValue;
     }
@@ -72,10 +70,7 @@ function fixCaps (originalCaps, desiredCapConstraints, log) {
   return caps;
 }
 
-export {
-  isW3cCaps,
-  fixCaps
-};
+export {isW3cCaps, fixCaps};
 
 /**
  * @typedef {import('@appium/types').Capabilities} Capabilities