appium-xcuitest-driver/build/lib/commands/context.d.ts

Appium driver for iOS using XCUITest for backend

import { RemoteDebugger } from 'appium-remote-debugger';
import type { XCUITestDriver } from '../driver';
import type { Page } from '../types';
import type { ViewContext, FullContext, PageChangeNotification } from './types';
/**
 * Retrieves the list of available contexts and their associated views.
 *
 * @param useUrl - Whether to filter webviews by URL
 */
export declare function getContextsAndViews(this: XCUITestDriver, useUrl?: boolean): Promise<ViewContext[]>;
/**
 * Activates the most recently available webview context.
 *
 * @throws {Error} If no webview is available or if the remote debugger cannot connect
 */
export declare function activateRecentWebview(this: XCUITestDriver): Promise<void>;
/**
 * Lists all available web frames (pages) from the remote debugger.
 *
 * @param useUrl - Whether to filter pages by the current URL
 */
export declare function listWebFrames(this: XCUITestDriver, useUrl?: boolean): Promise<Page[]>;
/**
 * Establishes a connection to the remote debugger and sets up event listeners.
 */
export declare function connectToRemoteDebugger(this: XCUITestDriver): Promise<void>;
/**
 * Retrieves the list of available contexts.
 *
 * The list includes extended context information, like URLs and page names.
 * This is different from the standard `getContexts` API, because the latter
 * only has web view names without any additional information.
 *
 * @remarks In situations where multiple web views are available at once, the
 * client code would have to connect to each of them in order to detect the
 * one which needs to be interacted with. This extra effort is not needed with
 * the information provided by this extension.
 *
 * @param waitForWebviewMs - The period to poll for available webview(s) (in ms)
 * @returns The list of available context objects along with their properties.
 */
export declare function mobileGetContexts(this: XCUITestDriver, waitForWebviewMs?: number): Promise<FullContext[]>;
/**
 * Handles page change notifications from the remote debugger.
 *
 * Updates the current context when new pages are detected or when pages are closed.
 *
 * @param pageChangeNotification - The notification containing page array and app ID
 */
export declare function onPageChange(this: XCUITestDriver, pageChangeNotification: PageChangeNotification): Promise<void>;
/**
 * Disconnects from the remote debugger and cleans up context state.
 */
export declare function stopRemote(this: XCUITestDriver): Promise<void>;
/**
 * Sets the current URL for the active webview context.
 *
 * @param url - The URL to set, or null to clear
 */
export declare function setCurrentUrl(this: XCUITestDriver, url: string | null): void;
/**
 * Gets the current URL for the active webview context.
 *
 * @returns The current URL, or undefined/null if not set
 */
export declare function getCurrentUrl(this: XCUITestDriver): string | undefined | null;
/**
 * Finds the most recent webview context ID matching the given title or URL patterns.
 *
 * @param titleRegExp - Regular expression to match against page titles
 * @param urlRegExp - Regular expression to match against page URLs
 * @returns The matching context ID, or undefined if no match is found
 * @throws {errors.InvalidArgumentError} If neither regex is provided
 */
export declare function getRecentWebviewContextId(this: XCUITestDriver, titleRegExp: RegExp, urlRegExp: RegExp): Promise<string | undefined>;
/**
 * Checks if the current context is a web context (not native).
 *
 * @returns True if currently in a web context
 */
export declare function isWebContext(this: XCUITestDriver): boolean;
/**
 * Checks if the current context is a webview.
 *
 * This is an alias for {@linkcode isWebContext}.
 *
 * @returns True if currently in a webview context
 */
export declare function isWebview(this: XCUITestDriver): boolean;
/**
 * Creates a new remote debugger instance configured for the current device.
 *
 * @returns A configured RemoteDebugger instance
 */
export declare function getNewRemoteDebugger(this: XCUITestDriver): Promise<RemoteDebugger>;
/**
 * Gets the identifier of the current context.
 *
 * @returns The context identifier (e.g., 'NATIVE_APP' or 'WEBVIEW_xxx')
 */
export declare function getCurrentContext(this: XCUITestDriver): Promise<string>;
/**
 * Switches to the specified context (native or webview).
 *
 * @param name - The name of context to set. Can be 'NATIVE_APP', 'WEBVIEW_xxx', or null
 * @param callback - The callback (not used, kept for compatibility)
 * @param skipReadyCheck - Whether to skip waiting for the new context to be ready
 * @throws {errors.NoSuchContextError} If the specified context does not exist
 */
export declare function setContext(this: XCUITestDriver, name: string | {
    id: string;
} | null, callback?: any, skipReadyCheck?: boolean): Promise<void>;
/**
 * Gets the list of available contexts.
 *
 * The format depends on the `fullContextList` option:
 * - If enabled, returns full context objects with title, URL, and bundleId
 * - If disabled, returns simple context ID strings
 *
 * @returns Array of context IDs or full context objects
 */
export declare function getContexts(this: XCUITestDriver): Promise<string[] | FullContext[]>;
/**
 * Sets the current window (context) in a web context.
 *
 * This is a wrapper around {@linkcode setContext} that translates errors appropriately.
 *
 * @param name - The window/context name to switch to
 * @param skipReadyCheck - Whether to skip waiting for the window to be ready
 * @throws {errors.NoSuchWindowError} If the window does not exist
 */
export declare function setWindow(this: XCUITestDriver, name: string, skipReadyCheck?: boolean): Promise<void>;
/**
 * Gets the handle of the current window.
 *
 * In native context, returns a default handle. In web context, returns the current context ID.
 *
 * @returns The window handle
 * @throws {errors.InvalidContextError} If not in a valid context
 */
export declare function getWindowHandle(this: XCUITestDriver): Promise<string>;
/**
 * Gets the list of all available window handles.
 *
 * In native context, returns a single default handle. In web context, returns all webview handles.
 *
 * @returns Array of window handle strings
 */
export declare function getWindowHandles(this: XCUITestDriver): Promise<string[]>;
/**
 * Notifies BiDi clients about context changes.
 *
 * @see https://github.com/appium/appium/issues/20741
 */
export declare function notifyBiDiContextChange(this: XCUITestDriver): Promise<void>;
//# sourceMappingURL=context.d.ts.map