@appium/base-driver 8.5.3 → 8.5.6

package/lib/jsonwp-proxy/proxy.js

@@ -1,30 +1,61 @@
 import _ from 'lodash';
-import { logger, util } from '@appium/support';
+import {logger, util} from '@appium/support';
 import axios from 'axios';
-import { getSummaryByCode } from '../jsonwp-status/status';
+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';
+import {routeToCommandName} from '../protocol';
+import {MAX_LOG_BODY_LENGTH, DEFAULT_BASE_PATH, PROTOCOLS} from '../constants';
 import ProtocolConverter from './protocol-converter';
-import { formatResponseValue, formatStatus } from '../protocol/helpers';
+import {formatResponseValue, formatStatus} from '../protocol/helpers';
 import http from 'http';
 import https from 'https';
 
 const DEFAULT_LOG = logger.getLogger('WD Proxy');
 const DEFAULT_REQUEST_TIMEOUT = 240000;
-const COMPACT_ERROR_PATTERNS = [
-  /\bECONNREFUSED\b/,
-  /socket hang up/,
-];
+const COMPACT_ERROR_PATTERNS = [/\bECONNREFUSED\b/, /socket hang up/];
 
 const {MJSONWP, W3C} = PROTOCOLS;
 
+const ALLOWED_OPTS = [
+  'scheme',
+  'server',
+  'port',
+  'base',
+  'reqBasePath',
+  'sessionId',
+  'timeout',
+  'log',
+  'keepAlive',
+];
+
 class JWProxy {
-  constructor (opts = {}) {
-    _.defaults(this, opts, {
+  /** @type {string} */
+  scheme;
+  /** @type {string} */
+  server;
+  /** @type {number} */
+  port;
+  /** @type {string} */
+  base;
+  /** @type {string} */
+  reqBasePath;
+  /** @type {string?} */
+  sessionId;
+  /** @type {number} */
+  timeout;
+
+  constructor(opts = {}) {
+    opts = _.pick(opts, ALLOWED_OPTS);
+
+    // omit 'log' in the defaults assignment here because 'log' is a getter and we are going to set
+    // it to this._log (which lies behind the getter) further down
+    const options = _.defaults(_.omit(opts, 'log'), {
       scheme: 'http',
       server: 'localhost',
       port: 4444,
@@ -33,7 +64,9 @@ class JWProxy {
       sessionId: null,
       timeout: DEFAULT_REQUEST_TIMEOUT,
     });
-    this.scheme = this.scheme.toLowerCase();
+    options.scheme = options.scheme.toLowerCase();
+    Object.assign(this, options);
+
     this._activeRequests = [];
     this._downstreamProtocol = null;
     const agentOpts = {
@@ -47,7 +80,7 @@ class JWProxy {
     this._log = opts.log;
   }
 
-  get log () {
+  get log() {
     return this._log ?? DEFAULT_LOG;
   }
 
@@ -57,10 +90,10 @@ class JWProxy {
    * @private - Do not call this method directly,
    * it uses client-specific arguments and responses!
    *
-   * @param {AxiosRequestConfig} requestConfig
-   * @returns {AxiosResponse}
+   * @param {import('axios').AxiosRequestConfig} requestConfig
+   * @returns {Promise<import('axios').AxiosResponse>}
    */
-  async request (requestConfig) {
+  async request(requestConfig) {
     const reqPromise = axios(requestConfig);
     this._activeRequests.push(reqPromise);
     try {
@@ -70,28 +103,28 @@ class JWProxy {
     }
   }
 
-  getActiveRequestsCount () {
+  getActiveRequestsCount() {
     return this._activeRequests.length;
   }
 
-  cancelActiveRequests () {
+  cancelActiveRequests() {
     this._activeRequests = [];
   }
 
-  endpointRequiresSessionId (endpoint) {
+  endpointRequiresSessionId(endpoint) {
     return !_.includes(['/session', '/sessions', '/status'], endpoint);
   }
 
-  set downstreamProtocol (value) {
+  set downstreamProtocol(value) {
     this._downstreamProtocol = value;
     this.protocolConverter.downstreamProtocol = value;
   }
 
-  get downstreamProtocol () {
+  get downstreamProtocol() {
     return this._downstreamProtocol;
   }
 
-  getUrlForProxy (url) {
+  getUrlForProxy(url) {
     if (url === '') {
       url = '/';
     }
@@ -99,12 +132,12 @@ class JWProxy {
     const endpointRe = '(/(session|status))';
     let remainingUrl = '';
     if (/^http/.test(url)) {
-      const first = (new RegExp(`(https?://.+)${endpointRe}`)).exec(url);
+      const first = new RegExp(`(https?://.+)${endpointRe}`).exec(url);
       if (!first) {
         throw new Error('Got a complete url but could not extract JWP endpoint');
       }
       remainingUrl = url.replace(first[1], '');
-    } else if ((new RegExp('^/')).test(url)) {
+    } else if (new RegExp('^/').test(url)) {
       remainingUrl = url;
     } else {
       throw new Error(`Did not know what to do with url '${url}'`);
@@ -112,10 +145,10 @@ class JWProxy {
 
     const stripPrefixRe = new RegExp('^.*?(/(session|status).*)$');
     if (stripPrefixRe.test(remainingUrl)) {
-      remainingUrl = stripPrefixRe.exec(remainingUrl)[1];
+      remainingUrl = /** @type {RegExpExecArray} */ (stripPrefixRe.exec(remainingUrl))[1];
     }
 
-    if (!(new RegExp(endpointRe)).test(remainingUrl)) {
+    if (!new RegExp(endpointRe).test(remainingUrl)) {
       remainingUrl = `/session/${this.sessionId}${remainingUrl}`;
     }
 
@@ -127,10 +160,20 @@ class JWProxy {
 
     const sessionBaseRe = new RegExp('^/session/([^/]+)');
     if (sessionBaseRe.test(remainingUrl)) {
+      if (this.sessionId === null) {
+        throw new ReferenceError(
+          `Session ID is not set, but saw a URL path referencing a session (${remainingUrl}). This may be a bug in your client.`
+        );
+      }
       // we have something like /session/:id/foobar, so we need to replace
       // the session id
       const match = sessionBaseRe.exec(remainingUrl);
-      remainingUrl = remainingUrl.replace(match[1], this.sessionId);
+      // TODO: if `requiresSessionId` is `false` and `sessionId` is `null`, this is a bug.
+      // are we sure `sessionId` is not `null`?
+      remainingUrl = remainingUrl.replace(
+        /** @type {RegExpExecArray} */ (match)[1],
+        /** @type {string} */ (this.sessionId)
+      );
     } else if (requiresSessionId) {
       throw new Error(`Could not find :session section for url: ${remainingUrl}`);
     }
@@ -139,12 +182,14 @@ class JWProxy {
     return proxyBase + remainingUrl;
   }
 
-  async proxy (url, method, body = null) {
+  async proxy(url, method, body = null) {
     method = method.toUpperCase();
     const newUrl = this.getUrlForProxy(url);
-    const truncateBody = (content) => _.truncate(
-      _.isString(content) ? content : JSON.stringify(content),
-      { length: MAX_LOG_BODY_LENGTH });
+    const truncateBody = (content) =>
+      _.truncate(_.isString(content) ? content : JSON.stringify(content), {
+        length: MAX_LOG_BODY_LENGTH,
+      });
+    /** @type {import('axios').AxiosRequestConfig} */
     const reqOpts = {
       url: newUrl,
       method,
@@ -171,14 +216,16 @@ class JWProxy {
       }
     }
 
-    this.log.debug(`Proxying [${method} ${url || '/'}] to [${method} ${newUrl}] ` +
-      (reqOpts.data ? `with body: ${truncateBody(reqOpts.data)}` : 'with no body'));
+    this.log.debug(
+      `Proxying [${method} ${url || '/'}] to [${method} ${newUrl}] ` +
+        (reqOpts.data ? `with body: ${truncateBody(reqOpts.data)}` : 'with no body')
+    );
 
     const throwProxyError = (error) => {
-      const err = new Error(`The request to ${url} has failed`);
+      const err = /** @type {ProxyError} */ (new Error(`The request to ${url} has failed`));
       err.response = {
         data: error,
-        status: 500
+        status: 500,
       };
       throw err;
     };
@@ -216,9 +263,11 @@ class JWProxy {
       if (util.hasValue(e.response)) {
         if (!isResponseLogged) {
           const error = truncateBody(e.response.data);
-          this.log.info(util.hasValue(e.response.status)
-            ? `Got response with status ${e.response.status}: ${error}`
-            : `Got response with unknown status: ${error}`);
+          this.log.info(
+            util.hasValue(e.response.status)
+              ? `Got response with status ${e.response.status}: ${error}`
+              : `Got response with unknown status: ${error}`
+          );
         }
       } else {
         proxyErrorMsg = `Could not proxy command to the remote server. Original error: ${e.message}`;
@@ -232,7 +281,7 @@ class JWProxy {
     }
   }
 
-  getProtocolFromResBody (resObj) {
+  getProtocolFromResBody(resObj) {
     if (_.isInteger(resObj.status)) {
       return MJSONWP;
     }
@@ -241,14 +290,29 @@ class JWProxy {
     }
   }
 
-  requestToCommandName (url, method) {
+  /**
+   *
+   * @param {string} url
+   * @param {import('@appium/types').HTTPMethod} method
+   * @returns {string|undefined}
+   */
+  requestToCommandName(url, method) {
+    /**
+     *
+     * @param {RegExp} pattern
+     * @returns {string|undefined}
+     */
     const extractCommandName = (pattern) => {
       const pathMatch = pattern.exec(url);
-      return pathMatch ? routeToCommandName(pathMatch[1], method, this.reqBasePath) : null;
+      if (pathMatch) {
+        return routeToCommandName(pathMatch[1], method, this.reqBasePath);
+      }
     };
     let commandName = routeToCommandName(url, method, this.reqBasePath);
     if (!commandName && _.includes(url, `${this.reqBasePath}/session/`)) {
-      commandName = extractCommandName(new RegExp(`${_.escapeRegExp(this.reqBasePath)}/session/[^/]+(.+)`));
+      commandName = extractCommandName(
+        new RegExp(`${_.escapeRegExp(this.reqBasePath)}/session/[^/]+(.+)`)
+      );
     }
     if (!commandName && _.includes(url, this.reqBasePath)) {
       commandName = extractCommandName(new RegExp(`${_.escapeRegExp(this.reqBasePath)}(/.+)`));
@@ -256,7 +320,7 @@ class JWProxy {
     return commandName;
   }
 
-  async proxyCommand (url, method, body = null) {
+  async proxyCommand(url, method, body = null) {
     const commandName = this.requestToCommandName(url, method);
     if (!commandName) {
       return await this.proxy(url, method, body);
@@ -266,7 +330,7 @@ class JWProxy {
     return await this.protocolConverter.convertAndProxy(commandName, url, method, body);
   }
 
-  async command (url, method, body = null) {
+  async command(url, method, body = null) {
     let response;
     let resBodyObj;
     try {
@@ -289,7 +353,10 @@ class JWProxy {
         if (_.has(message, 'message')) {
           message = message.message;
         }
-        throw errorFromMJSONWPStatusCode(status, _.isEmpty(message) ? getSummaryByCode(status) : message);
+        throw errorFromMJSONWPStatusCode(
+          status,
+          _.isEmpty(message) ? getSummaryByCode(status) : message
+        );
       }
     } else if (protocol === W3C) {
       // Got response in W3C format
@@ -297,22 +364,30 @@ class JWProxy {
         return resBodyObj.value;
       }
       if (_.isPlainObject(resBodyObj.value) && resBodyObj.value.error) {
-        throw errorFromW3CJsonCode(resBodyObj.value.error, resBodyObj.value.message, resBodyObj.value.stacktrace);
+        throw errorFromW3CJsonCode(
+          resBodyObj.value.error,
+          resBodyObj.value.message,
+          resBodyObj.value.stacktrace
+        );
       }
     } else if (response.statusCode === 200) {
       // Unknown protocol. Keeping it because of the backward compatibility
       return resBodyObj;
     }
-    throw new errors.UnknownError(`Did not know what to do with response code '${response.statusCode}' ` +
-                                  `and response body '${_.truncate(JSON.stringify(resBodyObj), {length: 300})}'`);
+    throw new errors.UnknownError(
+      `Did not know what to do with response code '${response.statusCode}' ` +
+        `and response body '${_.truncate(JSON.stringify(resBodyObj), {
+          length: 300,
+        })}'`
+    );
   }
 
-  getSessionIdFromUrl (url) {
+  getSessionIdFromUrl(url) {
     const match = url.match(/\/session\/([^/]+)/);
     return match ? match[1] : null;
   }
 
-  async proxyReqRes (req, res) {
+  async proxyReqRes(req, res) {
     // ! this method must not throw any exceptions
     // ! make sure to call res.send before return
     let statusCode;
@@ -331,7 +406,7 @@ class JWProxy {
     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})
+          _.truncate(`${resBodyObj}`, {length: 300})
       );
       [statusCode, resBodyObj] = getResponseForW3CError(error);
     }
@@ -354,5 +429,9 @@ class JWProxy {
   }
 }
 
-export { JWProxy };
+export {JWProxy};
 export default JWProxy;
+
+/**
+ * @typedef {Error & {response: {data: import('type-fest').JsonObject, status: import('http-status-codes').StatusCodes}}} ProxyError
+ */

package/lib/jsonwp-status/status.js

@@ -3,111 +3,118 @@ import _ from 'lodash';
 const codes = {
   Success: {
     code: 0,
-    summary: 'The command executed successfully.'
+    summary: 'The command executed successfully.',
   },
   NoSuchDriver: {
     code: 6,
-    summary: 'A session is either terminated or not started'
+    summary: 'A session is either terminated or not started',
   },
   NoSuchElement: {
     code: 7,
-    summary: 'An element could not be located on the page using the given search parameters.'
+    summary: 'An element could not be located on the page using the given search parameters.',
   },
   NoSuchFrame: {
     code: 8,
-    summary: 'A request to switch to a frame could not be satisfied because the frame could not be found.'
+    summary:
+      'A request to switch to a frame could not be satisfied because the frame could not be found.',
   },
   UnknownCommand: {
     code: 9,
-    summary: 'The requested resource could not be found, or a request was received using an HTTP method that is not supported by the mapped resource.'
+    summary:
+      'The requested resource could not be found, or a request was received using an HTTP method that is not supported by the mapped resource.',
   },
   StaleElementReference: {
     code: 10,
-    summary: 'An element command failed because the referenced element is no longer attached to the DOM.'
+    summary:
+      'An element command failed because the referenced element is no longer attached to the DOM.',
   },
   ElementNotVisible: {
     code: 11,
-    summary: 'An element command could not be completed because the element is not visible on the page.'
+    summary:
+      'An element command could not be completed because the element is not visible on the page.',
   },
   InvalidElementState: {
     code: 12,
-    summary: 'An element command could not be completed because the element is in an invalid state (e.g. attempting to click a disabled element).'
+    summary:
+      'An element command could not be completed because the element is in an invalid state (e.g. attempting to click a disabled element).',
   },
   UnknownError: {
     code: 13,
-    summary: 'An unknown server-side error occurred while processing the command.'
+    summary: 'An unknown server-side error occurred while processing the command.',
   },
   ElementIsNotSelectable: {
     code: 15,
-    summary: 'An attempt was made to select an element that cannot be selected.'
+    summary: 'An attempt was made to select an element that cannot be selected.',
   },
   JavaScriptError: {
     code: 17,
-    summary: 'An error occurred while executing user supplied JavaScript.'
+    summary: 'An error occurred while executing user supplied JavaScript.',
   },
   XPathLookupError: {
     code: 19,
-    summary: 'An error occurred while searching for an element by XPath.'
+    summary: 'An error occurred while searching for an element by XPath.',
   },
   Timeout: {
     code: 21,
-    summary: 'An operation did not complete before its timeout expired.'
+    summary: 'An operation did not complete before its timeout expired.',
   },
   NoSuchWindow: {
     code: 23,
-    summary: 'A request to switch to a different window could not be satisfied because the window could not be found.'
+    summary:
+      'A request to switch to a different window could not be satisfied because the window could not be found.',
   },
   InvalidCookieDomain: {
     code: 24,
-    summary: 'An illegal attempt was made to set a cookie under a different domain than the current page.'
+    summary:
+      'An illegal attempt was made to set a cookie under a different domain than the current page.',
   },
   UnableToSetCookie: {
     code: 25,
-    summary: 'A request to set a cookie\'s value could not be satisfied.'
+    summary: "A request to set a cookie's value could not be satisfied.",
   },
   UnexpectedAlertOpen: {
     code: 26,
-    summary: 'A modal dialog was open, blocking this operation'
+    summary: 'A modal dialog was open, blocking this operation',
   },
   NoAlertOpenError: {
     code: 27,
-    summary: 'An attempt was made to operate on a modal dialog when one was not open.'
+    summary: 'An attempt was made to operate on a modal dialog when one was not open.',
   },
   ScriptTimeout: {
     code: 28,
-    summary: 'A script did not complete before its timeout expired.'
+    summary: 'A script did not complete before its timeout expired.',
   },
   InvalidElementCoordinates: {
     code: 29,
-    summary: 'The coordinates provided to an interactions operation are invalid.'
+    summary: 'The coordinates provided to an interactions operation are invalid.',
   },
   IMENotAvailable: {
     code: 30,
-    summary: 'IME was not available.'
+    summary: 'IME was not available.',
   },
   IMEEngineActivationFailed: {
     code: 31,
-    summary: 'An IME engine could not be started.'
+    summary: 'An IME engine could not be started.',
   },
   InvalidSelector: {
     code: 32,
-    summary: 'Argument was an invalid selector (e.g. XPath/CSS).'
+    summary: 'Argument was an invalid selector (e.g. XPath/CSS).',
   },
   SessionNotCreatedException: {
     code: 33,
-    summary: 'A new session could not be created.'
+    summary: 'A new session could not be created.',
   },
   MoveTargetOutOfBounds: {
     code: 34,
-    summary: 'Target provided for a move action is out of bounds.'
+    summary: 'Target provided for a move action is out of bounds.',
   },
   NoSuchContext: {
     code: 35,
-    summary: 'No such context found.'
-  }
+    summary: 'No such context found.',
+  },
 };
 
-function getSummaryByCode (code) {
+function getSummaryByCode(code) {
   code = parseInt(code, 10);
   for (let obj of _.values(codes)) {
     if (!_.isUndefined(obj.code) && obj.code === code) {
@@ -118,4 +125,4 @@ function getSummaryByCode (code) {
 }
 
 export default codes;
-export { codes, getSummaryByCode };
+export {codes, getSummaryByCode};