appium 3.3.0 → 3.3.1

package/lib/cli/extension-command.ts

@@ -33,9 +33,6 @@ import * as semver from 'semver';
 const UPDATE_ALL = 'installed';
 const MAX_CONCURRENT_REPO_FETCHES = 5;
 
-class NotUpdatableError extends Error {}
-class NoUpdatesAvailableError extends Error {}
-
 /**
  * Options for the {@linkcode ExtensionCliCommand} constructor
  */
@@ -43,15 +40,15 @@ export type ExtensionCommandOptions<ExtType extends ExtensionType = ExtensionTyp
   config: ExtensionConfig<ExtType>;
   json: boolean;
 };
-
 export type ExtensionConfig<ExtType extends ExtensionType = ExtensionType> = BaseExtensionConfig<ExtType>;
+
 export type ExtRecord<ExtType extends ExtensionType = ExtensionType> = AppiumExtRecord<ExtType>;
+
 export type ExtMetadata<ExtType extends ExtensionType = ExtensionType> = AppiumExtMetadata<ExtType>;
 export type ExtManifest<ExtType extends ExtensionType = ExtensionType> = AppiumExtManifest<ExtType>;
 export type ExtPackageJson<ExtType extends ExtensionType = ExtensionType> = AppiumExtPackageJson<ExtType>;
 export type ExtInstallReceipt<ExtType extends ExtensionType = ExtensionType> =
   AppiumExtInstallReceipt<ExtType>;
-
 /**
  * Extra stuff about extensions; used indirectly by {@linkcode ExtensionCliCommand.list}.
  */
@@ -64,7 +61,6 @@ export type ExtensionListMetadata = {
   devMode?: boolean;
   repositoryUrl?: string;
 };
-
 /**
  * Possible return value for {@linkcode ExtensionCliCommand.list}
  */
@@ -85,32 +81,92 @@ export type ExtensionList<ExtType extends ExtensionType = ExtensionType> = Recor
 >;
 
 /**
- * Omits `driverName`/`pluginName` props from the receipt to make a {@linkcode ExtManifest}
+ * Return value of {@linkcode ExtensionCliCommand._run}
  */
-function receiptToManifest<ExtType extends ExtensionType>(
-  receipt: ExtInstallReceipt<ExtType>
-): ExtManifest<ExtType> {
-  return _.omit(receipt, 'driverName', 'pluginName') as ExtManifest<ExtType>;
-}
+export type RunOutput = {output?: string[]};
 
 /**
- * Fetches the remote extension version requirements
- *
- * @param pkgName Extension name
- * @param [pkgVer] Extension version (if not provided then the latest is assumed)
+ * Return type of {@linkcode ExtensionCliCommand.getPostInstallText}.
  */
-async function getRemoteExtensionVersionReq(
-  pkgName: string,
-  pkgVer?: string
-): Promise<[string, string | null]> {
-  const allDeps = await npm.getPackageInfo(
-    `${pkgName}${pkgVer ? `@${pkgVer}` : ``}`,
-    ['peerDependencies', 'dependencies']
-  );
-  const requiredVersionPair = _.flatMap(_.values(allDeps).map(_.toPairs))
-    .find(([name]) => name === 'appium');
-  return [npmPackage.version, requiredVersionPair ? requiredVersionPair[1] : null];
-}
+export type PostInstallText = string;
+
+/**
+ * Return value of {@linkcode ExtensionCliCommand._update}.
+ */
+export type ExtensionUpdateResult = {errors: Record<string, Error>; updates: Record<string, UpdateReport>};
+
+/**
+ * Used by {@linkcode ExtensionCliCommand.getPostInstallText}
+ */
+export type ExtensionArgs<ExtType extends ExtensionType = ExtensionType> = {
+  extName: string;
+  extData: ExtInstallReceipt<ExtType>;
+};
+
+/**
+ * Options for {@linkcode ExtensionCliCommand._run}.
+ */
+type RunOptions = {
+  installSpec: string;
+  scriptName?: string;
+  extraArgs?: string[];
+  bufferOutput?: boolean;
+};
+
+/**
+ * Options for {@linkcode ExtensionCliCommand.doctor}.
+ */
+type DoctorOptions = {installSpec: string};
+
+/**
+ * Options for {@linkcode ExtensionCliCommand._update}.
+ */
+type ExtensionUpdateOpts = {installSpec: string; unsafe: boolean};
+
+/**
+ * Part of result of {@linkcode ExtensionCliCommand._update}.
+ */
+type UpdateReport = {from: string; to: string | null};
+
+/**
+ * Options for {@linkcode ExtensionCliCommand._uninstall}.
+ */
+type UninstallOpts = {installSpec: string};
+
+/**
+ * Options for {@linkcode ExtensionCliCommand.installViaNpm}
+ */
+type InstallViaNpmArgs = {
+  installSpec: string;
+  pkgName: string;
+  installType: InstallType;
+  pkgVer?: string;
+};
+
+/**
+ * Object returned by {@linkcode ExtensionCliCommand.checkForExtensionUpdate}
+ */
+type PossibleUpdates = {current: string; safeUpdate: string | null; unsafeUpdate: string | null};
+
+/**
+ * Options for {@linkcode ExtensionCliCommand._install}
+ */
+type InstallOpts = {installSpec: string; installType: InstallType; packageName?: string};
+
+type ListOptions = {showInstalled: boolean; showUpdates: boolean; verbose?: boolean};
+
+type GetInstallationReceiptOpts<ExtType extends ExtensionType = ExtensionType> = {
+  installPath: string;
+  installSpec: string;
+  pkg: ExtPackageJson<ExtType>;
+  installType: InstallType;
+};
+
+type InstalledExtensionLike = {installType?: InstallType; installPath?: string};
+
+class NotUpdatableError extends Error {}
+
+class NoUpdatesAvailableError extends Error {}
 
 abstract class ExtensionCliCommand<ExtType extends ExtensionType = ExtensionType> {
   /**
@@ -190,19 +246,6 @@ abstract class ExtensionCliCommand<ExtType extends ExtensionType = ExtensionType
     return await this._displayNormalListOutput(listData, showUpdates);
   }
 
-  /**
-   * For any `package.json` fields which a particular type of extension requires, validate the
-   * presence and form of those fields on the `package.json` data, throwing an error if anything is
-   * amiss.
-   *
-   * @param extMetadata - the data in the "appium" field of `package.json` for an extension
-   * @param installSpec - Extension name/spec
-   */
-  protected abstract validateExtensionFields(
-    extMetadata: ExtMetadata<ExtType>,
-    installSpec: string
-  ): void;
-
   /**
    * Logs a message and returns an {@linkcode Error} to throw.
    *
@@ -373,13 +416,6 @@ abstract class ExtensionCliCommand<ExtType extends ExtensionType = ExtensionType
     return this.config.installedExtensions;
   }
 
-  /**
-   * Get the text which should be displayed to the user after an extension has been installed. This
-   * is designed to be overridden by drivers/plugins with their own particular text.
-   *
-   */
-  protected abstract getPostInstallText(args: ExtensionArgs<ExtType>): PostInstallText;
-
   /**
    * Uninstall an extension.
    *
@@ -1124,6 +1160,26 @@ abstract class ExtensionCliCommand<ExtType extends ExtensionType = ExtensionType
       }
     });
   }
+
+  /**
+   * For any `package.json` fields which a particular type of extension requires, validate the
+   * presence and form of those fields on the `package.json` data, throwing an error if anything is
+   * amiss.
+   *
+   * @param extMetadata - the data in the "appium" field of `package.json` for an extension
+   * @param installSpec - Extension name/spec
+   */
+  protected abstract validateExtensionFields(
+    extMetadata: ExtMetadata<ExtType>,
+    installSpec: string
+  ): void;
+
+  /**
+   * Get the text which should be displayed to the user after an extension has been installed. This
+   * is designed to be overridden by drivers/plugins with their own particular text.
+   *
+   */
+  protected abstract getPostInstallText(args: ExtensionArgs<ExtType>): PostInstallText;
 }
 
 /**
@@ -1164,6 +1220,34 @@ export async function injectAppiumSymlinks(
   );
 }
 
+/**
+ * Omits `driverName`/`pluginName` props from the receipt to make a {@linkcode ExtManifest}
+ */
+function receiptToManifest<ExtType extends ExtensionType>(
+  receipt: ExtInstallReceipt<ExtType>
+): ExtManifest<ExtType> {
+  return _.omit(receipt, 'driverName', 'pluginName') as ExtManifest<ExtType>;
+}
+
+/**
+ * Fetches the remote extension version requirements
+ *
+ * @param pkgName Extension name
+ * @param [pkgVer] Extension version (if not provided then the latest is assumed)
+ */
+async function getRemoteExtensionVersionReq(
+  pkgName: string,
+  pkgVer?: string
+): Promise<[string, string | null]> {
+  const allDeps = await npm.getPackageInfo(
+    `${pkgName}${pkgVer ? `@${pkgVer}` : ``}`,
+    ['peerDependencies', 'dependencies']
+  );
+  const requiredVersionPair = _.flatMap(_.values(allDeps).map(_.toPairs))
+    .find(([name]) => name === 'appium');
+  return [npmPackage.version, requiredVersionPair ? requiredVersionPair[1] : null];
+}
+
 /**
  * This is needed to ensure proper module resolution for installed extensions,
  * especially ESM ones.
@@ -1187,90 +1271,6 @@ async function injectAppiumSymlink(dstFolder: string, logger: AppiumLogger): Pro
   }
 }
 
-/**
- * Options for {@linkcode ExtensionCliCommand._run}.
- */
-type RunOptions = {
-  installSpec: string;
-  scriptName?: string;
-  extraArgs?: string[];
-  bufferOutput?: boolean;
-};
-
-/**
- * Options for {@linkcode ExtensionCliCommand.doctor}.
- */
-type DoctorOptions = {installSpec: string};
-
-/**
- * Return value of {@linkcode ExtensionCliCommand._run}
- */
-export type RunOutput = {output?: string[]};
-
-/**
- * Return type of {@linkcode ExtensionCliCommand.getPostInstallText}.
- */
-export type PostInstallText = string;
-
-/**
- * Options for {@linkcode ExtensionCliCommand._update}.
- */
-type ExtensionUpdateOpts = {installSpec: string; unsafe: boolean};
-
-/**
- * Part of result of {@linkcode ExtensionCliCommand._update}.
- */
-type UpdateReport = {from: string; to: string | null};
-
-/**
- * Return value of {@linkcode ExtensionCliCommand._update}.
- */
-export type ExtensionUpdateResult = {errors: Record<string, Error>; updates: Record<string, UpdateReport>};
-
-/**
- * Options for {@linkcode ExtensionCliCommand._uninstall}.
- */
-type UninstallOpts = {installSpec: string};
-
-/**
- * Used by {@linkcode ExtensionCliCommand.getPostInstallText}
- */
-export type ExtensionArgs<ExtType extends ExtensionType = ExtensionType> = {
-  extName: string;
-  extData: ExtInstallReceipt<ExtType>;
-};
-
-/**
- * Options for {@linkcode ExtensionCliCommand.installViaNpm}
- */
-type InstallViaNpmArgs = {
-  installSpec: string;
-  pkgName: string;
-  installType: InstallType;
-  pkgVer?: string;
-};
-
-/**
- * Object returned by {@linkcode ExtensionCliCommand.checkForExtensionUpdate}
- */
-type PossibleUpdates = {current: string; safeUpdate: string | null; unsafeUpdate: string | null};
-
-/**
- * Options for {@linkcode ExtensionCliCommand._install}
- */
-type InstallOpts = {installSpec: string; installType: InstallType; packageName?: string};
-
-type ListOptions = {showInstalled: boolean; showUpdates: boolean; verbose?: boolean};
-
-type GetInstallationReceiptOpts<ExtType extends ExtensionType = ExtensionType> = {
-  installPath: string;
-  installSpec: string;
-  pkg: ExtPackageJson<ExtType>;
-  installType: InstallType;
-};
-
-type InstalledExtensionLike = {installType?: InstallType; installPath?: string};
-
 export default ExtensionCliCommand;
 export {ExtensionCliCommand as ExtensionCommand};
 

package/lib/cli/extension.ts

@@ -3,7 +3,7 @@ import type {Class, DriverType, ExtensionType, PluginType} from '@appium/types';
 import type {Args, CliExtensionCommand, CliExtensionSubcommand} from 'appium/types';
 import type {ExtensionConfig} from '../extension/extension-config';
 import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
-import {isExtensionCommandArgs} from '../utils';
+import {isExtensionCommandArgs} from '../schema/cli-args-guards';
 import DriverCliCommand from './driver-command';
 import PluginCliCommand from './plugin-command';
 import {errAndQuit, JSON_SPACES} from './utils';
@@ -15,6 +15,12 @@ export const commandClasses = Object.freeze(
   } as const
 );
 
+export type ExtCommand<ExtType extends ExtensionType> = ExtType extends DriverType
+  ? Class<DriverCliCommand>
+  : ExtType extends PluginType
+    ? Class<PluginCliCommand>
+    : never;
+
 /**
  * Executes a driver/plugin extension subcommand and returns the command result.
  *
@@ -57,9 +63,3 @@ export async function runExtensionCommand<
 
   return jsonResult;
 }
-
-export type ExtCommand<ExtType extends ExtensionType> = ExtType extends DriverType
-  ? Class<DriverCliCommand>
-  : ExtType extends PluginType
-    ? Class<PluginCliCommand>
-    : never;

package/lib/cli/parser.ts

@@ -18,7 +18,7 @@ import {
   SETUP_SUBCOMMAND
 } from '../constants';
 import {finalizeSchema, getAllArgSpecs, getArgSpec, hasArgSpec} from '../schema';
-import {rootDir} from '../config';
+import {rootDir} from '../helpers/build';
 import {getExtensionArgs, getServerArgs} from './args';
 import type {ArgumentDefinitions} from './args';
 import {
@@ -104,53 +104,6 @@ export class ArgParser {
     this.parse_args = this.parseArgs;
   }
 
-  /**
-   * Parses CLI args and returns Appium's normalized argument object.
-   *
-   * If no explicit subcommand is provided, this injects `server`.
-   * `parse_args` is a backwards-compatible alias of this method.
-   */
-  parseArgs(args: string[] = process.argv.slice(2)): TransformedArgsMap {
-    if (!NON_SERVER_ARGS.has(args[0])) {
-      args.unshift(SERVER_SUBCOMMAND);
-    }
-
-    try {
-      const parsed = this.parser.parse_known_args(args);
-      const [knownArgs, unknownArgs] = parsed;
-      // XXX: you'd think that argparse, when given an alias for a subcommand,
-      // would set this value to the original subcommand name, but it doesn't.
-      if (knownArgs?.driverCommand === 'ls') {
-        knownArgs.driverCommand = 'list';
-      } else if (knownArgs?.pluginCommand === 'ls') {
-        knownArgs.pluginCommand = 'list';
-      }
-      if (
-        unknownArgs?.length &&
-        (knownArgs.driverCommand === 'run' || knownArgs.pluginCommand === 'run')
-      ) {
-        return ArgParser._transformParsedArgs(knownArgs, unknownArgs);
-      } else if (unknownArgs?.length) {
-        throw new Error(`[ERROR] Unrecognized arguments: ${unknownArgs.join(' ')}`);
-      }
-      return ArgParser._transformParsedArgs(knownArgs);
-    } catch (err) {
-      if (this.debug) {
-        throw err;
-      }
-      // this isn't tested via unit tests (we use `debug: true`) so may escape coverage.
-
-      /* istanbul ignore next */
-      {
-        // eslint-disable-next-line no-console
-        console.error(); // need an extra space since argparse prints usage.
-        // eslint-disable-next-line no-console
-        console.error(err.message);
-        process.exit(1);
-      }
-    }
-  }
-
   /**
    * Normalizes server arg keys from schema names to parser destination names.
    *
@@ -353,13 +306,60 @@ export class ArgParser {
       ArgParser._patchExit(parser);
     }
   }
+
+  /**
+   * Parses CLI args and returns Appium's normalized argument object.
+   *
+   * If no explicit subcommand is provided, this injects `server`.
+   * `parse_args` is a backwards-compatible alias of this method.
+   */
+  parseArgs(args: string[] = process.argv.slice(2)): TransformedArgsMap {
+    if (!NON_SERVER_ARGS.has(args[0])) {
+      args.unshift(SERVER_SUBCOMMAND);
+    }
+
+    try {
+      const parsed = this.parser.parse_known_args(args);
+      const [knownArgs, unknownArgs] = parsed;
+      // XXX: you'd think that argparse, when given an alias for a subcommand,
+      // would set this value to the original subcommand name, but it doesn't.
+      if (knownArgs?.driverCommand === 'ls') {
+        knownArgs.driverCommand = 'list';
+      } else if (knownArgs?.pluginCommand === 'ls') {
+        knownArgs.pluginCommand = 'list';
+      }
+      if (
+        unknownArgs?.length &&
+        (knownArgs.driverCommand === 'run' || knownArgs.pluginCommand === 'run')
+      ) {
+        return ArgParser._transformParsedArgs(knownArgs, unknownArgs);
+      } else if (unknownArgs?.length) {
+        throw new Error(`[ERROR] Unrecognized arguments: ${unknownArgs.join(' ')}`);
+      }
+      return ArgParser._transformParsedArgs(knownArgs);
+    } catch (err) {
+      if (this.debug) {
+        throw err;
+      }
+      // this isn't tested via unit tests (we use `debug: true`) so may escape coverage.
+
+      /* istanbul ignore next */
+      {
+        // eslint-disable-next-line no-console
+        console.error(); // need an extra space since argparse prints usage.
+        // eslint-disable-next-line no-console
+        console.error(err.message);
+        process.exit(1);
+      }
+    }
+  }
 }
 
 /**
  * Creates and returns an `ArgParser` after finalizing schema state.
  */
-export function getParser(debug = false) {
-  finalizeSchema();
+export async function getParser(debug = false): Promise<ArgParser> {
+  await finalizeSchema();
 
   return new ArgParser(debug);
 }

package/lib/cli/setup-command.ts

@@ -13,7 +13,7 @@ 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';
 
 /**
@@ -131,7 +131,7 @@ async function resetAllExtensions(driverConfig: DriverConfig, pluginConfig: Plug
     }
 
     const manifestPath = config.manifestPath;
-    if (!await fs.exists(manifestPath)) {
+    if (!manifestPath || !await fs.exists(manifestPath)) {
       continue;
     }
 

package/lib/cli/utils.ts

@@ -6,6 +6,39 @@ 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.
  *
@@ -62,36 +95,3 @@ export async function spinWith<T>(
     throw err;
   }
 }
-
-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();
-  }
-}

package/lib/doctor/doctor.ts

@@ -42,6 +42,14 @@ export class Doctor {
     this.foundIssues = [];
   }
 
+  private get issuesRequiredToFix(): DoctorIssue[] {
+    return this.foundIssues.filter((f) => !f.check.isOptional());
+  }
+
+  private get issuesOptionalToFix(): DoctorIssue[] {
+    return this.foundIssues.filter((f) => f.check.isOptional());
+  }
+
   /**
    * Runs diagnostics, reports issues, attempts automatic fixes where supported, and returns an exit code.
    *
@@ -62,14 +70,6 @@ export class Doctor {
     return EXIT_CODE.SUCCESS;
   }
 
-  private get issuesRequiredToFix(): DoctorIssue[] {
-    return this.foundIssues.filter((f) => !f.check.isOptional());
-  }
-
-  private get issuesOptionalToFix(): DoctorIssue[] {
-    return this.foundIssues.filter((f) => f.check.isOptional());
-  }
-
   /**
    * The doctor shows the report
    */