appium 3.2.2 → 3.3.1

package/lib/cli/{setup-command.js → setup-command.ts}

@@ -1,4 +1,11 @@
 import _ from 'lodash';
+import type {
+  Args,
+  CliCommandSetup,
+  CliCommandSetupSubcommand,
+  CliExtensionCommand,
+  CliExtensionSubcommand,
+} from 'appium/types';
 import {
   DESKTOP_BROWSERS,
   DESKTOP_DRIVERS,
@@ -6,7 +13,8 @@ import {
 } from '../constants';
 import {runExtensionCommand} from './extension';
 import { system, fs } from '@appium/support';
-import log from '../logger';
+import {log} from '../logger';
+import type {ExtensionConfig} from '../extension/extension-config';
 
 /**
  * Subcommands of preset for setup
@@ -20,13 +28,11 @@ export const SUBCOMMAND_RESET = 'reset';
  * Pairs of preset subcommand and driver candidates.
  * Driver names listed in KNOWN_DRIVERS to install by default
  */
-const PRESET_PAIRS = Object.freeze(
-  /** @type {const} */ ({
-    mobile: _.keys(MOBILE_DRIVERS),
-    desktop: _.keys(DESKTOP_DRIVERS),
-    browser: _.keys(DESKTOP_BROWSERS)
-  }),
-);
+const PRESET_PAIRS = Object.freeze({
+  mobile: _.keys(MOBILE_DRIVERS),
+  desktop: _.keys(DESKTOP_DRIVERS),
+  browser: _.keys(DESKTOP_BROWSERS),
+} as const);
 const DRIVERS_ONLY_MACOS = ['xcuitest', 'safari', 'mac2'];
 
 const DRIVERS_ONLY_WINDOWS = ['windows'];
@@ -36,12 +42,14 @@ const DRIVERS_ONLY_WINDOWS = ['windows'];
  */
 export const DEFAULT_PLUGINS = ['images', 'inspector'];
 
+type DriverConfig = ExtensionConfig<'driver'>;
+type PluginConfig = ExtensionConfig<'plugin'>;
+type CliExtArgs = Args<CliExtensionCommand, CliExtensionSubcommand>;
+
 /**
  * Return a list of drivers available for current host platform.
- * @param {import('appium/types').CliCommandSetupSubcommand} presetName
- * @returns {Array<string>}
  */
-export function getPresetDrivers(presetName) {
+export function getPresetDrivers(presetName: CliCommandSetupSubcommand): string[] {
   return _.filter(PRESET_PAIRS[presetName], (driver) => {
     if (_.includes(DRIVERS_ONLY_MACOS, driver)) {
       return system.isMac();
@@ -58,9 +66,8 @@ export function getPresetDrivers(presetName) {
 
 /**
  * Return desktop platform name for setup command description.
- * @returns {string}
  */
-export function determinePlatformName() {
+export function determinePlatformName(): string {
   if (system.isMac()) {
     return 'macOS';
   } else if (system.isWindows()) {
@@ -70,14 +77,16 @@ export function determinePlatformName() {
 }
 
 /**
- * Run 'setup' command to install drivers/plugins into the given appium home.
- * @template {import('appium/types').CliCommandSetup} SetupCmd
- * @param {import('appium/types').Args<SetupCmd>} preConfigArgs
- * @param {DriverConfig} driverConfig
- * @param {PluginConfig} pluginConfig
- * @returns {Promise<void>}
- */
-export async function runSetupCommand(preConfigArgs, driverConfig, pluginConfig) {
+ * Runs the `setup` command and applies the selected preset.
+ *
+ * Depending on the subcommand, this installs mobile/desktop/browser presets or
+ * removes all installed extensions and manifests via `reset`.
+ */
+export async function runSetupCommand(
+  preConfigArgs: Args<CliCommandSetup>,
+  driverConfig: DriverConfig,
+  pluginConfig: PluginConfig
+): Promise<void> {
   switch (preConfigArgs.setupCommand) {
     case SUBCOMMAND_DESKTOP:
       await setupDesktopAppDrivers(driverConfig);
@@ -99,22 +108,19 @@ export async function runSetupCommand(preConfigArgs, driverConfig, pluginConfig)
 
 /**
  * Resets all installed drivers and extensions
- *
- * @param {DriverConfig} driverConfig
- * @param {PluginConfig} pluginConfig
- * @returns {Promise<void>}
  */
-async function resetAllExtensions(driverConfig, pluginConfig) {
-  for (const [command, config] of [
+async function resetAllExtensions(driverConfig: DriverConfig, pluginConfig: PluginConfig): Promise<void> {
+  const commandConfigs: [CliExtensionCommand, DriverConfig | PluginConfig][] = [
     ['driver', driverConfig],
     ['plugin', pluginConfig],
-  ]) {
-    for (const extensionName of _.keys(/** @type {DriverConfig|PluginConfig} */ (config).installedExtensions)) {
+  ];
+  for (const [command, config] of commandConfigs) {
+    for (const extensionName of _.keys(config.installedExtensions)) {
       try {
         await uninstallExtension(
           extensionName,
-          extensionCommandArgs(/** @type {CliExtensionCommand} */ (command), extensionName, 'uninstall'),
-          /** @type {DriverConfig|PluginConfig} */ (config)
+          extensionCommandArgs(command, extensionName, 'uninstall'),
+          config
         );
       } catch (e) {
         log.warn(
@@ -124,8 +130,8 @@ async function resetAllExtensions(driverConfig, pluginConfig) {
       }
     }
 
-    const manifestPath = /** @type {DriverConfig|PluginConfig} */ (config).manifestPath;
-    if (!await fs.exists(manifestPath)) {
+    const manifestPath = config.manifestPath;
+    if (!manifestPath || !await fs.exists(manifestPath)) {
       continue;
     }
 
@@ -140,38 +146,29 @@ async function resetAllExtensions(driverConfig, pluginConfig) {
 
 /**
  * Install drivers listed in DEFAULT_DRIVERS.
- * @param {DriverConfig} driverConfig
- * @returns {Promise<void>}
  */
-async function setupMobileDrivers(driverConfig) {
+async function setupMobileDrivers(driverConfig: DriverConfig): Promise<void> {
   await installDrivers(SUBCOMMAND_MOBILE, driverConfig);
 }
 
 /**
  * Install all of known drivers listed in BROWSER_DRIVERS.
- * @param {DriverConfig} driverConfig
- * @returns {Promise<void>}
  */
-async function setupBrowserDrivers(driverConfig) {
+async function setupBrowserDrivers(driverConfig: DriverConfig): Promise<void> {
   await installDrivers(SUBCOMMAND_BROWSER, driverConfig);
 }
 
 /**
  * Install all of known drivers listed in DESKTOP_APP_DRIVERS.
- * @param {DriverConfig} driverConfig
- * @returns {Promise<void>}
  */
-async function setupDesktopAppDrivers(driverConfig) {
+async function setupDesktopAppDrivers(driverConfig: DriverConfig): Promise<void> {
   await installDrivers(SUBCOMMAND_DESKTOP, driverConfig);
 }
 
 /**
  * Install the given driver name. It skips the installation if the given driver name was already installed.
- * @param {import('appium/types').CliCommandSetupSubcommand} subcommand
- * @param {DriverConfig} driverConfig
- * @returns {Promise<void>}
  */
-async function installDrivers(subcommand, driverConfig) {
+async function installDrivers(subcommand: CliCommandSetupSubcommand, driverConfig: DriverConfig): Promise<void> {
   for (const driverName of getPresetDrivers(subcommand)) {
     await installExtension(driverName, extensionCommandArgs('driver', driverName, 'install'), driverConfig);
   }
@@ -179,10 +176,8 @@ async function installDrivers(subcommand, driverConfig) {
 
 /**
  * Install plugins listed in DEFAULT_PLUGINS.
- * @param {PluginConfig} pluginConfig
- * @returns {Promise<void>}
  */
-async function setupDefaultPlugins(pluginConfig) {
+async function setupDefaultPlugins(pluginConfig: PluginConfig): Promise<void> {
   for (const pluginName of DEFAULT_PLUGINS) {
     await installExtension(pluginName, extensionCommandArgs('plugin', pluginName, 'install'), pluginConfig);
   }
@@ -190,12 +185,12 @@ async function setupDefaultPlugins(pluginConfig) {
 
 /**
  * Run the given extensionConfigArgs command after checking if the given extensionName was already installed.
- * @param {string} extensionName
- * @param {Args} extensionConfigArgs
- * @param {DriverConfig|PluginConfig} extensionConfig
- * @returns {Promise<void>}
  */
-async function installExtension(extensionName, extensionConfigArgs, extensionConfig) {
+async function installExtension(
+  extensionName: string,
+  extensionConfigArgs: CliExtArgs,
+  extensionConfig: DriverConfig | PluginConfig
+): Promise<void> {
   if (_.keys(extensionConfig.installedExtensions).includes(extensionName)) {
     log.info(`${extensionName} (${extensionConfig.installedExtensions[extensionName].version}) is already installed. ` +
       `Skipping the installation.`);
@@ -206,12 +201,12 @@ async function installExtension(extensionName, extensionConfigArgs, extensionCon
 
 /**
  * Run the given extensionConfigArgs command after checking if the given extensionName was already installed.
- * @param {string} extensionName
- * @param {Args} extensionConfigArgs
- * @param {DriverConfig|PluginConfig} extensionConfig
- * @returns {Promise<void>}
  */
-async function uninstallExtension(extensionName, extensionConfigArgs, extensionConfig) {
+async function uninstallExtension(
+  extensionName: string,
+  extensionConfigArgs: CliExtArgs,
+  extensionConfig: DriverConfig | PluginConfig
+): Promise<void> {
   if (!_.keys(extensionConfig.installedExtensions).includes(extensionName)) {
     log.info(`${extensionName} (${extensionConfig.installedExtensions[extensionName].version}) is not installed. ` +
       `Skipping its uninstall.`);
@@ -222,24 +217,14 @@ async function uninstallExtension(extensionName, extensionConfigArgs, extensionC
 
 /**
  * Return the command config for driver or plugin.
- * @param {CliExtensionCommand} extensionCommand
- * @param {string} extensionName
- * @param {CliExtensionSubcommand} command
- * @returns {Args}
  */
-function extensionCommandArgs(extensionCommand, extensionName, command) {
+function extensionCommandArgs(
+  extensionCommand: CliExtensionCommand,
+  extensionName: string,
+  command: CliExtensionSubcommand
+): CliExtArgs {
   return (extensionCommand === 'plugin')
     ? {'subcommand': 'plugin', 'pluginCommand': command, 'plugin': extensionName}
     : {'subcommand': 'driver', 'driverCommand': command, 'driver': extensionName};
 }
 
-/**
- * @typedef {import('appium/types').CliExtensionCommand} CliExtensionCommand
- * @typedef {import('appium/types').CliExtensionSubcommand} CliExtensionSubcommand
- * @typedef {import('../extension/extension-config').ExtensionConfig<CliExtensionCommand>} PluginConfig
- * @typedef {import('../extension/extension-config').ExtensionConfig<CliExtensionCommand>} DriverConfig
- */
-
-/**
- * @typedef {import('appium/types').Args<CliExtensionCommand, CliExtensionSubcommand>} Args
- */

package/lib/cli/utils.ts

@@ -0,0 +1,97 @@
+/* eslint-disable no-console */
+
+import ora from 'ora';
+
+export const JSON_SPACES = 4;
+
+type ErrorLike = Error & {stderr?: unknown};
+
+export class RingBuffer<T = any> {
+  private readonly size: number;
+  private readonly buffer: T[] = [];
+
+  constructor(size = 50) {
+    this.size = size;
+  }
+
+  /**
+   * Get the current buffer contents.
+   */
+  getBuff(): T[] {
+    return this.buffer;
+  }
+
+  /**
+   * Add an item to the buffer.
+   */
+  enqueue(item: T): void {
+    if (this.buffer.length >= this.size) {
+      this.dequeue();
+    }
+    this.buffer.push(item);
+  }
+
+  /**
+   * Remove the oldest item from the buffer.
+   */
+  dequeue(): void {
+    this.buffer.shift();
+  }
+}
+
+/**
+ * Log an error to the console and exit the process.
+ *
+ * @param json - whether we should log json or text
+ * @param msg - error message, object, Error instance, etc.
+ */
+export function errAndQuit(json: boolean, msg: unknown): never {
+  if (json) {
+    console.log(JSON.stringify({error: String(msg)}, null, JSON_SPACES));
+  } else {
+    console.error((String(msg) as any).red);
+    if ((msg as ErrorLike)?.stderr) {
+      console.error((String((msg as ErrorLike).stderr) as any).red);
+    }
+  }
+  process.exit(1);
+}
+
+/**
+ * Conditionally log something to the console.
+ *
+ * @param json - whether we are in json mode (and should therefore not log)
+ * @param msg - string to log
+ */
+export function log(json: boolean, msg: string): void {
+  if (!json) {
+    console.log(msg);
+  }
+}
+
+/**
+ * Start a spinner, execute an async function, and then stop the spinner.
+ *
+ * @param json - whether we are in json mode (and should therefore not log)
+ * @param msg - string to log
+ * @param fn - function to wrap with spinning
+ * @returns result of `fn`
+ */
+export async function spinWith<T>(
+  json: boolean,
+  msg: string,
+  fn: () => T | Promise<T>
+): Promise<T> {
+  if (json) {
+    return await fn();
+  }
+  const spinner = ora(msg).start();
+  try {
+    const res = await fn();
+    spinner.succeed();
+    return res;
+  } catch (err) {
+    spinner.fail();
+    throw err;
+  }
+}

package/lib/{constants.js → constants.ts}

@@ -20,7 +20,6 @@ export const SERVER_SUBCOMMAND = 'server';
  */
 export const SETUP_SUBCOMMAND = 'setup';
 
-
 /**
  * The value of `--use-plugins` if _all_ plugins should be loaded
  */
@@ -30,51 +29,41 @@ export const USE_ALL_PLUGINS = 'all';
 // The plugins in this list will be available to the CLI so users can just
 // type 'appium plugin install 'name'', rather than having to specify the full
 // npm package. I.e., these are the officially recognized plugins.
-export const KNOWN_PLUGINS = Object.freeze(
-  /** @type {const} */ ({
-    'execute-driver': '@appium/execute-driver-plugin',
-    images: '@appium/images-plugin',
-    inspector: 'appium-inspector-plugin',
-    'relaxed-caps': '@appium/relaxed-caps-plugin',
-    storage: '@appium/storage-plugin',
-    'universal-xml': '@appium/universal-xml-plugin',
-  }),
-);
-
-export const MOBILE_DRIVERS = Object.freeze(
-  /** @type {const} */ ({
-    uiautomator2: 'appium-uiautomator2-driver',
-    xcuitest: 'appium-xcuitest-driver',
-    espresso: 'appium-espresso-driver',
-  }),
-);
-
-export const DESKTOP_DRIVERS = Object.freeze(
-  /** @type {const} */ ({
-    mac2: 'appium-mac2-driver',
-    windows: 'appium-windows-driver',
-  }),
-);
-
-export const DESKTOP_BROWSERS = Object.freeze(
-  /** @type {const} */ ({
-    safari: 'appium-safari-driver',
-    gecko: 'appium-geckodriver',
-    chromium: 'appium-chromium-driver',
-  }),
-);
+export const KNOWN_PLUGINS = Object.freeze({
+  'execute-driver': '@appium/execute-driver-plugin',
+  images: '@appium/images-plugin',
+  inspector: 'appium-inspector-plugin',
+  'relaxed-caps': '@appium/relaxed-caps-plugin',
+  storage: '@appium/storage-plugin',
+  'universal-xml': '@appium/universal-xml-plugin',
+} as const);
+
+export const MOBILE_DRIVERS = Object.freeze({
+  uiautomator2: 'appium-uiautomator2-driver',
+  xcuitest: 'appium-xcuitest-driver',
+  espresso: 'appium-espresso-driver',
+} as const);
+
+export const DESKTOP_DRIVERS = Object.freeze({
+  mac2: 'appium-mac2-driver',
+  windows: 'appium-windows-driver',
+} as const);
+
+export const DESKTOP_BROWSERS = Object.freeze({
+  safari: 'appium-safari-driver',
+  gecko: 'appium-geckodriver',
+  chromium: 'appium-chromium-driver',
+} as const);
 
 // This is a map of driver names to npm packages representing those drivers.
 // The drivers in this list will be available to the CLI so users can just
 // type 'appium driver install 'name'', rather than having to specify the full
 // npm package. I.e., these are the officially recognized drivers.
-export const KNOWN_DRIVERS = Object.freeze(
-  /** @type {const} */ ({
-    ...MOBILE_DRIVERS,
-    ...DESKTOP_DRIVERS,
-    ...DESKTOP_BROWSERS,
-  }),
-);
+export const KNOWN_DRIVERS = Object.freeze({
+  ...MOBILE_DRIVERS,
+  ...DESKTOP_DRIVERS,
+  ...DESKTOP_BROWSERS,
+} as const);
 
 /**
  * Relative path to directory containing any Appium internal files