appium 2.0.0-beta.3 → 2.0.0-beta.30

package/types/cli.d.ts

@@ -0,0 +1,134 @@
+import { DriverOpts } from '@appium/types';
+import {
+  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';
+
+/**
+ * Possible subcommands for the `appium` CLI.
+ */
+type CliSubcommand =
+  | typeof SERVER_SUBCOMMAND
+  | typeof DRIVER_SUBCOMMAND
+  | typeof PLUGIN_SUBCOMMAND;
+
+/**
+ * Possible subcommands of {@link DRIVER_SUBCOMMAND} or
+ * {@link PLUGIN_SUBCOMMAND}.
+ */
+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.
+ */
+interface MoreArgs {
+  /**
+   * 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.
+ */
+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 that Appium assigns while parsing the args.
+ */
+interface InternalArgs {
+  /**
+   * Subcommands of `driver` subcommand
+   */
+  driverCommand?: CliExtensionSubcommand;
+
+  /**
+   * Subcommands of `plugin` subcommand
+   */
+  pluginCommand?: CliExtensionSubcommand;
+
+  /**
+   * Possible subcommands
+   */
+  subcommand: CliSubcommand;
+}
+
+/**
+ * The same as {@link ParsedArgs} but with a nullable `subcommand`.
+ * This is _not_ the same as `Partial<ParsedArgs>`.
+ */
+export type PartialArgs = DriverOpts &
+  MoreArgs &
+  ProgrammaticArgs &
+  Partial<InternalArgs>;
+
+/**
+ * The Appium configuration as a flattened object, parsed via CLI args _and_ any
+ * CLI args unsupported by the config file.
+ * @todo Does not make any assumptions about property names derived from
+ * extensions.
+ */
+export type ParsedArgs = DriverOpts &
+  MoreArgs &
+  ProgrammaticArgs &
+  InternalArgs;
+
+/**
+ * Shown by `appium --build-info`
+ */
+export type BuildInfo = {
+  version: string;
+  'git-sha'?: string;
+  built?: string;
+};

package/types/extension.d.ts

@@ -0,0 +1,56 @@
+import { BaseDriverBase } from '@appium/base-driver/lib/basedriver/driver';
+import { Class, Driver, ExternalDriver } from '@appium/types';
+import { DriverType, ExtensionType, PluginType } from '.';
+
+export type DriverClass = BaseDriverBase<ExternalDriver, 
+  ExternalDriverStatic>;
+
+/**
+ * Additional static props for external driver classes
+ */
+interface ExternalDriverStatic {
+  driverName: string;
+}
+
+/**
+ * TODO: This should be derived from the base plugin.
+ */
+export type PluginClass = Class<PluginProto, ExternalPluginStatic>;
+
+/**
+ * Static props for plugin classes
+ */
+interface ExternalPluginStatic {
+  pluginName: string;
+}
+
+/**
+ * A plugin must have this shape.
+ * @todo Use base plugin instead of this
+ */
+interface PluginProto {
+  /**
+   * I'm not sure why `plugin.name` is required, but it is.
+   */
+  name: string;
+  /**
+   * Assigned by Appium; _not_ provided by implementor.
+   */
+  cliArgs?: Record<string, any>;
+  /**
+   * Don't know what this is, but it's also required.
+   */
+  onUnexpectedShutdown?: (
+    driver: Driver,
+    cause: Error | string,
+  ) => Promise<void>;
+}
+
+/**
+ * Generic to get at the class of an extension.
+ */
+export type ExtClass<ExtType extends ExtensionType> = ExtType extends DriverType
+  ? DriverClass
+  : ExtType extends PluginType
+  ? PluginClass
+  : never;

package/types/external-manifest.d.ts

@@ -0,0 +1,58 @@
+/**
+ * These types describe information about external extensions and the contents of their `package.json` files
+ */
+
+import { SchemaObject } from 'ajv';
+import { PackageJson, SetRequired } from 'type-fest';
+import { DriverType, ExtensionType, PluginType } from './index';
+
+/**
+ * This is what is allowed in the `appium.schema` prop of an extension's `package.json`.
+ */
+export type SchemaMetadata = string | (SchemaObject & {[key: number]: never});
+
+/**
+ * Manifest data shared by all extensions, as contained in `package.json`
+ */
+export interface CommonMetadata {
+  mainClass: string;
+  scripts?: Record<string, string>;
+  schema?: SchemaMetadata;
+}
+
+/**
+ * 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) &
+    CommonMetadata;
+
+/**
+ * A `package.json` containing extension metadata.
+ * Required fields are `name`, `version`, and `appium`.
+ */
+export type ExtPackageJson<ExtType extends ExtensionType> = SetRequired<
+  PackageJson,
+  'name' | 'version'
+> & {appium: ExtMetadata<ExtType>};

package/types/index.d.ts

@@ -0,0 +1,7 @@
+export * from './appium-manifest';
+export * from './external-manifest';
+export * from './extension';
+export * from './cli';
+export type DriverType = 'driver';
+export type PluginType = 'plugin';
+export type ExtensionType = DriverType | PluginType;