@appium/types 0.10.0 → 0.10.2

package/lib/driver.ts

@@ -1,22 +1,21 @@
 import type {EventEmitter} from 'events';
-import {Element, ActionSequence} from './action';
-import {
-  HTTPMethod,
-  AppiumServer,
-  UpdateServerCallback,
-  Class,
-  MethodMap,
-  AppiumLogger,
-  StringRecord,
-  ConstraintsToCaps,
-  BaseDriverCapConstraints,
-  W3CCapabilities,
-  Capabilities,
-  ExecuteMethodMap,
-} from '.';
+import {Entries} from 'type-fest';
+import {ActionSequence, Element} from './action';
+import {Capabilities, DriverCaps, W3CCapabilities, W3CDriverCaps} from './capabilities';
+import {ExecuteMethodMap, MethodMap} from './command';
 import {ServerArgs} from './config';
-import {AsyncReturnType, Entries} from 'type-fest';
+import {HTTPHeaders, HTTPMethod} from './http';
+import {AppiumLogger} from './logger';
+import {AppiumServer, UpdateServerCallback} from './server';
+import {Class, StringRecord} from './util';
 
+/**
+ * Interface implemented by the `DeviceSettings` class in `@appium/base-driver`
+ */
+export interface IDeviceSettings<T extends StringRecord> {
+  update(newSettings: T): Promise<void>;
+  getSettings(): T;
+}
 export interface ITimeoutCommands {
   /**
    * Set the various timeouts associated with a session
@@ -49,6 +48,7 @@ export interface ITimeoutCommands {
    * @param ms - the timeout in ms
    *
    * @deprecated Use `timeouts` instead
+   *
    */
   implicitWait(ms: number | string): Promise<void>;
 
@@ -66,7 +66,7 @@ export interface ITimeoutCommands {
    *
    * @returns The return value of the condition
    */
-  implicitWaitForCondition(condition: () => Promise<any>): Promise<unknown>;
+  implicitWaitForCondition(condition: (...args: any[]) => Promise<any>): Promise<unknown>;
 
   /**
    * Get the current timeouts
@@ -170,7 +170,7 @@ export interface ISessionCommands {
    *
    * @returns A session data object
    */
-  getSession(): Promise<SingularSessionData>;
+  getSession<C extends Constraints>(): Promise<SingularSessionData<C>>;
 }
 
 export interface IExecuteCommands {
@@ -183,23 +183,26 @@ export interface IExecuteCommands {
    *
    * @returns The result of calling the Execute Method
    */
-  executeMethod<TReturn = any>(script: string, args: [StringRecord] | any[]): Promise<TReturn>;
+  executeMethod<
+    TArgs extends readonly any[] | readonly [StringRecord<unknown>] = unknown[],
+    TReturn = unknown
+  >(
+    script: string,
+    args: TArgs
+  ): Promise<TReturn>;
 }
 
-export interface MultiSessionData<
-  C extends Constraints = BaseDriverCapConstraints,
-  Extra extends StringRecord | void = void
-> {
+export interface MultiSessionData<C extends Constraints = Constraints> {
   id: string;
-  capabilities: Capabilities<C, Extra>;
+  capabilities: DriverCaps<C>;
 }
 
-export type SingularSessionData<
-  C extends Constraints = BaseDriverCapConstraints,
-  Extra extends StringRecord | void = void
-> = Capabilities<C, Extra> & {events?: EventHistory; error?: string};
+export type SingularSessionData<C extends Constraints = Constraints> = DriverCaps<C> & {
+  events?: EventHistory;
+  error?: string;
+};
 
-export interface IFindCommands<Ctx = any> {
+export interface IFindCommands {
   /**
    * Find a UI element given a locator strategy and a selector, erroring if it can't be found
    * @see {@link https://w3c.github.io/webdriver/#find-element}
@@ -294,7 +297,7 @@ export interface IFindCommands<Ctx = any> {
    *
    * @returns A single element or list of elements
    */
-  findElOrEls<Mult extends boolean>(
+  findElOrEls<Mult extends boolean, Ctx = any>(
     strategy: string,
     selector: string,
     mult: Mult,
@@ -312,7 +315,7 @@ export interface IFindCommands<Ctx = any> {
    *
    * @returns A single element or list of elements
    */
-  findElOrElsWithProcessing<Mult extends boolean>(
+  findElOrElsWithProcessing<Mult extends boolean, Ctx = any>(
     strategy: string,
     selector: string,
     mult: Mult,
@@ -328,41 +331,35 @@ export interface IFindCommands<Ctx = any> {
   getPageSource(): Promise<string>;
 }
 
-export interface ILogCommands<C extends Constraints> {
+export interface ILogCommands {
   /**
    * Definition of the available log types
    */
-  supportedLogTypes: Readonly<LogDefRecord<C>>;
+  supportedLogTypes: Readonly<LogDefRecord>;
 
   /**
    * Get available log types as a list of strings
    */
-  getLogTypes(): Promise<(keyof ILogCommands<C>['supportedLogTypes'])[]>;
+  getLogTypes(): Promise<string[]>;
 
   /**
    * Get the log for a given log type.
    *
    * @param logType - Name/key of log type as defined in {@linkcode ILogCommands.supportedLogTypes}.
    */
-  getLog(
-    logType: keyof ILogCommands<C>['supportedLogTypes']
-  ): Promise<
-    AsyncReturnType<
-      ILogCommands<C>['supportedLogTypes'][keyof ILogCommands<C>['supportedLogTypes']]['getter']
-    >
-  >;
+  getLog(logType: string): Promise<unknown[]>;
 }
 
 /**
  * A record of {@linkcode LogDef} objects, keyed by the log type name.
  * Used in {@linkcode ILogCommands.supportedLogTypes}
  */
-export type LogDefRecord<C extends Constraints> = Record<string, LogDef<C>>;
+export type LogDefRecord = Record<string, LogDef>;
 
 /**
  * A definition of a log type
  */
-export interface LogDef<C extends Constraints, T = unknown> {
+export interface LogDef {
   /**
    * Description of the log type.
    *
@@ -375,10 +372,10 @@ export interface LogDef<C extends Constraints, T = unknown> {
    *
    * This implementation *should* drain, truncate or otherwise reset the log buffer.
    */
-  getter: (driver: Driver<C>) => Promise<T[]>;
+  getter: (driver: any) => Promise<unknown[]> | unknown[];
 }
 
-export interface ISettingsCommands {
+export interface ISettingsCommands<T extends StringRecord = StringRecord> {
   /**
    * Update the session's settings dictionary with a new settings object
    *
@@ -392,14 +389,29 @@ export interface ISettingsCommands {
    *
    * @returns The settings object
    */
-  getSettings(): Promise<StringRecord>;
+  getSettings(): Promise<T>;
 }
 
-export interface SessionHandler<
-  CreateResult,
-  DeleteResult,
-  C extends Constraints = BaseDriverCapConstraints,
-  Extra extends StringRecord | void = void
+/**
+ * @see {@linkcode ISessionHandler}
+ */
+export type DefaultCreateSessionResult<C extends Constraints> = [
+  sessionId: string,
+  capabilities: DriverCaps<C>
+];
+
+/**
+ * @see {@linkcode ISessionHandler}
+ */
+export type DefaultDeleteSessionResult = void;
+
+/**
+ * An interface which creates and deletes sessions.
+ */
+export interface ISessionHandler<
+  C extends Constraints = Constraints,
+  CreateResult = DefaultCreateSessionResult<C>,
+  DeleteResult = DefaultDeleteSessionResult
 > {
   /**
    * Start a new automation session
@@ -419,9 +431,9 @@ export interface SessionHandler<
    * @returns The capabilities object representing the created session
    */
   createSession(
-    w3cCaps1: W3CCapabilities<C, Extra>,
-    w3cCaps2?: W3CCapabilities<C, Extra>,
-    w3cCaps3?: W3CCapabilities<C, Extra>,
+    w3cCaps1: W3CDriverCaps<C>,
+    w3cCaps2?: W3CDriverCaps<C>,
+    w3cCaps3?: W3CDriverCaps<C>,
     driverData?: DriverData[]
   ): Promise<CreateResult>;
 
@@ -440,19 +452,6 @@ export interface SessionHandler<
  */
 export type DriverData = Record<string, unknown>;
 
-/**
- * Extensions can define new methods for the Appium server to map to command names, of the same
- * format as used in Appium's `routes.js`.
- *
- *
- * @example
- * {
- *   '/session/:sessionId/new_method': {
- *     GET: {command: 'getNewThing'},
- *     POST: {command: 'setNewThing', payloadParams: {required: ['someParam']}}
- *   }
- * }
- */
 export interface Constraint {
   readonly presence?: boolean | Readonly<{allowEmpty: boolean}>;
   readonly isString?: boolean;
@@ -461,17 +460,26 @@ export interface Constraint {
   readonly isObject?: boolean;
   readonly isArray?: boolean;
   readonly deprecated?: boolean;
-  readonly inclusion?: Readonly<[any, ...any[]]>;
-  readonly inclusionCaseInsensitive?: Readonly<[any, ...any[]]>;
+  readonly inclusion?: Readonly<[string, ...string[]]>;
+  readonly inclusionCaseInsensitive?: Readonly<[string, ...string[]]>;
+}
+
+/**
+ * A collection of constraints describing the allowed capabilities for a driver.
+ */
+export interface Constraints {
+  [name: string]: Constraint;
 }
-export type Constraints = Readonly<Record<string, Constraint>>;
 
-export interface DriverHelpers<C extends Constraints> {
-  configureApp: (app: string, supportedAppExtensions: string[]) => Promise<string>;
+export interface DriverHelpers {
+  configureApp: (
+    app: string,
+    supportedAppExtensions?: string | string[] | ConfigureAppOptions
+  ) => Promise<string>;
   isPackageOrBundle: (app: string) => boolean;
   duplicateKeys: <T>(input: T, firstKey: string, secondKey: string) => T;
   parseCapsArray: (cap: string | string[]) => string[];
-  generateDriverLogPrefix: (obj: Core<C>, sessionId?: string) => string;
+  generateDriverLogPrefix: <C extends Constraints>(obj: Core<C>, sessionId?: string) => string;
 }
 
 export type SettingsUpdateListener<T extends Record<string, unknown> = Record<string, unknown>> = (
@@ -480,11 +488,6 @@ export type SettingsUpdateListener<T extends Record<string, unknown> = Record<st
   curValue: unknown
 ) => Promise<void>;
 
-export interface DeviceSettings<T = any> {
-  update(newSettings: Record<string, T>): Promise<void>;
-  getSettings(): Record<string, T>;
-}
-
 // WebDriver
 
 export interface Rect {
@@ -588,13 +591,13 @@ export interface EventHistoryCommand {
  *
  * This should not be used directly by external code.
  */
-export interface Core<C extends Constraints = BaseDriverCapConstraints> {
+export interface Core<C extends Constraints, Settings extends StringRecord = StringRecord> {
   shouldValidateCaps: boolean;
   sessionId: string | null;
   opts: DriverOpts<C>;
-  initialOpts: ServerArgs;
+  initialOpts: Partial<DriverOpts<C>>;
   protocol?: string;
-  helpers: DriverHelpers<C>;
+  helpers: DriverHelpers;
   basePath: string;
   relaxedSecurityEnabled: boolean;
   allowInsecure: string[];
@@ -604,9 +607,9 @@ export interface Core<C extends Constraints = BaseDriverCapConstraints> {
   locatorStrategies: string[];
   webLocatorStrategies: string[];
   eventEmitter: EventEmitter;
-  settings: DeviceSettings;
+  settings: IDeviceSettings<Settings>;
   log: AppiumLogger;
-  driverData?: DriverData;
+  driverData: DriverData;
   isCommandsQueueEnabled: boolean;
   eventHistory: EventHistory;
   onUnexpectedShutdown(handler: () => any): void;
@@ -642,7 +645,7 @@ export interface Core<C extends Constraints = BaseDriverCapConstraints> {
    * ```
    */
   getStatus(): Promise<any>;
-  sessionExists(sessionId: string): boolean;
+  sessionExists(sessionId?: string): boolean;
   isW3CProtocol(): boolean;
   isMjsonwpProtocol(): boolean;
   isFeatureEnabled(name: string): boolean;
@@ -653,7 +656,7 @@ export interface Core<C extends Constraints = BaseDriverCapConstraints> {
   canProxy(sessionId?: string): boolean;
   proxyRouteIsAvoided(sessionId: string, method: string, url: string): boolean;
   addManagedDriver(driver: Driver): void;
-  getManagedDrivers(): Driver[];
+  getManagedDrivers(): Driver<Constraints>[];
   clearNewCommandTimeout(): Promise<void>;
   logEvent(eventName: string): void;
   driverForSession(sessionId: string): Core<C> | null;
@@ -665,25 +668,32 @@ export interface Core<C extends Constraints = BaseDriverCapConstraints> {
  *
  * `C` should be the constraints of the driver.
  * `CArgs` would be the shape of `cliArgs`.
- * `Ctx` would be the type of the element context (e.g., string, dictionary of some sort, etc.)
+ * `Settings` is the shape of the raw device settings object (see {@linkcode IDeviceSettings})
  */
 export interface Driver<
-  C extends Constraints = BaseDriverCapConstraints,
+  C extends Constraints = Constraints,
   CArgs extends StringRecord = StringRecord,
-  Ctx = any
+  Settings extends StringRecord = StringRecord,
+  CreateResult = DefaultCreateSessionResult<C>,
+  DeleteResult = DefaultDeleteSessionResult
 > extends ISessionCommands,
-    ILogCommands<C>,
-    IFindCommands<Ctx>,
-    ISettingsCommands,
+    ILogCommands,
+    IFindCommands,
+    ISettingsCommands<Settings>,
     ITimeoutCommands,
     IEventCommands,
     IExecuteCommands,
-    SessionHandler<[sessionId: string, caps: any], void, C>,
-    Core {
+    ISessionHandler<C, CreateResult, DeleteResult>,
+    Core<C, Settings> {
   /**
    * The set of command line arguments set for this driver
    */
   cliArgs: CArgs;
+  // The following properties are assigned by appium */
+  server?: AppiumServer;
+  serverHost?: string;
+  serverPort?: number;
+  serverPath?: string;
 
   // The following methods are implemented by `BaseDriver`.
 
@@ -715,6 +725,7 @@ export interface Driver<
    * Reset the current session (run the delete session and create session subroutines)
    *
    * @deprecated Use explicit session management commands instead
+   * @privateRemarks This is implemented by `BaseDriver` and is used within `@appium/driver-test-support`
    */
   reset(): Promise<void>;
 
@@ -742,7 +753,7 @@ export interface Driver<
    *
    * @returns Whether or not the capabilities are valid
    */
-  validateDesiredCaps(caps: Capabilities<C>): boolean;
+  validateDesiredCaps(caps: DriverCaps<C>): boolean;
 
   /**
    * A helper function to log unrecognized capabilities to the console
@@ -751,7 +762,7 @@ export interface Driver<
    *
    * @internal
    */
-  logExtraCaps(caps: Capabilities<C>): void;
+  logExtraCaps(caps: DriverCaps<C>): void;
 
   /**
    * A helper function used to assign server information to the driver instance so the driver knows
@@ -769,14 +780,7 @@ export interface Driver<
  * External drivers must subclass `BaseDriver`, and can implement any of these methods.
  * None of these are implemented within Appium itself.
  */
-export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints>
-  extends Driver<C> {
-  // The following properties are assigned by appium */
-  server?: AppiumServer;
-  serverHost?: string;
-  serverPort?: number;
-  serverPath?: string;
-
+export interface ExternalDriver<C extends Constraints = Constraints> extends Driver<C> {
   // WebDriver spec commands
 
   /**
@@ -1217,13 +1221,6 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
 
   // Appium W3C WebDriver Extension
 
-  /**
-   * Shake the device
-   *
-   * @deprecated
-   */
-  mobileShake?(): Promise<void>;
-
   /**
    * Get the current time on the device under timeouts
    *
@@ -1233,52 +1230,6 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    */
   getDeviceTime?(format?: string): Promise<string>;
 
-  /**
-   * Lock the device, and optionally unlock the device after a certain amount of time
-   *
-   * @param seconds - the number of seconds after which to unlock the device. Set to zero or leave
-   * empty to not unlock the device automatically
-   *
-   * @deprecated
-   */
-  lock?(seconds?: number): Promise<void>;
-
-  /**
-   * Unlock the device
-   *
-   * @deprecated
-   */
-  unlock?(): Promise<void>;
-
-  /**
-   * Determine whether the device is locked
-   *
-   * @returns True if the device is locked, false otherwise
-   *
-   * @deprecated
-   */
-  isLocked?(): Promise<boolean>;
-
-  /**
-   * Direct Appium to start recording the device screen
-   *
-   * @param options - parameters for screen recording
-   *
-   * @deprecated
-   */
-  startRecordingScreen?(options?: StartScreenRecordOptions): Promise<void>;
-
-  /**
-   * Direct Appium to stop screen recording and return the video
-   *
-   * @param options - parameters for stopping like video Uploading
-   *
-   * @returns The base64-encoded video data
-   *
-   * @deprecated
-   */
-  stopRecordingScreen?(options?: StopScreenRecordOptions): Promise<string>;
-
   /**
    * List the performance data types supported by this driver, which can be used in a call to get
    * the performance data by type.
@@ -1286,6 +1237,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @returns The list of types
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   getPerformanceDataTypes?(): Promise<string[]>;
 
@@ -1300,6 +1252,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @returns A list of performance data strings
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   getPerformanceData?(
     packageName: string,
@@ -1315,6 +1268,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param flags - the code denoting the combination of extra flags
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   pressKeyCode?(keycode: number, metastate?: number, flags?: number): Promise<void>;
 
@@ -1326,6 +1280,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param flags - the code denoting the combination of extra flags
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   longPressKeyCode?(keycode: number, metastate?: number, flags?: number): Promise<void>;
 
@@ -1335,6 +1290,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param fingerprintId - the numeric ID of the fingerprint to use
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   fingerprint?(fingerprintId: number): Promise<void>;
 
@@ -1345,6 +1301,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param message - the SMS text
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   sendSMS?(phoneNumber: string, message: string): Promise<void>;
 
@@ -1356,6 +1313,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param action - the action to take in response (accept, reject, etc...)
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   gsmCall?(phoneNumber: string, action: string): Promise<void>;
 
@@ -1365,6 +1323,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param singalStrength - the strength in a driver-appropriate string
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   gsmSignal?(signalStrength: string): Promise<void>;
 
@@ -1374,6 +1333,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param state - the state
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   gsmVoice?(state: string): Promise<void>;
 
@@ -1383,6 +1343,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param percent - how full the battery should become
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   powerCapacity?(percent: number): Promise<void>;
 
@@ -1392,6 +1353,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param state - whether the device is connected to power or not
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   powerAC?(state: string): Promise<void>;
 
@@ -1401,6 +1363,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param netspeed - the speed as a string, like '3G'
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   networkSpeed?(netspeed: string): Promise<void>;
 
@@ -1411,6 +1374,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param metastate - the combination of meta startUnexpectedShutdown
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   keyevent?(keycode: string, metastate?: string): Promise<void>;
 
@@ -1425,6 +1389,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param elementId - if we're rotating around an element
    *
    * @deprecated Use setRotation instead
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   mobileRotation?(
     x: number,
@@ -1442,6 +1407,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @returns The activity name
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   getCurrentActivity?(): Promise<string>;
 
@@ -1451,6 +1417,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @returns The package name
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   getCurrentPackage?(): Promise<string>;
 
@@ -1498,10 +1465,11 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    *
    * @param appId - the package or bundle ID of the application
    *
-   * @returns A number representing the state. 0 means not installed, 1 means not running, 3 means
-   * running in the background, and 4 means running in the foreground
+   * @returns A number representing the state. `0` means not installed, `1` means not running, `2`
+   * means running in background but suspended, `3` means running in the background, and `4` means
+   * running in the foreground
    */
-  queryAppState?(appId: string): Promise<0 | 1 | 3 | 4>;
+  queryAppState?(appId: string): Promise<0 | 1 | 2 | 3 | 4>;
 
   /**
    * Attempt to hide a virtual keyboard
@@ -1550,6 +1518,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * Toggle airplane/flight mode for the device
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   toggleFlightMode?(): Promise<void>;
 
@@ -1557,6 +1526,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * Toggle cell network data
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   toggleData?(): Promise<void>;
 
@@ -1564,6 +1534,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * Toggle WiFi radio status
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   toggleWiFi?(): Promise<void>;
 
@@ -1571,6 +1542,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * Toggle location services for the device
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   toggleLocationServices?(): Promise<void>;
 
@@ -1578,6 +1550,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * Open the notifications shade/screen
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   openNotifications?(): Promise<void>;
 
@@ -1597,6 +1570,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * activity
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   startActivity?(
     appPackage: string,
@@ -1616,6 +1590,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @returns An array of information objects of driver-specific shape
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   getSystemBars?(): Promise<unknown[]>;
 
@@ -1625,50 +1600,10 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @returns The density
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   getDisplayDensity?(): Promise<number>;
 
-  /**
-   * Trigger a touch/fingerprint match or match failure
-   *
-   * @param match - whether the match should be a success or failure
-   *
-   * @deprecated
-   */
-  touchId?(match: boolean): Promise<void>;
-
-  /**
-   * Toggle whether the device is enrolled in the touch ID program
-   *
-   * @param enabled - whether to enable or disable the touch ID program
-   *
-   * @deprecated
-   */
-  toggleEnrollTouchId?(enabled: boolean): Promise<void>;
-
-  /**
-   * Start the session after it has been started.
-   *
-   * @deprecated Don't use this, it never made sense.
-   */
-  launchApp?(): Promise<void>;
-
-  /**
-   * Stop the session without stopping the session
-   *
-   * @deprecated Don't use this, it never made sense.
-   */
-  closeApp?(): Promise<void>;
-
-  /**
-   * Background (close) the app either permanently or for a certain amount of time
-   *
-   * @param seconds - the number of seconds to background the app for, or `null` for permanently
-   *
-   * @deprecated
-   */
-  background?(seconds: null | number): Promise<void>;
-
   /**
    * End platform-specific code coverage tracing
    *
@@ -1676,31 +1611,10 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param path - the path to place the results
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   endCoverage?(intent: string, path: string): Promise<void>;
 
-  /**
-   * Return the language-specific strings for an app
-   *
-   * @param language - the language to retrieve strings for
-   * @param stringFile - the path to the localized strings file if not in the default location
-   *
-   * @returns A record of localized keys to localized text
-   *
-   * @deprecated
-   */
-  getStrings?(language?: string, stringFile?: string): Promise<Record<string, unknown>>;
-
-  /**
-   * Set the value, but like, now? Don't use this.
-   *
-   * @param value - the value to set
-   * @param elementId - the element to set the value of
-   *
-   * @deprecated
-   */
-  setValueImmediate?(value: string, elementId: string): Promise<void>;
-
   /**
    * Set the value of a text field but ensure the current value is replace and not appended
    *
@@ -1708,93 +1622,11 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param elementId - the element to set it in
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   replaceValue?(value: string, elementId: string): Promise<void>;
 
-  /**
-   * Collect the response of an async script execution? It's unclear what this is for. Don't use
-   * it.
-   *
-   * @param response - idk
-   *
-   * @deprecated
-   */
-  receiveAsyncResponse?(response: unknown): Promise<void>;
-
-  /**
-   * Set the contents of the device clipboard
-   *
-   * @param content - the text to set
-   * @param contentType - the media type if not text
-   * @param label - the label if not text
-   *
-   * @deprecated
-   */
-  setClipboard?(content: string, contentType?: string, label?: string): Promise<void>;
-
-  /**
-   * Get the contents of the device clipboard, converted into an appropriate media type
-   *
-   * @param contentType - the media type if not text
-   *
-   * @returns The text or media content (base64-encoded) of the clipboard
-   *
-   * @deprecated
-   */
-  getClipboard?(contentType?: string): Promise<string>;
-
   // JSONWP
-  /**
-   * Set the async execute script timeout
-   *
-   * @param ms - the timeout
-   *
-   * @deprecated Use the W3C timeouts command instead
-   */
-  asyncScriptTimeout?(ms: number): Promise<void>;
-
-  /**
-   * Get the window size
-   *
-   * @returns The size (width and height)
-   *
-   * @deprecated Use getWindowRect instead
-   */
-  getWindowSize?(): Promise<Size>;
-
-  /**
-   * Get the position of an element on screen
-   *
-   * @param elementId - the element ID
-   *
-   * @returns The position of the element
-   *
-   * @deprecated Use getElementRect instead
-   */
-  getLocation?(elementId: string): Promise<Position>;
-
-  /**
-   * Get the position of an element on screen within a certain other view
-   *
-   * @param elementId - the element ID
-   *
-   * @returns The position of the element
-   *
-   * @deprecated Use getElementRect instead
-   */
-  getLocationInView?(elementId: string): Promise<Position>;
-
-  /**
-   * Get the size of an element
-   *
-   * @param elementId - the element ID
-   *
-   * @returns The size of the element
-   *
-   * @deprecated Use getElementRect instead
-   */
-  getSize?(elementId: string): Promise<Size>;
-
   /**
    * Check whether two elements are identical
    *
@@ -1804,33 +1636,16 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @returns True if the elements are equal, false otherwise
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   equalsElement?(elementId: string, otherElementId: string): Promise<boolean>;
-
-  /**
-   * Submit the form an element is in
-   *
-   * @param elementId - the element ID
-   *
-   * @deprecated
-   */
-  submit?(elementId: string): Promise<void>;
-
-  /**
-   * Send keys to the app
-   *
-   * @param value: the array of keys to send
-   *
-   * @deprecated Use the W3C send keys method instead
-   */
-  keys?(value: string[]): Promise<void>;
-
   /**
    * Get the list of IME engines
    *
    * @returns The list of IME engines
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   availableIMEEngines?(): Promise<string[]>;
 
@@ -1840,6 +1655,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @returns The name of the active engine
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   getActiveIMEEngine?(): Promise<string>;
 
@@ -1849,6 +1665,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @returns True if the IME is activated
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   isIMEActivated?(): Promise<boolean>;
 
@@ -1856,6 +1673,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * Deactivate an IME engine
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   deactivateIMEEngine?(): Promise<void>;
 
@@ -1865,6 +1683,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param engine - the name of the engine
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   activateIMEEngine?(engine: string): Promise<void>;
 
@@ -1882,23 +1701,13 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    */
   setOrientation?(orientation: string): Promise<void>;
 
-  /**
-   * Move the mouse pointer to a particular screen location
-   *
-   * @param element - the element ID if the move is relative to an element
-   * @param xOffset - the x offset
-   * @param yOffset - the y offset
-   *
-   * @deprecated Use the Actions API instead
-   */
-  moveTo?(element?: null | string, xOffset?: number, yOffset?: number): Promise<void>;
-
   /**
    * Trigger a mouse button down
    *
    * @param button - the button ID
    *
    * @deprecated Use the Actions API instead
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   buttonDown?(button?: number): Promise<void>;
 
@@ -1908,6 +1717,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param button - the button ID
    *
    * @deprecated Use the Actions API instead
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   buttonUp?(button?: number): Promise<void>;
 
@@ -1917,6 +1727,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param button - the button ID
    *
    * @deprecated Use the Actions API instead
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   clickCurrent?(button?: number): Promise<void>;
 
@@ -1924,6 +1735,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * Double-click the current mouse location
    *
    * @deprecated Use the Actions API instead
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   doubleClick?(): Promise<void>;
 
@@ -1934,6 +1746,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param y - the y coordinate
    *
    * @deprecated Use the Actions API instead
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   touchDown?(x: number, y: number): Promise<void>;
 
@@ -1944,6 +1757,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param y - the y coordinate
    *
    * @deprecated Use the Actions API instead
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   touchUp?(x: number, y: number): Promise<void>;
 
@@ -1954,6 +1768,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param y - the y coordinate
    *
    * @deprecated Use the Actions API instead
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   touchMove?(x: number, y: number): Promise<void>;
 
@@ -1963,6 +1778,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param elementId - the id of the element to long touch
    *
    * @deprecated Use the Actions API instead
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   touchLongClick?(elementId: string): Promise<void>;
 
@@ -1977,6 +1793,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @param speed - the speed (unclear how this relates to xSpeed and ySpeed)
    *
    * @deprecated Use the Actions API instead
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   flick?(
     element?: string,
@@ -2017,7 +1834,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    *
    * @param name - the context name
    */
-  setContext?(name: string): Promise<void>;
+  setContext?(name: string, ...args: any[]): Promise<void>;
 
   /**
    * Get the list of available contexts
@@ -2035,6 +1852,7 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    * @returns The page index
    *
    * @deprecated
+   * @privateRemarks Not implemented in `appium-xcuitest-driver`
    */
   getPageIndex?(elementId: string): Promise<string>;
 
@@ -2055,25 +1873,6 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
    */
   setNetworkConnection?(type: number): Promise<void>;
 
-  /**
-   * Perform a set of touch actions
-   *
-   * @param actions - the old MJSONWP style touch action objects
-   *
-   * @deprecated Use the W3C Actions API instead
-   */
-  performTouch?(actions: unknown): Promise<void>;
-
-  /**
-   * Perform a set of touch actions
-   *
-   * @param actions - the old MJSONWP style touch action objects
-   * @param elementId - the id of an element if actions are restricted to one element
-   *
-   * @deprecated Use the W3C Actions API instead
-   */
-  performMultiAction?(actions: unknown, elementId: string): Promise<void>;
-
   /**
    * Get the current rotation state of the device
    * @see {@link https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#device-rotation}
@@ -2207,11 +2006,11 @@ export interface ExternalDriver<C extends Constraints = BaseDriverCapConstraints
  *
  * This is likely unusable by external consumers, but YMMV!
  */
-export interface DriverStatic<D extends Driver> {
+export interface DriverStatic<T extends Driver> {
   baseVersion: string;
   updateServer?: UpdateServerCallback;
-  newMethodMap?: MethodMap<D>;
-  executeMethodMap?: ExecuteMethodMap<D>;
+  newMethodMap?: MethodMap<T>;
+  executeMethodMap?: ExecuteMethodMap<T>;
 }
 
 /**
@@ -2219,9 +2018,9 @@ export interface DriverStatic<D extends Driver> {
  *
  * This is likely unusable by external consumers, but YMMV!
  */
-export type DriverClass<D extends Driver = ExternalDriver> = Class<
-  D,
-  DriverStatic<D>,
+export type DriverClass<T extends Driver = Driver> = Class<
+  T,
+  DriverStatic<T>,
   [] | [Partial<ServerArgs>] | [Partial<ServerArgs>, boolean]
 >;
 
@@ -2234,18 +2033,109 @@ export interface ExtraDriverOpts {
  *
  * The combination happens within Appium prior to calling the constructor.
  */
-export type DriverOpts<C extends Constraints = BaseDriverCapConstraints> = ServerArgs &
-  ExtraDriverOpts &
-  Partial<ConstraintsToCaps<C>>;
+export type DriverOpts<C extends Constraints> = ServerArgs & ExtraDriverOpts & DriverCaps<C>;
 
-export type DriverCommand<TArgs = any, TReturn = unknown> = (...args: TArgs[]) => Promise<TReturn>;
-
-export type DriverCommands<TArgs = any, TReturn = unknown> = Record<
-  string,
-  DriverCommand<TArgs, TReturn>
->;
+/**
+ * An instance method of a driver class, whose name may be referenced by {@linkcode MethodDef.command}, and serves as an Appium command.
+ *
+ * Note that this signature differs from a `PluginCommand`.
+ */
+export type DriverCommand<TArgs extends readonly any[] = any[], TRetval = unknown> = (
+  ...args: TArgs
+) => Promise<TRetval>;
 
 /**
  * Tuple of an HTTP method with a regex matching a request path
  */
 export type RouteMatcher = [HTTPMethod, RegExp];
+
+/**
+ * Result of the {@linkcode onPostProcess ConfigureAppOptions.onPostProcess} callback.
+ */
+export interface PostProcessResult {
+  /**
+   * The full past to the post-processed application package on the local file system .
+   *
+   * This might be a file or a folder path.
+   */
+  appPath: string;
+}
+
+/**
+ * Information about a cached app instance.
+ */
+export interface CachedAppInfo {
+  /**
+   * SHA1 hash of the package if it is a file (and not a folder)
+   */
+  packageHash: string;
+  /**
+   * Date instance; the value of the file's `Last-Modified` header
+   */
+  lastModified?: Date;
+  /**
+   * `true` if the file contains an `immutable` mark in `Cache-control` header
+   */
+  immutable?: boolean;
+  /**
+   * Integer representation of `maxAge` parameter in `Cache-control` header
+   */
+  maxAge?: number;
+  /**
+   * The timestamp this item has been added to the cache (measured in Unix epoch milliseconds)
+   */
+  timestamp?: number;
+  /**
+   * An object containing either `file` property with SHA1 hash of the file or `folder` property
+   * with total amount of cached files and subfolders
+   */
+  integrity?: {file?: string} | {folder?: number};
+  /**
+   * The full path to the cached app
+   */
+  fullPath?: string;
+}
+
+/**
+ * Options for the post-processing step
+ *
+ * The generic can be supplied if using `axios`, where `headers` is a fancy object.
+ */
+export interface PostProcessOptions<Headers = HTTPHeaders> {
+  /**
+   * The information about the previously cached app instance (if exists)
+   */
+  cachedAppInfo?: CachedAppInfo;
+  /**
+   * Whether the app has been downloaded from a remote URL
+   */
+  isUrl?: boolean;
+  /**
+   * Optional headers object.
+   *
+   * Only present if `isUrl` is `true` and if the server responds to `HEAD` requests. All header names are normalized to lowercase.
+   */
+  headers?: Headers;
+  /**
+   * A string containing full path to the preprocessed application package (either downloaded or a local one)
+   */
+  appPath?: string;
+}
+
+export interface ConfigureAppOptions {
+  /**
+   *
+   * Optional function, which should be applied to the application after it is
+   * downloaded/preprocessed.
+   *
+   * This function may be async and is expected to accept single object parameter. The function is
+   * expected to either return a falsy value, which means the app must not be cached and a fresh
+   * copy of it is downloaded each time, _or_ if this function returns an object containing an
+   * `appPath` property, then the integrity of it will be verified and stored into the cache.
+   * @returns
+   */
+  onPostProcess?: (
+    obj: PostProcessOptions
+  ) => Promise<PostProcessResult | undefined> | PostProcessResult | undefined;
+  supportedExtensions: string[];
+}