@appium/base-driver 9.17.0 → 10.0.0-beta.1

package/lib/basedriver/validation.ts

@@ -0,0 +1,145 @@
+import type { Constraint } from '@appium/types';
+import log from './logger';
+import _ from 'lodash';
+
+export class Validator {
+  private readonly _validators: Record<
+    keyof Constraint,
+    (value: any, options?: any, key?: string) => string | null
+  > = {
+    isString: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || _.isNil(options)) {
+        return null;
+      }
+
+      if (_.isString(value)) {
+        return options ? null : 'must not be of type string';
+      }
+
+      return options ? 'must be of type string' : null;
+    },
+    isNumber: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || _.isNil(options)) {
+        return null;
+      }
+
+      if (_.isNumber(value)) {
+        return options ? null : 'must not be of type number';
+      }
+
+      // allow a string value
+      if (options && _.isString(value) && !isNaN(Number(value))) {
+        log.warn('Number capability passed in as string. Functionality may be compromised.');
+        return null;
+      }
+
+      return options ? 'must be of type number' : null;
+    },
+    isBoolean: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || _.isNil(options)) {
+        return null;
+      }
+
+      if (_.isBoolean(value)) {
+        return options ? null : 'must not be of type boolean';
+      }
+
+      // allow a string value
+      if (options && _.isString(value) && ['true', 'false', ''].includes(value)) {
+        return null;
+      }
+
+      return options ? 'must be of type boolean' : null;
+    },
+    isObject: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || _.isNil(options)) {
+        return null;
+      }
+
+      if (_.isPlainObject(value)) {
+        return options ? null : 'must not be a plain object';
+      }
+
+      return options ? 'must be a plain object' : null;
+    },
+    isArray: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || _.isNil(options)) {
+        return null;
+      }
+
+      if (_.isArray(value)) {
+        return options ? null : 'must not be of type array';
+      }
+
+      return options ? 'must be of type array' : null;
+    },
+    deprecated: (value: any, options?: any, key?: string): string | null => {
+      if (!_.isUndefined(value) && options) {
+        log.warn(
+          `The '${key}' capability has been deprecated and must not be used anymore. ` +
+          `Please check the driver documentation for possible alternatives.`
+        );
+      }
+      return null;
+    },
+    inclusion: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || !options) {
+        return null;
+      }
+      const optionsArr = _.isArray(options) ? options : [options];
+      if (optionsArr.some((opt) => opt === value)) {
+        return null;
+      }
+      return `must be contained by ${JSON.stringify(optionsArr)}`;
+    },
+    inclusionCaseInsensitive: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || !options) {
+        return null;
+      }
+      const optionsArr = _.isArray(options) ? options : [options];
+      if (optionsArr.some((opt) => _.toLower(opt) === _.toLower(value))) {
+        return null;
+      }
+      return `must be contained by ${JSON.stringify(optionsArr)}`;
+    },
+    presence: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) && options) {
+        return 'is required to be present';
+      }
+      if (
+        !options?.allowEmpty &&
+        ((!_.isUndefined(value) && _.isEmpty(value)) || (_.isString(value) && !_.trim(value)))
+      ) {
+        return 'must not be empty or blank';
+      }
+      return null;
+    }
+  };
+
+  validate(values: Record<string, any>, constraints: Record<string, Constraint>): Record<string, string[]> | null {
+    const result: Record<string, string[]> = {};
+    for (const [key, constraint] of _.toPairs(constraints)) {
+      const value = values[key];
+      for (const [validatorName, options] of _.toPairs(constraint)) {
+        if (!(validatorName in this._validators)) {
+          continue;
+        }
+
+        const validationError = this._validators[validatorName](value, options, key);
+        if (_.isNil(validationError)) {
+          continue;
+        }
+
+        if (key in result) {
+          result[key].push(validationError);
+        } else {
+          result[key] = [validationError];
+        }
+      }
+    }
+    return _.isEmpty(result) ? null : result;
+  }
+
+}
+
+export const validator = new Validator();

package/lib/express/middleware.js

@@ -5,6 +5,9 @@ export {handleIdempotency} from './idempotency';
 import {match} from 'path-to-regexp';
 import {util} from '@appium/support';
 import {calcSignature} from '../helpers/session';
+import {getResponseForW3CError} from '../protocol/errors';
+
+const SESSION_ID_PATTERN = /\/session\/([^/]+)/;
 
 /**
  *
@@ -14,20 +17,16 @@ import {calcSignature} from '../helpers/session';
  * @returns {any}
  */
 export 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-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'
+  );
 
-    // need to respond 200 to OPTIONS
-    if ('OPTIONS' === req.method) {
-      return res.sendStatus(200);
-    }
-  } catch (err) {
-    log.error(`Unexpected error: ${err.stack}`);
+  // need to respond 200 to OPTIONS
+  if ('OPTIONS' === req.method) {
+    return res.sendStatus(200);
   }
   next();
 }
@@ -50,26 +49,6 @@ export function allowCrossDomainAsyncExecute(basePath) {
   };
 }
 
-/**
- *
- * @param {string} basePath
- * @returns {import('express').RequestHandler}
- */
-export 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 (req.headers['content-type'] === 'application/x-www-form-urlencoded') {
-        req.headers['content-type'] = 'application/json; charset=utf-8';
-      }
-    }
-    next();
-  };
-}
-
 /**
  *
  * @param {import('express').Request} req
@@ -147,19 +126,8 @@ export 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,
-      },
-    })
-  );
-  log.error(err);
+  const [status, body] = getResponseForW3CError(err);
+  res.status(status).json(body);
 }
 
 /**
@@ -168,35 +136,8 @@ export function catchAllHandler(err, req, res, next) {
  */
 export 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: '',
-      },
-    })
-  );
-}
-
-const SESSION_ID_PATTERN = /\/session\/([^/]+)/;
-
-/**
- * @param {import('express').Request} req
- * @param {any} body
- * @returns {any}
- */
-function patchWithSessionId(req, body) {
-  const match = SESSION_ID_PATTERN.exec(req.url);
-  if (match) {
-    body.sessionId = match[1];
-  }
-  return body;
+  const [status, body] = getResponseForW3CError(new errors.UnknownCommandError());
+  res.status(status).json(body);
 }
 
 /**

package/lib/express/server.js

@@ -9,7 +9,6 @@ import log from './logger';
 import {startLogFormatter, endLogFormatter} from './express-logging';
 import {
   allowCrossDomain,
-  fixPythonContentType,
   defaultToJSONContentType,
   catchAllHandler,
   allowCrossDomainAsyncExecute,
@@ -122,7 +121,7 @@ export async function server(opts) {
       // once all configurations and updaters have been applied, make sure to set up a catchall
       // handler so that anything unknown 404s. But do this after everything else since we don't
       // want to block extensions' ability to add routes if they want.
-      app.all('*', catch404Handler);
+      app.all('/*all', catch404Handler);
 
       await startServer({
         httpServer,
@@ -172,7 +171,6 @@ export function configureServer({
     app.use(allowCrossDomainAsyncExecute(basePath));
   }
   app.use(handleIdempotency);
-  app.use(fixPythonContentType(basePath));
   app.use(defaultToJSONContentType);
   app.use(bodyParser.urlencoded({extended: true}));
   app.use(methodOverride());

package/lib/helpers/capabilities.js

@@ -2,7 +2,14 @@
 
 import _ from 'lodash';
 
-function isW3cCaps(caps) {
+/**
+ * Determine whether the given agument is valid
+ * W3C capabilities instance.
+ *
+ * @param {any} caps
+ * @returns {caps is import('@appium/types').W3CCapabilities}
+ */
+export function isW3cCaps(caps) {
   if (!_.isPlainObject(caps)) {
     return false;
   }
@@ -32,7 +39,7 @@ function isW3cCaps(caps) {
  * @param {AppiumLogger} log
  * @returns {Capabilities<C>}
  */
-function fixCaps(oldCaps, desiredCapConstraints, log) {
+export function fixCaps(oldCaps, desiredCapConstraints, log) {
   let caps = _.clone(oldCaps);
 
   // boolean capabilities can be passed in as strings 'false' and 'true'
@@ -73,8 +80,6 @@ function fixCaps(oldCaps, desiredCapConstraints, log) {
   return caps;
 }
 
-export {isW3cCaps, fixCaps};
-
 /**
  * @typedef {import('@appium/types').Constraints} Constraints
  * @typedef {import('@appium/types').AppiumLogger} AppiumLogger

package/lib/index.js

@@ -54,6 +54,8 @@ export {BIDI_COMMANDS} from './protocol/bidi-commands';
 
 export {generateDriverLogPrefix} from './basedriver/helpers';
 
+export {isW3cCaps} from './helpers/capabilities';
+
 /**
  * @typedef {import('./express/server').ServerOpts} ServerOpts
  */

package/lib/jsonwp-proxy/proxy.js

@@ -11,7 +11,7 @@ import {
 import {isSessionCommand, 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, ensureW3cResponse} from '../protocol/helpers';
 import http from 'http';
 import https from 'https';
 import { match as pathToRegexMatch } from 'path-to-regexp';
@@ -290,37 +290,6 @@ export class JWProxy {
     }
   }
 
-  /**
-   * @deprecated This method is not used anymore and will be removed
-   *
-   * @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);
-      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/[^/]+(.+)`)
-      );
-    }
-    if (!commandName && _.includes(url, this.reqBasePath)) {
-      commandName = extractCommandName(new RegExp(`${_.escapeRegExp(this.reqBasePath)}(/.+)`));
-    }
-    return commandName;
-  }
-
   /**
    *
    * @param {string} url
@@ -457,7 +426,7 @@ export class JWProxy {
       }
     }
     resBodyObj.value = formatResponseValue(resBodyObj.value);
-    res.status(statusCode).send(JSON.stringify(formatStatus(resBodyObj)));
+    res.status(statusCode).json(ensureW3cResponse(resBodyObj));
   }
 
   /**