appium 2.0.0-beta.9 → 2.0.0-rc.2

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "appium",
+  "version": "2.0.0-rc.2",
   "description": "Automation for Apps.",
-  "tags": [
+  "keywords": [
     "automation",
     "javascript",
     "selenium",
@@ -11,102 +12,101 @@
     "firefoxos",
     "testing"
   ],
-  "version": "2.0.0-beta.9",
-  "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": ">=12",
-    "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",
-    "postinstall.js"
+    "build",
+    "index.js",
+    "driver.*",
+    "support.*",
+    "plugin.*",
+    "scripts/autoinstall-extensions.js",
+    "types",
+    "tsconfig.json",
+    "!build/tsconfig.tsbuildinfo"
   ],
+  "scripts": {
+    "build:docs": "node docs/scripts/build-docs.js",
+    "build:docs:preview": "cross-env APPIUM_DOCS_PREVIEW=1 npm run build:docs",
+    "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": "appium-docs build --serve --mkdocs-yml ./docs/mkdocs-en.yml",
+    "dev:docs:ja": "appium-docs build --serve --mkdocs-yml ./docs/mkdocs-ja.yml",
+    "dev:docs:zh": "appium-docs build --serve --mkdocs-yml ./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.2",
-    "appium-support": "2.x",
-    "argparse": "^2.0.1",
-    "async-lock": "^1.0.0",
-    "asyncbox": "2.x",
-    "axios": "^0.21.0",
-    "bluebird": "3.x",
-    "continuation-local-storage": "3.x",
-    "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.3.12",
+    "@appium/base-plugin": "^2.2.12",
+    "@appium/docutils": "^0.4.1",
+    "@appium/schema": "^0.3.0",
+    "@appium/support": "^4.0.3",
+    "@appium/types": "^0.12.0",
+    "@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.5.0",
+    "@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.4.0",
+    "bluebird": "3.7.2",
+    "cross-env": "7.0.3",
+    "find-up": "5.0.0",
+    "glob": "8.1.0",
+    "lilconfig": "2.1.0",
+    "lodash": "4.17.21",
+    "npmlog": "7.0.1",
+    "ora": "5.4.1",
+    "package-changed": "3.0.0",
+    "resolve-from": "5.0.0",
+    "semver": "7.5.1",
+    "source-map-support": "0.5.21",
+    "teen_process": "2.0.2",
+    "type-fest": "3.11.1",
+    "winston": "3.9.0",
+    "wrap-ansi": "7.0.0",
+    "yaml": "2.3.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",
-    "postinstall": "node ./postinstall.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"
+  "engines": {
+    "node": "^14.17.0 || ^16.13.0 || >=18.0.0",
+    "npm": ">=8"
   },
-  "pre-commit": [
-    "precommit-msg",
-    "precommit-test"
-  ],
-  "devDependencies": {
-    "@appium/fake-plugin": ">=0.3.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",
-    "webdriverio": "^6.12.0",
-    "yaml-js": "^0.2.0"
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "gitHead": "af066eb5c3542338eec821b81d6aa4bcf2d81188",
+  "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,243 @@
+#!/usr/bin/env node
+
+// @ts-check
+
+/* 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 B = require('bluebird');
+const path = require('node:path');
+const {realpath} = require('node:fs/promises');
+
+B.config({
+  cancellation: true,
+});
+
+/** @type {typeof import('../lib/cli/extension').runExtensionCommand} */
+let runExtensionCommand;
+/** @type {typeof import('../lib/constants').DRIVER_TYPE} */
+let DRIVER_TYPE;
+/** @type {typeof import('../lib/constants').PLUGIN_TYPE} */
+let PLUGIN_TYPE;
+/** @type {typeof 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');
+
+/** @type {typeof import('@appium/support').env} */
+let env;
+/** @type {typeof import('@appium/support').util} */
+let util;
+/** @type {typeof import('@appium/support').logger} */
+let logger;
+
+function log(message) {
+  console.error(wrap(`[Appium] ${message}`));
+}
+
+/**
+ * This is a naive attempt at determining whether or not we are in a dev environment; in other
+ * words, is `postinstall` being run from within the `appium` monorepo?
+ *
+ * When we're in the monorepo, `npm_config_local_prefix` will be set to the root of the monorepo root
+ * dir when running this lifecycle script from an `npm install` in the monorepo root.
+ *
+ * `realpath` is necessary due to macOS omitting `/private` from paths
+ */
+async function isDevEnvironment() {
+  return (
+    process.env.npm_config_local_prefix &&
+    path.join(process.env.npm_config_local_prefix, 'packages', 'appium') ===
+      (await realpath(path.join(__dirname, '..')))
+  );
+}
+
+/**
+ * Setup / check environment if we should do anything here
+ * @returns {Promise<boolean>} `true` if Appium is built and ready to go
+ */
+async function init() {
+  if (await isDevEnvironment()) {
+    log('Dev environment likely; skipping automatic installation of extensions');
+    return false;
+  }
+  try {
+    ({env, util, logger} = require('@appium/support'));
+    // @ts-ignore
+    ({runExtensionCommand} = require('../build/lib/cli/extension'));
+    ({DRIVER_TYPE, PLUGIN_TYPE} = require('../build/lib/constants'));
+    // @ts-ignore
+    ({loadExtensions} = require('../build/lib/extension'));
+    logger.getLogger('Appium').level = 'error';
+
+    // 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(process.cwd()))) {
+      log(`Found local Appium installation; skipping automatic installation of extensions.`);
+      return false;
+    }
+    return true;
+  } catch {
+    log('Dev environment likely; skipping automatic installation of extensions');
+    return false;
+  }
+}
+
+async function main() {
+  if (!(await init())) {
+    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;
+  }
+
+  /**
+   * @type {[[typeof DRIVER_TYPE, string?], [typeof PLUGIN_TYPE, string?]]}
+   */
+  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.`
+  );
+}
+
+/**
+ * @privateRemarks the two `@ts-ignore` directives here are because I have no idea what's wrong with
+ * the types and don't want to spend more time on it. regardless, it seems to work for now.
+ * @param {CheckAndInstallExtensionsOpts} opts
+ */
+async function checkAndInstallExtension({
+  runExtensionCommand,
+  appiumHome,
+  type,
+  ext,
+  driverConfig,
+  pluginConfig,
+  spinner,
+}) {
+  const extList = await runExtensionCommand(
+    // @ts-ignore
+    {
+      appiumHome,
+      subcommand: type,
+      [`${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(
+    // @ts-ignore
+    {
+      subcommand: type,
+      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);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = main;
+
+/**
+ * @typedef CheckAndInstallExtensionsOpts
+ * @property {typeof runExtensionCommand} runExtensionCommand
+ * @property {string} appiumHome
+ * @property {DRIVER_TYPE | PLUGIN_TYPE} type
+ * @property {string} ext
+ * @property {import('../lib/extension/driver-config').DriverConfig} driverConfig
+ * @property {import('../lib/extension/plugin-config').PluginConfig} pluginConfig
+ * @property {import('ora').Ora} spinner
+ */

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,193 @@
+import {DriverType, PluginType, ServerArgs} from '@appium/types';
+import {SetOptional} from 'type-fest';
+import {InstallType} from './manifest';
+export type CliCommandServer = 'server';
+export type CliCommandDriver = DriverType;
+export type CliCommandPlugin = PluginType;
+
+/**
+ * Extension-specific commands
+ */
+export type CliExtensionCommand = CliCommandDriver | CliCommandPlugin;
+
+/**
+ * Possible commands for the `appium` CLI.
+ */
+export type CliCommand = CliCommandServer | CliExtensionCommand;
+
+/**
+ * Possible subcommands of {@linkcode CliCommandDriver} or
+ * {@linkcode CliCommandPlugin}.
+ */
+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 CliCommandServer}.
+   */
+  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 CliCommandDriver
+    ? DriverExtArgs
+    : Cmd extends CliCommandPlugin
+    ? 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 = CliCommandServer,
+  SubCmd extends CliExtensionSubcommand | void = void
+> = MoreArgs &
+  ProgrammaticArgs &
+  (Cmd extends CliCommandServer
+    ? 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 = CliCommandServer,
+  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 = CliCommandServer,
+  SubCmd extends CliExtensionSubcommand | void = void
+> = Cmd extends CliCommandServer
+  ? SetOptional<CommonArgs<Cmd>, keyof ServerArgs>
+  : ParsedArgs<Cmd, SubCmd>;
+
+/**
+ * Shown by `appium --build-info`
+ */
+export type BuildInfo = {
+  version: string;
+  'git-sha'?: string;
+  built?: string;
+};