@appium/base-driver 8.5.7 → 8.7.0

package/lib/express/server.js

@@ -30,11 +30,17 @@ import {EventEmitter} from 'events';
 
 const KEEP_ALIVE_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
 
-async function server(opts = {}) {
+/**
+ *
+ * @param {ServerOpts} opts
+ * @returns {Promise<AppiumServer>}
+ */
+async function server(opts) {
   const {
     routeConfiguringFunction,
     port,
-    hostname = null,
+    hostname,
+    cliArgs,
     allowCors = true,
     basePath = DEFAULT_BASE_PATH,
     extraMethodMap = {},
@@ -52,7 +58,11 @@ async function server(opts = {}) {
     // way we resolve it is to use an async function here but to wrap all the inner logic in
     // try/catch so any errors can be passed to reject.
     try {
-      configureHttp({httpServer, reject, keepAliveTimeout});
+      const appiumServer = configureHttp({
+        httpServer,
+        reject,
+        keepAliveTimeout,
+      });
       configureServer({
         app,
         addRoutes: routeConfiguringFunction,
@@ -62,7 +72,7 @@ async function server(opts = {}) {
       });
       // allow extensions to update the app and http server objects
       for (const updater of serverUpdaters) {
-        await updater(app, httpServer);
+        await updater(app, appiumServer, cliArgs);
       }
 
       // once all configurations and updaters have been applied, make sure to set up a catchall
@@ -71,13 +81,18 @@ async function server(opts = {}) {
       app.all('*', catch404Handler);
 
       await startServer({httpServer, hostname, port, keepAliveTimeout});
-      resolve(httpServer);
+
+      resolve(appiumServer);
     } catch (err) {
       reject(err);
     }
   });
 }
 
+/**
+ * Sets up some Express middleware and stuff
+ * @param {ConfigureServerOpts} opts
+ */
 function configureServer({
   app,
   addRoutes,
@@ -125,20 +140,28 @@ function configureServer({
   app.all('/test/guinea-pig-app-banner', guineaPigAppBanner);
 }
 
+/**
+ * Monkeypatches the `http.Server` instance and returns a {@linkcode AppiumServer}.
+ * This function _mutates_ the `httpServer` parameter.
+ * @param {ConfigureHttpOpts} opts
+ * @returns {AppiumServer}
+ */
 function configureHttp({httpServer, reject, keepAliveTimeout}) {
   const serverState = {
     notifier: new EventEmitter(),
     closed: false,
   };
-  httpServer.addWebSocketHandler = addWebSocketHandler;
-  httpServer.removeWebSocketHandler = removeWebSocketHandler;
-  httpServer.removeAllWebSocketHandlers = removeAllWebSocketHandlers;
-  httpServer.getWebSocketHandlers = getWebSocketHandlers;
+  // TS does not love monkeypatching.
+  const appiumServer = /** @type {AppiumServer} */ (/** @type {unknown} */ (httpServer));
+  appiumServer.addWebSocketHandler = addWebSocketHandler;
+  appiumServer.removeWebSocketHandler = removeWebSocketHandler;
+  appiumServer.removeAllWebSocketHandlers = removeAllWebSocketHandlers;
+  appiumServer.getWebSocketHandlers = getWebSocketHandlers;
 
   // 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 () =>
+  const close = appiumServer.close.bind(appiumServer);
+  appiumServer.close = async () =>
     await new B((resolve, reject) => {
       // https://github.com/nodejs/node-v0.x-archive/issues/9066#issuecomment-124210576
       serverState.closed = true;
@@ -153,35 +176,41 @@ function configureHttp({httpServer, reject, keepAliveTimeout}) {
       });
     });
 
-  httpServer.on('error', (err) => {
-    if (err.code === 'EADDRNOTAVAIL') {
-      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.'
-      );
+  appiumServer.on(
+    'error',
+    /** @param {NodeJS.ErrnoException} err */ (err) => {
+      if (err.code === 'EADDRNOTAVAIL') {
+        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.'
+        );
+      }
+      reject(err);
     }
-    reject(err);
-  });
+  );
 
-  httpServer.on('connection', (socket) => {
-    socket.setTimeout(keepAliveTimeout);
-    socket.on('error', reject);
+  appiumServer.on(
+    'connection',
+    /** @param {AppiumServerSocket} socket */ (socket) => {
+      socket.setTimeout(keepAliveTimeout);
+      socket.on('error', reject);
 
-    function destroy() {
-      socket.destroy();
+      function destroy() {
+        socket.destroy();
+      }
+      socket._openReqCount = 0;
+      socket.once('close', () => serverState.notifier.removeListener('shutdown', destroy));
+      serverState.notifier.once('shutdown', destroy);
     }
-    socket._openReqCount = 0;
-    socket.once('close', () => serverState.notifier.removeListener('shutdown', destroy));
-    serverState.notifier.once('shutdown', destroy);
-  });
+  );
 
-  httpServer.on('request', function (req, res) {
-    const socket = req.connection || req.socket;
+  appiumServer.on('request', function (req, res) {
+    const socket = /** @type {AppiumServerSocket} */ (req.connection || req.socket);
     socket._openReqCount++;
     res.on('finish', function () {
       socket._openReqCount--;
@@ -190,11 +219,14 @@ function configureHttp({httpServer, reject, keepAliveTimeout}) {
       }
     });
   });
+
+  return appiumServer;
 }
 
 /**
- *
+ * Starts an {@linkcode AppiumServer}
  * @param {StartServerOpts} opts
+ * @returns {Promise<void>}
  */
 async function startServer({httpServer, port, hostname, keepAliveTimeout}) {
   // If the hostname is omitted, the server will accept
@@ -208,6 +240,11 @@ async function startServer({httpServer, port, hostname, keepAliveTimeout}) {
   await startPromise;
 }
 
+/**
+ * Normalize base path string
+ * @param {string} basePath
+ * @returns {string}
+ */
 function normalizeBasePath(basePath) {
   if (!_.isString(basePath)) {
     throw new Error(`Invalid path prefix ${basePath}`);
@@ -236,3 +273,56 @@ export {server, configureServer, normalizeBasePath};
  * @property {number} keepAliveTimeout - Keep-alive timeout in milliseconds
  * @property {string} [hostname] - Optional hostname
  */
+
+/**
+ * @typedef {import('@appium/types').AppiumServer} AppiumServer
+ * @typedef {import('@appium/types').AppiumServerSocket} AppiumServerSocket
+ * @typedef {import('@appium/types').MethodMap} MethodMap
+ */
+
+/**
+ * Options for {@linkcode configureHttp}
+ * @typedef ConfigureHttpOpts
+ * @property {import('http').Server} httpServer - HTTP server instance
+ * @property {(error?: any) => void} reject - Rejection function from `Promise` constructor
+ * @property {number} keepAliveTimeout - Keep-alive timeout in milliseconds
+ */
+
+/**
+ * Options for {@linkcode server}
+ * @typedef ServerOpts
+ * @property {RouteConfiguringFunction} routeConfiguringFunction
+ * @property {number} port
+ * @property {import('@appium/types').ServerArgs} cliArgs
+ * @property {string} [hostname]
+ * @property {boolean} [allowCors]
+ * @property {string} [basePath]
+ * @property {MethodMap} [extraMethodMap]
+ * @property {import('@appium/types').UpdateServerCallback[]} [serverUpdaters]
+ * @property {number} [keepAliveTimeout]
+ */
+
+/**
+ * A function which configures routes
+ * @callback RouteConfiguringFunction
+ * @param {import('express').Express} app
+ * @param {RouteConfiguringFunctionOpts} [opts]
+ * @returns {void}
+ */
+
+/**
+ * Options for a {@linkcode RouteConfiguringFunction}
+ * @typedef RouteConfiguringFunctionOpts
+ * @property {string} [basePath]
+ * @property {MethodMap} [extraMethodMap]
+ */
+
+/**
+ * Options for {@linkcode configureServer}
+ * @typedef ConfigureServerOpts
+ * @property {import('express').Express} app
+ * @property {RouteConfiguringFunction} addRoutes
+ * @property {boolean} [allowCors]
+ * @property {string} [basePath]
+ * @property {MethodMap} [extraMethodMap]
+ */

package/lib/express/websocket.js

@@ -1,3 +1,4 @@
+/* eslint-disable require-await */
 import _ from 'lodash';
 import {URL} from 'url';
 import B from 'bluebird';
@@ -9,20 +10,21 @@ const DEFAULT_WS_PATHNAME_PREFIX = '/ws';
  * It is expected this function is called in Express
  * server instance context.
  *
- * @this {WebSocketServer} - An instance of express HTTP server.
+ * @this {AppiumServer} - 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.
- * @param {Object} handlerServer - WebSocket server instance. See
+ * @param {import('ws').Server} handlerServer - WebSocket server instance. See
  * https://github.com/websockets/ws/pull/885 for more details
  * on how to configure the handler properly.
+ * @returns {Promise<void>}
  */
-// eslint-disable-next-line require-await
 async function addWebSocketHandler(handlerPathname, handlerServer) {
+  const server = /** @type {AppiumServer} */ (this);
   if (_.isUndefined(this.webSocketsMapping)) {
-    this.webSocketsMapping = {};
+    server.webSocketsMapping = {};
     // https://github.com/websockets/ws/pull/885
-    this.on('upgrade', (request, socket, head) => {
+    server.on('upgrade', (request, socket, head) => {
       let currentPathname;
       try {
         // @ts-expect-error
@@ -30,7 +32,7 @@ async function addWebSocketHandler(handlerPathname, handlerServer) {
       } catch {
         currentPathname = request.url;
       }
-      for (const [pathname, wsServer] of _.toPairs(this.webSocketsMapping)) {
+      for (const [pathname, wsServer] of _.toPairs(server.webSocketsMapping)) {
         if (currentPathname === pathname) {
           wsServer.handleUpgrade(request, socket, head, (ws) => {
             wsServer.emit('connection', ws, request);
@@ -50,10 +52,10 @@ async function addWebSocketHandler(handlerPathname, handlerServer) {
  * It is expected this function is called in Express
  * server instance context.
  *
+ * @this {AppiumServer}
  * @param {string?} [keysFilter] - Only include pathnames with given
  * `keysFilter` value if set. All pairs will be included by default.
- * @returns {Promise<Object>} pathnames to websocket server isntances mapping
- * matching the search criteria or an empty object otherwise.
+ * @returns {Promise<Record<string, import('ws').Server>>} pathnames to websocket server instances mapping matching the search criteria or an empty object otherwise.
  */
 // eslint-disable-next-line require-await
 async function getWebSocketHandlers(keysFilter = null) {
@@ -75,7 +77,7 @@ async function getWebSocketHandlers(keysFilter = null) {
  * is not present in the handlers list.
  * It is expected this function is called in Express
  * server instance context.
- *
+ * @this {AppiumServer}
  * @param {string} handlerPathname - Websocket endpoint path.
  * @returns {Promise<boolean>} true if the handlerPathname was found and deleted
  */
@@ -104,7 +106,7 @@ async function removeWebSocketHandler(handlerPathname) {
  * Removes all existing websocket handler from express server instance.
  * It is expected this function is called in Express
  * server instance context.
- *
+ * @this {AppiumServer}
  * @returns {Promise<boolean>} true if at least one handler has been deleted
  */
 async function removeAllWebSocketHandlers() {
@@ -128,5 +130,5 @@ export {
 };
 
 /**
- * @typedef {import('http').Server & {webSocketsMapping: Record<string,import('ws').Server>}} WebSocketServer
+ * @typedef {import('@appium/types').AppiumServer} AppiumServer
  */

package/lib/index.js

@@ -7,79 +7,37 @@ B.config({
 // BaseDriver exports
 import {BaseDriver} from './basedriver/driver';
 export {DriverCore} from './basedriver/core';
-import {DeviceSettings} from './basedriver/device-settings';
+export {DeviceSettings} from './basedriver/device-settings';
 
-export {BaseDriver, DeviceSettings};
+export {BaseDriver};
 export default BaseDriver;
 
 // MJSONWP exports
-import * as protocol from './protocol';
-import {DEFAULT_BASE_PATH, PROTOCOLS} from './constants';
-
-const {
-  routeConfiguringFunction,
-  errors,
-  isErrorType,
-  errorFromMJSONWPStatusCode,
-  errorFromW3CJsonCode,
-  ALL_COMMANDS,
-  METHOD_MAP,
-  routeToCommandName,
-  NO_SESSION_ID_COMMANDS,
-  isSessionCommand,
-  determineProtocol,
-  CREATE_SESSION_COMMAND,
-  DELETE_SESSION_COMMAND,
-  GET_STATUS_COMMAND,
-} = protocol;
-
-export {
-  routeConfiguringFunction,
-  errors,
-  isErrorType,
-  PROTOCOLS,
-  errorFromMJSONWPStatusCode,
-  errorFromW3CJsonCode,
-  determineProtocol,
-  errorFromMJSONWPStatusCode as errorFromCode,
-  ALL_COMMANDS,
-  METHOD_MAP,
-  routeToCommandName,
-  NO_SESSION_ID_COMMANDS,
-  isSessionCommand,
-  DEFAULT_BASE_PATH,
-  CREATE_SESSION_COMMAND,
-  DELETE_SESSION_COMMAND,
-  GET_STATUS_COMMAND,
-};
+export * from './protocol';
+export {errorFromMJSONWPStatusCode as errorFromCode} from './protocol';
+export {DEFAULT_BASE_PATH, PROTOCOLS} from './constants';
 
 // Express exports
-import * as staticIndex from './express/static';
-const {STATIC_DIR} = staticIndex;
-export {STATIC_DIR};
-
-import * as serverIndex from './express/server';
-const {server, normalizeBasePath} = serverIndex;
-export {server, normalizeBasePath};
+export {STATIC_DIR} from './express/static';
+export {server, normalizeBasePath} from './express/server';
 
 // jsonwp-proxy exports
-import * as proxyIndex from './jsonwp-proxy/proxy';
-const {JWProxy} = proxyIndex;
-export {JWProxy};
+export {JWProxy} from './jsonwp-proxy/proxy';
 
 // jsonwp-status exports
-import * as statusIndex from './jsonwp-status/status';
-const {codes: statusCodes, getSummaryByCode} = statusIndex;
-export {statusCodes, getSummaryByCode};
+export {getSummaryByCode, codes as statusCodes} from './jsonwp-status/status';
 
 // W3C capabilities parser
-import * as caps from './basedriver/capabilities';
-const {processCapabilities, isStandardCap, validateCaps} = caps;
-export {processCapabilities, isStandardCap, validateCaps};
+export {
+  PREFIXED_APPIUM_OPTS_CAP,
+  processCapabilities,
+  isStandardCap,
+  validateCaps,
+} from './basedriver/capabilities';
 
 // Web socket helpers
-import * as ws from './express/websocket';
-const {DEFAULT_WS_PATHNAME_PREFIX} = ws;
-export {DEFAULT_WS_PATHNAME_PREFIX};
+export {DEFAULT_WS_PATHNAME_PREFIX} from './express/websocket';
 
-export {PREFIXED_APPIUM_OPTS_CAP} from './basedriver/capabilities';
+/**
+ * @typedef {import('./express/server').ServerOpts} ServerOpts
+ */

package/lib/protocol/index.js

@@ -5,6 +5,8 @@ import {
   CREATE_SESSION_COMMAND,
   DELETE_SESSION_COMMAND,
   GET_STATUS_COMMAND,
+  makeArgs,
+  checkParams,
 } from './protocol';
 import {NO_SESSION_ID_COMMANDS, ALL_COMMANDS, METHOD_MAP, routeToCommandName} from './routes';
 import {errors, isErrorType, errorFromMJSONWPStatusCode, errorFromW3CJsonCode} from './errors';
@@ -13,6 +15,8 @@ export {
   routeConfiguringFunction,
   errors,
   isErrorType,
+  makeArgs,
+  checkParams,
   errorFromMJSONWPStatusCode,
   errorFromW3CJsonCode,
   ALL_COMMANDS,

package/lib/protocol/protocol.js

@@ -94,7 +94,7 @@ function unwrapParams(paramSets, jsonObj) {
   return res;
 }
 
-function checkParams(paramSets, jsonObj, protocol) {
+export function checkParams(paramSets, jsonObj, protocol) {
   let requiredParams = [];
   let optionalParams = [];
   let receivedParams = _.keys(jsonObj);
@@ -162,7 +162,7 @@ function checkParams(paramSets, jsonObj, protocol) {
  * on handling parameters. This method returns an array of arguments which will
  * be applied to a command.
  */
-function makeArgs(requestParams, jsonObj, payloadParams, protocol) {
+export function makeArgs(requestParams, jsonObj, payloadParams, protocol) {
   // We want to pass the "url" parameters to the commands in reverse order
   // since the command will sometimes want to ignore, say, the sessionId.
   // This has the effect of putting sessionId last, which means in JS we can
@@ -212,18 +212,25 @@ function makeArgs(requestParams, jsonObj, payloadParams, protocol) {
   return args;
 }
 
+/**
+ *
+ * @param {import('@appium/types').Core} driver
+ * @returns {import('../express/server').RouteConfiguringFunction}
+ */
 function routeConfiguringFunction(driver) {
   if (!driver.sessionExists) {
     throw new Error('Drivers must implement `sessionExists` property');
   }
 
+  // "execute" isn't defined anywhere
+  // @ts-expect-error
   if (!(driver.executeCommand || driver.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
   // passed in as defined by Appium plugins, so we need to add those to the default list
-  return function addRoutes(app, {basePath = DEFAULT_BASE_PATH, extraMethodMap = {}}) {
+  return function addRoutes(app, {basePath = DEFAULT_BASE_PATH, extraMethodMap = {}} = {}) {
     // store basePath on the driver instance so it can use it if necessary
     // for example in determining proxy avoidance
     driver.basePath = basePath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/base-driver",
-  "version": "8.5.7",
+  "version": "8.7.0",
   "description": "Base driver class for Appium drivers",
   "keywords": [
     "automation",
@@ -31,28 +31,29 @@
     "index.d.ts",
     "lib",
     "static",
-    "test/basedriver",
-    "!test/e2e/fixtures",
-    "build",
-    "!build/test/e2e/fixtures"
+    "build"
   ],
   "scripts": {
-    "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\"",
+    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
     "prepare": "npm run build",
     "test": "npm run test:unit",
     "test:e2e": "mocha --timeout 20s --slow 10s \"./test/e2e/**/*.spec.js\"",
+    "test:smoke": "node ./index.js",
     "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/support": "^2.59.2",
-    "@babel/runtime": "7.18.3",
+    "@appium/support": "^2.59.5",
+    "@babel/runtime": "7.18.9",
     "@colors/colors": "1.5.0",
-    "async-lock": "1.3.1",
+    "@types/async-lock": "1.1.5",
+    "@types/bluebird": "3.5.36",
+    "@types/express": "4.17.13",
+    "@types/method-override": "0.0.32",
+    "@types/serve-favicon": "2.5.3",
+    "async-lock": "1.3.2",
     "asyncbox": "2.9.2",
     "axios": "0.27.2",
     "bluebird": "3.7.2",
@@ -61,20 +62,21 @@
     "express": "4.18.1",
     "http-status-codes": "2.2.0",
     "lodash": "4.17.21",
-    "lru-cache": "7.10.1",
+    "lru-cache": "7.13.2",
     "method-override": "3.0.0",
     "morgan": "1.10.0",
     "serve-favicon": "2.5.0",
     "source-map-support": "0.5.21",
+    "type-fest": "2.18.0",
     "validate.js": "0.13.1"
   },
   "engines": {
     "node": ">=14",
-    "npm": ">=6"
+    "npm": ">=8"
   },
   "publishConfig": {
     "access": "public"
   },
   "types": "./build/lib/index.d.ts",
-  "gitHead": "4cf2cc92d066ed32adda27e0439547290a4b71ce"
+  "gitHead": "c58f32441daba3aae9768a57d0a412fe92f4b587"
 }

package/build/test/basedriver/README.md

@@ -1,5 +0,0 @@
-# Driver Test Helpers
-
-This directory contains modules which expose test suites that an external driver can use to test against the base implementation.  They are published in the `@appium/base-driver` package.
-
-Drivers wanting to leverage these suites will want to add `@appium/base-driver` to their `devDependencies`.