appium 2.0.0-beta.4 → 2.0.0-beta.42

package/lib/utils.js

@@ -1,65 +1,70 @@
 import _ from 'lodash';
 import logger from './logger';
-import { processCapabilities, PROTOCOLS } from 'appium-base-driver';
-import findRoot from 'find-root';
+import {processCapabilities, PROTOCOLS} from '@appium/base-driver';
+import {inspect as dump} from 'util';
 
 const W3C_APPIUM_PREFIX = 'appium';
 
-function inspectObject (args) {
-  function getValueArray (obj, indent = '  ') {
-    if (!_.isObject(obj)) {
-      return [obj];
-    }
+/**
+ *
+ * If `stdout` is a TTY, this is `true`.
+ *
+ * Used for tighter control over log output.
+ * @type {boolean}
+ */
+const isStdoutTTY = process.stdout.isTTY;
 
-    let strArr = ['{'];
-    for (let [arg, value] of _.toPairs(obj)) {
-      if (!_.isObject(value)) {
-        strArr.push(`${indent}  ${arg}: ${value}`);
-      } else {
-        value = getValueArray(value, `${indent}  `);
-        strArr.push(`${indent}  ${arg}: ${value.shift()}`);
-        strArr.push(...value);
-      }
-    }
-    strArr.push(`${indent}}`);
-    return strArr;
-  }
-  for (let [arg, value] of _.toPairs(args)) {
-    value = getValueArray(value);
-    logger.info(`  ${arg}: ${value.shift()}`);
-    for (let val of value) {
-      logger.info(val);
-    }
+/**
+ * Dumps to value to the console using `info` logger.
+ *
+ * @todo May want to force color to be `false` if {@link isStdoutTTY} is `false`.
+ */
+const inspect = _.flow(
+  _.partialRight(
+    /** @type {(object: any, options: import('util').InspectOptions) => string} */ (dump),
+    {colors: true, depth: null, compact: !isStdoutTTY}
+  ),
+  (...args) => {
+    logger.info(...args);
   }
-}
+);
 
 /**
  * Takes the caps that were provided in the request and translates them
  * into caps that can be used by the inner drivers.
  *
- * @param {Object} jsonwpCapabilities
- * @param {Object} w3cCapabilities
- * @param {Object} constraints
- * @param {Object} defaultCapabilities
+ * @param {any} jsonwpCapabilities
+ * @param {W3CCapabilities} w3cCapabilities
+ * @param {import('@appium/types').Constraints} constraints
+ * @param {import('@appium/types').DefaultCapabilitiesConfig} [defaultCapabilities]
+ * @returns {ParsedDriverCaps|InvalidCaps}
  */
-function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constraints = {}, defaultCapabilities = {}) {
+function parseCapsForInnerDriver(
+  jsonwpCapabilities,
+  w3cCapabilities,
+  constraints = {},
+  defaultCapabilities = {}
+) {
   // Check if the caller sent JSONWP caps, W3C caps, or both
-  const hasW3CCaps = _.isPlainObject(w3cCapabilities) &&
+  const hasW3CCaps =
+    _.isPlainObject(w3cCapabilities) &&
     (_.has(w3cCapabilities, 'alwaysMatch') || _.has(w3cCapabilities, 'firstMatch'));
   const hasJSONWPCaps = _.isPlainObject(jsonwpCapabilities);
-  let protocol = null;
-  let desiredCaps = {};
-  let processedW3CCapabilities = null;
-  let processedJsonwpCapabilities = null;
+  let desiredCaps = /** @type {ParsedDriverCaps['desiredCaps']} */ ({});
+  /** @type {ParsedDriverCaps['processedW3CCapabilities']} */
+  let processedW3CCapabilities;
+  /** @type {ParsedDriverCaps['processedJsonwpCapabilities']} */
+  let processedJsonwpCapabilities;
 
-  if (!hasJSONWPCaps && !hasW3CCaps) {
-    return {
+  if (!hasW3CCaps) {
+    return /** @type {InvalidCaps} */ ({
       protocol: PROTOCOLS.W3C,
-      error: new Error('Either JSONWP or W3C capabilities should be provided'),
-    };
+      error: new Error('W3C capabilities should be provided'),
+    });
   }
 
-  const {W3C, MJSONWP} = PROTOCOLS;
+  const {W3C} = PROTOCOLS;
+  const protocol = W3C;
 
   // Make sure we don't mutate the original arguments
   jsonwpCapabilities = _.cloneDeep(jsonwpCapabilities);
@@ -71,16 +76,23 @@ function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constrain
       for (const [defaultCapKey, defaultCapValue] of _.toPairs(defaultCapabilities)) {
         let isCapAlreadySet = false;
         // Check if the key is already present in firstMatch entries
-        for (const firstMatchEntry of (w3cCapabilities.firstMatch || [])) {
-          if (_.isPlainObject(firstMatchEntry)
-              && _.has(removeAppiumPrefixes(firstMatchEntry), removeAppiumPrefix(defaultCapKey))) {
+        for (const firstMatchEntry of w3cCapabilities.firstMatch || []) {
+          if (
+            _.isPlainObject(firstMatchEntry) &&
+            _.has(removeAppiumPrefixes(firstMatchEntry), removeAppiumPrefix(defaultCapKey))
+          ) {
             isCapAlreadySet = true;
             break;
           }
         }
         // Check if the key is already present in alwaysMatch entries
-        isCapAlreadySet = isCapAlreadySet || (_.isPlainObject(w3cCapabilities.alwaysMatch)
-          && _.has(removeAppiumPrefixes(w3cCapabilities.alwaysMatch), removeAppiumPrefix(defaultCapKey)));
+        isCapAlreadySet =
+          isCapAlreadySet ||
+          (_.isPlainObject(w3cCapabilities.alwaysMatch) &&
+            _.has(
+              removeAppiumPrefixes(w3cCapabilities.alwaysMatch),
+              removeAppiumPrefix(defaultCapKey)
+            ));
         if (isCapAlreadySet) {
           // Skip if the key is already present in the provided caps
           continue;
@@ -95,62 +107,33 @@ function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constrain
       }
     }
     if (hasJSONWPCaps) {
-      jsonwpCapabilities = Object.assign({}, removeAppiumPrefixes(defaultCapabilities), jsonwpCapabilities);
+      jsonwpCapabilities = {
+        ...removeAppiumPrefixes(defaultCapabilities),
+        ...jsonwpCapabilities,
+      };
     }
   }
 
   // Get MJSONWP caps
   if (hasJSONWPCaps) {
-    protocol = MJSONWP;
-    desiredCaps = jsonwpCapabilities;
     processedJsonwpCapabilities = {...jsonwpCapabilities};
   }
 
   // Get W3C caps
   if (hasW3CCaps) {
-    protocol = W3C;
     // Call the process capabilities algorithm to find matching caps on the W3C
     // (see: https://github.com/jlipps/simple-wd-spec#processing-capabilities)
-    let isFixingNeededForW3cCaps = false;
     try {
       desiredCaps = processCapabilities(w3cCapabilities, constraints, true);
     } catch (error) {
-      if (!hasJSONWPCaps) {
-        return {
-          desiredCaps,
-          processedJsonwpCapabilities,
-          processedW3CCapabilities,
-          protocol,
-          error,
-        };
-      }
       logger.info(`Could not parse W3C capabilities: ${error.message}`);
-      isFixingNeededForW3cCaps = true;
-    }
-
-    if (hasJSONWPCaps && !isFixingNeededForW3cCaps) {
-      const differingKeys = _.difference(_.keys(removeAppiumPrefixes(processedJsonwpCapabilities)), _.keys(removeAppiumPrefixes(desiredCaps)));
-      if (!_.isEmpty(differingKeys)) {
-        logger.info(`The following capabilities were provided in the JSONWP desired capabilities that are missing ` +
-          `in W3C capabilities: ${JSON.stringify(differingKeys)}`);
-        isFixingNeededForW3cCaps = true;
-      }
-    }
-
-    if (isFixingNeededForW3cCaps && hasJSONWPCaps) {
-      logger.info('Trying to fix W3C capabilities by merging them with JSONWP caps');
-      w3cCapabilities = fixW3cCapabilities(w3cCapabilities, jsonwpCapabilities);
-      try {
-        desiredCaps = processCapabilities(w3cCapabilities, constraints, true);
-      } catch (error) {
-        logger.warn(`Could not parse fixed W3C capabilities: ${error.message}. Falling back to JSONWP protocol`);
-        return {
-          desiredCaps: processedJsonwpCapabilities,
-          processedJsonwpCapabilities,
-          processedW3CCapabilities: null,
-          protocol: MJSONWP,
-        };
-      }
+      return /** @type {InvalidCaps} */ ({
+        desiredCaps,
+        processedJsonwpCapabilities,
+        processedW3CCapabilities,
+        protocol,
+        error,
+      });
     }
 
     // Create a new w3c capabilities payload that contains only the matching caps in `alwaysMatch`
@@ -160,55 +143,20 @@ function parseCapsForInnerDriver (jsonwpCapabilities, w3cCapabilities, constrain
     };
   }
 
-  return {desiredCaps, processedJsonwpCapabilities, processedW3CCapabilities, protocol};
-}
-
-/**
- * This helper method tries to fix corrupted W3C capabilities by
- * merging them to existing JSONWP capabilities.
- *
- * @param {Object} w3cCaps W3C capabilities
- * @param {Object} jsonwpCaps JSONWP capabilities
- * @return {Object} Fixed W3C capabilities
- */
-function fixW3cCapabilities (w3cCaps, jsonwpCaps) {
-  const result = {
-    firstMatch: w3cCaps.firstMatch || [],
-    alwaysMatch: w3cCaps.alwaysMatch || {},
-  };
-  const keysToInsert = _.keys(jsonwpCaps);
-  const removeMatchingKeys = (match) => {
-    _.pull(keysToInsert, match);
-    const colonIndex = match.indexOf(':');
-    if (colonIndex >= 0 && match.length > colonIndex) {
-      _.pull(keysToInsert, match.substring(colonIndex + 1));
-    }
-    if (keysToInsert.includes(`${W3C_APPIUM_PREFIX}:${match}`)) {
-      _.pull(keysToInsert, `${W3C_APPIUM_PREFIX}:${match}`);
-    }
-  };
-
-  for (const firstMatchEntry of result.firstMatch) {
-    for (const pair of _.toPairs(firstMatchEntry)) {
-      removeMatchingKeys(pair[0]);
-    }
-  }
-
-  for (const pair of _.toPairs(result.alwaysMatch)) {
-    removeMatchingKeys(pair[0]);
-  }
-
-  for (const key of keysToInsert) {
-    result.alwaysMatch[key] = jsonwpCaps[key];
-  }
-  return result;
+  return /** @type {ParsedDriverCaps} */ ({
+    desiredCaps,
+    processedJsonwpCapabilities,
+    processedW3CCapabilities,
+    protocol,
+  });
 }
 
 /**
  * Takes a capabilities objects and prefixes capabilities with `appium:`
- * @param {Object} caps Desired capabilities object
+ * @param {Capabilities} caps Desired capabilities object
+ * @returns {AppiumW3CCapabilities}
  */
-function insertAppiumPrefixes (caps) {
+function insertAppiumPrefixes(caps) {
   // Standard, non-prefixed capabilities (see https://www.w3.org/TR/webdriver/#dfn-table-of-standard-capabilities)
   const STANDARD_CAPS = [
     'browserName',
@@ -219,7 +167,7 @@ function insertAppiumPrefixes (caps) {
     'proxy',
     'setWindowRect',
     'timeouts',
-    'unhandledPromptBehavior'
+    'unhandledPromptBehavior',
   ];
 
   let prefixedCaps = {};
@@ -233,11 +181,17 @@ function insertAppiumPrefixes (caps) {
   return prefixedCaps;
 }
 
-function removeAppiumPrefixes (caps) {
+/**
+ *
+ * @param {AppiumW3CCapabilities} caps
+ * @returns {Capabilities}
+ */
+function removeAppiumPrefixes(caps) {
   if (!_.isPlainObject(caps)) {
     return caps;
   }
 
+  /** @type {Capabilities} */
   const fixedCaps = {};
   for (let [name, value] of _.toPairs(caps)) {
     fixedCaps[removeAppiumPrefix(name)] = value;
@@ -245,12 +199,12 @@ function removeAppiumPrefixes (caps) {
   return fixedCaps;
 }
 
-function removeAppiumPrefix (key) {
+function removeAppiumPrefix(key) {
   const prefix = `${W3C_APPIUM_PREFIX}:`;
   return _.startsWith(key, prefix) ? key.substring(prefix.length) : key;
 }
 
-function getPackageVersion (pkgName) {
+function getPackageVersion(pkgName) {
   const pkgInfo = require(`${pkgName}/package.json`) || {};
   return pkgInfo.version;
 }
@@ -271,7 +225,7 @@ function getPackageVersion (pkgName) {
  * setting items or a dictionary containing parsed Appium setting names along with
  * their values.
  */
-function pullSettings (caps) {
+function pullSettings(caps) {
   if (!_.isPlainObject(caps) || _.isEmpty(caps)) {
     return {};
   }
@@ -289,9 +243,36 @@ function pullSettings (caps) {
   return result;
 }
 
-const rootDir = findRoot(__dirname);
-
 export {
-  inspectObject, parseCapsForInnerDriver, insertAppiumPrefixes, rootDir,
-  getPackageVersion, pullSettings, removeAppiumPrefixes,
+  inspect,
+  parseCapsForInnerDriver,
+  insertAppiumPrefixes,
+  getPackageVersion,
+  pullSettings,
+  removeAppiumPrefixes,
 };
+
+/**
+ * @todo protocol is more specific
+ * @typedef ParsedDriverCaps
+ * @property {Capabilities} desiredCaps
+ * @property {string} protocol
+ * @property {any} [processedJsonwpCapabilities]
+ * @property {W3CCapabilities} [processedW3CCapabilities]
+ */
+
+/**
+ * @todo protocol is more specific
+ * @typedef InvalidCaps
+ * @property {Error} error
+ * @property {string} protocol
+ * @property {Capabilities} [desiredCaps]
+ * @property {any} [processedJsonwpCapabilities]
+ * @property {W3CCapabilities} [processedW3CCapabilities]
+ */
+
+/**
+ * @typedef {import('@appium/types').W3CCapabilities} W3CCapabilities
+ * @typedef {import('@appium/types').Capabilities} Capabilities
+ * @typedef {import('@appium/types').AppiumW3CCapabilities} AppiumW3CCapabilities
+ */

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "appium",
+  "version": "2.0.0-beta.42",
   "description": "Automation for Apps.",
-  "tags": [
+  "keywords": [
     "automation",
     "javascript",
     "selenium",
@@ -11,102 +12,101 @@
     "firefoxos",
     "testing"
   ],
-  "version": "2.0.0-beta.4",
-  "author": "https://github.com/appium",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/appium/appium.git"
-  },
+  "homepage": "https://appium.io",
   "bugs": {
     "url": "https://github.com/appium/appium/issues"
   },
-  "engines": {
-    "node": ">=8",
-    "npm": ">=6"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/appium/appium.git",
+    "directory": "packages/appium"
   },
-  "main": "./build/lib/main.js",
+  "license": "Apache-2.0",
+  "author": "https://github.com/appium",
+  "types": "./build/lib/main.d.ts",
   "bin": {
-    "appium": "./build/lib/main.js"
+    "appium": "index.js"
   },
   "directories": {
-    "lib": "./lib",
-    "doc": "./docs"
+    "lib": "./lib"
   },
   "files": [
-    "bin",
     "lib",
-    "build/lib",
-    "npm-shrinkwrap.json"
+    "build",
+    "index.js",
+    "driver.*",
+    "support.*",
+    "plugin.*",
+    "test.*",
+    "scripts/autoinstall-extensions.js",
+    "types"
   ],
+  "scripts": {
+    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "build:docs": "node docs/scripts/build-docs.js",
+    "build:docs:assets": "node docs/scripts/copy-assets.js",
+    "dev": "npm run build -- --watch",
+    "dev:docs": "npm run build:docs:assets && npm run dev:docs:en",
+    "dev:docs:en": "mkdocs serve -f ./docs/mkdocs-en.yml",
+    "dev:docs:ja": "mkdocs serve -f ./docs/mkdocs-ja.yml",
+    "dev:docs:zh": "mkdocs serve -f ./docs/mkdocs-zh.yml",
+    "fix": "npm run lint -- --fix",
+    "postinstall": "node ./scripts/autoinstall-extensions.js",
+    "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
+    "prepare": "npm run build",
+    "publish:docs": "cross-env APPIUM_DOCS_PUBLISH=1 npm run build:docs",
+    "test": "npm run test:unit",
+    "test:e2e": "mocha --timeout 1m --slow 30s \"./test/e2e/**/*.spec.js\"",
+    "test:smoke": "cross-env APPIUM_HOME=./local_appium_home node ./index.js driver install uiautomator2 && cross-env APPIUM_HOME=./local_appium_home node ./index.js driver list",
+    "test:unit": "mocha \"./test/unit/**/*.spec.js\""
+  },
   "dependencies": {
-    "@appium/base-plugin": "^1.0.0",
-    "@babel/runtime": "^7.6.0",
-    "appium-base-driver": "8.0.0-beta.0",
-    "appium-support": "2.x",
-    "argparse": "^1.0.10",
-    "async-lock": "^1.0.0",
-    "asyncbox": "2.x",
-    "axios": "^0.20.0",
-    "bluebird": "3.x",
-    "continuation-local-storage": "3.x",
-    "dateformat": "^3.0.3",
-    "find-root": "^1.1.0",
-    "lodash": "^4.17.11",
-    "longjohn": "^0.2.12",
-    "npmlog": "4.x",
-    "ora": "^4.0.4",
-    "semver": "^7.0.0",
-    "source-map-support": "0.x",
-    "teen_process": "1.x",
-    "winston": "3.x",
-    "word-wrap": "^1.2.3",
-    "yaml": "^1.7.2"
+    "@appium/base-driver": "^8.6.1",
+    "@appium/base-plugin": "^1.10.1",
+    "@appium/docutils": "^0.0.9",
+    "@appium/schema": "^0.0.9",
+    "@appium/support": "^2.59.4",
+    "@appium/test-support": "^1.4.1",
+    "@appium/types": "^0.3.1",
+    "@babel/runtime": "7.18.9",
+    "@sidvind/better-ajv-errors": "2.0.0",
+    "@types/argparse": "2.0.10",
+    "@types/bluebird": "3.5.36",
+    "@types/fancy-log": "2.0.0",
+    "@types/semver": "7.3.10",
+    "@types/teen_process": "1.16.1",
+    "@types/wrap-ansi": "3.0.0",
+    "ajv": "8.11.0",
+    "ajv-formats": "2.1.1",
+    "argparse": "2.0.1",
+    "async-lock": "1.3.2",
+    "asyncbox": "2.9.2",
+    "axios": "0.27.2",
+    "bluebird": "3.7.2",
+    "cross-env": "7.0.3",
+    "find-up": "5.0.0",
+    "lilconfig": "2.0.6",
+    "lodash": "4.17.21",
+    "longjohn": "0.2.12",
+    "npmlog": "6.0.2",
+    "ora": "5.4.1",
+    "package-changed": "1.9.0",
+    "resolve-from": "5.0.0",
+    "semver": "7.3.7",
+    "source-map-support": "0.5.21",
+    "teen_process": "1.16.0",
+    "type-fest": "2.18.0",
+    "winston": "3.8.1",
+    "wrap-ansi": "7.0.0",
+    "yaml": "2.1.1"
   },
-  "scripts": {
-    "clean": "rm -rf node_modules && rm -f package-lock.json && npm install",
-    "prepare": "gulp prepublish",
-    "prepublishOnly": "npm run prune-shrinkwrap && gulp fixShrinkwrap",
-    "postpublish": "npm run restore-shrinkwrap",
-    "prune-shrinkwrap": "!(test -e npm-shrinkwrap.json) || (npm ci --production --ignore-scripts && npm run backup-shrinkwrap && npm shrinkwrap && npm install --only=dev --no-shrinkwrap)",
-    "restore-shrinkwrap": "!(test -e npm-shrinkwrap.json) || (mv npm-shrinkwrap-backup.json npm-shrinkwrap.json)",
-    "backup-shrinkwrap": "mv npm-shrinkwrap.json npm-shrinkwrap-backup.json",
-    "check-pruned-shrinkwrap": "node check-pruned-shrinkwrap.js",
-    "test": "gulp once",
-    "e2e-test": "gulp e2e-test",
-    "watch": "gulp watch",
-    "build": "gulp transpile",
-    "mocha": "mocha",
-    "precommit-msg": "echo 'Pre-commit checks...' && exit 0",
-    "precommit-test": "REPORTER=dot gulp once",
-    "lint": "gulp lint",
-    "lint:fix": "gulp lint --fix",
-    "coverage": "gulp coveralls",
-    "generate-docs": "node ./build/commands-yml/parse.js",
-    "zip": "zip -qr appium.zip .",
-    "upload": "gulp github-upload",
-    "zip-and-upload": "npm run zip && npm run upload",
-    "authorize-ios": "authorize-ios"
+  "engines": {
+    "node": ">=14",
+    "npm": ">=8"
   },
-  "pre-commit": [
-    "precommit-msg",
-    "precommit-test"
-  ],
-  "devDependencies": {
-    "@appium/fake-plugin": "^0.2.0",
-    "appium-fake-driver": "^1.0.1",
-    "appium-gulp-plugins": "^5.2.1",
-    "chai": "4.x",
-    "chai-as-promised": "7.x",
-    "eslint-config-appium": "^4.0.1",
-    "fancy-log": "^1.3.2",
-    "gulp": "^4.0.0",
-    "handlebars": "^4.2.0",
-    "mocha": "^8.0.1",
-    "pre-commit": "1.x",
-    "sinon": "^9.0.0",
-    "validate.js": "^0.13.0",
-    "wd": "^1.10.0",
-    "yaml-js": "^0.2.0"
-  }
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "gitHead": "500c08f3929b1dd531d119872d11cea59d417eb7"
 }

package/plugin.d.ts

@@ -0,0 +1 @@
+export * from '@appium/base-plugin';

package/plugin.js

@@ -0,0 +1,13 @@
+'use strict';
+
+// @ts-check
+
+/**
+ * This module is here to re-export `@appium/base-plugin` for Appium extensions.
+ *
+ * @see https://npm.im/@appium/base-plugin
+ * @example
+ * const { BasePlugin } = require('appium/plugin');
+ */
+
+module.exports = require('@appium/base-plugin');