@appium/base-driver 8.2.4 → 8.4.0

package/lib/basedriver/helpers.js

@@ -2,7 +2,7 @@ import _ from 'lodash';
 import path from 'path';
 import url from 'url';
 import logger from './logger';
-import { tempDir, fs, util, zip, net, timing } from '@appium/support';
+import { tempDir, fs, util, zip, net, timing, node } from '@appium/support';
 import LRU from 'lru-cache';
 import AsyncLock from 'async-lock';
 import axios from 'axios';
@@ -15,17 +15,17 @@ const ZIP_MIME_TYPES = [
   'multipart/x-zip',
 ];
 const CACHED_APPS_MAX_AGE = 1000 * 60 * 60 * 24; // ms
+const MAX_CACHED_APPS = 1024;
 const APPLICATIONS_CACHE = new LRU({
-  maxAge: CACHED_APPS_MAX_AGE, // expire after 24 hours
+  max: MAX_CACHED_APPS,
+  ttl: CACHED_APPS_MAX_AGE, // expire after 24 hours
   updateAgeOnGet: true,
   dispose: (app, {fullPath}) => {
     logger.info(`The application '${app}' cached at '${fullPath}' has ` +
       `expired after ${CACHED_APPS_MAX_AGE}ms`);
-    setTimeout(async () => {
-      if (fullPath) {
-        await fs.rimraf(fullPath);
-      }
-    });
+    if (fullPath) {
+      fs.rimraf(fullPath);
+    }
   },
   noDisposeOnSet: true,
 });
@@ -35,11 +35,11 @@ const DEFAULT_BASENAME = 'appium-app';
 const APP_DOWNLOAD_TIMEOUT_MS = 120 * 1000;
 
 process.on('exit', () => {
-  if (APPLICATIONS_CACHE.itemCount === 0) {
+  if (APPLICATIONS_CACHE.size === 0) {
     return;
   }
 
-  const appPaths = APPLICATIONS_CACHE.values()
+  const appPaths = [...APPLICATIONS_CACHE.values()]
     .map(({fullPath}) => fullPath);
   logger.debug(`Performing cleanup of ${appPaths.length} cached ` +
     util.pluralize('application', appPaths.length));
@@ -151,7 +151,7 @@ async function isAppIntegrityOk (currentPath, expectedIntegrity = {}) {
 }
 
 /**
- * @typedef {Object} PostProcessOptions
+ * @typedef PostProcessOptions
  * @property {?Object} cachedAppInfo The information about the previously cached app instance (if exists):
  *    - packageHash: SHA1 hash of the package if it is a file and not a folder
  *    - lastModified: Optional Date instance, the value of file's `Last-Modified` header
@@ -171,13 +171,13 @@ async function isAppIntegrityOk (currentPath, expectedIntegrity = {}) {
  */
 
 /**
- * @typedef {Object} PostProcessResult
+ * @typedef PostProcessResult
  * @property {string} appPath The full past to the post-processed application package on the
  * local file system (might be a file or a folder path)
  */
 
 /**
- * @typedef {Object} ConfigureAppOptions
+ * @typedef ConfigureAppOptions
  * @property {(obj: PostProcessOptions) => (Promise<PostProcessResult|undefined>|PostProcessResult|undefined)} onPostProcess
  * Optional function, which should be applied
  * to the application after it is downloaded/preprocessed. This function may be async
@@ -193,6 +193,8 @@ async function isAppIntegrityOk (currentPath, expectedIntegrity = {}) {
 /**
  * Prepares an app to be used in an automated test. The app gets cached automatically
  * if it is an archive or if it is downloaded from an URL.
+ * If the downloaded app has `.zip` extension, this method will unzip it.
+ * The unzip does not work when `onPostProcess` is provided.
  *
  * @param {string} app Either a full path to the app or a remote URL
  * @param {string|string[]|ConfigureAppOptions} options
@@ -544,6 +546,22 @@ function parseCapsArray (cap) {
   throw new Error(`must provide a string or JSON Array; received ${cap}`);
 }
 
+/**
+ * Generate a string that uniquely describes driver instance
+ *
+ * @param {import('@appium/types').Core} obj driver instance
+ * @param {string?} sessionId session identifier (if exists)
+ * @returns {string}
+ */
+function generateDriverLogPrefix (obj, sessionId = null) {
+  const instanceName = `${obj.constructor.name}@${node.getObjectId(obj).substring(0, 4)}`;
+  return sessionId ? `${instanceName} (${sessionId.substring(0, 8)})` : instanceName;
+}
+
+/** @type {import('@appium/types').DriverHelpers} */
+export default {
+  configureApp, isPackageOrBundle, duplicateKeys, parseCapsArray, generateDriverLogPrefix
+};
 export {
-  configureApp, isPackageOrBundle, duplicateKeys, parseCapsArray
+  configureApp, isPackageOrBundle, duplicateKeys, parseCapsArray, generateDriverLogPrefix
 };

package/lib/express/express-logging.js

@@ -1,5 +1,5 @@
 import _ from 'lodash';
-import '@dabh/colors';
+import '@colors/colors';
 import morgan from 'morgan';
 import log from './logger';
 import { MAX_LOG_BODY_LENGTH } from '../constants';

package/lib/express/idempotency.js

@@ -20,7 +20,7 @@ const MONITORED_METHODS = ['POST', 'PATCH'];
 const IDEMPOTENCY_KEY_HEADER = 'x-idempotency-key';
 
 process.on('exit', () => {
-  const resPaths = IDEMPOTENT_RESPONSES.values()
+  const resPaths = [...IDEMPOTENT_RESPONSES.values()]
     .map(({response}) => response)
     .filter(Boolean);
   for (const resPath of resPaths) {

package/lib/helpers/capabilities.js

@@ -0,0 +1,84 @@
+// @ts-check
+
+import _ from 'lodash';
+
+function isW3cCaps (caps) {
+  if (!_.isPlainObject(caps)) {
+    return false;
+  }
+
+  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();
+  }
+  if (_.has(caps, 'firstMatch')) {
+    return isFirstMatchValid();
+  }
+  if (_.has(caps, 'alwaysMatch')) {
+    return isAlwaysMatchValid();
+  }
+  return false;
+}
+
+/**
+ *
+ * @param {Capabilities} originalCaps
+ * @param {Constraints} desiredCapConstraints
+ * @param {AppiumLogger} log
+ * @returns {Capabilities}
+ */
+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),
+  );
+  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`,
+        );
+        caps[cap] = value === 'true';
+      }
+    }
+  }
+
+  // int capabilities are often sent in as strings by frameworks
+  let intCaps = _.keys(
+    _.pickBy(desiredCapConstraints, (k) => k.isNumber === true),
+  );
+  for (let cap of intCaps) {
+    let value = originalCaps[cap];
+    if (_.isString(value)) {
+      value = value.trim();
+      let newValue = parseInt(value, 10);
+      if (value !== `${newValue}`) {
+        newValue = parseFloat(value);
+      }
+      log.warn(
+        `Capability '${cap}' changed from string ('${value}') to integer (${newValue}). This may cause unexpected behavior`,
+      );
+      caps[cap] = newValue;
+    }
+  }
+
+  return caps;
+}
+
+export {
+  isW3cCaps,
+  fixCaps
+};
+
+/**
+ * @typedef {import('@appium/types').Capabilities} Capabilities
+ * @typedef {import('@appium/types').Constraints} Constraints
+ * @typedef {import('@appium/types').AppiumLogger} AppiumLogger
+ */

package/lib/index.js

@@ -1,13 +1,17 @@
-// transpile:main
+// @ts-check
 
-// BaseDriver exports
-import * as driver from './basedriver/driver';
-import * as deviceSettings from './basedriver/device-settings';
+import B from 'bluebird';
+
+B.config({
+  cancellation: true,
+});
 
-const { BaseDriver } = driver;
-const { DeviceSettings, BASEDRIVER_HANDLED_SETTINGS } = deviceSettings;
+// BaseDriver exports
+import { BaseDriver } from './basedriver/driver';
+export { DriverCore } from './basedriver/core';
+import { DeviceSettings } from './basedriver/device-settings';
 
-export { BaseDriver, DeviceSettings, BASEDRIVER_HANDLED_SETTINGS };
+export { BaseDriver, DeviceSettings };
 export default BaseDriver;
 
 
@@ -18,19 +22,19 @@ import {
 } from './constants';
 
 const {
-  Protocol, routeConfiguringFunction, errors, isErrorType,
+  routeConfiguringFunction, errors, isErrorType,
   errorFromMJSONWPStatusCode, errorFromW3CJsonCode, ALL_COMMANDS, METHOD_MAP,
   routeToCommandName, NO_SESSION_ID_COMMANDS, isSessionCommand,
-  normalizeBasePath, determineProtocol, CREATE_SESSION_COMMAND,
+  determineProtocol, CREATE_SESSION_COMMAND,
   DELETE_SESSION_COMMAND, GET_STATUS_COMMAND,
 } = protocol;
 
 export {
-  Protocol, routeConfiguringFunction, errors, isErrorType, PROTOCOLS,
+  routeConfiguringFunction, errors, isErrorType, PROTOCOLS,
   errorFromMJSONWPStatusCode, errorFromW3CJsonCode, determineProtocol,
   errorFromMJSONWPStatusCode as errorFromCode, ALL_COMMANDS, METHOD_MAP,
   routeToCommandName, NO_SESSION_ID_COMMANDS, isSessionCommand,
-  DEFAULT_BASE_PATH, normalizeBasePath, CREATE_SESSION_COMMAND,
+  DEFAULT_BASE_PATH, CREATE_SESSION_COMMAND,
   DELETE_SESSION_COMMAND, GET_STATUS_COMMAND,
 };
 
@@ -40,8 +44,8 @@ const { STATIC_DIR } = staticIndex;
 export { STATIC_DIR };
 
 import * as serverIndex from './express/server';
-const { server } = serverIndex;
-export { server };
+const { server, normalizeBasePath } = serverIndex;
+export { server, normalizeBasePath };
 
 // jsonwp-proxy exports
 import * as proxyIndex from './jsonwp-proxy/proxy';

package/lib/jsonwp-proxy/protocol-converter.js

@@ -5,9 +5,6 @@ import {
   MJSONWP_ELEMENT_KEY, W3C_ELEMENT_KEY, PROTOCOLS
 } from '../constants';
 
-const log = logger.getLogger('Protocol Converter');
-
-
 export const COMMAND_URLS_CONFLICTS = [
   {
     commandNames: ['execute', 'executeAsync'],
@@ -41,20 +38,24 @@ export const COMMAND_URLS_CONFLICTS = [
     jsonwpConverter: (w3cUrl) => {
       const w3cPropertyRegex = /\/element\/([^/]+)\/property\/([^/]+)/;
       const jsonwpUrl = w3cUrl.replace(w3cPropertyRegex, '/element/$1/attribute/$2');
-      log.info(`Converting W3C '${w3cUrl}' to '${jsonwpUrl}'`);
       return jsonwpUrl;
     },
     w3cConverter: (jsonwpUrl) => jsonwpUrl // Don't convert JSONWP URL to W3C. W3C accepts /attribute and /property
   }
 ];
-
 const {MJSONWP, W3C} = PROTOCOLS;
+const DEFAULT_LOG = logger.getLogger('Protocol Converter');
 
 
 class ProtocolConverter {
-  constructor (proxyFunc) {
+  constructor (proxyFunc, log = null) {
     this.proxyFunc = proxyFunc;
     this._downstreamProtocol = null;
+    this._log = log;
+  }
+
+  get log () {
+    return this._log ?? DEFAULT_LOG;
   }
 
   set downstreamProtocol (value) {
@@ -107,7 +108,7 @@ class ProtocolConverter {
     let response, resBody;
 
     const timeoutRequestObjects = this.getTimeoutRequestObjects(body);
-    log.debug(`Will send the following request bodies to /timeouts: ${JSON.stringify(timeoutRequestObjects)}`);
+    this.log.debug(`Will send the following request bodies to /timeouts: ${JSON.stringify(timeoutRequestObjects)}`);
     for (const timeoutObj of timeoutRequestObjects) {
       [response, resBody] = await this.proxyFunc(url, method, timeoutObj);
 
@@ -130,14 +131,14 @@ class ProtocolConverter {
     const bodyObj = util.safeJsonParse(body);
     if (_.isPlainObject(bodyObj)) {
       if (this.downstreamProtocol === W3C && _.has(bodyObj, 'name') && !_.has(bodyObj, 'handle')) {
-        log.debug(`Copied 'name' value '${bodyObj.name}' to 'handle' as per W3C spec`);
+        this.log.debug(`Copied 'name' value '${bodyObj.name}' to 'handle' as per W3C spec`);
         return await this.proxyFunc(url, method, {
           ...bodyObj,
           handle: bodyObj.name,
         });
       }
       if (this.downstreamProtocol === MJSONWP && _.has(bodyObj, 'handle') && !_.has(bodyObj, 'name')) {
-        log.debug(`Copied 'handle' value '${bodyObj.handle}' to 'name' as per JSONWP spec`);
+        this.log.debug(`Copied 'handle' value '${bodyObj.handle}' to 'name' as per JSONWP spec`);
         return await this.proxyFunc(url, method, {
           ...bodyObj,
           name: bodyObj.handle,
@@ -156,12 +157,12 @@ class ProtocolConverter {
         value = _.isString(text)
           ? [...text]
           : (_.isArray(text) ? text : []);
-        log.debug(`Added 'value' property ${JSON.stringify(value)} to 'setValue' request body`);
+        this.log.debug(`Added 'value' property ${JSON.stringify(value)} to 'setValue' request body`);
       } else if (!util.hasValue(text) && util.hasValue(value)) {
         text = _.isArray(value)
           ? value.join('')
           : (_.isString(value) ? value : '');
-        log.debug(`Added 'text' property ${JSON.stringify(text)} to 'setValue' request body`);
+        this.log.debug(`Added 'text' property ${JSON.stringify(text)} to 'setValue' request body`);
       }
       return await this.proxyFunc(url, method, Object.assign({}, bodyObj, {
         text,
@@ -236,11 +237,11 @@ class ProtocolConverter {
         ? jsonwpConverter(url)
         : w3cConverter(url);
       if (rewrittenUrl === url) {
-        log.debug(`Did not know how to rewrite the original URL '${url}' ` +
+        this.log.debug(`Did not know how to rewrite the original URL '${url}' ` +
           `for ${this.downstreamProtocol} protocol`);
         break;
       }
-      log.info(`Rewrote the original URL '${url}' to '${rewrittenUrl}' ` +
+      this.log.info(`Rewrote the original URL '${url}' to '${rewrittenUrl}' ` +
         `for ${this.downstreamProtocol} protocol`);
       return await this.proxyFunc(rewrittenUrl, method, body);
     }

package/lib/jsonwp-proxy/proxy.js

@@ -12,8 +12,7 @@ import { formatResponseValue, formatStatus } from '../protocol/helpers';
 import http from 'http';
 import https from 'https';
 
-
-const log = logger.getLogger('WD Proxy');
+const DEFAULT_LOG = logger.getLogger('WD Proxy');
 const DEFAULT_REQUEST_TIMEOUT = 240000;
 const COMPACT_ERROR_PATTERNS = [
   /\bECONNREFUSED\b/,
@@ -43,7 +42,12 @@ class JWProxy {
     };
     this.httpAgent = new http.Agent(agentOpts);
     this.httpsAgent = new https.Agent(agentOpts);
-    this.protocolConverter = new ProtocolConverter(this.proxy.bind(this));
+    this.protocolConverter = new ProtocolConverter(this.proxy.bind(this), opts.log);
+    this._log = opts.log;
+  }
+
+  get log () {
+    return this._log ?? DEFAULT_LOG;
   }
 
   /**
@@ -166,7 +170,7 @@ class JWProxy {
       }
     }
 
-    log.debug(`Proxying [${method} ${url || '/'}] to [${method} ${newUrl}] ` +
+    this.log.debug(`Proxying [${method} ${url || '/'}] to [${method} ${newUrl}] ` +
       (reqOpts.data ? `with body: ${truncateBody(reqOpts.data)}` : 'with no body'));
 
     const throwProxyError = (error) => {
@@ -187,7 +191,7 @@ class JWProxy {
         // If it cannot be coerced to an object then the response is wrong
         throwProxyError(data);
       }
-      log.debug(`Got response with status ${status}: ${truncateBody(data)}`);
+      this.log.debug(`Got response with status ${status}: ${truncateBody(data)}`);
       isResponseLogged = true;
       const isSessionCreationRequest = /\/session$/.test(url) && method === 'POST';
       if (isSessionCreationRequest) {
@@ -195,7 +199,7 @@ class JWProxy {
           this.sessionId = data.sessionId || (data.value || {}).sessionId;
         }
         this.downstreamProtocol = this.getProtocolFromResBody(data);
-        log.info(`Determined the downstream protocol as '${this.downstreamProtocol}'`);
+        this.log.info(`Determined the downstream protocol as '${this.downstreamProtocol}'`);
       }
       if (_.has(data, 'status') && parseInt(data.status, 10) !== 0) {
         // Some servers, like chromedriver may return response code 200 for non-zero JSONWP statuses
@@ -211,16 +215,16 @@ class JWProxy {
       if (util.hasValue(e.response)) {
         if (!isResponseLogged) {
           const error = truncateBody(e.response.data);
-          log.info(util.hasValue(e.response.status)
+          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}`;
         if (COMPACT_ERROR_PATTERNS.some((p) => p.test(e.message))) {
-          log.info(e.message);
+          this.log.info(e.message);
         } else {
-          log.info(e.stack);
+          this.log.info(e.stack);
         }
       }
       throw new errors.ProxyRequestError(proxyErrorMsg, e.response?.data, e.response?.status);
@@ -256,7 +260,7 @@ class JWProxy {
     if (!commandName) {
       return await this.proxy(url, method, body);
     }
-    log.debug(`Matched '${url}' to command name '${commandName}'`);
+    this.log.debug(`Matched '${url}' to command name '${commandName}'`);
 
     return await this.protocolConverter.convertAndProxy(commandName, url, method, body);
   }
@@ -318,10 +322,10 @@ class JWProxy {
     const reqSessionId = this.getSessionIdFromUrl(req.originalUrl);
     if (_.has(resBodyObj, 'sessionId')) {
       if (reqSessionId) {
-        log.info(`Replacing sessionId ${resBodyObj.sessionId} with ${reqSessionId}`);
+        this.log.info(`Replacing sessionId ${resBodyObj.sessionId} with ${reqSessionId}`);
         resBodyObj.sessionId = reqSessionId;
       } else if (this.sessionId) {
-        log.info(`Replacing sessionId ${resBodyObj.sessionId} with ${this.sessionId}`);
+        this.log.info(`Replacing sessionId ${resBodyObj.sessionId} with ${this.sessionId}`);
         resBodyObj.sessionId = this.sessionId;
       }
     }