appium 2.0.0-beta.3 → 2.0.0-beta.34

package/lib/utils.js

@@ -1,65 +1,64 @@
+
 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 = {}) {
   // Check if the caller sent JSONWP caps, W3C caps, or both
   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;
-
-  if (!hasJSONWPCaps && !hasW3CCaps) {
-    return {
+  let desiredCaps = /** @type {ParsedDriverCaps['desiredCaps']} */({});
+  /** @type {ParsedDriverCaps['processedW3CCapabilities']} */
+  let processedW3CCapabilities;
+  /** @type {ParsedDriverCaps['processedJsonwpCapabilities']} */
+  let processedJsonwpCapabilities;
+
+  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);
@@ -95,62 +94,30 @@ 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,53 +127,13 @@ 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) {
   // Standard, non-prefixed capabilities (see https://www.w3.org/TR/webdriver/#dfn-table-of-standard-capabilities)
@@ -233,11 +160,17 @@ function insertAppiumPrefixes (caps) {
   return prefixedCaps;
 }
 
+/**
+ *
+ * @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;
@@ -289,9 +222,32 @@ 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.34",
   "description": "Automation for Apps.",
-  "tags": [
+  "keywords": [
     "automation",
     "javascript",
     "selenium",
@@ -11,102 +12,84 @@
     "firefoxos",
     "testing"
   ],
-  "version": "2.0.0-beta.3",
-  "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",
   "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",
+    "scripts/postinstall.js",
+    "types"
   ],
+  "scripts": {
+    "build": "babel lib --root-mode=upward --out-dir=build/lib",
+    "dev": "npm run build -- --watch",
+    "fix": "npm run lint -- --fix",
+    "build:docs": "node docs/scripts/build-docs.js",
+    "build:docs:assets": "node docs/scripts/copy-assets.js",
+    "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",
+    "publish:docs": "APPIUM_DOCS_PUBLISH=1 npm run build:docs",
+    "postinstall": "node ./scripts/postinstall.js",
+    "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
+    "test": "npm run test:unit",
+    "test:e2e": "mocha --timeout 30s --slow 15s \"./test/e2e/**/*.spec.js\"",
+    "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.5.3",
+    "@appium/base-plugin": "^1.8.5",
+    "@appium/docutils": "^0.0.4",
+    "@appium/schema": "^0.0.5",
+    "@appium/support": "^2.58.0",
+    "@babel/runtime": "7.17.9",
+    "@sidvind/better-ajv-errors": "1.1.1",
+    "ajv": "8.11.0",
+    "ajv-formats": "2.1.1",
+    "argparse": "2.0.1",
+    "async-lock": "1.3.1",
+    "asyncbox": "2.9.2",
+    "axios": "0.27.2",
+    "bluebird": "3.7.2",
+    "find-up": "5.0.0",
+    "lilconfig": "2.0.5",
+    "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",
+    "winston": "3.7.2",
+    "word-wrap": "1.2.3",
+    "yaml": "2.0.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": ">=12",
+    "npm": ">=6"
   },
-  "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"
+  },
+  "types": "./build/lib/main.d.ts",
+  "gitHead": "5482c921bc187ed8807922c00bd2355585f4971a"
 }

package/scripts/postinstall.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/* eslint-disable no-console, promise/prefer-await-to-then */
+
+async function main () {
+  const driverEnv = process.env.npm_config_drivers;
+  const pluginEnv = process.env.npm_config_plugins;
+
+  if (!driverEnv && !pluginEnv) {
+    console.log('Not auto-installing any drivers or plugins');
+    return;
+  }
+
+  let extension;
+  try {
+    extension = require('../build/lib/cli/extension');
+  } catch (e) {
+    throw new Error(`Could not load extension CLI file; has the project been transpiled? ` +
+                    `(${e.message})`);
+  }
+
+  const {DEFAULT_APPIUM_HOME, DRIVER_TYPE, PLUGIN_TYPE} = require('./build/lib/extension-config');
+  const {runExtensionCommand} = extension;
+  const appiumHome = process.env.npm_config_appium_home || DEFAULT_APPIUM_HOME;
+  const specs = [[DRIVER_TYPE, driverEnv], [PLUGIN_TYPE, pluginEnv]];
+
+  for (const [type, extEnv] of specs) {
+    if (extEnv) {
+      for (const ext of extEnv.split(',')) {
+        try {
+          await checkAndInstallExtension({runExtensionCommand, appiumHome, type, ext});
+        } catch (e) {
+          console.log(`There was an error checking and installing ${type} ${ext}: ${e.message}`);
+        }
+      }
+    }
+  }
+}
+
+async function checkAndInstallExtension ({
+  runExtensionCommand,
+  appiumHome,
+  type,
+  ext,
+}) {
+  const extList = await runExtensionCommand({
+    appiumHome,
+    [`${type}Command`]: 'list',
+    showInstalled: true,
+    suppressOutput: true,
+  }, type);
+  if (extList[ext]) {
+    console.log(`The ${type} ${ext} was already installed, skipping...`);
+    return;
+  }
+  console.log(`Installing the ${type} ${ext}...`);
+  await runExtensionCommand({
+    appiumHome,
+    [`${type}Command`]: 'install',
+    [type]: ext,
+    suppressOutput: true,
+  }, type);
+}
+
+if (require.main === module) {
+  main().then(() => {
+    process.exit(0);
+  }).catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}

package/types/appium-manifest.ts

@@ -0,0 +1,61 @@
+import { CommonMetadata, ExtMetadata, SchemaMetadata } from './external-manifest';
+import { ExtensionType, DriverType, PluginType } from '.';
+
+export type InstallType = 'npm' | 'git' | 'local' | 'github';
+
+export interface InternalMetadata {
+  pkgName: string;
+  version: string;
+  installType: InstallType;
+  /**
+   * Whatever the user typed as the extension to install. May be derived from `package.json`
+   */
+  installSpec: string;
+}
+
+/**
+ * Combination of external + internal extension data with `driverName`/`pluginName` removed (it becomes a key in an {@linkcode ExtRecord} object).
+ * Part of `extensions.yaml`.
+ */
+export type ExtManifest<ExtType extends ExtensionType> = Omit<
+  ExtMetadata<ExtType>,
+  ExtType extends DriverType
+    ? 'driverName'
+    : ExtType extends PluginType
+    ? 'pluginName'
+    : never
+> &
+  InternalMetadata &
+  CommonMetadata; // XXX: ExtMetadata should be a union with CommonMetadata. why is this needed?
+
+export type WithSchemaManifest = {
+  schema: SchemaMetadata;
+};
+
+/**
+ * This is just a {@linkcode ExtManifest} except it _for sure_ has a `schema` prop.
+ */
+export type ExtManifestWithSchema<ExtType extends ExtensionType> =
+  ExtManifest<ExtType> & WithSchemaManifest;
+
+/**
+ * Generic type for an object keyed by extension name, with values of type {@linkcode ExtData}
+ */
+export type ExtRecord<ExtType extends ExtensionType> = Record<
+  string,
+  ExtManifest<ExtType>
+>;
+
+export type DriverRecord = ExtRecord<DriverType>;
+export type PluginRecord = ExtRecord<PluginType>;
+
+export type ExtName<ExtType extends ExtensionType> = keyof ExtRecord<ExtType>;
+
+/**
+ * Represents an entire YAML manifest (`extensions.yaml`)
+ */
+export interface ManifestData {
+  drivers: DriverRecord;
+  plugins: PluginRecord;
+  schemaRev?: number;
+}