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

Appium driver for iOS using XCUITest for backend

import type { XCUITestDriver } from '../driver';
import type { Element, Cookie, Size, Position } from '@appium/types';
import type { AtomsElement } from './types';
import type { CalibrationData } from '../types';
/**
 * Sets the current web frame context.
 *
 * @param frame - Frame identifier (number, string, or null to return to default content)
 * @group Mobile Web Only
 * @throws {errors.NotImplementedError} If not in a web context
 * @throws {errors.NoSuchFrameError} If the specified frame is not found
 */
export declare function setFrame(this: XCUITestDriver, frame: number | string | null): Promise<void>;
/**
 * Gets the value of a CSS property for an element.
 *
 * @param propertyName - Name of the CSS property
 * @param el - Element to get the property from
 * @group Mobile Web Only
 * @throws {errors.NotImplementedError} If not in a web context
 */
export declare function getCssProperty(this: XCUITestDriver, propertyName: string, el: Element | string): Promise<string>;
/**
 * Submits the form that contains the specified element.
 *
 * @param el - The element ID or element object
 * @group Mobile Web Only
 * @throws {errors.NotImplementedError} If not in a web context
 */
export declare function submit(this: XCUITestDriver, el: string | Element): Promise<void>;
/**
 * Refreshes the current page.
 *
 * @group Mobile Web Only
 * @throws {errors.NotImplementedError} If not in a web context
 */
export declare function refresh(this: XCUITestDriver): Promise<void>;
/**
 * Gets the current page URL.
 *
 * @group Mobile Web Only
 * @throws {errors.NotImplementedError} If not in a web context
 */
export declare function getUrl(this: XCUITestDriver): Promise<string>;
/**
 * Gets the current page title.
 *
 * @group Mobile Web Only
 * @throws {errors.NotImplementedError} If not in a web context
 */
export declare function title(this: XCUITestDriver): Promise<string>;
/**
 * Gets all cookies for the current page.
 *
 * Cookie values are automatically URI-decoded.
 *
 * @group Mobile Web Only
 * @throws {errors.NotImplementedError} If not in a web context
 */
export declare function getCookies(this: XCUITestDriver): Promise<Cookie[]>;
/**
 * Sets a cookie for the current page.
 *
 * If the cookie's path is not specified, it defaults to '/'.
 *
 * @param cookie - Cookie object to set
 * @group Mobile Web Only
 * @throws {errors.NotImplementedError} If not in a web context
 */
export declare function setCookie(this: XCUITestDriver, cookie: Cookie): Promise<void>;
/**
 * Deletes a cookie by name.
 *
 * If the cookie is not found, the operation is silently ignored.
 *
 * @param cookieName - Name of the cookie to delete
 * @group Mobile Web Only
 * @throws {errors.NotImplementedError} If not in a web context
 */
export declare function deleteCookie(this: XCUITestDriver, cookieName: string): Promise<void>;
/**
 * Deletes all cookies for the current page.
 *
 * @group Mobile Web Only
 * @throws {errors.NotImplementedError} If not in a web context
 */
export declare function deleteCookies(this: XCUITestDriver): Promise<void>;
/**
 * Caches a web element for later use.
 *
 * @param el - Element to cache
 * @returns The cached element wrapper
 */
export declare function cacheWebElement(this: XCUITestDriver, el: Element | string): Element | string;
/**
 * Recursively caches all web elements in a response object.
 *
 * @param response - Response object that may contain web elements
 * @returns Response with cached element wrappers
 */
export declare function cacheWebElements(this: XCUITestDriver, response: any): any;
/**
 * Executes a Selenium atom script in the current web context.
 *
 * @param atom - Name of the atom to execute
 * @param args - Arguments to pass to the atom
 * @param alwaysDefaultFrame - If true, always use the default frame instead of current frames
 * @privateRemarks This should return `Promise<T>` where `T` extends `unknown`, but that's going to cause a lot of things to break.
 */
export declare function executeAtom(this: XCUITestDriver, atom: string, args: unknown[], alwaysDefaultFrame?: boolean): Promise<any>;
/**
 * Executes a Selenium atom script asynchronously.
 *
 * @param atom - Name of the atom to execute
 * @param args - Arguments to pass to the atom
 */
export declare function executeAtomAsync(this: XCUITestDriver, atom: string, args: any[]): Promise<any>;
/**
 * Gets the atoms-compatible element representation.
 *
 * @template S - Element identifier type
 * @param elOrId - Element or element ID
 * @returns Atoms-compatible element object
 * @throws {errors.StaleElementReferenceError} If the element is not in the cache
 */
export declare function getAtomsElement<S extends string = string>(this: XCUITestDriver, elOrId: S | Element<S>): AtomsElement<S>;
/**
 * Converts elements in an argument array to atoms-compatible format.
 *
 * @param args - Array of arguments that may contain elements
 * @returns Array with elements converted to atoms format
 */
export declare function convertElementsForAtoms(this: XCUITestDriver, args?: readonly any[]): any[];
/**
 * Extracts the element ID from an element object.
 *
 * @param element - Element object
 * @returns Element ID if found, undefined otherwise
 */
export declare function getElementId(element: any): string | undefined;
/**
 * Checks if an object has an element ID (type guard).
 *
 * @param element - Object to check
 * @returns True if the object has an element ID
 */
export declare function hasElementId(element: any): element is Element;
/**
 * Finds one or more web elements using the specified strategy.
 *
 * @param strategy - Locator strategy (e.g., 'id', 'css selector')
 * @param selector - Selector value
 * @param many - If true, returns array of elements; if false, returns single element
 * @param ctx - Optional context element to search within
 * @returns Element or array of elements
 * @throws {errors.NoSuchElementError} If element not found and many is false
 */
export declare function findWebElementOrElements(this: XCUITestDriver, strategy: string, selector: string, many?: boolean, ctx?: Element | string | null): Promise<Element | Element[]>;
/**
 * Clicks at the specified web coordinates.
 *
 * Coordinates are automatically translated from web to native coordinates.
 *
 * @param x - X coordinate in web space
 * @param y - Y coordinate in web space
 */
export declare function clickWebCoords(this: XCUITestDriver, x: number, y: number): Promise<void>;
/**
 * Determines if the current Safari session is running on an iPhone.
 *
 * The result is cached after the first call.
 *
 * @returns True if running on iPhone, false otherwise
 */
export declare function getSafariIsIphone(this: XCUITestDriver): Promise<boolean>;
/**
 * Gets the device size from Safari's perspective.
 *
 * Returns normalized dimensions (width <= height).
 *
 * @returns Device size with width and height
 */
export declare function getSafariDeviceSize(this: XCUITestDriver): Promise<Size>;
/**
 * Determines if the current device has a notch (iPhone X and later).
 *
 * The result is cached after the first call.
 *
 * @returns True if device has a notch, false otherwise
 */
export declare function getSafariIsNotched(this: XCUITestDriver): Promise<boolean>;
/**
 * Calculates and applies extra offset for web coordinate translation.
 *
 * Takes into account Safari UI elements like tab bars, smart app banners, and device notches.
 * Modifies wvPos and realDims in place.
 *
 * @param wvPos - WebView position object (modified in place)
 * @param realDims - Real dimensions object (modified in place)
 * @throws {errors.InvalidArgumentError} If Safari tab bar position is invalid
 */
export declare function getExtraTranslateWebCoordsOffset(this: XCUITestDriver, wvPos: {
    x: number;
    y: number;
}, realDims: {
    w: number;
    h: number;
}): Promise<void>;
/**
 * Calculates additional offset for native web tap based on smart app banner visibility.
 *
 * @param isIphone - Whether the device is an iPhone
 * @param bannerVisibility - Banner visibility setting ('visible', 'invisible', or 'detect')
 * @returns Additional offset in pixels
 */
export declare function getExtraNativeWebTapOffset(this: XCUITestDriver, isIphone: boolean, bannerVisibility: string): Promise<number>;
/**
 * Performs a native tap on a web element.
 *
 * Attempts to use a simple native tap first, falling back to coordinate-based tapping if needed.
 *
 * @param el - Element to tap
 */
export declare function nativeWebTap(this: XCUITestDriver, el: any): Promise<void>;
/**
 * Translates web coordinates to native screen coordinates.
 *
 * Uses calibration data if available, otherwise falls back to legacy algorithm.
 *
 * @param x - X coordinate in web space
 * @param y - Y coordinate in web space
 * @returns Translated position in native coordinates
 * @throws {Error} If no WebView is found or if translation fails
 */
export declare function translateWebCoords(this: XCUITestDriver, x: number, y: number): Promise<Position>;
/**
 * Checks if an alert is currently present.
 *
 * @returns True if an alert is present, false otherwise
 */
export declare function checkForAlert(this: XCUITestDriver): Promise<boolean>;
/**
 * Waits for an atom promise to resolve, monitoring for alerts during execution.
 *
 * @param promise - Promise returned by atom execution
 * @returns The result of the atom execution
 * @throws {errors.UnexpectedAlertOpenError} If an alert appears during execution
 * @throws {errors.TimeoutError} If the atom execution times out
 */
export declare function waitForAtom(this: XCUITestDriver, promise: Promise<any>): Promise<any>;
/**
 * Performs browser navigation (back, forward, etc.) using history API.
 *
 * @param navType - Navigation type (e.g., 'back', 'forward')
 */
export declare function mobileWebNav(this: XCUITestDriver, navType: string): Promise<void>;
/**
 * Gets the base URL for accessing WDA HTTP endpoints.
 *
 * @returns The base URL (e.g., 'http://127.0.0.1:8100')
 */
export declare function getWdaLocalhostRoot(this: XCUITestDriver): string;
/**
 * Calibrates web to real coordinates translation.
 * This API can only be called from Safari web context.
 * It must load a custom page to the browser, and then restore
 * the original one, so don't call it if you can potentially
 * lose the current web app state.
 * The outcome of this API is then used in nativeWebTap mode.
 * The returned value could also be used to manually transform web coordinates
 * to real devices ones in client scripts.
 *
 * @returns Calibration data with offset and pixel ratio information
 * @throws {errors.NotImplementedError} If not in a web context
 */
export declare function mobileCalibrateWebToRealCoordinatesTranslation(this: XCUITestDriver): Promise<CalibrationData>;
/**
 * Updates Mobile Safari preferences on an iOS Simulator
 *
 * @param preferences - An object containing Safari settings to be updated.
 * The list of available setting names and their values can be retrieved by changing the
 * corresponding Safari settings in the UI and then inspecting
 * `Library/Preferences/com.apple.mobilesafari.plist` file inside of the `com.apple.mobilesafari`
 * app container within the simulator filesystem. The full path to Mobile Safari's container can
 * be retrieved by running `xcrun simctl get_app_container <sim_udid> com.apple.mobilesafari
 * data`. Use the `xcrun simctl spawn <sim_udid> defaults read <path_to_plist>` command to print
 * the plist content to the Terminal.
 *
 * @group Simulator Only
 * @throws {Error} If run on a real device
 * @throws {errors.InvalidArgumentError} If the preferences argument is invalid
 */
export declare function mobileUpdateSafariPreferences(this: XCUITestDriver, preferences: Record<string, any>): Promise<void>;
//# sourceMappingURL=web.d.ts.map