@appium/types 1.0.0 → 1.1.0

package/lib/commands/basedriver.ts

@@ -0,0 +1,476 @@
+import type {DriverCaps, W3CDriverCaps} from '../capabilities';
+import type {Constraints} from '../constraints';
+import type {Element, StringRecord} from '../util';
+
+export interface IBidiCommands {
+  bidiSubscribe(events: string[], contexts: string[]): Promise<void>;
+  bidiUnsubscribe(events: string[], contexts: string[]): Promise<void>;
+  bidiStatus(): Promise<DriverStatus>;
+}
+
+export interface DriverStatus {
+  ready: boolean,
+  message: string,
+  [key: string]: any;
+}
+
+export interface ITimeoutCommands {
+  /**
+   * Set the various timeouts associated with a session
+   * @see {@link https://w3c.github.io/webdriver/#set-timeouts}
+   *
+   * @param type - used only for the old (JSONWP) command, the type of the timeout
+   * @param ms - used only for the old (JSONWP) command, the ms for the timeout
+   * @param script - the number in ms for the script timeout, used for the W3C command
+   * @param pageLoad - the number in ms for the pageLoad timeout, used for the W3C command
+   * @param implicit - the number in ms for the implicit wait timeout, used for the W3C command
+   */
+  timeouts(
+    type?: string,
+    ms?: number | string,
+    script?: number,
+    pageLoad?: number,
+    implicit?: number | string,
+  ): Promise<void>;
+
+  /**
+   * Set the new command timeout
+   *
+   * @param ms - the timeout in ms
+   */
+  setNewCommandTimeout(ms: number): void;
+
+  /**
+   * A helper method (not a command) used to set the implicit wait value
+   *
+   * @param ms - the implicit wait in ms
+   */
+  setImplicitWait(ms: number): void;
+
+  /**
+   * Periodically retry an async function up until the currently set implicit wait timeout
+   *
+   * @param condition - the behaviour to retry until it returns truthy
+   *
+   * @returns The return value of the condition
+   */
+  implicitWaitForCondition(condition: (...args: any[]) => Promise<any>): Promise<unknown>;
+
+  /**
+   * Get the current timeouts
+   * @see {@link https://w3c.github.io/webdriver/#get-timeouts}
+   *
+   * @returns A map of timeout names to ms values
+   */
+  getTimeouts(): Promise<Record<string, number>>;
+
+  /**
+   * Set the implicit wait value that was sent in via the W3C protocol
+   *
+   * @param ms - the timeout in ms
+   */
+  implicitWaitW3C(ms: number): Promise<void>;
+
+  /**
+   * Set the page load timeout value that was sent in via the W3C protocol
+   *
+   * @param ms - the timeout in ms
+   */
+  pageLoadTimeoutW3C(ms: number): Promise<void>;
+
+  /**
+   * Set the script timeout value that was sent in via the W3C protocol
+   *
+   * @param ms - the timeout in ms
+   */
+  scriptTimeoutW3C(ms: number): Promise<void>;
+
+  /**
+   * Set Appium's new command timeout
+   *
+   * @param ms - the timeout in ms
+   */
+  newCommandTimeout(ms: number): Promise<void>;
+
+  /**
+   * Get a timeout value from a number or a string
+   *
+   * @param ms - the timeout value as a number or a string
+   *
+   * @returns The timeout as a number in ms
+   */
+  parseTimeoutArgument(ms: number | string): number;
+}
+
+export interface IEventCommands {
+  /**
+   * Add a custom-named event to the Appium event log
+   *
+   * @param vendor - the name of the vendor or tool the event belongs to, to namespace the event
+   * @param event - the name of the event itself
+   */
+  logCustomEvent(vendor: string, event: string): Promise<void>;
+
+  /**
+   * Get a list of events that have occurred in the current session
+   *
+   * @param type - filter the returned events by including one or more types
+   *
+   * @returns The event history for the session
+   */
+  getLogEvents(type?: string | string[]): Promise<EventHistory | Record<string, number>>;
+}
+
+export interface EventHistory {
+  commands: EventHistoryCommand[];
+  [key: string]: any;
+}
+
+export interface EventHistoryCommand {
+  cmd: string;
+  startTime: number;
+  endTime: number;
+}
+
+export interface IExecuteCommands {
+  /**
+   * Call an `Execute Method` by its name with the given arguments. This method will check that the
+   * driver has registered the method matching the name, and send it the arguments.
+   *
+   * @param script - the name of the Execute Method
+   * @param args - a singleton array containing an arguments object
+   *
+   * @returns The result of calling the Execute Method
+   */
+  executeMethod<
+    TArgs extends readonly any[] | readonly [StringRecord<unknown>] = unknown[],
+    TReturn = unknown,
+  >(
+    script: string,
+    args: TArgs,
+  ): Promise<TReturn>;
+}
+
+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}
+   *
+   * @param strategy - the locator strategy
+   * @param selector - the selector to combine with the strategy to find the specific element
+   *
+   * @returns The element object encoding the element id which can be used in element-related
+   * commands
+   */
+  findElement(strategy: string, selector: string): Promise<Element>;
+
+  /**
+   * Find a a list of all UI elements matching a given a locator strategy and a selector
+   * @see {@link https://w3c.github.io/webdriver/#find-elements}
+   *
+   * @param strategy - the locator strategy
+   * @param selector - the selector to combine with the strategy to find the specific elements
+   *
+   * @returns A possibly-empty list of element objects
+   */
+  findElements(strategy: string, selector: string): Promise<Element[]>;
+
+  /**
+   * Find a UI element given a locator strategy and a selector, erroring if it can't be found. Only
+   * look for elements among the set of descendants of a given element
+   * @see {@link https://w3c.github.io/webdriver/#find-element-from-element}
+   *
+   * @param strategy - the locator strategy
+   * @param selector - the selector to combine with the strategy to find the specific element
+   * @param elementId - the id of the element to use as the search basis
+   *
+   * @returns The element object encoding the element id which can be used in element-related
+   * commands
+   */
+  findElementFromElement(strategy: string, selector: string, elementId: string): Promise<Element>;
+
+  /**
+   * Find a a list of all UI elements matching a given a locator strategy and a selector. Only
+   * look for elements among the set of descendants of a given element
+   * @see {@link https://w3c.github.io/webdriver/#find-elements-from-element}
+   *
+   * @param strategy - the locator strategy
+   * @param selector - the selector to combine with the strategy to find the specific elements
+   * @param elementId - the id of the element to use as the search basis
+   *
+   * @returns A possibly-empty list of element objects
+   */
+  findElementsFromElement(
+    strategy: string,
+    selector: string,
+    elementId: string,
+  ): Promise<Element[]>;
+
+  /**
+   * Find an element from a shadow root
+   * @see {@link https://w3c.github.io/webdriver/#find-element-from-shadow-root}
+   * @param strategy - the locator strategy
+   * @param selector - the selector to combine with the strategy to find the specific elements
+   * @param shadowId - the id of the element to use as the search basis
+   *
+   * @returns The element inside the shadow root matching the selector
+   */
+  findElementFromShadowRoot?(
+    strategy: string,
+    selector: string,
+    shadowId: string,
+  ): Promise<Element>;
+
+  /**
+   * Find elements from a shadow root
+   * @see {@link https://w3c.github.io/webdriver/#find-element-from-shadow-root}
+   * @param strategy - the locator strategy
+   * @param selector - the selector to combine with the strategy to find the specific elements
+   * @param shadowId - the id of the element to use as the search basis
+   *
+   * @returns A possibly empty list of elements inside the shadow root matching the selector
+   */
+  findElementsFromShadowRoot?(
+    strategy: string,
+    selector: string,
+    shadowId: string,
+  ): Promise<Element[]>;
+
+  /**
+   * A helper method that returns one or more UI elements based on the search criteria
+   *
+   * @param strategy - the locator strategy
+   * @param selector - the selector
+   * @param mult - whether or not we want to find multiple elements
+   * @param context - the element to use as the search context basis if desiredCapabilities
+   *
+   * @returns A single element or list of elements
+   */
+  findElOrEls(strategy: string, selector: string, mult: true, context?: any): Promise<Element[]>;
+  findElOrEls(strategy: string, selector: string, mult: false, context?: any): Promise<Element>;
+
+  /**
+   * This is a wrapper for {@linkcode findElOrEls} that validates locator strategies
+   * and implements the `appium:printPageSourceOnFindFailure` capability
+   *
+   * @param strategy - the locator strategy
+   * @param selector - the selector
+   * @param mult - whether or not we want to find multiple elements
+   * @param context - the element to use as the search context basis if desiredCapabilities
+   *
+   * @returns A single element or list of elements
+   */
+  findElOrElsWithProcessing(
+    strategy: string,
+    selector: string,
+    mult: true,
+    context?: any,
+  ): Promise<Element[]>;
+  findElOrElsWithProcessing(
+    strategy: string,
+    selector: string,
+    mult: false,
+    context?: any,
+  ): Promise<Element>;
+
+  /**
+   * Get the current page/app source as HTML/XML
+   * @see {@link https://w3c.github.io/webdriver/#get-page-source}
+   *
+   * @returns The UI hierarchy in a platform-appropriate format (e.g., HTML for a web page)
+   */
+  getPageSource(): Promise<string>;
+}
+
+export interface ILogCommands {
+  /**
+   * Definition of the available log types
+   */
+  supportedLogTypes: Readonly<LogDefRecord>;
+
+  /**
+   * Get available log types as a list of strings
+   */
+  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: string): Promise<any>;
+}
+
+/**
+ * A record of {@linkcode LogDef} objects, keyed by the log type name.
+ * Used in {@linkcode ILogCommands.supportedLogTypes}
+ */
+export type LogDefRecord = Record<string, LogDef>;
+
+/**
+ * A definition of a log type
+ */
+export interface LogDef {
+  /**
+   * Description of the log type.
+   *
+   * The only place this is used is in error messages if the client provides an invalid log type
+   * via {@linkcode ILogCommands.getLog}.
+   */
+  description: string;
+  /**
+   * Returns all the log data for the given type
+   *
+   * This implementation *should* drain, truncate or otherwise reset the log buffer.
+   */
+  getter: (driver: any) => Promise<unknown> | unknown;
+}
+
+export interface ISettingsCommands<T extends object = object> {
+  /**
+   * Update the session's settings dictionary with a new settings object
+   *
+   * @param settings - A key-value map of setting names to values. Settings not named in the map
+   * will not have their value adjusted.
+   */
+  updateSettings: (settings: T) => Promise<void>;
+
+  /**
+   * Get the current settings for the session
+   *
+   * @returns The settings object
+   */
+  getSettings(): Promise<T>;
+}
+
+/**
+ * An interface which creates and deletes sessions.
+ */
+export interface ISessionHandler<
+  C extends Constraints = Constraints,
+  CreateResult = DefaultCreateSessionResult<C>,
+  DeleteResult = DefaultDeleteSessionResult,
+  SessionData extends StringRecord = StringRecord,
+> {
+  /**
+   * Start a new automation session
+   * @see {@link https://w3c.github.io/webdriver/#new-session}
+   *
+   * @privateRemarks
+   * The shape of this method is strange because it used to support both JSONWP and W3C
+   * capabilities. This will likely change in the future to simplify.
+   *
+   * @param w3cCaps1 - the new session capabilities
+   * @param w3cCaps2 - another place the new session capabilities could be sent (typically left undefined)
+   * @param w3cCaps3 - another place the new session capabilities could be sent (typically left undefined)
+   * @param driverData - a list of DriverData objects representing other sessions running for this
+   * driver on the same Appium server. This information can be used to help ensure no conflict of
+   * resources
+   *
+   * @returns The capabilities object representing the created session
+   */
+  createSession(
+    w3cCaps1: W3CDriverCaps<C>,
+    w3cCaps2?: W3CDriverCaps<C>,
+    w3cCaps3?: W3CDriverCaps<C>,
+    driverData?: DriverData[],
+  ): Promise<CreateResult>;
+
+  /**
+   * Stop an automation session
+   * @see {@link https://w3c.github.io/webdriver/#delete-session}
+   *
+   * @param sessionId - the id of the session that is to be deleted
+   * @param driverData - the driver data for other currently-running sessions
+   */
+  deleteSession(sessionId?: string, driverData?: DriverData[]): Promise<DeleteResult | void>;
+
+  /**
+   * Get the data for the current session
+   *
+   * @returns A session data object
+   */
+  getSession(): Promise<SingularSessionData<C, SessionData>>;
+
+  /**
+   * Get the capabilities of the current session
+   *
+   * @returns A session capabilities object
+   */
+  getAppiumSessionCapabilities(): Promise<SessionCapabilities<C>>;
+}
+
+/**
+ * @see {@linkcode ISessionHandler}
+ */
+export type DefaultCreateSessionResult<C extends Constraints> = [
+  sessionId: string,
+  capabilities: DriverCaps<C>,
+];
+
+/**
+ * @see {@linkcode ISessionHandler}
+ */
+export type DefaultDeleteSessionResult = void;
+
+/**
+ * Custom session data for a driver.
+ */
+export type DriverData = Record<string, unknown>;
+
+/**
+ * Data returned by {@linkcode ISessionHandler.getSession}.
+ *
+ * @typeParam C - The driver's capability constraints
+ * @typeParam T - Any extra data the driver stuffs in here
+ * @privateRemarks The content of this object looks implementation-specific and in practice is not well-defined.  It's _possible_ to fully type this in the future.
+ */
+export type SingularSessionData<
+  C extends Constraints = Constraints,
+  T extends StringRecord = StringRecord,
+> = DriverCaps<C> & {
+  events?: EventHistory;
+  error?: string;
+} & T;
+
+/**
+ * Data returned by `AppiumDriver.getAppiumSessions`
+ *
+ * @typeParam C - The driver's constraints
+ */
+export interface TimestampedMultiSessionData<C extends Constraints = Constraints> {
+  id: string;
+  created: number; // Unix timestamp in milliseconds
+  capabilities: DriverCaps<C>;
+}
+
+/**
+ * Data returned by {@linkcode ISessionCommands.getAppiumSessionCapabilities}.
+ *
+ * @typeParam C - The driver's constraints
+ * @typeParam T - Any extra data the driver stuffs in here
+ */
+export type SessionCapabilities<
+  C extends Constraints = Constraints,
+  T extends StringRecord = StringRecord,
+> = {
+  capabilities: DriverCaps<C>;
+} & T;
+
+/**
+ * Interface for all commands expected to be implemented by BaseDriver.
+ */
+export type IImplementedCommands<
+  C extends Constraints = Constraints,
+  Settings extends StringRecord = StringRecord,
+  CreateResult = DefaultCreateSessionResult<C>,
+  DeleteResult = DefaultDeleteSessionResult,
+  SessionData extends StringRecord = StringRecord,
+> = IBidiCommands
+  & ILogCommands
+  & IFindCommands
+  & ISettingsCommands<Settings>
+  & ITimeoutCommands
+  & IEventCommands
+  & IExecuteCommands
+  & ISessionHandler<C, CreateResult, DeleteResult, SessionData>;

package/lib/commands/index.ts

@@ -0,0 +1,6 @@
+export * from './appium';
+export * from './basedriver';
+export * from './jsonwp';
+export * from './mjsonwp';
+export * from './other-protocols';
+export * from './webdriver';

package/lib/commands/jsonwp.ts

@@ -0,0 +1,41 @@
+/**
+ * Interface for all JSONWP commands proxied to the external driver.
+ */
+export interface IJSONWPCommands {
+  /**
+   * Get the device orientation
+   *
+   * @returns The orientation string
+   */
+  getOrientation?(): Promise<string>;
+
+  /**
+   * Set the device orientation
+   *
+   * @param orientation - the orientation string
+   */
+  setOrientation?(orientation: string): Promise<void>;
+
+  /**
+   * Get the virtual or real geographical location of a device
+   *
+   * @returns The location
+   */
+  getGeoLocation?(): Promise<Location>;
+
+  /**
+   * Set the virtual geographical location of a device
+   *
+   * @param location - the location including latitude and longitude
+   * @returns The complete location
+   */
+  setGeoLocation?(location: Partial<Location>): Promise<Location>;
+}
+
+export type Orientation = 'LANDSCAPE' | 'PORTRAIT';
+
+export interface Location {
+  latitude: number;
+  longitude: number;
+  altitude?: number;
+}

package/lib/commands/mjsonwp.ts

@@ -0,0 +1,71 @@
+/**
+ * Interface for all MJSONWP commands proxied to the external driver.
+ */
+export interface IMJSONWPCommands<Ctx = string> {
+  /**
+   * Get the currently active context
+   * @see {@link https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#webviews-and-other-contexts}
+   *
+   * @returns The context name
+   */
+  getCurrentContext?(): Promise<Ctx | null>;
+
+  /**
+   * Switch to a context by name
+   * @see {@link https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#webviews-and-other-contexts}
+   *
+   * @param name - the context name
+   */
+  setContext?(name: string, ...args: any[]): Promise<void>;
+
+  /**
+   * Get the list of available contexts
+   * @see {@link https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#webviews-and-other-contexts}
+   *
+   * @returns The list of context names
+   */
+  getContexts?(): Promise<Ctx[]>;
+
+  /**
+   * Get the network connection state of a device
+   * @see {@link https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#device-modes}
+   *
+   * @returns A number which is a bitmask representing categories like Data, Wifi, and Airplane
+   * mode status
+   */
+  getNetworkConnection?(): Promise<number>;
+
+  /**
+   * Set the network connection of the device
+   * @see {@link https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#device-modes}
+   *
+   * @param type - the bitmask representing network state
+   * @returns A number which is a bitmask representing categories like Data, Wifi, and Airplane
+   * mode status
+   */
+  setNetworkConnection?(type: number): Promise<number>;
+
+  /**
+   * Get the current rotation state of the device
+   * @see {@link https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#device-rotation}
+   *
+   * @returns The Rotation object consisting of x, y, and z rotation values (0 <= n <= 360)
+   */
+  getRotation?(): Promise<Rotation>;
+
+  /**
+   * Set the device rotation state
+   * @see {@link https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#device-rotation}
+   *
+   * @param x - the degree to which the device is rotated around the x axis (0 <= x <= 360)
+   * @param y - the degree to which the device is rotated around the y axis (0 <= y <= 360)
+   * @param z - the degree to which the device is rotated around the z axis (0 <= z <= 360)
+   */
+  setRotation?(x: number, y: number, z: number): Promise<void>;
+}
+
+export interface Rotation {
+  x: number;
+  y: number;
+  z: number;
+}