appium-xcuitest-driver 10.3.0 → 10.4.1

package/lib/commands/increase-contrast.js

@@ -9,41 +9,39 @@ const INCREASE_CONTRAST_CONFIG = [
     'disabled',
 ];
 
-export default {
-  /**
-   * 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}
-   */
-  async mobileSetIncreaseContrast(increaseContrast) {
-    const simulator = assertSimulator(this);
+/**
+ * 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(',')}`
-      );
-    }
+  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);
-  },
+  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}
-   */
-  async mobileGetIncreaseContrast() {
-    return /** @type {IncreaseContrastResult} */ (await assertSimulator(this).getIncreaseContrast());
-  },
-};
+/**
+ * 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

package/lib/commands/iohid.js

@@ -1,6 +1,38 @@
 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
@@ -30,37 +62,3 @@ function isHIDPageEvent(value) {
   }
   return value in HIDPageEvent;
 }
-
-export default {
-  /**
-   * 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}
-   */
-  async 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});
-  },
-};

package/lib/commands/keyboard.js

@@ -1,59 +1,57 @@
 import _ from 'lodash';
 
-export default {
-  /**
-   * @this {XCUITestDriver}
-   * @deprecated
-   */
-  async 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}
+ * @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
-   */
-  async mobileHideKeyboard(keys = []) {
-    if (!keys.includes('done')) {
-      keys.push('done');
-    }
-    await this.proxyCommand('/wda/keyboard/dismiss', 'POST', {keyNames: keys});
-  },
+/**
+ * @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}
-   */
-  async isKeyboardShown() {
-    try {
-      await this.findNativeElementOrElements('class name', 'XCUIElementTypeKeyboard', false);
-      return true;
-    } catch {
-      return false;
-    }
-  },
+/**
+ * @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.
-   */
-  async mobileKeys(keys, elementId = null) {
-    const url = `/wda/element/${elementId || 0}/keyboardInput`;
-    return await this.proxyCommand(url, 'POST', { keys });
-  },
-};
+/**
+ * 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

package/lib/commands/keychains.js

@@ -3,18 +3,16 @@ import {assertSimulator as _assertSimulator} from '../utils';
 
 const assertSimulator = _.partial(_assertSimulator, 'Keychain modification');
 
-export default {
-  /**
-   * 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
-   */
-  async mobileClearKeychains() {
-    assertSimulator(this);
+/**
+ * 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();
-  },
-};
+  await /** @type {import('../driver').Simulator} */ (this.device).clearKeychains();
+}

package/lib/commands/localization.js

@@ -3,30 +3,28 @@ import {assertSimulator as _assertSimulator} from '../utils';
 
 const assertSimulator = _.partial(_assertSimulator, 'Localization configuration');
 
-export default {
-  /**
-   * 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}
-   */
-  async mobileConfigureLocalization(keyboard, language, locale) {
-    assertSimulator(this);
+/**
+ * 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);
-  },
-};
+  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

@@ -4,127 +4,125 @@ import {util} from 'appium/support';
 import {AuthorizationStatus} from './enum';
 import { isIos17OrNewer } from '../utils';
 
-export default {
-  /**
-   * 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}
-   */
-  async 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.`);
+/**
+ * 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};
     }
 
-    // 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')
-    );
+    this.log.warn(`No location was set by mobile:setSimulatedLocation. Trying to return the location from the device.`);
+  }
 
-    // '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.`,
-      );
-    }
+  // 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')
+  );
 
-    return {latitude, longitude, altitude};
-  },
+  // '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.`,
+    );
+  }
 
-  /**
-   * 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}
-   */
-  async setGeoLocation(location) {
-    let {latitude, longitude} = location;
+  return {latitude, longitude, altitude};
+}
 
-    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});
-    }
+/**
+ * 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 (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();
-      }
-    }
+  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});
-  },
-
-  /**
-   * 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}
-   */
-  async mobileResetLocationService() {
-    if (this.isSimulator()) {
-      throw new errors.NotImplementedError();
-    }
+  }
 
+  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.resetLocation();
-    } catch (err) {
+      service.setLocation(latitude, longitude);
+    } catch (e) {
       throw this.log.errorWithException(
-        `Failed to reset the location on the device on device '${this.opts.udid}'. ` +
-          `Original error: ${err.message}`,
+        `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