appium-xcuitest-driver
Version:
Appium driver for iOS using XCUITest for backend
1,070 lines • 43.3 kB
JavaScript
"use strict";
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
var desc = Object.getOwnPropertyDescriptor(m, k);
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
desc = { enumerable: true, get: function() { return m[k]; } };
}
Object.defineProperty(o, k2, desc);
}) : (function(o, m, k, k2) {
if (k2 === undefined) k2 = k;
o[k2] = m[k];
}));
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
Object.defineProperty(o, "default", { enumerable: true, value: v });
}) : function(o, v) {
o["default"] = v;
});
var __importStar = (this && this.__importStar) || (function () {
var ownKeys = function(o) {
ownKeys = Object.getOwnPropertyNames || function (o) {
var ar = [];
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
return ar;
};
return ownKeys(o);
};
return function (mod) {
if (mod && mod.__esModule) return mod;
var result = {};
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
__setModuleDefault(result, mod);
return result;
};
})();
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.setFrame = setFrame;
exports.getCssProperty = getCssProperty;
exports.submit = submit;
exports.refresh = refresh;
exports.getUrl = getUrl;
exports.title = title;
exports.getCookies = getCookies;
exports.setCookie = setCookie;
exports.deleteCookie = deleteCookie;
exports.deleteCookies = deleteCookies;
exports.cacheWebElement = cacheWebElement;
exports.cacheWebElements = cacheWebElements;
exports.executeAtom = executeAtom;
exports.executeAtomAsync = executeAtomAsync;
exports.getAtomsElement = getAtomsElement;
exports.convertElementsForAtoms = convertElementsForAtoms;
exports.getElementId = getElementId;
exports.hasElementId = hasElementId;
exports.findWebElementOrElements = findWebElementOrElements;
exports.clickWebCoords = clickWebCoords;
exports.getSafariIsIphone = getSafariIsIphone;
exports.getSafariDeviceSize = getSafariDeviceSize;
exports.getSafariIsNotched = getSafariIsNotched;
exports.getExtraTranslateWebCoordsOffset = getExtraTranslateWebCoordsOffset;
exports.getExtraNativeWebTapOffset = getExtraNativeWebTapOffset;
exports.nativeWebTap = nativeWebTap;
exports.translateWebCoords = translateWebCoords;
exports.checkForAlert = checkForAlert;
exports.waitForAtom = waitForAtom;
exports.mobileWebNav = mobileWebNav;
exports.getWdaLocalhostRoot = getWdaLocalhostRoot;
exports.mobileCalibrateWebToRealCoordinatesTranslation = mobileCalibrateWebToRealCoordinatesTranslation;
exports.mobileUpdateSafariPreferences = mobileUpdateSafariPreferences;
const driver_1 = require("appium/driver");
const support_1 = require("appium/support");
const asyncbox_1 = require("asyncbox");
const bluebird_1 = __importStar(require("bluebird"));
const lodash_1 = __importDefault(require("lodash"));
const utils_1 = require("../utils");
const IPHONE_TOP_BAR_HEIGHT = 71;
const IPHONE_SCROLLED_TOP_BAR_HEIGHT = 41;
const IPHONE_X_SCROLLED_OFFSET = 55;
const IPHONE_X_NOTCH_OFFSET_IOS = 24;
const IPHONE_X_NOTCH_OFFSET_IOS_13 = 20;
const IPHONE_LANDSCAPE_TOP_BAR_HEIGHT = 51;
const IPHONE_BOTTOM_BAR_OFFSET = 49;
const TAB_BAR_OFFSET = 33;
const IPHONE_WEB_COORD_SMART_APP_BANNER_OFFSET = 84;
const IPAD_WEB_COORD_SMART_APP_BANNER_OFFSET = 95;
const CALIBRATION_TAP_DELTA_PX = 7;
const NOTCHED_DEVICE_SIZES = [
{ w: 1125, h: 2436 }, // 11 Pro, X, Xs
{ w: 828, h: 1792 }, // 11, Xr
{ w: 1242, h: 2688 }, // 11 Pro Max, Xs Max
{ w: 1080, h: 2340 }, // 13 mini, 12 mini
{ w: 1170, h: 2532 }, // 14, 13, 13 Pro, 12, 12 Pro
{ w: 1284, h: 2778 }, // 14 Plus, 13 Pro Max, 12 Pro Max
{ w: 1179, h: 2556 }, // 14 Pro
{ w: 1290, h: 2796 }, // 14 Pro Max
];
const { W3C_WEB_ELEMENT_IDENTIFIER } = support_1.util;
const ATOM_WAIT_TIMEOUT_MS = 2 * 60000;
// This value must be greater than the alerts check interval in WDA:
// https://github.com/appium/WebDriverAgent/blob/8bc3135f021b529d916846477544f4b8ca890f59/WebDriverAgentLib/Utilities/FBAlertsMonitor.m#L17
const ATOM_INITIAL_WAIT_MS = 2100;
const OBSTRUCTING_ALERT_PRESENCE_CHECK_INTERVAL_MS = 500;
const ON_OBSTRUCTING_ALERT_EVENT = 'alert';
const ON_APP_CRASH_EVENT = 'app_crash';
const VISIBLE = 'visible';
const INVISIBLE = 'invisible';
const DETECT = 'detect';
const VISIBILITIES = [VISIBLE, INVISIBLE, DETECT];
// The position of Safari's tab (search bar).
// Since iOS 15, the bar is the bottom by default.
const TAB_BAR_POSITION_TOP = 'top';
const TAB_BAR_POSITION_BOTTOM = 'bottom';
const TAB_BAR_POSSITIONS = [TAB_BAR_POSITION_TOP, TAB_BAR_POSITION_BOTTOM];
/**
* 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
*/
async function setFrame(frame) {
if (!this.isWebContext()) {
throw new driver_1.errors.NotImplementedError();
}
if (lodash_1.default.isNull(frame)) {
this.curWebFrames = [];
this.log.debug('Leaving web frame and going back to default content');
return;
}
if (hasElementId(frame)) {
const atomsElement = this.getAtomsElement(frame);
const value = await this.executeAtom('get_frame_window', [atomsElement]);
this.log.debug(`Entering new web frame: '${value.WINDOW}'`);
this.curWebFrames.unshift(value.WINDOW);
}
else {
const atom = lodash_1.default.isNumber(frame) ? 'frame_by_index' : 'frame_by_id_or_name';
const value = await this.executeAtom(atom, [frame]);
if (lodash_1.default.isNull(value) || lodash_1.default.isUndefined(value.WINDOW)) {
throw new driver_1.errors.NoSuchFrameError();
}
this.log.debug(`Entering new web frame: '${value.WINDOW}'`);
this.curWebFrames.unshift(value.WINDOW);
}
}
/**
* 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
*/
async function getCssProperty(propertyName, el) {
if (!this.isWebContext()) {
throw new driver_1.errors.NotImplementedError();
}
const atomsElement = this.getAtomsElement(el);
return await this.executeAtom('get_value_of_css_property', [atomsElement, propertyName]);
}
/**
* 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
*/
async function submit(el) {
if (!this.isWebContext()) {
throw new driver_1.errors.NotImplementedError();
}
const atomsElement = this.getAtomsElement(el);
await this.executeAtom('submit', [atomsElement]);
}
/**
* Refreshes the current page.
*
* @group Mobile Web Only
* @throws {errors.NotImplementedError} If not in a web context
*/
async function refresh() {
if (!this.isWebContext()) {
throw new driver_1.errors.NotImplementedError();
}
await this.remote.execute('window.location.reload()');
}
/**
* Gets the current page URL.
*
* @group Mobile Web Only
* @throws {errors.NotImplementedError} If not in a web context
*/
async function getUrl() {
if (!this.isWebContext()) {
throw new driver_1.errors.NotImplementedError();
}
return await this.remote.execute('window.location.href');
}
/**
* Gets the current page title.
*
* @group Mobile Web Only
* @throws {errors.NotImplementedError} If not in a web context
*/
async function title() {
if (!this.isWebContext()) {
throw new driver_1.errors.NotImplementedError();
}
return await this.remote.execute('window.document.title');
}
/**
* 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
*/
async function getCookies() {
if (!this.isWebContext()) {
throw new driver_1.errors.NotImplementedError();
}
// get the cookies from the remote debugger, or an empty object
const { cookies } = await this.remote.getCookies();
// the value is URI encoded, so decode it safely
return cookies.map((cookie) => {
if (!lodash_1.default.isEmpty(cookie.value)) {
try {
cookie.value = decodeURI(cookie.value);
}
catch (error) {
this.log.debug(`Cookie ${cookie.name} was not decoded successfully. Cookie value: ${cookie.value}`);
this.log.warn(error);
// Keep the original value
}
}
return 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
*/
async function setCookie(cookie) {
if (!this.isWebContext()) {
throw new driver_1.errors.NotImplementedError();
}
const clonedCookie = lodash_1.default.clone(cookie);
// if `path` field is not specified, Safari will not update cookies as expected; eg issue #1708
if (!clonedCookie.path) {
clonedCookie.path = '/';
}
const jsCookie = createJSCookie(clonedCookie.name, clonedCookie.value, {
expires: lodash_1.default.isNumber(clonedCookie.expiry)
? new Date(clonedCookie.expiry * 1000).toUTCString()
: clonedCookie.expiry,
path: clonedCookie.path,
domain: clonedCookie.domain,
httpOnly: clonedCookie.httpOnly,
secure: clonedCookie.secure,
});
const script = `document.cookie = ${JSON.stringify(jsCookie)}`;
await this.executeAtom('execute_script', [script, []]);
}
/**
* 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
*/
async function deleteCookie(cookieName) {
if (!this.isWebContext()) {
throw new driver_1.errors.NotImplementedError();
}
const cookies = await this.getCookies();
const cookie = cookies.find(({ name }) => name === cookieName);
if (!cookie) {
this.log.debug(`Cookie '${cookieName}' not found. Ignoring.`);
return;
}
await _deleteCookie.bind(this)(cookie);
}
/**
* Deletes all cookies for the current page.
*
* @group Mobile Web Only
* @throws {errors.NotImplementedError} If not in a web context
*/
async function deleteCookies() {
if (!this.isWebContext()) {
throw new driver_1.errors.NotImplementedError();
}
const cookies = await this.getCookies();
await bluebird_1.default.all(cookies.map((cookie) => _deleteCookie.bind(this)(cookie)));
}
/**
* Caches a web element for later use.
*
* @param el - Element to cache
* @returns The cached element wrapper
*/
function cacheWebElement(el) {
if (!lodash_1.default.isPlainObject(el)) {
return el;
}
const elId = support_1.util.unwrapElement(el);
if (!isValidElementIdentifier(elId)) {
return el;
}
// In newer debugger releases element identifiers look like `:wdc:1628151649325`
// We assume it is safe to use these to identify cached elements
const cacheId = lodash_1.default.includes(elId, ':') ? elId : support_1.util.uuidV4();
this.webElementsCache.set(cacheId, elId);
return support_1.util.wrapElement(cacheId);
}
/**
* Recursively caches all web elements in a response object.
*
* @param response - Response object that may contain web elements
* @returns Response with cached element wrappers
*/
function cacheWebElements(response) {
const toCached = (v) => (lodash_1.default.isArray(v) || lodash_1.default.isPlainObject(v)) ? this.cacheWebElements(v) : v;
if (lodash_1.default.isArray(response)) {
return response.map(toCached);
}
else if (lodash_1.default.isPlainObject(response)) {
const result = { ...response, ...this.cacheWebElement(response) };
return lodash_1.default.toPairs(result).reduce((acc, [key, value]) => {
acc[key] = toCached(value);
return acc;
}, {});
}
return response;
}
/**
* 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.
*/
async function executeAtom(atom, args, alwaysDefaultFrame = false) {
const frames = alwaysDefaultFrame === true ? [] : this.curWebFrames;
const promise = this.remote.executeAtom(atom, args, frames);
return await this.waitForAtom(promise);
}
/**
* Executes a Selenium atom script asynchronously.
*
* @param atom - Name of the atom to execute
* @param args - Arguments to pass to the atom
*/
async function executeAtomAsync(atom, args) {
// save the resolve and reject methods of the promise to be waited for
const promise = new bluebird_1.default((resolve, reject) => {
this.asyncPromise = { resolve, reject };
});
await this.remote.executeAtomAsync(atom, args, this.curWebFrames);
return await this.waitForAtom(promise);
}
/**
* 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
*/
function getAtomsElement(elOrId) {
const elId = support_1.util.unwrapElement(elOrId);
if (!this.webElementsCache?.has(elId)) {
throw new driver_1.errors.StaleElementReferenceError();
}
return { ELEMENT: this.webElementsCache.get(elId) };
}
/**
* 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
*/
function convertElementsForAtoms(args = []) {
return args.map((arg) => {
if (hasElementId(arg)) {
try {
return this.getAtomsElement(arg);
}
catch (err) {
if (!(0, driver_1.isErrorType)(err, driver_1.errors.StaleElementReferenceError)) {
throw err;
}
}
return arg;
}
return lodash_1.default.isArray(arg) ? this.convertElementsForAtoms(arg) : arg;
});
}
/**
* Extracts the element ID from an element object.
*
* @param element - Element object
* @returns Element ID if found, undefined otherwise
*/
function getElementId(element) {
return element?.ELEMENT || element?.[W3C_WEB_ELEMENT_IDENTIFIER];
}
/**
* Checks if an object has an element ID (type guard).
*
* @param element - Object to check
* @returns True if the object has an element ID
*/
function hasElementId(element) {
return (support_1.util.hasValue(element) &&
(support_1.util.hasValue(element.ELEMENT) || support_1.util.hasValue(element[W3C_WEB_ELEMENT_IDENTIFIER])));
}
/**
* 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
*/
async function findWebElementOrElements(strategy, selector, many, ctx) {
const contextElement = lodash_1.default.isNil(ctx) ? null : this.getAtomsElement(ctx);
const atomName = many ? 'find_elements' : 'find_element_fragment';
let element;
const doFind = async () => {
element = await this.executeAtom(atomName, [strategy, selector, contextElement]);
return !lodash_1.default.isNull(element);
};
try {
await this.implicitWaitForCondition(doFind);
}
catch (err) {
if (err.message && lodash_1.default.isFunction(err.message.match) && err.message.match(/Condition unmet/)) {
// condition was not met setting res to empty array
element = [];
}
else {
throw err;
}
}
if (many) {
return this.cacheWebElements(element);
}
if (lodash_1.default.isEmpty(element)) {
throw new driver_1.errors.NoSuchElementError();
}
return this.cacheWebElements(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
*/
async function clickWebCoords(x, y) {
const { x: translatedX, y: translatedY } = await this.translateWebCoords(x, y);
await this.mobileTap(translatedX, translatedY);
}
/**
* 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
*/
async function getSafariIsIphone() {
if (lodash_1.default.isBoolean(this._isSafariIphone)) {
return this._isSafariIphone;
}
try {
const userAgent = await this.execute('return navigator.userAgent');
this._isSafariIphone = userAgent.toLowerCase().includes('iphone');
}
catch (err) {
this.log.warn(`Unable to find device type from useragent. Assuming iPhone`);
this.log.debug(`Error: ${err.message}`);
}
return this._isSafariIphone ?? true;
}
/**
* Gets the device size from Safari's perspective.
*
* Returns normalized dimensions (width <= height).
*
* @returns Device size with width and height
*/
async function getSafariDeviceSize() {
const script = 'return {height: window.screen.availHeight * window.devicePixelRatio, width: window.screen.availWidth * window.devicePixelRatio};';
const { width, height } = await this.execute(script);
const [normHeight, normWidth] = height > width ? [height, width] : [width, height];
return {
width: normWidth,
height: normHeight,
};
}
/**
* 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
*/
async function getSafariIsNotched() {
if (lodash_1.default.isBoolean(this._isSafariNotched)) {
return this._isSafariNotched;
}
try {
const { width, height } = await this.getSafariDeviceSize();
for (const device of NOTCHED_DEVICE_SIZES) {
if (device.w === width && device.h === height) {
this._isSafariNotched = true;
}
}
}
catch (err) {
this.log.warn(`Unable to find device type from dimensions. Assuming the device is not notched`);
this.log.debug(`Error: ${err.message}`);
}
return this._isSafariNotched ?? false;
}
/**
* 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
*/
async function getExtraTranslateWebCoordsOffset(wvPos, realDims) {
let topOffset = 0;
let bottomOffset = 0;
const isIphone = await this.getSafariIsIphone();
// No need to check whether the Smart App Banner or Tab Bar is visible or not
// if already defined by nativeWebTapTabBarVisibility or nativeWebTapSmartAppBannerVisibility in settings.
const { nativeWebTapTabBarVisibility, nativeWebTapSmartAppBannerVisibility, safariTabBarPosition = support_1.util.compareVersions(this.opts.platformVersion, '>=', '15.0') &&
isIphone
? TAB_BAR_POSITION_BOTTOM
: TAB_BAR_POSITION_TOP, } = this.settings.getSettings();
let tabBarVisibility = lodash_1.default.lowerCase(String(nativeWebTapTabBarVisibility));
let bannerVisibility = lodash_1.default.lowerCase(String(nativeWebTapSmartAppBannerVisibility));
const tabBarPosition = lodash_1.default.lowerCase(String(safariTabBarPosition));
if (!VISIBILITIES.includes(tabBarVisibility)) {
tabBarVisibility = DETECT;
}
if (!VISIBILITIES.includes(bannerVisibility)) {
bannerVisibility = DETECT;
}
if (!TAB_BAR_POSSITIONS.includes(tabBarPosition)) {
throw new driver_1.errors.InvalidArgumentError(`${safariTabBarPosition} is invalid as Safari tab bar position. Available positions are ${TAB_BAR_POSSITIONS}.`);
}
const isNotched = isIphone && (await this.getSafariIsNotched());
const orientation = realDims.h > realDims.w ? 'PORTRAIT' : 'LANDSCAPE';
const notchOffset = isNotched
? support_1.util.compareVersions(this.opts.platformVersion, '=', '13.0')
? IPHONE_X_NOTCH_OFFSET_IOS_13
: IPHONE_X_NOTCH_OFFSET_IOS
: 0;
const isScrolled = await this.execute('return document.documentElement.scrollTop > 0');
if (isScrolled) {
topOffset = IPHONE_SCROLLED_TOP_BAR_HEIGHT + notchOffset;
if (isNotched) {
topOffset -= IPHONE_X_SCROLLED_OFFSET;
}
// If the iPhone is landscape then there is no top bar
if (orientation === 'LANDSCAPE' && isIphone) {
topOffset = 0;
}
}
else {
topOffset = tabBarPosition === TAB_BAR_POSITION_BOTTOM ? 0 : IPHONE_TOP_BAR_HEIGHT;
topOffset += notchOffset;
this.log.debug(`tabBarPosition and topOffset: ${tabBarPosition}, ${topOffset}`);
if (isIphone) {
if (orientation === 'PORTRAIT') {
// The bottom bar is only visible when portrait
bottomOffset = IPHONE_BOTTOM_BAR_OFFSET;
}
else {
topOffset = IPHONE_LANDSCAPE_TOP_BAR_HEIGHT;
}
}
if (orientation === 'LANDSCAPE' || !isIphone) {
if (tabBarVisibility === VISIBLE) {
topOffset += TAB_BAR_OFFSET;
}
else if (tabBarVisibility === DETECT) {
// Tabs only appear if the device is landscape or if it's an iPad so we only check visibility in this case
// Assume that each tab bar is a WebView
const contextsAndViews = await this.getContextsAndViews();
const tabs = contextsAndViews.filter((ctx) => ctx.id.startsWith('WEBVIEW_'));
if (tabs.length > 1) {
this.log.debug(`Found ${tabs.length} tabs. Assuming the tab bar is visible`);
topOffset += TAB_BAR_OFFSET;
}
}
}
}
topOffset += await this.getExtraNativeWebTapOffset(isIphone, bannerVisibility);
wvPos.y += topOffset;
realDims.h -= topOffset + bottomOffset;
}
/**
* 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
*/
async function getExtraNativeWebTapOffset(isIphone, bannerVisibility) {
let offset = 0;
if (bannerVisibility === VISIBLE) {
offset += isIphone
? IPHONE_WEB_COORD_SMART_APP_BANNER_OFFSET
: IPAD_WEB_COORD_SMART_APP_BANNER_OFFSET;
}
else if (bannerVisibility === DETECT) {
// try to see if there is an Smart App Banner
const banners = await this.findNativeElementOrElements('accessibility id', 'Close app download offer', true);
if (banners?.length) {
offset += isIphone
? IPHONE_WEB_COORD_SMART_APP_BANNER_OFFSET
: IPAD_WEB_COORD_SMART_APP_BANNER_OFFSET;
}
}
this.log.debug(`Additional native web tap offset computed: ${offset}`);
return offset;
}
/**
* 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
*/
async function nativeWebTap(el) {
const atomsElement = this.getAtomsElement(el);
// if strict native tap, do not try to do it with WDA directly
if (!(this.settings.getSettings()).nativeWebTapStrict &&
(await tapWebElementNatively.bind(this)(atomsElement))) {
return;
}
this.log.warn('Unable to do simple native web tap. Attempting to convert coordinates');
const [size, coordinates] = await bluebird_1.default.Promise.all([
this.executeAtom('get_size', [atomsElement]),
this.executeAtom('get_top_left_coordinates', [atomsElement]),
]);
const { width, height } = size;
const { x, y } = coordinates;
await this.clickWebCoords(x + width / 2, y + height / 2);
}
/**
* 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
*/
async function translateWebCoords(x, y) {
this.log.debug(`Translating web coordinates (${JSON.stringify({ x, y })}) to native coordinates`);
if (this.webviewCalibrationResult) {
this.log.debug(`Will use the recent calibration result: ${JSON.stringify(this.webviewCalibrationResult)}`);
const { offsetX, offsetY, pixelRatioX, pixelRatioY } = this.webviewCalibrationResult;
const cmd = '(function () {return {innerWidth: window.innerWidth, innerHeight: window.innerHeight, ' +
'outerWidth: window.outerWidth, outerHeight: window.outerHeight}; })()';
const wvDims = await this.remote.execute(cmd);
// https://tripleodeon.com/2011/12/first-understand-your-screen/
const shouldApplyPixelRatio = wvDims.innerWidth > wvDims.outerWidth
|| wvDims.innerHeight > wvDims.outerHeight;
return {
x: offsetX + x * (shouldApplyPixelRatio ? pixelRatioX : 1),
y: offsetY + y * (shouldApplyPixelRatio ? pixelRatioY : 1),
};
}
else {
this.log.debug(`Using the legacy algorithm for coordinates translation. ` +
`Invoke 'mobile: calibrateWebToRealCoordinatesTranslation' to change that.`);
}
// absolutize web coords
let webview;
try {
webview = await (0, asyncbox_1.retryInterval)(5, 100, async () => await this.findNativeElementOrElements('class name', 'XCUIElementTypeWebView', false));
}
catch { }
if (!webview) {
throw new Error(`No WebView found. Unable to translate web coordinates for native web tap.`);
}
webview = support_1.util.unwrapElement(webview);
const rect = await this.proxyCommand(`/element/${webview}/rect`, 'GET');
const wvPos = { x: rect.x, y: rect.y };
const realDims = { w: rect.width, h: rect.height };
const cmd = '(function () { return {w: window.innerWidth, h: window.innerHeight}; })()';
const wvDims = await this.remote.execute(cmd);
// keep track of implicit wait, and set locally to 0
// https://github.com/appium/appium/issues/14988
const implicitWaitMs = this.implicitWaitMs;
this.setImplicitWait(0);
try {
await this.getExtraTranslateWebCoordsOffset(wvPos, realDims);
}
finally {
this.setImplicitWait(implicitWaitMs);
}
if (!wvDims || !realDims || !wvPos) {
throw new Error(`Web coordinates ${JSON.stringify({ x, y })} cannot be translated into real coordinates. ` +
`Try to invoke 'mobile: calibrateWebToRealCoordinatesTranslation' or consider translating the ` +
`coordinates from the client code.`);
}
const xRatio = realDims.w / wvDims.w;
const yRatio = realDims.h / wvDims.h;
const newCoords = {
x: wvPos.x + Math.round(xRatio * x),
y: wvPos.y + Math.round(yRatio * y),
};
// additional logging for coordinates, since it is sometimes broken
// see https://github.com/appium/appium/issues/9159
this.log.debug(`Converted coordinates: ${JSON.stringify(newCoords)}`);
this.log.debug(` rect: ${JSON.stringify(rect)}`);
this.log.debug(` wvPos: ${JSON.stringify(wvPos)}`);
this.log.debug(` realDims: ${JSON.stringify(realDims)}`);
this.log.debug(` wvDims: ${JSON.stringify(wvDims)}`);
this.log.debug(` xRatio: ${JSON.stringify(xRatio)}`);
this.log.debug(` yRatio: ${JSON.stringify(yRatio)}`);
this.log.debug(`Converted web coords ${JSON.stringify({ x, y })} into real coords ${JSON.stringify(newCoords)}`);
return newCoords;
}
/**
* Checks if an alert is currently present.
*
* @returns True if an alert is present, false otherwise
*/
async function checkForAlert() {
return lodash_1.default.isString(await this.getAlertText());
}
/**
* 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
*/
async function waitForAtom(promise) {
const timer = new support_1.timing.Timer().start();
const atomWaitTimeoutMs = lodash_1.default.isNumber(this.opts.webviewAtomWaitTimeout) && this.opts.webviewAtomWaitTimeout > 0
? this.opts.webviewAtomWaitTimeout
: ATOM_WAIT_TIMEOUT_MS;
// need to check for alert while the atom is being executed.
// so notify ourselves when it happens
const timedAtomPromise = bluebird_1.default.resolve(promise).timeout(atomWaitTimeoutMs);
const handlePromiseError = async (p) => {
try {
return await p;
}
catch (err) {
const originalError = err instanceof bluebird_1.AggregateError ? err[0] : err;
this.log.debug(`Error received while executing atom: ${originalError.message}`);
throw (originalError instanceof bluebird_1.TimeoutError
? (await generateAtomTimeoutError.bind(this)(timer))
: originalError);
}
};
// if the atom promise is fulfilled within ATOM_INITIAL_WAIT_MS
// then we don't need to check for an alert presence
await handlePromiseError(bluebird_1.default.any([bluebird_1.default.delay(ATOM_INITIAL_WAIT_MS), timedAtomPromise]));
if (timedAtomPromise.isFulfilled()) {
return await timedAtomPromise;
}
// ...otherwise make sure there is no unexpected alert covering the element
this._waitingAtoms.count++;
let onAlertCallback;
let onAppCrashCallback;
try {
// only restart the monitor if it is not running already
if (this._waitingAtoms.alertMonitor.isResolved()) {
this._waitingAtoms.alertMonitor = bluebird_1.default.resolve((async () => {
while (this._waitingAtoms.count > 0) {
try {
if (await this.checkForAlert()) {
this._waitingAtoms.alertNotifier.emit(ON_OBSTRUCTING_ALERT_EVENT);
}
}
catch (err) {
if ((0, driver_1.isErrorType)(err, driver_1.errors.InvalidElementStateError)) {
this._waitingAtoms.alertNotifier.emit(ON_APP_CRASH_EVENT, err);
}
}
await bluebird_1.default.delay(OBSTRUCTING_ALERT_PRESENCE_CHECK_INTERVAL_MS);
}
})());
}
return await new bluebird_1.default((resolve, reject) => {
onAlertCallback = () => reject(new driver_1.errors.UnexpectedAlertOpenError());
onAppCrashCallback = reject;
this._waitingAtoms.alertNotifier.once(ON_OBSTRUCTING_ALERT_EVENT, onAlertCallback);
this._waitingAtoms.alertNotifier.once(ON_APP_CRASH_EVENT, onAppCrashCallback);
handlePromiseError(timedAtomPromise)
.then(resolve)
.catch(reject);
});
}
finally {
if (onAlertCallback) {
this._waitingAtoms.alertNotifier.removeListener(ON_OBSTRUCTING_ALERT_EVENT, onAlertCallback);
}
if (onAppCrashCallback) {
this._waitingAtoms.alertNotifier.removeListener(ON_APP_CRASH_EVENT, onAppCrashCallback);
}
this._waitingAtoms.count--;
}
}
/**
* Performs browser navigation (back, forward, etc.) using history API.
*
* @param navType - Navigation type (e.g., 'back', 'forward')
*/
async function mobileWebNav(navType) {
this.remote.allowNavigationWithoutReload = true;
try {
await this.executeAtom('execute_script', [`history.${navType}();`, null]);
}
finally {
this.remote.allowNavigationWithoutReload = false;
}
}
/**
* Gets the base URL for accessing WDA HTTP endpoints.
*
* @returns The base URL (e.g., 'http://127.0.0.1:8100')
*/
function getWdaLocalhostRoot() {
const wdaPort = () => {
try {
return this.wda.url?.port;
}
catch {
// this.wda could raise an error when that was not initialized yet.
return null;
}
};
const remotePort = ((this.isRealDevice() ? this.opts.wdaRemotePort : null)
?? wdaPort()
?? this.opts.wdaLocalPort)
|| 8100;
const remoteIp = this.opts.wdaBindingIP ?? '127.0.0.1';
return `http://${remoteIp}:${remotePort}`;
}
/**
* 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
*/
async function mobileCalibrateWebToRealCoordinatesTranslation() {
if (!this.isWebContext()) {
throw new driver_1.errors.NotImplementedError('This API can only be called from a web context');
}
const currentUrl = await this.getUrl();
await this.setUrl(`${this.getWdaLocalhostRoot()}/calibrate`);
const { width, height } = await this.proxyCommand('/window/rect', 'GET');
const [centerX, centerY] = [width / 2, height / 2];
const errorPrefix = 'Cannot determine web view coordinates offset. Are you in Safari context?';
const performCalibrationTap = async (tapX, tapY) => {
await this.mobileTap(tapX, tapY);
let result;
try {
const title = await this.title();
this.log.debug(JSON.stringify(title));
result = lodash_1.default.isPlainObject(title) ? title : JSON.parse(title);
}
catch (e) {
throw new Error(`${errorPrefix} Original error: ${e.message}`);
}
const { x, y } = result;
if (!lodash_1.default.isInteger(x) || !lodash_1.default.isInteger(y)) {
throw new Error(errorPrefix);
}
return result;
};
await (0, asyncbox_1.retryInterval)(6, 500, async () => {
const { x: x0, y: y0 } = await performCalibrationTap(centerX - CALIBRATION_TAP_DELTA_PX, centerY - CALIBRATION_TAP_DELTA_PX);
const { x: x1, y: y1 } = await performCalibrationTap(centerX + CALIBRATION_TAP_DELTA_PX, centerY + CALIBRATION_TAP_DELTA_PX);
const pixelRatioX = CALIBRATION_TAP_DELTA_PX * 2 / (x1 - x0);
const pixelRatioY = CALIBRATION_TAP_DELTA_PX * 2 / (y1 - y0);
this.webviewCalibrationResult = {
offsetX: centerX - CALIBRATION_TAP_DELTA_PX - x0 * pixelRatioX,
offsetY: centerY - CALIBRATION_TAP_DELTA_PX - y0 * pixelRatioY,
pixelRatioX,
pixelRatioY,
};
});
if (currentUrl) {
// restore the previous url
await this.setUrl(currentUrl);
}
const result = this.webviewCalibrationResult;
return {
...result,
offsetX: Math.round(result.offsetX),
offsetY: Math.round(result.offsetY),
};
}
/**
* 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
*/
async function mobileUpdateSafariPreferences(preferences) {
const simulator = utils_1.assertSimulator.call(this, 'Updating Safari preferences');
if (!lodash_1.default.isPlainObject(preferences)) {
throw new driver_1.errors.InvalidArgumentError('"preferences" argument must be a valid object');
}
this.log.debug(`About to update Safari preferences: ${JSON.stringify(preferences)}`);
await simulator.updateSafariSettings(preferences);
}
/**
* Generates a timeout error with detailed information about atom execution failure.
*
* @param timer - Timer instance to get duration from
* @returns Timeout error with descriptive message
*/
async function generateAtomTimeoutError(timer) {
let message = (`The remote Safari debugger did not respond to the requested ` +
`command after ${timer.getDuration().asMilliSeconds}ms. `);
message += (await this._remote?.isJavascriptExecutionBlocked()) ? (`It appears that JavaScript execution is blocked, ` +
`which could be caused by either a modal dialog obstructing the current page, ` +
`or a JavaScript routine monopolizing the event loop.`) : (`However, the debugger still responds to JavaScript commands, ` +
`which suggests that the provided atom script is taking too long to execute.`);
if (lodash_1.default.isUndefined(this.opts.webviewAtomWaitTimeout)) {
message += (` You may also consider adjusting the timeout by setting the ` +
`'webviewAtomWaitTimeout' driver capability.`);
}
return new driver_1.errors.TimeoutError(message);
}
/**
* Attempts to tap a web element using native element matching.
*
* Tries to find a native element by matching text content, then taps it directly.
*
* @param atomsElement - Atoms-compatible element to tap
* @returns True if the native tap was successful, false otherwise
*/
async function tapWebElementNatively(atomsElement) {
// try to get the text of the element, which will be accessible in the
// native context
try {
const [text1, text2] = await bluebird_1.default.all([
this.executeAtom('get_text', [atomsElement]),
this.executeAtom('get_attribute_value', [atomsElement, 'value'])
]);
const text = text1 || text2;
if (!text) {
return false;
}
const els = await this.findNativeElementOrElements('accessibility id', text, true);
if (![1, 2].includes(els.length)) {
return false;
}
const el = els[0];
// use tap because on iOS 11.2 and below `nativeClick` crashes WDA
const rect = await this.proxyCommand(`/element/${support_1.util.unwrapElement(el)}/rect`, 'GET');
if (els.length > 1) {
const el2 = els[1];
const rect2 = await this.proxyCommand(`/element/${support_1.util.unwrapElement(el2)}/rect`, 'GET');
if (rect.x !== rect2.x || rect.y !== rect2.y
|| rect.width !== rect2.width || rect.height !== rect2.height) {
// These 2 native elements are not referring to the same web element
return false;
}
}
await this.mobileTap(rect.x + rect.width / 2, rect.y + rect.height / 2);
return true;
}
catch (err) {
// any failure should fall through and trigger the more elaborate
// method of clicking
this.log.warn(`Error attempting to click: ${err.message}`);
}
return false;
}
/**
* Validates if a value is a valid element identifier.
*
* @param id - Value to validate
* @returns True if the value is a valid element identifier
*/
function isValidElementIdentifier(id) {
if (!lodash_1.default.isString(id) && !lodash_1.default.isNumber(id)) {
return false;
}
if (lodash_1.default.isString(id) && lodash_1.default.isEmpty(id)) {
return false;
}
if (lodash_1.default.isNumber(id) && isNaN(id)) {
return false;
}
return true;
}
/**
* Creates a JavaScript cookie string.
*
* @param key - Cookie name
* @param value - Cookie value
* @param options - Cookie options (expires, path, domain, secure, httpOnly)
* @returns Cookie string suitable for document.cookie
*/
function createJSCookie(key, value, options = {}) {
return [
encodeURIComponent(key),
'=',
value,
options.expires ? `; expires=${options.expires}` : '',
options.path ? `; path=${options.path}` : '',
options.domain ? `; domain=${options.domain}` : '',
options.secure ? '; secure' : '',
].join('');
}
/**
* Deletes a cookie via the remote debugger.
*
* @param cookie - Cookie object to delete
*/
async function _deleteCookie(cookie) {
const url = `http${cookie.secure ? 's' : ''}://${cookie.domain}${cookie.path}`;
return await this.remote.deleteCookie(cookie.name, url);
}
//# sourceMappingURL=web.js.map