appium 2.0.0-beta.5 → 2.0.0-beta.52

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "appium",
+  "version": "2.0.0-beta.52",
   "description": "Automation for Apps.",
-  "tags": [
+  "keywords": [
     "automation",
     "javascript",
     "selenium",
@@ -11,102 +12,100 @@
     "firefoxos",
     "testing"
   ],
-  "version": "2.0.0-beta.5",
-  "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.*",
+    "scripts/autoinstall-extensions.js",
+    "types",
+    "tsconfig.json"
   ],
+  "scripts": {
+    "build:docs": "node docs/scripts/build-docs.js",
+    "build:docs:assets": "node docs/scripts/copy-assets.js",
+    "build:docs:cli": "node docs/scripts/gen-cli-args-docs.js",
+    "build:docs:reference": "node docs/scripts/build-reference.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",
+    "dev:docs:zh": "mkdocs serve -f ./docs/mkdocs-zh.yml",
+    "postinstall": "node ./scripts/autoinstall-extensions.js",
+    "publish:docs": "cross-env APPIUM_DOCS_PUBLISH=1 npm run build:docs",
+    "test": "npm run test:unit",
+    "test:e2e": "mocha -p --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": "^9.2.3",
+    "@appium/base-plugin": "^2.1.3",
+    "@appium/docutils": "^0.1.5",
+    "@appium/schema": "^0.2.3",
+    "@appium/support": "^3.1.3",
+    "@appium/types": "^0.8.3",
+    "@sidvind/better-ajv-errors": "2.1.0",
+    "@types/argparse": "2.0.10",
+    "@types/bluebird": "3.5.38",
+    "@types/fancy-log": "2.0.0",
+    "@types/semver": "7.3.13",
+    "@types/teen_process": "2.0.0",
+    "@types/wrap-ansi": "3.0.0",
+    "ajv": "8.12.0",
+    "ajv-formats": "2.1.1",
+    "argparse": "2.0.1",
+    "async-lock": "1.4.0",
+    "asyncbox": "2.9.4",
+    "axios": "1.2.2",
+    "bluebird": "3.7.2",
+    "cross-env": "7.0.3",
+    "find-up": "5.0.0",
+    "glob": "8.0.3",
+    "lilconfig": "2.0.6",
+    "lodash": "4.17.21",
+    "longjohn": "0.2.12",
+    "npmlog": "7.0.1",
+    "ora": "5.4.1",
+    "package-changed": "1.9.0",
+    "resolve-from": "5.0.0",
+    "semver": "7.3.8",
+    "source-map-support": "0.5.21",
+    "teen_process": "2.0.2",
+    "type-fest": "3.5.1",
+    "winston": "3.8.2",
+    "wrap-ansi": "7.0.0",
+    "yaml": "2.2.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.17.0 || ^16.13.0 || >=18.0.0",
+    "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": "67c9bdfbceeb049aa134bf1d9b107543ff0a80b0",
+  "typedoc": {
+    "entryPoint": "./lib/main.js"
   }
 }

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');

package/scripts/autoinstall-extensions.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+/* eslint-disable no-console, promise/prefer-await-to-then */
+
+/**
+ * This script is intended to be run as a `postinstall` lifecycle script,
+ * and will automatically install extensions if requested by the user.
+ *
+ * If the current working directory is within a project which has `appium`
+ * as a dependency, this script does nothing; extensions must be managed
+ * via `npm` or another package manager.
+ *
+ * If `CI=1` is in the environment, this script will exit with a non-zero
+ * code upon failure (which will typically break a build).  Otherwise, it
+ * will always exit with code 0, even if errors occur.
+ *
+ * @module
+ * @example
+ * `npm install -g appium --drivers=uiautomator2,xcuitest --plugins=images`
+ */
+
+const path = require('path');
+const {exec} = require('teen_process');
+const B = require('bluebird');
+
+B.config({
+  cancellation: true,
+});
+
+/**
+ * This is only used if we're actually in the monorepo
+ */
+const MONOREPO_ROOT = path.join(__dirname, '..', '..', '..');
+
+/** @type {import('../lib/cli/extension').runExtensionCommand} */
+let runExtensionCommand;
+/** @type {import('../lib/constants').DRIVER_TYPE} */
+let DRIVER_TYPE;
+/** @type {import('../lib/constants').PLUGIN_TYPE} */
+let PLUGIN_TYPE;
+/** @type {import('../lib/extension').loadExtensions} */
+let loadExtensions;
+
+const _ = require('lodash');
+const wrap = _.partial(
+  require('wrap-ansi'),
+  _,
+  process.stderr.columns ?? process.stdout.columns ?? 80
+);
+const ora = require('ora');
+
+let env, util, logger;
+
+function log(message) {
+  console.error(wrap(`[Appium] ${message}`));
+}
+
+async function init() {
+  /** @type {import('ora').Ora} */
+  let spinner;
+
+  try {
+    ({env, util, logger} = require('@appium/support'));
+    require('..');
+  } catch {
+    spinner = ora({
+      text: 'Building Appium dev environment...',
+      prefixText: '[Appium]',
+    }).start();
+
+    try {
+      const {stderr, code} = await exec('npm', ['run', 'build'], {
+        cwd: MONOREPO_ROOT,
+        encoding: 'utf8',
+      });
+      if (!code) {
+        spinner.succeed('Appium build successfully.');
+      } else {
+        spinner.fail(`Building Appium failed!`);
+        log(stderr);
+      }
+    } catch (err) {
+      spinner.fail(`Building Appium failed!`);
+      log(err);
+    }
+  }
+
+  spinner = ora({
+    text: 'Checking Appium installation...',
+    prefixText: '[Appium]',
+  }).start();
+
+  try {
+    ({env, util, logger} = require('@appium/support'));
+    ({runExtensionCommand} = require('../build/lib/cli/extension'));
+    ({DRIVER_TYPE, PLUGIN_TYPE} = require('../build/lib/constants'));
+    ({loadExtensions} = require('../build/lib/extension'));
+    spinner.succeed('Appium installation OK');
+    // suppress logs from Appium, which mess up the script output
+    logger.getLogger('Appium').level = 'error';
+  } catch (e) {
+    spinner.fail(`Could not load required module(s); has Appium been built? (${e.message})`);
+    if (process.env.CI) {
+      log('Detected CI environment, exiting with code 1');
+      process.exitCode = 1;
+    } else {
+      process.exitCode = 0;
+    }
+    return false;
+  }
+
+  return true;
+}
+
+async function main() {
+  if (!(await init())) {
+    return;
+  }
+
+  // if we're doing `npm install -g appium` then we will assume we don't have a local appium.
+  if (!process.env.npm_config_global && (await env.hasAppiumDependency())) {
+    log(`Found local Appium installation; skipping automatic installation of extensions.`);
+    return;
+  }
+
+  const driverEnv = process.env.npm_config_drivers;
+  const pluginEnv = process.env.npm_config_plugins;
+
+  const spinner = ora({
+    text: 'Looking for extensions to automatically install...',
+    prefixText: '[Appium]',
+  }).start();
+
+  if (!driverEnv && !pluginEnv) {
+    spinner.succeed(
+      wrap(`No drivers or plugins to automatically install. 
+      If desired, provide arguments with comma-separated values "--drivers=<known_driver>[,known_driver...]" and/or "--plugins=<known_plugin>[,known_plugin...]" to the "npm install appium" command. The specified extensions will be installed automatically with Appium.  Note: to see the list of known extensions, run "appium <driver|plugin> list".`)
+    );
+    return;
+  }
+
+  const specs = [
+    [DRIVER_TYPE, driverEnv],
+    [PLUGIN_TYPE, pluginEnv],
+  ];
+
+  spinner.start('Resolving Appium home directory...');
+  const appiumHome = await env.resolveAppiumHome();
+  spinner.succeed(`Found Appium home: ${appiumHome}`);
+
+  spinner.start(`Loading extension data...`);
+  const {driverConfig, pluginConfig} = await loadExtensions(appiumHome);
+  spinner.succeed(`Loaded extension data.`);
+
+  const installedStats = {[DRIVER_TYPE]: 0, [PLUGIN_TYPE]: 0};
+  for (const [type, extEnv] of specs) {
+    if (extEnv) {
+      for await (let ext of extEnv.split(',')) {
+        ext = ext.trim();
+        try {
+          await checkAndInstallExtension({
+            runExtensionCommand,
+            appiumHome,
+            type,
+            ext,
+            driverConfig,
+            pluginConfig,
+            spinner,
+          });
+          installedStats[type]++;
+        } catch (e) {
+          spinner.fail(`Could not install ${type} "${ext}": ${e.message}`);
+          if (process.env.CI) {
+            process.exitCode = 1;
+          }
+          return;
+        }
+      }
+    }
+  }
+  spinner.succeed(
+    `Done. ${installedStats[DRIVER_TYPE]} ${util.pluralize(
+      'driver',
+      installedStats[DRIVER_TYPE]
+    )} and ${installedStats[PLUGIN_TYPE]} ${util.pluralize(
+      'plugin',
+      installedStats[PLUGIN_TYPE]
+    )} are installed.`
+  );
+}
+
+async function checkAndInstallExtension({
+  runExtensionCommand,
+  appiumHome,
+  type,
+  ext,
+  driverConfig,
+  pluginConfig,
+  spinner,
+}) {
+  const extList = await runExtensionCommand(
+    {
+      appiumHome,
+      [`${type}Command`]: 'list',
+      showInstalled: true,
+      suppressOutput: true,
+    },
+    type === DRIVER_TYPE ? driverConfig : pluginConfig
+  );
+  if (extList[ext]) {
+    spinner.info(`The ${type} "${ext}" is already installed.`);
+    return;
+  }
+  spinner.start(`Installing ${type} "${ext}"...`);
+  await runExtensionCommand(
+    {
+      appiumHome,
+      [`${type}Command`]: 'install',
+      suppressOutput: true,
+      [type]: ext,
+    },
+    type === DRIVER_TYPE ? driverConfig : pluginConfig
+  );
+  spinner.succeed(`Installed ${type} "${ext}".`);
+}
+
+if (require.main === module) {
+  main().catch((e) => {
+    log(e);
+    if (process.env.CI) {
+      log('Detected CI environment, exiting with code 1');
+      process.exitCode = 1;
+    }
+  });
+}
+
+module.exports = main;

package/support.d.ts

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

package/support.js

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

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "extends": "@appium/tsconfig/tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "build",
+    "paths": {
+      "@appium/support": ["../support"],
+      "@appium/base-driver": ["../base-driver"],
+      "@appium/base-plugin": ["../base-plugin"],
+      "@appium/types": ["../types"],
+      "@appium/schema": ["../schema"],
+      "appium": ["."]
+    },
+    "checkJs": true
+  },
+  "include": ["lib", "types"],
+  "references": [
+    {"path": "../schema"},
+    {"path": "../types"},
+    {"path": "../support"},
+    {"path": "../base-driver"},
+    {"path": "../base-plugin"},
+    {"path": "../test-support"}
+  ]
+}

package/types/cli.ts

@@ -0,0 +1,189 @@
+import {DriverType, PluginType, ServerArgs} from '@appium/types';
+import {SetOptional} from 'type-fest';
+import {InstallType} from './manifest';
+export type ServerCommand = 'server';
+export type DriverCommand = DriverType;
+export type PluginCommand = PluginType;
+
+/**
+ * Extension-specific commands
+ */
+export type CliExtensionCommand = DriverCommand | PluginCommand;
+
+/**
+ * Possible commands for the `appium` CLI.
+ */
+export type CliCommand = ServerCommand | CliExtensionCommand;
+
+/**
+ * Possible subcommands of {@linkcode DriverCommand} or
+ * {@linkcode PluginCommand}.
+ */
+export type CliExtensionSubcommand = 'install' | 'list' | 'run' | 'uninstall' | 'update';
+
+export interface CliExtensionSubcommandListArgs {
+  showInstalled?: boolean;
+  showUpdates?: boolean;
+}
+
+export interface CliExtensionSubcommandInstallArgs {
+  installType: InstallType;
+  packageName?: string;
+}
+
+export interface CliExtensionSubcommandUpdateArgs {
+  unsafe?: boolean;
+}
+
+/**
+ * Random stuff that may appear in the parsed args which has no equivalent in a
+ * config file.
+ */
+export interface MoreArgs {
+  /**
+   * Possible subcommands. If empty, defaults to {@linkcode ServerCommand}.
+   */
+  subcommand?: CliCommand;
+
+  /**
+   * Path to config file, if any. Does not make sense for this to be allowed in a config file!
+   */
+  configFile?: string;
+
+  /**
+   * If true, show the config and exit
+   */
+  showConfig?: boolean;
+
+  /**
+   * If true, open a REPL
+   */
+  shell?: boolean;
+}
+
+/**
+ * These arguments are _not_ supported by the CLI, but only via programmatic usage / tests.
+ */
+export interface ProgrammaticArgs {
+  /**
+   * If `true`, throw on error instead of exit.
+   */
+  throwInsteadOfExit?: boolean;
+
+  /**
+   * Seems to only be used in tests or standalone driver calls
+   */
+  logHandler?: (...args: any[]) => void;
+
+  /**
+   * Alternate way to set `APPIUM_HOME` for tests. Since we don't want to muck about
+   * with the environment, we just set it here.
+   *
+   * Setting this means that any discovery of the proper `APPIUM_HOME` path is bypassed
+   * and is equivalent to setting `APPIUM_HOME` in the environment.
+   */
+  appiumHome?: string;
+
+  /**
+   * If true, show the {@link BuildInfo build info} and exit
+   */
+  showBuildInfo?: boolean;
+
+  /**
+   * If true, show config and exit
+   */
+  showConfig?: boolean;
+}
+
+export interface DriverExtArgs {
+  driverCommand: CliExtensionSubcommand;
+  driver?: string;
+}
+
+export interface PluginExtArgs {
+  pluginCommand: CliExtensionSubcommand;
+  plugin?: string;
+}
+
+/**
+ * These are args which the user will specify if using an extension command
+ */
+export interface BaseExtArgs<Cmd extends CliExtensionCommand> {
+  subcommand: Cmd;
+
+  /**
+   * Output JSON instead of human-readable text
+   */
+  json?: boolean;
+
+  /**
+   * Output nothing
+   */
+  suppressOutput?: boolean;
+
+  /**
+   * Extra args to pass to extension scripts
+   */
+  extraArgs?: string[];
+}
+
+/**
+ * Args for extension commands; includes a subcommand
+ */
+export type ExtArgs<
+  Cmd extends CliExtensionCommand,
+  SubCmd extends CliExtensionSubcommand
+> = BaseExtArgs<Cmd> &
+  (Cmd extends DriverCommand ? DriverExtArgs : Cmd extends PluginCommand ? PluginExtArgs : never) &
+  (SubCmd extends 'install'
+    ? CliExtensionSubcommandInstallArgs
+    : SubCmd extends 'list'
+    ? CliExtensionSubcommandListArgs
+    : SubCmd extends 'update'
+    ? CliExtensionSubcommandUpdateArgs
+    : never);
+
+/**
+ * Some generic bits of arguments; should not be used outside this declaration
+ */
+export type CommonArgs<
+  Cmd extends CliCommand = ServerCommand,
+  SubCmd extends CliExtensionSubcommand | void = void
+> = MoreArgs &
+  ProgrammaticArgs &
+  (Cmd extends ServerCommand
+    ? ServerArgs
+    : Cmd extends CliExtensionCommand
+    ? SubCmd extends CliExtensionSubcommand
+      ? ExtArgs<Cmd, SubCmd>
+      : never
+    : never);
+
+/**
+ * Fully-parsed arguments, containing defaults, computed args, and config file values.
+ */
+export type ParsedArgs<
+  Cmd extends CliCommand = ServerCommand,
+  SubCmd extends CliExtensionSubcommand | void = void
+> = CommonArgs<Cmd, SubCmd>;
+
+/**
+ * Like {@linkcode ParsedArgs} except server arguments are all optional.
+ *
+ * _May_ have defaults applied; _may_ contain config values; _may_ contain computed args.
+ */
+export type Args<
+  Cmd extends CliCommand = ServerCommand,
+  SubCmd extends CliExtensionSubcommand | void = void
+> = Cmd extends ServerCommand
+  ? SetOptional<CommonArgs<Cmd>, keyof ServerArgs>
+  : ParsedArgs<Cmd, SubCmd>;
+
+/**
+ * Shown by `appium --build-info`
+ */
+export type BuildInfo = {
+  version: string;
+  'git-sha'?: string;
+  built?: string;
+};