appium 2.0.0-beta.4 → 2.0.0-beta.40

package/scripts/autoinstall-extensions.js

@@ -0,0 +1,177 @@
+#!/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.
+ *
+ * @example
+ * `npm install -g appium --drivers=uiautomator2,xcuitest --plugins=images`
+ */
+
+/** @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 {env, util, logger} = require('@appium/support');
+
+const ora = require('ora');
+
+const log = (message) => {
+  console.error(`[Appium] ${message}`);
+};
+
+const spinner = ora({
+  text: 'Checking Appium installation...',
+  prefixText: '[Appium]',
+}).start();
+
+try {
+  ({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) {
+    console.error('Detected CI environment, exiting with code 1');
+    process.exitCode = 1;
+  } else {
+    process.exitCode = 0;
+  }
+  process.exit();
+}
+
+async function main() {
+  if (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(
+      '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/types/appium-manifest.ts

@@ -0,0 +1,73 @@
+import {CommonExtMetadata, ExtMetadata, ExtSchemaMetadata} from './extension-manifest';
+import {ExtensionType, DriverType, PluginType} from '@appium/types';
+
+export type InstallType = 'npm' | 'git' | 'local' | 'github';
+
+export interface InternalMetadata {
+  /**
+   * Package name of extension
+   *
+   * `name` from its `package.json`
+   */
+  pkgName: string;
+  /**
+   * Version of extension
+   *
+   * `version` from its `package.json`
+   */
+  version: string;
+  /**
+   * The method in which the user installed the extension (the `source` CLI arg)
+   */
+  installType: InstallType;
+  /**
+   * Whatever the user typed as the extension to install. May be derived from `package.json`
+   */
+  installSpec: string;
+  /**
+   * Maximum version of Appium that this extension is compatible with.
+   *
+   * If `undefined`, we'll try anyway.
+   */
+  appiumVersion?: 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 &
+  CommonExtMetadata; // XXX: ExtMetadata should be a union with CommonMetadata. why is this needed?
+
+export type WithSchemaManifest = {
+  schema: ExtSchemaMetadata;
+};
+
+/**
+ * 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;
+}

package/types/cli.ts

@@ -0,0 +1,146 @@
+import {ServerArgs} from '@appium/types';
+import type {
+  DRIVER_TYPE as DRIVER_SUBCOMMAND,
+  EXT_SUBCOMMAND_INSTALL,
+  EXT_SUBCOMMAND_LIST,
+  EXT_SUBCOMMAND_RUN,
+  EXT_SUBCOMMAND_UNINSTALL,
+  EXT_SUBCOMMAND_UPDATE,
+  PLUGIN_TYPE as PLUGIN_SUBCOMMAND,
+  SERVER_SUBCOMMAND,
+} from '../lib/constants';
+
+export type ServerSubcommand = typeof SERVER_SUBCOMMAND;
+export type DriverSubcommand = typeof DRIVER_SUBCOMMAND;
+export type PluginSubcommand = typeof PLUGIN_SUBCOMMAND;
+
+/**
+ * Possible subcommands for the `appium` CLI.
+ */
+export type CliSubcommand = ServerSubcommand | DriverSubcommand | PluginSubcommand;
+
+/**
+ * Possible subcommands of {@linkcode DriverSubcommand} or
+ * {@linkcode PluginSubcommand}.
+ */
+export type CliExtensionSubcommand =
+  | typeof EXT_SUBCOMMAND_INSTALL
+  | typeof EXT_SUBCOMMAND_LIST
+  | typeof EXT_SUBCOMMAND_RUN
+  | typeof EXT_SUBCOMMAND_UPDATE
+  | typeof EXT_SUBCOMMAND_UNINSTALL;
+
+/**
+ * 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 ServerSubcommand}.
+   */
+  subcommand?: CliSubcommand;
+
+  /**
+   * 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;
+}
+
+/**
+ * These are args which the user will specify if using an extension command
+ */
+export interface ExtArgs extends WithExtSubcommand {
+  /**
+   * Subcommands of `driver` subcommand
+   */
+  driverCommand?: CliExtensionSubcommand;
+
+  /**
+   * Subcommands of `plugin` subcommand
+   */
+  pluginCommand?: CliExtensionSubcommand;
+}
+
+/**
+ * Args having the `server` subcommand
+ */
+export interface WithServerSubcommand {
+  subcommand?: ServerSubcommand;
+}
+
+/**
+ * Args having the `driver` or `plugin` subcommand
+ */
+export interface WithExtSubcommand {
+  subcommand: DriverSubcommand | PluginSubcommand;
+}
+
+/**
+ * Some generic bits of arguments; should not be used outside this declaration
+ */
+type CommonArgs<SArgs, T = WithServerSubcommand> = MoreArgs &
+  ProgrammaticArgs &
+  (T extends WithServerSubcommand ? SArgs : T extends WithExtSubcommand ? ExtArgs : never);
+
+/**
+ * Fully-parsed arguments, containing defaults, computed args, and config file values.
+ */
+export type ParsedArgs<T = WithServerSubcommand> = CommonArgs<ServerArgs, T>;
+
+/**
+ * Partial arguments, as supplied by a user. _May_ have defaults applied; _may_ contain config values; _may_ contain computed args.
+ */
+export type Args<T = WithServerSubcommand> = CommonArgs<Partial<ServerArgs>, T>;
+
+/**
+ * Shown by `appium --build-info`
+ */
+export type BuildInfo = {
+  version: string;
+  'git-sha'?: string;
+  built?: string;
+};

package/types/extension-manifest.ts

@@ -0,0 +1,64 @@
+/**
+ * These types describe information about external extensions and the contents of their `package.json` files
+ */
+
+import type {SchemaObject} from 'ajv';
+import type {PackageJson, SetRequired} from 'type-fest';
+import {DriverType, ExtensionType, PluginType} from '@appium/types';
+
+/**
+ * This is what is allowed in the `appium.schema` prop of an extension's `package.json`.
+ */
+export type ExtSchemaMetadata = string | (SchemaObject & {[key: number]: never});
+
+/**
+ * Manifest data shared by all extensions, as contained in `package.json`
+ */
+export interface CommonExtMetadata {
+  mainClass: string;
+  scripts?: Record<string, string>;
+  schema?: ExtSchemaMetadata;
+}
+
+/**
+ * Driver-specific manifest data as contained in `package.json`
+ */
+export interface DriverMetadata {
+  automationName: string;
+  platformNames: string[];
+  driverName: string;
+}
+
+/**
+ * Plugin-specific manifest data as stored in `package.json`
+ */
+export interface PluginMetadata {
+  pluginName: string;
+}
+
+/**
+ * Generic type to refer to either {@linkcode DriverMetadata} or {@linkcode PluginMetadata}
+ * Corresponds to the `appium` prop in an extension's `package.json`.
+ */
+export type ExtMetadata<ExtType extends ExtensionType> = (ExtType extends DriverType
+  ? DriverMetadata
+  : ExtType extends PluginType
+  ? PluginMetadata
+  : never) &
+  CommonExtMetadata;
+
+/**
+ * A `package.json` containing extension metadata.
+ * Must have the following properties:
+ * - `name`: the name of the extension
+ * - `version`: the version of the extension
+ * - `appium`: the metadata for the extension
+ * - `peerDependencies.appium`: the maximum compatible version of Appium
+ */
+export type ExtPackageJson<ExtType extends ExtensionType> = SetRequired<
+  PackageJson,
+  'name' | 'version'
+> & {
+  appium: ExtMetadata<ExtType>;
+  peerDependencies: {appium: string; [key: string]: string};
+};

package/types/index.ts

@@ -0,0 +1,21 @@
+import {ExtensionType, DriverType, DriverClass, PluginType, PluginClass} from '@appium/types';
+
+export * from './appium-manifest';
+export * from './extension-manifest';
+export * from './cli';
+
+/**
+ * Known environment variables concerning Appium
+ */
+export interface AppiumEnv extends NodeJS.ProcessEnv {
+  APPIUM_HOME?: string;
+}
+
+/**
+ * Generic to get at the class of an extension.
+ */
+export type ExtClass<ExtType extends ExtensionType> = ExtType extends DriverType
+  ? DriverClass
+  : ExtType extends PluginType
+  ? PluginClass
+  : never;