@limrun/appium-xcuitest-driver 10.4.3-lim.1

package/lib/commands/increase-contrast.js

@@ -0,0 +1,50 @@
+import _ from 'lodash';
+import {assertSimulator as _assertSimulator} from '../utils';
+import { errors } from 'appium/driver';
+
+const assertSimulator = _.partial(_assertSimulator, 'Content size ui command');
+
+const INCREASE_CONTRAST_CONFIG = [
+    'enabled',
+    'disabled',
+];
+
+/**
+ * Sets the increase contrast configuration for the given simulator.
+ *
+ * @since Xcode 15 (but lower xcode could have this command)
+ * @param {IncreaseContrastAction} increaseContrast valid increase contrast configuration value.
+ *                                                  Acceptable value is 'enabled' or 'disabled' with Xcode 16.2.
+ * @throws {Error} if the current platform does not support content size appearance changes
+ * @this {XCUITestDriver}
+ */
+export async function mobileSetIncreaseContrast(increaseContrast) {
+  const simulator = assertSimulator(this);
+
+  if (!INCREASE_CONTRAST_CONFIG.includes(_.lowerCase(increaseContrast))) {
+    throw new errors.InvalidArgumentError(
+      `The 'increaseContrast' value is expected to be one of ${INCREASE_CONTRAST_CONFIG.join(',')}`
+    );
+  }
+
+  await simulator.setIncreaseContrast(increaseContrast);
+}
+
+/**
+ * Retrieves the current increase contrast configuration value from the given simulator.
+ *
+ * @since Xcode 15 (but lower xcode could have this command)
+ * @returns {Promise<IncreaseContrastResult>} the contrast configuration value.
+ *                                      Possible return value is 'enabled', 'disabled',
+ *                                      'unsupported' or 'unknown' with Xcode 16.2.
+ * @this {XCUITestDriver}
+ */
+export async function mobileGetIncreaseContrast() {
+  return /** @type {IncreaseContrastResult} */ (await assertSimulator(this).getIncreaseContrast());
+}
+
+/**
+ * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
+ * @typedef {import('./types').IncreaseContrastAction} IncreaseContrastAction
+ * @typedef {import('./types').IncreaseContrastResult} IncreaseContrastResult
+ */

package/lib/commands/iohid.js

@@ -0,0 +1,64 @@
+import {errors} from 'appium/driver';
+import {HIDUsageEvent, HIDPageEvent} from './hid-event';
+
+/**
+ * Emulates triggering of the given low-level IO HID device event.
+ *
+ * Popular constants:
+ * - `kHIDPage_Consumer` = `0x0C`
+ * - `kHIDUsage_Csmr_VolumeIncrement` = `0xE9` (Volume Up)
+ * - `kHIDUsage_Csmr_VolumeDecrement` = `0xEA` (Volume Down)
+ * - `kHIDUsage_Csmr_Menu` = `0x40` (Home)
+ * - `kHIDUsage_Csmr_Power` = `0x30` (Power)
+ * - `kHIDUsage_Csmr_Snapshot` = `0x65` (Power + Home)
+ *
+ * @param {HIDPageEvent} page - The event page identifier
+ * @param {HIDUsageEvent} usage - The event usage identifier (usages are defined per-page)
+ * @param {number|string} durationSeconds - The event duration in float seconds (XCTest uses `0.005` for a single press event)
+ * @this {import('../driver').XCUITestDriver}
+ */
+export async function mobilePerformIoHidEvent(page, usage, durationSeconds) {
+  if (!isHIDPageEvent(page)) {
+    throw new errors.InvalidArgumentError(
+      `'page' argument must be a valid HIDPageEvent identifier`,
+    );
+  }
+  if (!isHIDUsageEvent(usage)) {
+    throw new errors.InvalidArgumentError(`'usage' must be a valid HIDUsageEvent identifier`);
+  }
+  const duration = parseFloat(String(durationSeconds));
+  if (Number.isNaN(duration)) {
+    throw new errors.InvalidArgumentError(`'durationSeconds' argument must be a valid number`);
+  }
+  return await this.proxyCommand('/wda/performIoHidEvent', 'POST', {page, usage, duration});
+}
+
+/**
+ * Type guard for {@linkcode HIDUsageEvent}
+ * @param {any} value
+ * @returns {value is HIDUsageEvent}
+ */
+function isHIDUsageEvent(value) {
+  if (typeof value === 'string') {
+    value = parseInt(value, 10);
+  }
+  if (Number.isNaN(value) || typeof value !== 'number') {
+    return false;
+  }
+  return value in HIDUsageEvent;
+}
+
+/**
+ * Type guard for {@linkcode HIDPageEvent}
+ * @param {any} value
+ * @returns {value is HIDPageEvent}
+ **/
+function isHIDPageEvent(value) {
+  if (typeof value === 'string') {
+    value = parseInt(value, 10);
+  }
+  if (Number.isNaN(value) || typeof value !== 'number') {
+    return false;
+  }
+  return value in HIDPageEvent;
+}

package/lib/commands/keyboard.js

@@ -0,0 +1,62 @@
+import _ from 'lodash';
+
+/**
+ * @this {XCUITestDriver}
+ * @deprecated
+ */
+export async function hideKeyboard(strategy, ...possibleKeys) {
+  // last parameter is the session id
+  const keyNames = _.compact(possibleKeys.slice(0, -1)).map((x) => `${x}`);
+  await this.mobileHideKeyboard(keyNames);
+  return true;
+}
+
+/**
+ * @this {XCUITestDriver}
+ * @param {string[]} keys
+ */
+export async function mobileHideKeyboard(keys = []) {
+  if (!keys.includes('done')) {
+    keys.push('done');
+  }
+  await this.proxyCommand('/wda/keyboard/dismiss', 'POST', {keyNames: keys});
+}
+
+/**
+ * @this {XCUITestDriver}
+ */
+export async function isKeyboardShown() {
+  try {
+    await this.findNativeElementOrElements('class name', 'XCUIElementTypeKeyboard', false);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Send keys to the given element or to the application under test.
+ * This API is not supported on tvOS
+ *
+ * @since Xcode 15/iOS 17
+ * @this {import('../driver').XCUITestDriver}
+ * @param {(Key|string)[]} keys Array of keys to type.
+ * Each item could either be a string, that represents a key itself (see
+ * https://developer.apple.com/documentation/xctest/xcuielement/1500604-typekey?language=objc
+ * and https://developer.apple.com/documentation/xctest/xcuikeyboardkey?language=objc)
+ * or a dictionary, if the key should also be entered with modifiers.
+ * @param {string?} [elementId=null] uuid of the element to send keys to.
+ * If the element is not provided then the keys will be sent to the current application.
+ */
+export async function mobileKeys(keys, elementId = null) {
+  const url = `/wda/element/${elementId || 0}/keyboardInput`;
+  return await this.proxyCommand(url, 'POST', { keys });
+}
+
+/**
+ * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
+ */
+
+/**
+ * @typedef {import('./types').KeyboardKey} Key
+ */

package/lib/commands/keychains.js

@@ -0,0 +1,18 @@
+import _ from 'lodash';
+import {assertSimulator as _assertSimulator} from '../utils';
+
+const assertSimulator = _.partial(_assertSimulator, 'Keychain modification');
+
+/**
+ * Clears keychains on a simulated device.
+ *
+ * @throws {Error} If current device is not a Simulator or there was an error
+ * while clearing keychains.
+ * @this {import('../driver').XCUITestDriver}
+ * @group Simulator Only
+ */
+export async function mobileClearKeychains() {
+  assertSimulator(this);
+
+  await /** @type {import('../driver').Simulator} */ (this.device).clearKeychains();
+}

package/lib/commands/localization.js

@@ -0,0 +1,30 @@
+import _ from 'lodash';
+import {assertSimulator as _assertSimulator} from '../utils';
+
+const assertSimulator = _.partial(_assertSimulator, 'Localization configuration');
+
+/**
+ * Change localization settings on the currently booted simulator
+ *
+ * The changed settings are only applied for _newly started_ applications and activities.
+ * Currently running applications will be unchanged. This means, for example, that the keyboard should be hidden and shown again in order to observe the changed layout, and corresponding apps must be restarted in order to observe their interface using the newly set locale/language.
+ *
+ * The driver performs no strict checking of the arguments (such as locale names). Be aware that an incorrect or invalid string may cause unexpected behavior.
+ * @param {import('./types').KeyboardOptions} [keyboard] - Keyboard options
+ * @param {import('./types').LanguageOptions} [language] - Language options
+ * @param {import('./types').LocaleOptions} [locale] - Locale options
+ * @throws {Error} If there was a failure while setting the preferences
+ * @returns {Promise<boolean>} `true` if any of settings has been successfully changed
+ * @group Simulator Only
+ * @this {import('../driver').XCUITestDriver}
+ */
+export async function mobileConfigureLocalization(keyboard, language, locale) {
+  assertSimulator(this);
+
+  const localizationOptions = {locale, keyboard};
+  if (language) {
+    // Assign skipSyncUiDialogTranslation: true option in order to avoid shutting down the WDA session
+    localizationOptions.language = Object.assign(language, {skipSyncUiDialogTranslation: true});
+  }
+  return await /** @type {import('../driver').Simulator} */ (this.device).configureLocalization(localizationOptions);
+}

package/lib/commands/location.js

@@ -0,0 +1,131 @@
+import {services} from 'appium-ios-device';
+import {errors} from 'appium/driver';
+import {util} from 'appium/support';
+import {AuthorizationStatus} from './enum';
+import { isIos17OrNewer } from '../utils';
+
+/**
+ * Returns location of the device under test.
+ * The device under test must allow the location services for WDA
+ * as 'Always' to get the location data correctly.
+ *
+ * The 'latitude', 'longitude' and 'altitude' could be zero even
+ * if the Location Services are set to 'Always', because the device
+ * needs some time to update the location data.
+ *
+ * For iOS 17, the return value could be the result of
+ * "mobile:getSimulatedLocation" if the simulated location has been previously set
+ * "mobile:setSimulatedLocation" already.
+ *
+ * @returns {Promise<import('./types').LocationWithAltitude>}
+ * @throws {Error} If the device under test returns an error message.
+ *                 i.e.: tvOS returns unsupported error
+ * @this {XCUITestDriver}
+ */
+export async function getGeoLocation() {
+  // Currently we proxy the setGeoLocation to mobile:setSimulatedLocation for iOS 17+.
+  // It would be helpful to address to use "mobile:getSimulatedLocation" for iOS 17+.
+  if (isIos17OrNewer(this.opts)) {
+    const {latitude, longitude} = await this.mobileGetSimulatedLocation();
+    if (latitude && longitude) {
+      this.log.debug('Returning the geolocation that has been previously set by mobile:setSimulatedLocation. ' +
+        'mobile:resetSimulatedLocation can reset the location configuration.');
+      return {latitude, longitude, altitude: 0};
+    }
+
+    this.log.warn(`No location was set by mobile:setSimulatedLocation. Trying to return the location from the device.`);
+  }
+
+  // Please do not change the way to get the location here with '/wda/simulatedLocation'
+  // endpoint because they could return different value before setting the simulated location.
+  // '/wda/device/location' returns current device location information,
+  // but '/wda/simulatedLocation' returns `null` values until the WDA process
+  // sets a simulated location. After setting the value, both returns the same values.
+  const {authorizationStatus, latitude, longitude, altitude} = /** @type {WDALocationInfo} */ (
+    await this.proxyCommand('/wda/device/location', 'GET')
+  );
+
+  // '3' is 'Always' in the privacy
+  // https://developer.apple.com/documentation/corelocation/clauthorizationstatus
+  if (authorizationStatus !== AuthorizationStatus.authorizedAlways) {
+    throw this.log.errorWithException(
+      `Location service must be set to 'Always' in order to ` +
+        `retrieve the current geolocation data. Please set it up manually via ` +
+        `'Settings > Privacy > Location Services -> WebDriverAgentRunner-Runner'. ` +
+        `Or please use 'mobile:getSimulatedLocation'/'mobile:setSimulatedLocation' commands ` +
+        `to simulate locations instead.`,
+    );
+  }
+
+  return {latitude, longitude, altitude};
+}
+
+/**
+ * Set location of the device under test.
+ *
+ * iOS 17+ real device environment will be via "mobile:setSimulatedLocation" as
+ * setting simulated location for XCTest session.
+ *
+ * @param {Partial<Location>} location
+ * @this {XCUITestDriver}
+ */
+export async function setGeoLocation(location) {
+  let {latitude, longitude} = location;
+
+  if (!util.hasValue(latitude) || !util.hasValue(longitude)) {
+    throw new errors.InvalidArgumentError(`Both latitude and longitude should be set`);
+  }
+
+  if (this.isSimulator()) {
+    await /** @type {import('../driver').Simulator} */ (this.device).setGeolocation(`${latitude}`, `${longitude}`);
+    return /** @type {Location} */ ({latitude, longitude, altitude: 0});
+  }
+
+  if (isIos17OrNewer(this.opts)) {
+    this.log.info(`Proxying to mobile:setSimulatedLocation method for iOS 17+ platform version`);
+    await this.mobileSetSimulatedLocation(latitude, longitude);
+  } else {
+    const service = await services.startSimulateLocationService(this.opts.udid);
+    try {
+      service.setLocation(latitude, longitude);
+    } catch (e) {
+      throw this.log.errorWithException(
+        `Can't set the location on device '${this.opts.udid}'. Original error: ${e.message}`,
+      );
+    } finally {
+      service.close();
+    }
+  }
+
+  return /** @type {Location} */ ({latitude, longitude, altitude: 0});
+}
+
+/**
+ * Reset the location service on real device.
+ * Raises not implemented error for simulator.
+ * @throws {Error} If the device is simulator, or 'resetLocation' raises an error.
+ * @this {XCUITestDriver}
+ */
+export async function mobileResetLocationService() {
+  if (this.isSimulator()) {
+    throw new errors.NotImplementedError();
+  }
+
+  const service = await services.startSimulateLocationService(this.opts.udid);
+  try {
+    service.resetLocation();
+  } catch (err) {
+    throw this.log.errorWithException(
+      `Failed to reset the location on the device on device '${this.opts.udid}'. ` +
+        `Original error: ${err.message}`,
+    );
+  } finally {
+    service.close();
+  }
+}
+
+/**
+ * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
+ * @typedef {import('./types').WDALocationInfo} WDALocationInfo
+ * @typedef {import('@appium/types').Location} Location
+ */

package/lib/commands/lock.js

@@ -0,0 +1,46 @@
+import B from 'bluebird';
+
+/**
+ * Lock the device (and optionally unlock the device after a certain amount of time)
+ *
+ * @param {number|string} [seconds] - the number of seconds after which to unlock the device. Set to `0` or leave empty to require manual unlock (do not automatically unlock).
+ * @defaultValue 0
+ * @this {XCUITestDriver}
+ */
+export async function lock(seconds) {
+  await this.proxyCommand('/wda/lock', 'POST');
+  if (isNaN(Number(seconds))) {
+    return;
+  }
+
+  const floatSeconds = parseFloat(String(seconds));
+  if (floatSeconds <= 0) {
+    return;
+  }
+
+  await B.delay(floatSeconds * 1000);
+  await this.proxyCommand('/wda/unlock', 'POST');
+}
+
+/**
+ * Unlock the device
+ *
+ * @this {XCUITestDriver}
+ */
+export async function unlock() {
+  await this.proxyCommand('/wda/unlock', 'POST');
+}
+
+/**
+ * Determine whether the device is locked
+ *
+ * @this {XCUITestDriver}
+ * @returns {Promise<boolean>} `true` if the device is locked, `false` otherwise
+ */
+export async function isLocked() {
+  return /** @type {boolean} */ (await this.proxyCommand('/wda/locked', 'GET'));
+}
+
+/**
+ * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
+ */