From d8588e107c107d5b75c27604cbd9c1c36bba20fb Mon Sep 17 00:00:00 2001 From: Jonathan Lipps Date: Tue, 10 Jan 2023 14:36:48 -0800 Subject: [PATCH] docs: add ExternalDriver docstrings (#17985) --- packages/base-driver/lib/protocol/routes.js | 2 +- .../test/unit/protocol/routes.spec.js | 2 +- packages/types/lib/driver.ts | 1672 ++++++++++++++++- 3 files changed, 1609 insertions(+), 67 deletions(-) diff --git a/packages/base-driver/lib/protocol/routes.js b/packages/base-driver/lib/protocol/routes.js index 2ebb5db6e..df17bbc9c 100644 --- a/packages/base-driver/lib/protocol/routes.js +++ b/packages/base-driver/lib/protocol/routes.js @@ -135,7 +135,7 @@ const METHOD_MAP = /** @type {const} */ ({ POST: {command: 'setFrame', payloadParams: {required: ['id']}}, }, '/session/:sessionId/frame/parent': { - POST: {}, + POST: {command: 'switchToParentFrame'}, }, '/session/:sessionId/window': { GET: {command: 'getWindowHandle'}, diff --git a/packages/base-driver/test/unit/protocol/routes.spec.js b/packages/base-driver/test/unit/protocol/routes.spec.js index eaec92d87..cad716303 100644 --- a/packages/base-driver/test/unit/protocol/routes.spec.js +++ b/packages/base-driver/test/unit/protocol/routes.spec.js @@ -35,7 +35,7 @@ describe('Protocol', function () { } let hash = shasum.digest('hex').substring(0, 8); // Modify the hash whenever the protocol has intentionally been modified. - hash.should.equal('43ef41a2'); + hash.should.equal('b1985791'); }); }); diff --git a/packages/types/lib/driver.ts b/packages/types/lib/driver.ts index 0f3ce9a0a..116efe19d 100644 --- a/packages/types/lib/driver.ts +++ b/packages/types/lib/driver.ts @@ -17,6 +17,16 @@ import {ServerArgs} from './config'; import {AsyncReturnType, ConditionalPick} from 'type-fest'; 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, @@ -24,32 +34,154 @@ export interface ITimeoutCommands { pageLoad?: number, implicit?: number | string ): Promise; + + /** + * Set the new command timeout + * + * @param ms - the timeout in ms + */ setNewCommandTimeout(ms: number): void; + + /** + * Set the implicit wait timeout + * + * @param ms - the timeout in ms + * + * @deprecated Use `timeouts` instead + */ implicitWait(ms: number | string): Promise; + + /** + * 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: () => Promise): Promise; + + /** + * Get the current timeouts + * @see {@link https://w3c.github.io/webdriver/#get-timeouts} + * + * @returns A map of timeout names to ms values + */ getTimeouts(): Promise>; + + /** + * Set the implicit wait value that was sent in via the W3C protocol + * + * @param ms - the timeout in ms + */ implicitWaitW3C(ms: number): Promise; + + /** + * Set the implicit wait value that was sent in via the JSONWP + * + * @param ms - the timeout in ms + * @deprecated + */ implicitWaitMJSONWP(ms: number): Promise; + + /** + * Set the page load timeout value that was sent in via the W3C protocol + * + * @param ms - the timeout in ms + */ pageLoadTimeoutW3C(ms: number): Promise; + + /** + * Set the page load timeout value that was sent in via the JSONWP + * + * @param ms - the timeout in ms + * @deprecated + */ pageLoadTimeoutMJSONWP(ms: number): Promise; + + /** + * Set the script timeout value that was sent in via the W3C protocol + * + * @param ms - the timeout in ms + */ scriptTimeoutW3C(ms: number): Promise; + + /** + * Set the script timeout value that was sent in via the JSONWP + * + * @param ms - the timeout in ms + * @deprecated + */ scriptTimeoutMJSONWP(ms: number): Promise; + + /** + * Set Appium's new command timeout + * + * @param ms - the timeout in ms + */ newCommandTimeout(ms: number): Promise; + + /** + * 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; + + /** + * 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>; } export interface ISessionCommands { + /** + * Get data for all sessions running on an Appium server + * + * @returns A list of session data objects + */ getSessions(): Promise; + + /** + * Get the data for the current session + * + * @returns A session data object + */ getSession(): Promise; } 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(script: string, args: [StringRecord] | []): Promise; } @@ -76,19 +208,99 @@ export type SingularSessionData< export interface IFindCommands { /** - * Finds an element - * @param strategy Strategy - * @param selector Selector + * 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; + + /** + * 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; + + /** + * 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; + + /** + * 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; + /** + * 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; + + /** + * 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; + + /** + * 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, @@ -96,6 +308,17 @@ export interface IFindCommands { context?: Ctx ): Promise; + /** + * This is a wrapper for {@linkcode IFindCommands.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, @@ -103,6 +326,12 @@ export interface IFindCommands { context?: Ctx ): Promise; + /** + * 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; } @@ -157,7 +386,19 @@ export interface LogDef { } export interface ISettingsCommands { + /** + * 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: StringRecord) => Promise; + + /** + * Get the current settings for the session + * + * @returns The settings object + */ getSettings(): Promise; } @@ -168,12 +409,21 @@ export interface SessionHandler< Extra extends StringRecord | void = void > { /** - * Creates a new session - * @param w3cCaps1 W3C Capabilities - * @param w3cCaps2 W3C Capabilities (alternate) - * @param w3cCaps3 W3C Capabilities (alternate) - * @param driverData Driver data - * @returns Tuple of the session ID and normalized capabilities + * Start a new automation session + * @see {@link https://w3c.github.io/webdriver/#new-session} + * + * @remarks + * 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 w3cCaps - 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: W3CCapabilities, @@ -182,6 +432,13 @@ export interface SessionHandler< driverData?: DriverData[] ): Promise; + /** + * 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; } @@ -264,7 +521,7 @@ export interface Cookie { // Appium W3C WebDriver Extension -export interface ScreenRecordOptions { +export interface StartScreenRecordOptions { remotePath?: string; username?: string; password?: string; @@ -280,6 +537,16 @@ export interface ScreenRecordOptions { bugReport?: string; } +export interface StopScreenRecordOptions { + remotePath?: string; + user?: string; + pass?: string; + method?: string; + headers?: Record; + fileFieldName?: string; + formFields: Record | Array<[string, string]>; +} + // JSONWP export type Size = Pick; @@ -387,17 +654,88 @@ export interface Driver< IExecuteCommands, SessionHandler<[string, any], void, C>, Core { + /** + * The set of command line arguments set for this driver + */ cliArgs: CArgs; + // The following methods are implemented by `BaseDriver`. + + /** + * Execute a driver (WebDriver-protocol) command by its name as defined in the routes file + * + * @param cmd - the name of the command + * @param args - arguments to pass to the command + * + * @returns The result of running the command + */ executeCommand(cmd: string, ...args: any[]): Promise; + + /** + * Signify to any owning processes that this driver encountered an error which should cause the + * session to terminate immediately (for example an upstream service failed) + * + * @param err - the Error object which is causing the shutdown + */ startUnexpectedShutdown(err?: Error): Promise; + + /** + * Start the timer for the New Command Timeout, which when it runs out, will stop the current + * session + */ startNewCommandTimeout(): Promise; + + /** + * Reset the current session (run the delete session and create session subroutines) + * + * @deprecated Use explicit session management commands instead + */ reset(): Promise; + + /** + * The processed capabilities used to start the session represented by the current driver instance + */ caps?: Capabilities; + + /** + * The original capabilities used to start the session represented by the current driver instance + */ originalCaps?: W3CCapabilities; + + /** + * The constraints object used to validate capabilities + */ desiredCapConstraints: C; + + /** + * Validate the capabilities used to start a session + * + * @param caps - the capabilities + * + * @internal + * + * @returns Whether or not the capabilities are valid + */ validateDesiredCaps(caps: Capabilities): boolean; + + /** + * A helper function to log unrecognized capabilities to the console + * + * @params caps - the capabilities + * + * @internal + */ logExtraCaps(caps: Capabilities): void; + + /** + * A helper function used to assign server information to the driver instance so the driver knows + * where the server is Running + * + * @param server - the server object + * @param host - the server hostname + * @param port - the server port + * @param path - the server base url + */ assignServer?(server: AppiumServer, host: string, port: number, path: string): void; } @@ -413,80 +751,655 @@ export interface ExternalDriver; + + /** + * Get the current url + * @see {@link https://w3c.github.io/webdriver/#get-current-url} + * + * @returns The url + */ getUrl?(): Promise; + + /** + * Navigate back in the page history + * @see {@link https://w3c.github.io/webdriver/#back} + */ back?(): Promise; + + /** + * Navigate forward in the page history + * @see {@link https://w3c.github.io/webdriver/#forward} + */ forward?(): Promise; + + /** + * Refresh the page + * @see {@link https://w3c.github.io/webdriver/#refresh} + */ refresh?(): Promise; + + /** + * Get the current page title + * @see {@link https://w3c.github.io/webdriver/#get-title} + * + * @returns The title + * + * @example + * ```js + * await driver.getTitle() + * ``` + * ```py + * driver.title + * ``` + * ```java + * driver.getTitle(); + * ``` + */ title?(): Promise; + + /** + * Get the handle (id) associated with the current browser window + * @see {@link https://w3c.github.io/webdriver/#get-window-handle} + * + * @returns The handle string + */ getWindowHandle?(): Promise; + + /** + * Close the current browsing context (window) + * @see {@link https://w3c.github.io/webdriver/#close-window} + * + * @returns An array of window handles representing currently-open windows + */ closeWindow?(): Promise; + + /** + * Switch to a specified window + * @see {@link https://w3c.github.io/webdriver/#switch-to-window} + * + * @param handle - the window handle of the window to make active + */ setWindow?(handle: string): Promise; + + /** + * Get a set of handles representing open browser windows + * @see {@link https://w3c.github.io/webdriver/#get-window-handles} + * + * @returns An array of window handles representing currently-open windows + */ getWindowHandles?(): Promise; - setFrame?(id: null | number | string): Promise; - getWindowRect?(): Promise; - setWindowRect?(x: number, y: number, width: number, height: number): Promise; - maximizeWindow?(): Promise; - minimizeWindow?(): Promise; - fullScreenWindow?(): Promise; + + /** + * Create a new browser window + * @see {@link https://w3c.github.io/webdriver/#new-window} + * + * @param type - a hint to the driver whether to create a "tab" or "window" + * + * @returns An object containing the handle of the newly created window and its type + */ createNewWindow?(type?: NewWindowType): Promise; + + /** + * Switch the current browsing context to a frame + * @see {@link https://w3c.github.io/webdriver/#switch-to-frame} + * + * @param id - the frame id, index, or `null` (indicating the top-level context) + */ + setFrame?(id: null | number | string): Promise; + + /** + * Set the current browsing context to the parent of the current context + * @see {@link https://w3c.github.io/webdriver/#switch-to-parent-frame} + */ + switchToParentFrame?(): Promise; + + /** + * Get the size and position of the current window + * @see {@link https://w3c.github.io/webdriver/#get-window-rect} + * + * @returns A `Rect` JSON object with x, y, width, and height properties + */ + getWindowRect?(): Promise; + + /** + * Set the current window's size and position + * @see {@link https://w3c.github.io/webdriver/#set-window-rect} + * + * @param x - the screen coordinate for the new left edge of the window + * @param y - the screen coordinate for the new top edge of the window + * @param width - the width in pixels to resize the window to + * @param height - the height in pixels to resize the window to + * + * @returns The actual `Rect` of the window after running the command + */ + setWindowRect?(x: number, y: number, width: number, height: number): Promise; + + /** + * Run the window-manager specific 'maximize' operation on the current window + * @see {@link https://w3c.github.io/webdriver/#maximize-window} + * + * @returns The actual `Rect` of the window after running the command + */ + maximizeWindow?(): Promise; + + /** + * Run the window-manager specific 'minimize' operation on the current window + * @see {@link https://w3c.github.io/webdriver/#minimize-window} + * + * @returns The actual `Rect` of the window after running the command + */ + minimizeWindow?(): Promise; + + /** + * Put the current window into full screen mode + * @see {@link https://w3c.github.io/webdriver/#fullscreen-window} + * + * @returns The actual `Rect` of the window after running the command + */ + fullScreenWindow?(): Promise; + + /** + * Get the active element + * @see {@link https://w3c.github.io/webdriver/#get-active-element} + * + * @returns The JSON object encapsulating the active element reference + */ active?(): Promise; + + /** + * Get the shadow root of an element + * @see {@link https://w3c.github.io/webdriver/#get-element-shadow-root} + * + * @param elementId - the id of the element to retrieve the shadow root for + * + * @returns The shadow root for an element, as an element + */ + elementShadowRoot?(elementId: string): Promise; + + /** + * Determine if the reference element is selected or not + * @see {@link https://w3c.github.io/webdriver/#is-element-selected} + * + * @param elementId - the id of the element + * + * @returns True if the element is selected, False otherwise + */ elementSelected?(elementId: string): Promise; + + /** + * Retrieve the value of an element's attribute + * @see {@link https://w3c.github.io/webdriver/#get-element-attribute} + * + * @param name - the attribute name + * @param elementId - the id of the element + * + * @returns The attribute value + */ getAttribute?(name: string, elementId: string): Promise; + + /** + * Retrieve the value of a named property of an element's JS object + * @see {@link https://w3c.github.io/webdriver/#get-element-property} + * + * @param name - the object property name + * @param elementId - the id of the element + * + * @returns The property value + */ getProperty?(name: string, elementId: string): Promise; + + /** + * Retrieve the value of a CSS property of an element + * @see {@link https://w3c.github.io/webdriver/#get-element-css-value} + * + * @param name - the CSS property name + * @param elementId - the id of the element + * + * @returns The property value + */ getCssProperty?(name: string, elementId: string): Promise; + + /** + * Get the text of an element as rendered + * @see {@link https://w3c.github.io/webdriver/#get-element-text} + * + * @param elementId - the id of the element + * + * @returns The text rendered for the element + */ getText?(elementId: string): Promise; + + /** + * Get the tag name of an element + * @see {@link https://w3c.github.io/webdriver/#get-element-tag-name} + * + * @param elementId - the id of the element + * + * @returns The tag name + */ getName?(elementId: string): Promise; + + /** + * Get the dimensions and position of an element + * @see {@link https://w3c.github.io/webdriver/#get-element-rect} + * + * @param elementId - the id of the element + * + * @returns The Rect object containing x, y, width, and height properties + */ getElementRect?(elementId: string): Promise; + + /** + * Determine whether an element is enabled + * @see {@link https://w3c.github.io/webdriver/#is-element-enabled} + * + * @param elementId - the id of the element + * + * @returns True if the element is enabled, False otherwise + */ elementEnabled?(elementId: string): Promise; - elementDisplayed?(elementId: string): Promise; - click?(elementId: string): Promise; - clear?(elementId: string): Promise; - setValue?(text: string, elementId: string): Promise; - execute?(script: string, args: unknown[]): Promise; - executeAsync?(script: string, args: unknown[]): Promise; - getCookies?(): Promise; - getCookie?(name: string): Promise; - setCookie?(cookie: Cookie): Promise; - deleteCookie?(name: string): Promise; - deleteCookies?(): Promise; - performActions?(actions: ActionSequence[]): Promise; - releaseActions?(): Promise; - postDismissAlert?(): Promise; - postAcceptAlert?(): Promise; - getAlertText?(): Promise; - setAlertText?(text: string): Promise; - getScreenshot?(): Promise; - getElementScreenshot?(elementId: string): Promise; + + /** + * Get the WAI-ARIA role of an element + * @see {@link https://w3c.github.io/webdriver/#get-computed-role} + * + * @param elementId - the id of the element + * + * @returns The role + */ getComputedRole?(elementId: string): Promise; + + /** + * Get the accessible name/label of an element + * @see {@link https://w3c.github.io/webdriver/#get-computed-label} + * + * @param elementId - the id of the element + * + * @returns The accessible name + */ getComputedLabel?(elementId: string): Promise; + /** + * Determine whether an element is displayed + * @see {@link https://w3c.github.io/webdriver/#element-displayedness} + * + * @param elementId - the id of the element + * + * @returns True if any part of the element is rendered within the viewport, False otherwise + */ + elementDisplayed?(elementId: string): Promise; + + /** + * Click/tap an element + * @see {@link https://w3c.github.io/webdriver/#element-click} + * + * @param elementId - the id of the element + */ + click?(elementId: string): Promise; + + /** + * Clear the text/value of an editable element + * @see {@link https://w3c.github.io/webdriver/#element-clear} + * + * @param elementId - the id of the element + */ + clear?(elementId: string): Promise; + + /** + * Send keystrokes to an element (or otherwise set its value) + * @see {@link https://w3c.github.io/webdriver/#element-send-keys} + * + * @param text - the text to send to the element + * @param elementId - the id of the element + */ + setValue?(text: string, elementId: string): Promise; + + /** + * Execute JavaScript (or some other kind of script) in the browser/app context + * @see {@link https://w3c.github.io/webdriver/#execute-script} + * + * @param script - the string to be evaluated as the script, which will be made the body of an + * anonymous function in the case of JS + * @param args - the list of arguments to be applied to the script as a function + * + * @returns The return value of the script execution + */ + execute?(script: string, args: unknown[]): Promise; + + /** + * Execute JavaScript (or some other kind of script) in the browser/app context, asynchronously + * @see {@link https://w3c.github.io/webdriver/#execute-async-script} + * + * @param script - the string to be evaluated as the script, which will be made the body of an + * anonymous function in the case of JS + * @param args - the list of arguments to be applied to the script as a function + * + * @returns The promise resolution of the return value of the script execution (or an error + * object if the promise is rejected) + */ + executeAsync?(script: string, args: unknown[]): Promise; + + /** + * Get all cookies known to the browsing context + * @see {@link https://w3c.github.io/webdriver/#get-all-cookies} + * + * @returns A list of serialized cookies + */ + getCookies?(): Promise; + + /** + * Get a cookie by name + * @see {@link https://w3c.github.io/webdriver/#get-named-cookie} + * + * @param name - the name of the cookie + * + * @returns A serialized cookie + */ + getCookie?(name: string): Promise; + + /** + * Add a cookie to the browsing context + * @see {@link https://w3c.github.io/webdriver/#add-cookie} + * + * @param cookie - the cookie data including properties like name, value, path, domain, + * secure, httpOnly, expiry, and samesite + */ + setCookie?(cookie: Cookie): Promise; + + /** + * Delete a named cookie + * @see {@link https://w3c.github.io/webdriver/#delete-cookie} + * + * @param name - the name of the cookie to delete + */ + deleteCookie?(name: string): Promise; + + /** + * Delete all cookies + * @see {@link https://w3c.github.io/webdriver/#delete-all-cookies} + */ + deleteCookies?(): Promise; + + /** + * Perform touch or keyboard actions + * @see {@link https://w3c.github.io/webdriver/#perform-actions} + * + * @param actions - the action sequence + */ + performActions?(actions: ActionSequence[]): Promise; + + /** + * Release all keys or buttons that are currently pressed + * @see {@link https://w3c.github.io/webdriver/#release-actions} + */ + releaseActions?(): Promise; + + /** + * Dismiss a simple dialog/alert + * @see {@link https://w3c.github.io/webdriver/#dismiss-alert} + */ + postDismissAlert?(): Promise; + + /** + * Accept a simple dialog/alert + * @see {@link https://w3c.github.io/webdriver/#accept-alert} + */ + postAcceptAlert?(): Promise; + + /** + * Get the text of the displayed alert + * @see {@link https://w3c.github.io/webdriver/#get-alert-text} + * + * @returns The text of the alert + */ + getAlertText?(): Promise; + + /** + * Set the text field of an alert prompt + * @see {@link https://w3c.github.io/webdriver/#send-alert-text} + * + * @param text - the text to send to the prompt + */ + setAlertText?(text: string): Promise; + + /** + * Get a screenshot of the current document as rendered + * @see {@link https://w3c.github.io/webdriver/#take-screenshot} + * + * @returns A base64-encoded string representing the PNG image data + */ + getScreenshot?(): Promise; + + /** + * Get an image of a single element as rendered on screen + * @see {@link https://w3c.github.io/webdriver/#take-element-screenshot} + * + * @param elementId - the id of the element + * + * @returns A base64-encoded string representing the PNG image data for the element rect + */ + getElementScreenshot?(elementId: string): Promise; + // Appium W3C WebDriver Extension + + /** + * Shake the device + * + * @deprecated + */ mobileShake?(): Promise; + + /** + * Get the current time on the device under timeouts + * + * @param format - the date/time format you would like the response into + * + * @returns The formatted time + */ getDeviceTime?(format?: string): Promise; + + /** + * 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; + + /** + * Unlock the device + * + * @deprecated + */ unlock?(): Promise; + + /** + * Determine whether the device is locked + * + * @returns True if the device is locked, false otherwise + * + * @deprecated + */ isLocked?(): Promise; - startRecordingScreen?(options?: ScreenRecordOptions): Promise; - stopRecordingScreen?(options?: ScreenRecordOptions): Promise; + + /** + * Direct Appium to start recording the device screen + * + * @param options - parameters for screen recording + * + * @deprecated + */ + startRecordingScreen?(options?: StartScreenRecordOptions): Promise; + + /** + * 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; + + /** + * List the performance data types supported by this driver, which can be used in a call to get + * the performance data by type. + * + * @returns The list of types + * + * @deprecated + */ getPerformanceDataTypes?(): Promise; + + /** + * Get the list of performance data associated with a given type + * + * @param packageName - the package name / id of the app to retrieve data for + * @param dataType - the performance data type; one of those retrieved in a call to + * getPerformanceDataTypes + * @param dataReadTimeout - how long to wait for data before timing out + * + * @returns A list of performance data strings + * + * @deprecated + */ getPerformanceData?( packageName: string, dataType: string, dataReadTimeout?: number ): Promise; + + /** + * Press a device hardware key by its code for the default duration + * + * @param keycode - the keycode + * @param metastate - the code denoting the simultaneous pressing of any meta keys (shift etc) + * @param flags - the code denoting the combination of extra flags + * + * @deprecated + */ pressKeyCode?(keycode: number, metastate?: number, flags?: number): Promise; + + /** + * Press a device hardware key by its code for a longer duration + * + * @param keycode - the keycode + * @param metastate - the code denoting the simultaneous pressing of any meta keys (shift etc) + * @param flags - the code denoting the combination of extra flags + * + * @deprecated + */ longPressKeyCode?(keycode: number, metastate?: number, flags?: number): Promise; + + /** + * Apply a synthetic fingerprint to the fingerprint detector of the device + * + * @param fingerprintId - the numeric ID of the fingerprint to use + * + * @deprecated + */ fingerprint?(fingerprintId: number): Promise; + + /** + * Simulate sending an SMS message from a certain phone number to the device + * + * @param phoneNumber - the number to pretend the message is from + * @param message - the SMS text + * + * @deprecated + */ sendSMS?(phoneNumber: string, message: string): Promise; + + /** + * Simulate triggering a phone call from a phone number and having the device take an action in + * response + * + * @param phoneNumber - the number to pretend the call is from + * @param action - the action to take in response (accept, reject, etc...) + * + * @deprecated + */ gsmCall?(phoneNumber: string, action: string): Promise; + + /** + * Simulate setting the GSM signal strength for a cell phone + * + * @param singalStrength - the strength in a driver-appropriate string + * + * @deprecated + */ gsmSignal?(signalStrength: string): Promise; + + /** + * Do something with GSM voice (unclear; this should not be implemented anywhere) + * + * @param state - the state + * + * @deprecated + */ gsmVoice?(state: string): Promise; + + /** + * Set the simulated power capacity of the device + * + * @param percent - how full the battery should become + * + * @deprecated + */ powerCapacity?(percent: number): Promise; + + /** + * Set the AC-connected power state of the device + * + * @param state - whether the device is connected to power or not + * + * @deprecated + */ powerAC?(state: string): Promise; + + /** + * Set the network speed of the device + * + * @param netspeed - the speed as a string, like '3G' + * + * @deprecated + */ networkSpeed?(netspeed: string): Promise; + + /** + * Simulate a keyevent on the device + * + * @param keycode - the manufacturer defined keycode + * @param metastate - the combination of meta startUnexpectedShutdown + * + * @deprecated + */ keyevent?(keycode: string, metastate?: string): Promise; + + /** + * Construct a rotation gesture? Unclear what this command does and it does not appear to be used + * + * @param x - the x coordinate of the rotation center + * @param y - the y coordinate of the rotation center + * @param radius - the radius of the rotation circle + * @param rotation - the rotation angle? idk + * @param touchCount - how many fingers to rotate + * @param elementId - if we're rotating around an element + * + * @deprecated Use setRotation instead + */ mobileRotation?( x: number, y: number, @@ -496,29 +1409,171 @@ export interface ExternalDriver; - getCurrentActivity?(): Promise; - getCurrentPackage?(): Promise; - installApp?(appPath: string, options?: unknown): Promise; + /** - * Activates the app - * @param appId Application ID - * @param options Options + * Get the current activity name + * + * @returns The activity name + * + * @deprecated + */ + getCurrentActivity?(): Promise; + + /** + * Get the current active app package name/id + * + * @returns The package name + * + * @deprecated + */ + getCurrentPackage?(): Promise; + + /** + * Install an app on a device + * + * @param appPath - the absolute path to a local app or a URL of a downloadable app bundle + * @param options - driver-specific install options + */ + installApp?(appPath: string, options?: unknown): Promise; + + /** + * Launch an app + * + * @param appId - the package or bundle ID of the application + * @param options - driver-specific launch options */ activateApp?(appId: string, options?: unknown): Promise; + + /** + * Remove / uninstall an app + * + * @param appId - the package or bundle ID of the application + * @param options - driver-specific launch options + */ removeApp?(appId: string, options?: unknown): Promise; + + /** + * Quit / terminate / stop a running application + * + * @param appId - the package or bundle ID of the application + * @param options - driver-specific launch options + */ terminateApp?(appId: string, options?: unknown): Promise; + + /** + * Determine whether an app is installed + * + * @param appId - the package or bundle ID of the application + */ isAppInstalled?(appId: string): Promise; - queryAppState?(appId: string): Promise; + + /** + * Get the running state of an app + * + * @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 + */ + queryAppState?(appId: string): Promise<0 | 1 | 3 | 4>; + + /** + * Attempt to hide a virtual keyboard + * + * @param strategy - the driver-specific name of a hiding strategy to follow + * @param key - the text of a key to use to hide the keyboard + * @param keyCode - a key code to trigger to hide the keyboard + * @param keyName - the name of a key to use to hide the keyboard + * + * @deprecated + */ hideKeyboard?(strategy?: string, key?: string, keyCode?: string, keyName?: string): Promise; + + /** + * Determine whether the keyboard is shown + * + * @returns Whether the keyboard is shown + */ isKeyboardShown?(): Promise; + + /** + * Push data to a file at a remote path on the device + * + * @param path - the remote path on the device to create the file at + * @param data - the base64-encoded data which will be decoded and written to `path` + */ pushFile?(path: string, data: string): Promise; + + /** + * Retrieve the data from a file on the device at a given path + * + * @param path - the remote path on the device to pull file data from + * + * @returns The base64-encoded file data + */ pullFile?(path: string): Promise; + + /** + * Retrieve the data from a folder on the device at a given path + * + * @param path - the remote path of a directory on the device + * + * @returns The base64-encoded zip file of the directory contents + */ pullFolder?(path: string): Promise; + + /** + * Toggle airplane/flight mode for the device + * + * @deprecated + */ toggleFlightMode?(): Promise; + + /** + * Toggle cell network data + * + * @deprecated + */ toggleData?(): Promise; + + /** + * Toggle WiFi radio status + * + * @deprecated + */ toggleWiFi?(): Promise; + + /** + * Toggle location services for the device + * + * @deprecated + */ toggleLocationServices?(): Promise; + + /** + * Open the notifications shade/screen + * + * @deprecated + */ openNotifications?(): Promise; + + /** + * Start an Android activity within an app + * + * @param appPackage - the app package id + * @param appActivity - the activity name + * @param appWaitPackage - the package id to wait for if different from the app package + * @param appWaitActivity - the activity name to wait for being active if different from + * appActivity + * @param intentAction - the action for the intent to use to start the activity + * @param intentCategory - the category for the intent + * @param flags - the flags for the intent + * @param optionalIntentArguments - additional arguments to be passed to launching the intent + * @param dontStopAppOnReset - set to true to not stop the current app before launching the + * activity + * + * @deprecated + */ startActivity?( appPackage: string, appActivity: string, @@ -530,57 +1585,375 @@ export interface ExternalDriver; + + /** + * Get information from the system bars of a device + * + * @returns An array of information objects of driver-specific shape + * + * @deprecated + */ getSystemBars?(): Promise; + + /** + * Get the display's pixel density + * + * @returns The density + * + * @deprecated + */ getDisplayDensity?(): Promise; + + /** + * Trigger a touch/fingerprint match or match failure + * + * @param match - whether the match should be a success or failure + * + * @deprecated + */ touchId?(match: boolean): Promise; + + /** + * 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; + + /** + * Start the session after it has been started. + * + * @deprecated Don't use this, it never made sense. + */ launchApp?(): Promise; + + /** + * Stop the session without stopping the session + * + * @deprecated Don't use this, it never made sense. + */ closeApp?(): Promise; + + /** + * 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; + + /** + * End platform-specific code coverage tracing + * + * @param intent - the Android intent for the coverage activity + * @param path - the path to place the results + * + * @deprecated + */ endCoverage?(intent: string, path: string): Promise; + + /** + * 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>; + + /** + * 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; + + /** + * Set the value of a text field but ensure the current value is replace and not appended + * + * @param value - the text to set + * @param elementId - the element to set it in + * + * @deprecated + */ replaceValue?(value: string, elementId: string): Promise; + + /** + * 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; + + /** + * 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; + + /** + * 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; // JSONWP + /** + * Set the async execute script timeout + * + * @param ms - the timeout + * + * @deprecated Use the W3C timeouts command instead + */ asyncScriptTimeout?(ms: number): Promise; + + /** + * Get the window size + * + * @returns The size (width and height) + * + * @deprecated Use getWindowRect instead + */ getWindowSize?(): Promise; + + /** + * 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; + + /** + * 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; + + /** + * 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; - elementShadowRoot?(elementId: string): Promise; - findElementFromShadowRoot?( - strategy: string, - selector: string, - shadowId: string - ): Promise; - findElementsFromShadowRoot?( - strategy: string, - selector: string, - shadowId: string - ): Promise; + + /** + * Check whether two elements are identical + * + * @param elementId - the first element's ID + * @param otherElementId - the second element's ID + * + * @returns True if the elements are equal, false otherwise + * + * @deprecated + */ equalsElement?(elementId: string, otherElementId: string): Promise; + + /** + * Submit the form an element is in + * + * @param elementId - the element ID + * + * @deprecated + */ submit?(elementId: string): Promise; + + /** + * 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; + + /** + * Get the list of IME engines + * + * @returns The list of IME engines + * + * @deprecated + */ availableIMEEngines?(): Promise; + + /** + * Get the active IME engine + * + * @returns The name of the active engine + * + * @deprecated + */ getActiveIMEEngine?(): Promise; + + /** + * Determine whether an IME is active + * + * @returns True if the IME is activated + * + * @deprecated + */ isIMEActivated?(): Promise; + + /** + * Deactivate an IME engine + * + * @deprecated + */ deactivateIMEEngine?(): Promise; + + /** + * Activate an IME engine + * + * @param engine - the name of the engine + * + * @deprecated + */ activateIMEEngine?(engine: string): Promise; + + /** + * Get the device orientation + * + * @returns The orientation string + */ getOrientation?(): Promise; + + /** + * Set the device orientation + * + * @param orientation - the orientation string + */ setOrientation?(orientation: string): Promise; + + /** + * 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; + + /** + * Trigger a mouse button down + * + * @param button - the button ID + * + * @deprecated Use the Actions API instead + */ buttonDown?(button?: number): Promise; + + /** + * Trigger a mouse button up + * + * @param button - the button ID + * + * @deprecated Use the Actions API instead + */ buttonUp?(button?: number): Promise; + + /** + * Click the current mouse location + * + * @param button - the button ID + * + * @deprecated Use the Actions API instead + */ clickCurrent?(button?: number): Promise; + + /** + * Double-click the current mouse location + * + * @deprecated Use the Actions API instead + */ doubleClick?(): Promise; + + /** + * Perform a touch down event at the location specified + * + * @param x - the x coordinate + * @param y - the y coordinate + * + * @deprecated Use the Actions API instead + */ touchDown?(x: number, y: number): Promise; + + /** + * Perform a touch up event at the location specified + * + * @param x - the x coordinate + * @param y - the y coordinate + * + * @deprecated Use the Actions API instead + */ touchUp?(x: number, y: number): Promise; + + /** + * Perform a touch move event at the location specified + * + * @param x - the x coordinate + * @param y - the y coordinate + * + * @deprecated Use the Actions API instead + */ touchMove?(x: number, y: number): Promise; + + /** + * Perform a long touch down event at the location specified + * + * @param elementId - the id of the element to long touch + * + * @deprecated Use the Actions API instead + */ touchLongClick?(elementId: string): Promise; + + /** + * Perform a flick event at the location specified + * + * @param element - the element to make coordinates relative to + * @param xSpeed - the horizontal flick speed (in driver-specific units) + * @param ySpeed - the vertical flick speed (in driver-specific units) + * @param xOffset - the x coordinate + * @param yOffset - the y coordinate + * @param speed - the speed (unclear how this relates to xSpeed and ySpeed) + * + * @deprecated Use the Actions API instead + */ flick?( element?: string, xSpeed?: number, @@ -589,50 +1962,219 @@ export interface ExternalDriver; + + /** + * Get the virtual or real geographical location of a device + * + * @returns The location + */ getGeoLocation?(): Promise; + + /** + * Set the virtual geographical location of a device + * + * @param location - the location including latitude and longitude + */ setGeoLocation?(location: Partial): Promise; // MJSONWIRE + /** - * Get current context - * @deprecated + * 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; + + /** + * 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): Promise; + + /** + * 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; + + /** + * Get the index of an element on the page + * + * @param elementId - the element id + * + * @returns The page index + * + * @deprecated + */ getPageIndex?(elementId: string): Promise; + + /** + * 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; + + /** + * 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 + */ setNetworkConnection?(type: number): Promise; + + /** + * 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; + + /** + * 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; + + /** + * 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; + + /** + * 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; // Chromium DevTools + + /** + * Execute a devtools command + * + * @param cmd - the command + * @param params - any command-specific command parameters + * + * @returns The result of the command execution + */ executeCdp?(cmd: string, params: unknown): Promise; // Web Authentication + + /** + * Add a virtual authenticator to a browser + * @see {@link https://www.w3.org/TR/webauthn-2/#sctn-automation-add-virtual-authenticator} + * + * @param protocol - the protocol + * @param transport - a valid AuthenticatorTransport value + * @param hasResidentKey - whether there is a resident key + * @param hasUserVerification - whether the authenticator has user verification + * @param isUserConsenting - whether it is a user consenting authenticator + * @param isUserVerified - whether the user is verified + * + * @returns The authenticator ID + */ addVirtualAuthenticator?( - protocol: string, + protocol: 'ctap/u2f' | 'ctap2' | 'ctap2_1', transport: string, hasResidentKey?: boolean, hasUserVerification?: boolean, isUserConsenting?: boolean, isUserVerified?: boolean - ): Promise; - removeVirtualAuthenticator?(): Promise; + ): Promise; + + /** + * Remove a virtual authenticator + * @see {@link https://www.w3.org/TR/webauthn-2/#sctn-automation-remove-virtual-authenticator} + * + * @param authenticatorId - the ID returned in the call to add the authenticator + */ + removeVirtualAuthenticator?(authenticatorId: string): Promise; + + /** + * Inject a public key credential source into a virtual authenticator + * @see {@link https://www.w3.org/TR/webauthn-2/#sctn-automation-add-credential} + * + * @param credentialId - the base64 encoded credential ID + * @param isResidentCredential - if true, a client-side credential, otherwise a server-side + * credential + * @param rpId - the relying party ID the credential is scoped to + * @param privateKey - the base64 encoded private key package + * @param userHandle - the base64 encoded user handle + * @param signCount - the initial value for a signature counter + */ addAuthCredential?( credentialId: string, isResidentCredential: boolean, rpId: string, privateKey: string, - userHandle?: string, - signCount?: number + userHandle: string, + signCount: number, + authenticatorId: string ): Promise; + + /** + * Get the list of public key credential sources + * @see {@link https://www.w3.org/TR/webauthn-2/#sctn-automation-get-credentials} + * + * @returns The list of Credentials + */ getAuthCredential?(): Promise; + + /** + * Remove all auth credentials + * @see {@link https://www.w3.org/TR/webauthn-2/#sctn-automation-remove-all-credentials} + */ removeAllAuthCredentials?(): Promise; - removeAuthCredential?(): Promise; - setUserAuthVerified?(isUserVerified: boolean): Promise; + + /** + * Remove a specific auth credential + * + * @param credentialId - the credential ID + * @param authenticatorId - the authenticator ID + */ + removeAuthCredential?(credentialId: string, authenticatorId: string): Promise; + + /** + * Set the isUserVerified property of an authenticator + * @see {@link https://www.w3.org/TR/webauthn-2/#sctn-automation-set-user-verified} + * + * @param isUserVerified - the value of the isUserVerified property + * @param authenticatorId - the authenticator id + */ + setUserAuthVerified?(isUserVerified: boolean, authenticatorId: string): Promise; + + /** + * Proxy a command to a connected WebDriver server + * + * @typeParam T - the type of the return value + * @param url - the incoming URL + * @param method - the incoming HTTP method + * @param body - the incoming HTTP body + * + * @returns The return value of the proxied command + */ proxyCommand?(url: string, method: HTTPMethod, body?: string): Promise; }