appium 2.0.0-beta.30 → 2.0.0-beta.33

package/build/types/cli.d.ts

@@ -0,0 +1,112 @@
+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 declare type ServerSubcommand = typeof SERVER_SUBCOMMAND;
+export declare type DriverSubcommand = typeof DRIVER_SUBCOMMAND;
+export declare type PluginSubcommand = typeof PLUGIN_SUBCOMMAND;
+/**
+ * Possible subcommands for the `appium` CLI.
+ */
+export declare type CliSubcommand = ServerSubcommand | DriverSubcommand | PluginSubcommand;
+/**
+ * Possible subcommands of {@linkcode DriverSubcommand} or
+ * {@linkcode PluginSubcommand}.
+ */
+export declare 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
+ */
+declare 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 declare 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 declare type Args<T = WithServerSubcommand> = CommonArgs<Partial<ServerArgs>, T>;
+/**
+ * Shown by `appium --build-info`
+ */
+export declare type BuildInfo = {
+    version: string;
+    'git-sha'?: string;
+    built?: string;
+};
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/build/types/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../types/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,EACV,WAAW,IAAI,iBAAiB,EAChC,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,WAAW,IAAI,iBAAiB,EAChC,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAE1B,oBAAY,gBAAgB,GAAG,OAAO,iBAAiB,CAAC;AACxD,oBAAY,gBAAgB,GAAG,OAAO,iBAAiB,CAAC;AACxD,oBAAY,gBAAgB,GAAG,OAAO,iBAAiB,CAAC;AAExD;;GAEG;AACH,oBAAY,aAAa,GACrB,gBAAgB,GAChB,gBAAgB,GAChB,gBAAgB,CAAC;AAErB;;;GAGG;AACH,oBAAY,sBAAsB,GAC9B,OAAO,sBAAsB,GAC7B,OAAO,mBAAmB,GAC1B,OAAO,kBAAkB,GACzB,OAAO,qBAAqB,GAC5B,OAAO,wBAAwB,CAAC;AAEpC;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;IAE3B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;IAEtC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,OAAQ,SAAQ,iBAAiB;IAChD;;OAEG;IACH,aAAa,CAAC,EAAE,sBAAsB,CAAC;IAEvC;;OAEG;IACH,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,gBAAgB,GAAG,gBAAgB,CAAC;CACjD;AAED;;GAEG;AACH,aAAK,UAAU,CAAC,KAAK,EAAE,CAAC,GAAG,oBAAoB,IAAI,QAAQ,GACzD,gBAAgB,GAChB,CAAC,CAAC,SAAS,oBAAoB,GAC3B,KAAK,GACL,CAAC,SAAS,iBAAiB,GAC3B,OAAO,GACP,KAAK,CAAC,CAAC;AAEb;;GAEG;AACH,oBAAY,UAAU,CAAC,CAAC,GAAG,oBAAoB,IAAI,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;AAE7E;;GAEG;AACH,oBAAY,IAAI,CAAC,CAAC,GAAG,oBAAoB,IAAI,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;AAEhF;;GAEG;AACH,oBAAY,SAAS,GAAG;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC"}

package/build/types/extension.d.ts

@@ -0,0 +1,43 @@
+import type { BaseDriverBase } from '@appium/base-driver/lib/basedriver/driver';
+import { Class, Driver, ExternalDriver } from '@appium/types';
+import { DriverType, ExtensionType, PluginType } from '.';
+export declare type DriverClass = BaseDriverBase<ExternalDriver, ExternalDriverStatic>;
+/**
+ * Additional static props for external driver classes
+ */
+export interface ExternalDriverStatic {
+    driverName: string;
+}
+/**
+ * TODO: This should be derived from the base plugin.
+ */
+export declare type PluginClass = Class<PluginProto, ExternalPluginStatic>;
+/**
+ * Static props for plugin classes
+ */
+export interface ExternalPluginStatic {
+    pluginName: string;
+}
+/**
+ * A plugin must have this shape.
+ * @todo Use base plugin instead of this
+ */
+export 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 declare type ExtClass<ExtType extends ExtensionType> = ExtType extends DriverType ? DriverClass : ExtType extends PluginType ? PluginClass : never;
+//# sourceMappingURL=extension.d.ts.map

package/build/types/extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../types/extension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAC;AAChF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,GAAG,CAAC;AAE1D,oBAAY,WAAW,GAAG,cAAc,CAAC,cAAc,EACrD,oBAAoB,CAAC,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,oBAAY,WAAW,GAAG,KAAK,CAAC,WAAW,EAAE,oBAAoB,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B;;OAEG;IACH,oBAAoB,CAAC,EAAE,CACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,GAAG,MAAM,KAClB,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAED;;GAEG;AACH,oBAAY,QAAQ,CAAC,OAAO,SAAS,aAAa,IAAI,OAAO,SAAS,UAAU,GAC5E,WAAW,GACX,OAAO,SAAS,UAAU,GAC1B,WAAW,GACX,KAAK,CAAC"}

package/build/types/external-manifest.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 './index';
+/**
+ * This is what is allowed in the `appium.schema` prop of an extension's `package.json`.
+ */
+export declare 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 declare 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 declare type ExtPackageJson<ExtType extends ExtensionType> = SetRequired<PackageJson, 'name' | 'version'> & {
+    appium: ExtMetadata<ExtType>;
+};
+//# sourceMappingURL=external-manifest.d.ts.map

package/build/types/external-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-manifest.d.ts","sourceRoot":"","sources":["../../types/external-manifest.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,KAAK,CAAC;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEhE;;GAEG;AACH,oBAAY,cAAc,GAAG,MAAM,GAAG,CAAC,YAAY,GAAG;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAAA;CAAC,CAAC,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,oBAAY,WAAW,CAAC,OAAO,SAAS,aAAa,IACnD,CAAC,OAAO,SAAS,UAAU,GACvB,cAAc,GACd,OAAO,SAAS,UAAU,GAC1B,cAAc,GACd,KAAK,CAAC,GACR,cAAc,CAAC;AAEnB;;;GAGG;AACH,oBAAY,cAAc,CAAC,OAAO,SAAS,aAAa,IAAI,WAAW,CACrE,WAAW,EACX,MAAM,GAAG,SAAS,CACnB,GAAG;IAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;CAAC,CAAC"}

package/build/types/index.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="node" />
+export * from './appium-manifest';
+export * from './external-manifest';
+export * from './extension';
+export * from './cli';
+export declare type DriverType = 'driver';
+export declare type PluginType = 'plugin';
+export declare type ExtensionType = DriverType | PluginType;
+/**
+ * Known environment variables concerning Appium
+ */
+export interface AppiumEnv extends NodeJS.ProcessEnv {
+    APPIUM_HOME?: string;
+}
+//# sourceMappingURL=index.d.ts.map

package/build/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../types/index.ts"],"names":[],"mappings":";AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,OAAO,CAAC;AACtB,oBAAY,UAAU,GAAG,QAAQ,CAAC;AAClC,oBAAY,UAAU,GAAG,QAAQ,CAAC;AAClC,oBAAY,aAAa,GAAG,UAAU,GAAG,UAAU,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,SAAU,SAAQ,MAAM,CAAC,UAAU;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/lib/appium.js

@@ -274,10 +274,14 @@ class AppiumDriver extends DriverCore {
       // the driver so that they cannot be mimicked by a malicious user sending in capabilities
       this.assignCliArgsToExtension('driver', driverName, driverInstance);
 
-
       // This assignment is required for correct web sockets functionality inside the driver
       // Drivers/plugins might also want to know where they are hosted
-      driverInstance.assignServer(this.server, this.args.address, this.args.port, this.args.basePath);
+
+      // XXX: temporary hack to work around #16747
+      driverInstance.server = this.server;
+      driverInstance.serverHost = this.args.address;
+      driverInstance.serverPort = this.args.port;
+      driverInstance.serverPath = this.args.basePath;
 
       try {
         runningDriversData = await this.curSessionDataForDriver(InnerDriver) ?? [];
@@ -737,7 +741,7 @@ export { AppiumDriver };
  * @typedef {import('@appium/types').ExternalDriver} ExternalDriver
  * @typedef {import('@appium/types').W3CCapabilities} W3CCapabilities
  * @typedef {import('@appium/types').DriverData} DriverData
- * @typedef {import('@appium/types').DriverOpts} DriverOpts
+ * @typedef {import('@appium/types').ServerArgs} DriverOpts
  * @typedef {import('@appium/types').Constraints} Constraints
  * @typedef {import('@appium/types').AppiumServer} AppiumServer
  * @typedef {import('../types').ExtensionType} ExtensionType

package/lib/cli/parser.js

@@ -99,8 +99,9 @@ class ArgParser {
    * If no subcommand is passed in, this method will inject the `server` subcommand.
    *
    * `ArgParser.prototype.parse_args` is an alias of this method.
+   * @template [T=import('../../types').WithServerSubcommand]
    * @param {string[]} [args] - Array of arguments, ostensibly from `process.argv`. Gathers args from `process.argv` if not provided.
-   * @returns {import('../../types/cli').ParsedArgs} - The parsed arguments
+   * @returns {import('../../types').Args<T>} - The parsed arguments
    */
   parseArgs (args = process.argv.slice(2)) {
     if (!NON_SERVER_ARGS.has(args[0])) {

package/lib/config.js

@@ -160,14 +160,14 @@ async function showBuildInfo () {
 
 /**
  * Returns k/v pairs of server arguments which are _not_ the defaults.
- * @param {ParsedArgs} parsedArgs
- * @returns {Partial<ParsedArgs>}
+ * @param {Args} parsedArgs
+ * @returns {Args}
  */
 function getNonDefaultServerArgs (parsedArgs) {
   /**
    * Flattens parsed args into a single level object for comparison with
    * flattened defaults across server args and extension args.
-   * @param {ParsedArgs} args
+   * @param {Args} args
    * @returns {Record<string, { value: any, argSpec: ArgSpec }>}
    */
   const flatten = (args) => {
@@ -237,7 +237,7 @@ function getNonDefaultServerArgs (parsedArgs) {
   return _.reduce(
     _.pickBy(args, (__, key) => isNotDefault(key)),
     // explodes the flattened object back into nested one
-    (acc, {value, argSpec}) => _.set(acc, argSpec.dest, value), /** @type {Partial<ParsedArgs>} */({})
+    (acc, {value, argSpec}) => _.set(acc, argSpec.dest, value), /** @type {Args} */({})
   );
 }
 
@@ -306,7 +306,8 @@ export {
 };
 
 /**
- * @typedef {import('../types/cli').ParsedArgs} ParsedArgs
+ * @typedef {import('../types').ParsedArgs} ParsedArgs
+ * @typedef {import('../types').Args} Args
  * @typedef {import('./schema/arg-spec').ArgSpec} ArgSpec
  */
 

package/lib/extension/manifest.js

@@ -1,5 +1,3 @@
-/// <reference path="../../types/appium-manifest.d.ts" />
-
 /**
  * Module containing {@link Manifest} which handles reading & writing of extension config files.
  */

package/lib/main.js

@@ -54,13 +54,16 @@ async function preflightChecks (args, throwInsteadOfExit = false) {
 }
 
 /**
- * @param {Partial<ParsedArgs>} args
+ * @param {Args} args
  */
 function logNonDefaultArgsWarning (args) {
   logger.info('Non-default server args:');
   inspect(args);
 }
 
+/**
+ * @param {Args['defaultCapabilities']} caps
+ */
 function logDefaultCapabilitiesWarning (caps) {
   logger.info('Default capabilities, which will be added to each request ' +
               'unless overridden by desired capabilities:');
@@ -122,11 +125,20 @@ function getServerUpdaters (driverClasses, pluginClasses) {
  */
 function getExtraMethodMap (driverClasses, pluginClasses) {
   return [...driverClasses, ...pluginClasses].reduce(
-    (map, klass) => ({...map, ...klass.newMethodMap}),
+    (map, klass) => ({...map, .../** @type {DriverClass} */(klass).newMethodMap ?? {}}),
     {}
   );
 }
 
+/**
+ * @template [T=WithServerSubcommand]
+ * @param {Args<T>} args
+ * @returns {args is Args<WithServerSubcommand>}
+ */
+function areServerCommandArgs (args) {
+  return args.subcommand === SERVER_SUBCOMMAND;
+}
+
 /**
  * Initializes Appium, but does not start the server.
  *
@@ -134,7 +146,8 @@ function getExtraMethodMap (driverClasses, pluginClasses) {
  *
  * If `args` contains a non-empty `subcommand` which is not `server`, this function will return an empty object.
  *
- * @param {PartialArgs} [args] - Partial args (progammatic usage only)
+ * @template [T=WithServerSubcommand]
+ * @param {Args<T>} [args] - Partial args (progammatic usage only)
  * @returns {Promise<ServerInitResult | ExtCommandInitResult>}
  * @example
  * import {init, getSchema} from 'appium';
@@ -149,16 +162,9 @@ async function init (args) {
 
   const parser = getParser();
   let throwInsteadOfExit = false;
-  /** @type {ParsedArgs} */
-  let preConfigParsedArgs;
-  /** @type {ParsedArgs} */
-  let parsedArgs;
-  /**
-   * This is a definition (instead of declaration) because TS can't figure out
-   * the value will be defined when it's used.
-   * @type {ReturnType<getDefaultsForSchema>}
-   */
-  let defaults = {};
+  /** @type {Args<T>} */
+  let preConfigArgs;
+
   if (args) {
     // if we have a containing package instead of running as a CLI process,
     // that package might not appreciate us calling 'process.exit' willy-
@@ -168,13 +174,13 @@ async function init (args) {
       // but remove it since it's not a real server arg per se
       delete args.throwInsteadOfExit;
     }
-    preConfigParsedArgs = /** @type {ParsedArgs} */({...args, subcommand: args.subcommand ?? SERVER_SUBCOMMAND});
+    preConfigArgs = {...args, subcommand: args.subcommand ?? SERVER_SUBCOMMAND};
   } else {
     // otherwise parse from CLI
-    preConfigParsedArgs = parser.parseArgs();
+    preConfigArgs = /** @type {Args<T>} */(parser.parseArgs());
   }
 
-  const configResult = await readConfigFile(preConfigParsedArgs.configFile);
+  const configResult = await readConfigFile(preConfigArgs.configFile);
 
   if (!_.isEmpty(configResult.errors)) {
     throw new Error(`Errors in config file ${configResult.filepath}:\n ${configResult.reason ?? configResult.errors}`);
@@ -185,63 +191,65 @@ async function init (args) {
   // 1. command line args
   // 2. config file
   // 3. defaults from config file.
-  if (preConfigParsedArgs.subcommand === SERVER_SUBCOMMAND) {
-    defaults = getDefaultsForSchema(false);
+  if (!areServerCommandArgs(preConfigArgs)) {
 
-    parsedArgs = _.defaultsDeep(
-      preConfigParsedArgs,
+    // if the user has requested the 'driver' CLI, don't run the normal server,
+    // but instead pass control to the driver CLI
+    if (preConfigArgs.subcommand === DRIVER_TYPE) {
+      await runExtensionCommand(preConfigArgs, driverConfig);
+      return {};
+    }
+    if (preConfigArgs.subcommand === PLUGIN_TYPE) {
+      await runExtensionCommand(preConfigArgs, pluginConfig);
+      return {};
+    }
+    /* istanbul ignore next */
+    return {}; // should never happen
+  } else {
+    const defaults = getDefaultsForSchema(false);
+
+    /** @type {ParsedArgs} */
+    const serverArgs = _.defaultsDeep(
+      preConfigArgs,
       configResult.config?.server,
       defaults
     );
 
-    if (preConfigParsedArgs.showConfig) {
-      showConfig(getNonDefaultServerArgs(preConfigParsedArgs), configResult, defaults, parsedArgs);
+    if (preConfigArgs.showConfig) {
+      showConfig(getNonDefaultServerArgs(preConfigArgs), configResult, defaults, serverArgs);
       return {};
     }
 
-  } else {
-    parsedArgs = preConfigParsedArgs;
-  }
-
-  await logsinkInit(parsedArgs);
-
-  // if the user has requested the 'driver' CLI, don't run the normal server,
-  // but instead pass control to the driver CLI
-  if (parsedArgs.subcommand === DRIVER_TYPE) {
-    await runExtensionCommand(parsedArgs, driverConfig);
-    return {};
-  }
-  if (parsedArgs.subcommand === PLUGIN_TYPE) {
-    await runExtensionCommand(parsedArgs, pluginConfig);
-    return {};
-  }
+    await logsinkInit(serverArgs);
 
-  if (parsedArgs.logFilters) {
-    const {issues, rules} = await logFactory.loadSecureValuesPreprocessingRules(parsedArgs.logFilters);
-    if (!_.isEmpty(issues)) {
-      throw new Error(`The log filtering rules config '${parsedArgs.logFilters}' has issues: ` +
+    if (serverArgs.logFilters) {
+      const {issues, rules} = await logFactory.loadSecureValuesPreprocessingRules(serverArgs.logFilters);
+      if (!_.isEmpty(issues)) {
+        throw new Error(`The log filtering rules config '${serverArgs.logFilters}' has issues: ` +
         JSON.stringify(issues, null, 2));
+      }
+      if (_.isEmpty(rules)) {
+        logger.warn(`Found no log filtering rules in '${serverArgs.logFilters}'. Is that expected?`);
+      } else {
+        logger.info(`Loaded ${util.pluralize('filtering rule', rules.length, true)} from '${serverArgs.logFilters}'`);
+      }
     }
-    if (_.isEmpty(rules)) {
-      logger.warn(`Found no log filtering rules in '${parsedArgs.logFilters}'. Is that expected?`);
-    } else {
-      logger.info(`Loaded ${util.pluralize('filtering rule', rules.length, true)} from '${parsedArgs.logFilters}'`);
-    }
-  }
 
-  const appiumDriver = new AppiumDriver(parsedArgs);
-  // set the config on the umbrella driver so it can match drivers to caps
-  appiumDriver.driverConfig = driverConfig;
-  await preflightChecks(parsedArgs, throwInsteadOfExit);
+    const appiumDriver = new AppiumDriver(serverArgs);
+    // set the config on the umbrella driver so it can match drivers to caps
+    appiumDriver.driverConfig = driverConfig;
+    await preflightChecks(serverArgs, throwInsteadOfExit);
 
-  return /** @type {ServerInitResult} */({appiumDriver, parsedArgs, driverConfig, pluginConfig});
+    return /** @type {ServerInitResult} */({appiumDriver, parsedArgs: serverArgs, driverConfig, pluginConfig});
+  }
 }
 
 /**
  * Initializes Appium's config.  Starts server if appropriate and resolves the
  * server instance if so; otherwise resolves w/ `undefined`.
- * @param {PartialArgs} [args] - Arguments from CLI or otherwise
- * @returns {Promise<import('http').Server|undefined>}
+ * @template [T=WithServerSubcommand]
+ * @param {Args<T>} [args] - Arguments from CLI or otherwise
+ * @returns {Promise<import('@appium/types').AppiumServer|undefined>}
  */
 async function main (args) {
   const {appiumDriver, parsedArgs, pluginConfig, driverConfig} = /** @type {ServerInitResult} */(await init(args));
@@ -339,15 +347,11 @@ export { finalizeSchema, getSchema, validate } from './schema/schema';
 export { main, init, resolveAppiumHome };
 
 /**
- * @typedef {import('../types/cli').ParsedArgs} ParsedArgs
- */
-
-/**
- * @typedef {import('../types/cli').PartialArgs} PartialArgs
  * @typedef {import('../types').DriverType} DriverType
  * @typedef {import('../types').PluginType} PluginType
- * @typedef {import('../types/extension').DriverClass} DriverClass
- * @typedef {import('../types/extension').PluginClass} PluginClass
+ * @typedef {import('../types').DriverClass} DriverClass
+ * @typedef {import('../types').PluginClass} PluginClass
+ * @typedef {import('../types').WithServerSubcommand} WithServerSubcommand
  */
 
 /**
@@ -358,9 +362,20 @@ export { main, init, resolveAppiumHome };
 /**
  * @typedef ServerInitData
  * @property {AppiumDriver} appiumDriver - The Appium driver
- * @property {ParsedArgs} parsedArgs - The parsed arguments
+ * @property {import('../types').ParsedArgs} parsedArgs - The parsed arguments
  */
 
 /**
  * @typedef {ServerInitData & import('./extension').ExtensionConfigs} ServerInitResult
  */
+
+/**
+ * @template [T=WithServerSubcommand]
+ * @typedef {import('../types').Args<T>} Args
+ */
+
+/**
+ * @template [T=WithServerSubcommand]
+ * @typedef {import('../types').ParsedArgs<T>} ParsedArgs
+ */
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium",
-  "version": "2.0.0-beta.30",
+  "version": "2.0.0-beta.33",
   "description": "Automation for Apps.",
   "keywords": [
     "automation",
@@ -40,18 +40,24 @@
     "build": "babel lib --root-mode=upward --out-dir=build/lib",
     "dev": "npm run build -- --watch",
     "fix": "npm run lint -- --fix",
-    "generate-docs": "node ./scripts/parse-yml-commands.js",
+    "build:docs": "node docs/scripts/build-docs.js",
+    "build:docs:assets": "node docs/scripts/copy-assets.js",
+    "dev:docs": "npm run build:docs:assets && npm run dev:docs:en",
+    "dev:docs:en": "mkdocs serve -f ./docs/mkdocs-en.yml",
+    "dev:docs:ja": "mkdocs serve -f ./docs/mkdocs-ja.yml",
+    "publish:docs": "APPIUM_DOCS_PUBLISH=1 npm run build:docs",
     "postinstall": "node ./scripts/postinstall.js",
     "lint": "eslint -c ../../.eslintrc --ignore-path ../../.eslintignore .",
     "test": "npm run test:unit",
-    "test:e2e": "mocha --require ../../test/setup-babel.js --timeout 20s --slow 10s \"./test/e2e/**/*.spec.js\"",
-    "test:unit": "mocha --require ../../test/setup-babel.js \"./test/unit/**/*.spec.js\""
+    "test:e2e": "mocha --timeout 30s --slow 15s \"./test/e2e/**/*.spec.js\"",
+    "test:unit": "mocha \"./test/unit/**/*.spec.js\""
   },
   "dependencies": {
-    "@appium/base-driver": "^8.4.2",
-    "@appium/base-plugin": "1.8.1",
-    "@appium/schema": "^0.0.2",
-    "@appium/support": "^2.57.1",
+    "@appium/base-driver": "^8.5.2",
+    "@appium/base-plugin": "^1.8.4",
+    "@appium/docutils": "^0.0.3",
+    "@appium/schema": "^0.0.5",
+    "@appium/support": "^2.57.4",
     "@babel/runtime": "7.17.9",
     "@sidvind/better-ajv-errors": "1.1.1",
     "ajv": "8.11.0",
@@ -69,12 +75,12 @@
     "ora": "5.4.1",
     "package-changed": "1.9.0",
     "resolve-from": "5.0.0",
-    "semver": "7.3.6",
+    "semver": "7.3.7",
     "source-map-support": "0.5.21",
     "teen_process": "1.16.0",
     "winston": "3.7.2",
     "word-wrap": "1.2.3",
-    "yaml": "1.10.2"
+    "yaml": "2.0.1"
   },
   "engines": {
     "node": ">=12",
@@ -84,6 +90,6 @@
     "access": "public",
     "tag": "next"
   },
-  "types": "./build/lib/index.d.ts",
-  "gitHead": "319f7289e7019efaeac1271936b2d991041a02c2"
+  "types": "./build/lib/main.d.ts",
+  "gitHead": "f15f11bc14d777185ed908a7840657b089cb1049"
 }

package/types/{appium-manifest.d.ts → appium-manifest.ts}

@@ -28,7 +28,7 @@ export type ExtManifest<ExtType extends ExtensionType> = Omit<
   InternalMetadata &
   CommonMetadata; // XXX: ExtMetadata should be a union with CommonMetadata. why is this needed?
 
-type WithSchemaManifest = {
+export type WithSchemaManifest = {
   schema: SchemaMetadata;
 };