@limrun/appium-xcuitest-driver 10.11.0-lim.4 → 10.14.6-lim.1

package/lib/commands/increase-contrast.ts

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

package/lib/commands/{iohid.js → iohid.ts}

@@ -1,5 +1,6 @@
 import {errors} from 'appium/driver';
 import {HIDUsageEvent, HIDPageEvent} from './hid-event';
+import type {XCUITestDriver} from '../driver';
 
 /**
  * Emulates triggering of the given low-level IO HID device event.
@@ -12,12 +13,16 @@ import {HIDUsageEvent, HIDPageEvent} from './hid-event';
  * - `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}
+ * @param page - The event page identifier
+ * @param usage - The event usage identifier (usages are defined per-page)
+ * @param durationSeconds - The event duration in float seconds (XCTest uses `0.005` for a single press event)
  */
-export async function mobilePerformIoHidEvent(page, usage, durationSeconds) {
+export async function mobilePerformIoHidEvent(
+  this: XCUITestDriver,
+  page: HIDPageEvent,
+  usage: number,
+  durationSeconds: number | string,
+): Promise<void> {
   if (!isHIDPageEvent(page)) {
     throw new errors.InvalidArgumentError(
       `'page' argument must be a valid HIDPageEvent identifier`,
@@ -30,15 +35,13 @@ export async function mobilePerformIoHidEvent(page, usage, 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});
+  await this.proxyCommand('/wda/performIoHidEvent', 'POST', {page, usage, duration});
 }
 
 /**
  * Type guard for {@linkcode HIDUsageEvent}
- * @param {any} value
- * @returns {value is HIDUsageEvent}
  */
-function isHIDUsageEvent(value) {
+function isHIDUsageEvent(value: any): value is keyof typeof HIDUsageEvent {
   if (typeof value === 'string') {
     value = parseInt(value, 10);
   }
@@ -50,10 +53,8 @@ function isHIDUsageEvent(value) {
 
 /**
  * Type guard for {@linkcode HIDPageEvent}
- * @param {any} value
- * @returns {value is HIDPageEvent}
- **/
-function isHIDPageEvent(value) {
+ */
+function isHIDPageEvent(value: any): value is HIDPageEvent {
   if (typeof value === 'string') {
     value = parseInt(value, 10);
   }
@@ -62,3 +63,4 @@ function isHIDPageEvent(value) {
   }
   return value in HIDPageEvent;
 }
+

package/lib/commands/keyboard.ts

@@ -0,0 +1,70 @@
+import _ from 'lodash';
+import type {XCUITestDriver} from '../driver';
+import type {KeyboardKey} from './types';
+
+/**
+ * Hides the keyboard.
+ *
+ * @deprecated
+ */
+export async function hideKeyboard(
+  this: XCUITestDriver,
+  strategy?: string,
+  ...possibleKeys: string[]
+): Promise<boolean> {
+  // last parameter is the session id
+  const keyNames = _.compact(possibleKeys.slice(0, -1)).map((x) => `${x}`);
+  await this.mobileHideKeyboard(keyNames);
+  return true;
+}
+
+/**
+ * Hides the keyboard using the specified key names.
+ *
+ * @param keys - Array of key names to use for dismissing the keyboard
+ */
+export async function mobileHideKeyboard(
+  this: XCUITestDriver,
+  keys: string[] = [],
+): Promise<void> {
+  await this.proxyCommand('/wda/keyboard/dismiss', 'POST', {
+    keyNames: keys.includes('done') ? keys : [...keys, 'done'],
+  });
+}
+
+/**
+ * Checks whether the keyboard is currently shown.
+ *
+ * @returns `true` if the keyboard is shown, `false` otherwise
+ */
+export async function isKeyboardShown(this: XCUITestDriver): Promise<boolean> {
+  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
+ * @param 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 elementId - 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(
+  this: XCUITestDriver,
+  keys: (KeyboardKey | string)[],
+  elementId: string | null = null,
+): Promise<void> {
+  const url = `/wda/element/${elementId || 0}/keyboardInput`;
+  await this.proxyCommand(url, 'POST', { keys });
+}
+

package/lib/commands/keychains.ts

@@ -0,0 +1,16 @@
+import {assertSimulator} from '../utils';
+import type {XCUITestDriver} from '../driver';
+
+/**
+ * Clears keychains on a simulated device.
+ *
+ * @throws {Error} If current device is not a Simulator or there was an error
+ * while clearing keychains.
+ * @group Simulator Only
+ */
+export async function mobileClearKeychains(
+  this: XCUITestDriver,
+): Promise<void> {
+  await assertSimulator.call(this, 'Keychain modification').clearKeychains();
+}
+

package/lib/commands/{localization.js → localization.ts}

@@ -1,6 +1,6 @@
-import {assertSimulator as _assertSimulator} from '../utils';
-
-const assertSimulator = (driver) => _assertSimulator.call(driver, 'Localization configuration');
+import {assertSimulator} from '../utils';
+import type {XCUITestDriver} from '../driver';
+import type {KeyboardOptions, LanguageOptions, LocaleOptions} from './types';
 
 /**
  * Change localization settings on the currently booted simulator
@@ -9,21 +9,31 @@ const assertSimulator = (driver) => _assertSimulator.call(driver, 'Localization
  * 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
+ * @param keyboard - Keyboard options
+ * @param language - Language options
+ * @param 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
+ * @returns `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);
+export async function mobileConfigureLocalization(
+  this: XCUITestDriver,
+  keyboard?: KeyboardOptions,
+  language?: LanguageOptions,
+  locale?: LocaleOptions,
+): Promise<boolean> {
+  ;
 
-  const localizationOptions = {locale, keyboard};
+  const localizationOptions: {
+    locale?: LocaleOptions;
+    keyboard?: KeyboardOptions;
+    language?: LanguageOptions & {skipSyncUiDialogTranslation?: boolean};
+  } = {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('appium-ios-simulator').Simulator} */ (this.device).configureLocalization(localizationOptions);
+  return await assertSimulator.call(this, 'Localization configuration')
+    .configureLocalization(localizationOptions);
 }
+

package/lib/commands/{location.js → location.ts}

@@ -3,6 +3,10 @@ import {errors} from 'appium/driver';
 import {util} from 'appium/support';
 import {AuthorizationStatus} from './enum';
 import { isIos17OrNewer } from '../utils';
+import type {XCUITestDriver} from '../driver';
+import type {Location} from '@appium/types';
+import type {LocationWithAltitude, WDALocationInfo} from './types';
+import type {Simulator} from 'appium-ios-simulator';
 
 /**
  * Returns location of the device under test.
@@ -17,12 +21,11 @@ import { isIos17OrNewer } from '../utils';
  * "mobile:getSimulatedLocation" if the simulated location has been previously set
  * "mobile:setSimulatedLocation" already.
  *
- * @returns {Promise<import('./types').LocationWithAltitude>}
+ * @returns Location with altitude
  * @throws {Error} If the device under test returns an error message.
  *                 i.e.: tvOS returns unsupported error
- * @this {XCUITestDriver}
  */
-export async function getGeoLocation() {
+export async function getGeoLocation(this: XCUITestDriver): Promise<LocationWithAltitude> {
   // 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)) {
@@ -41,9 +44,7 @@ export async function getGeoLocation() {
   // '/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')
-  );
+  const {authorizationStatus, latitude, longitude, altitude} = await this.proxyCommand('/wda/device/location', 'GET') as WDALocationInfo;
 
   // '3' is 'Always' in the privacy
   // https://developer.apple.com/documentation/corelocation/clauthorizationstatus
@@ -66,19 +67,21 @@ export async function getGeoLocation() {
  * iOS 17+ real device environment will be via "mobile:setSimulatedLocation" as
  * setting simulated location for XCTest session.
  *
- * @param {Partial<Location>} location
- * @this {XCUITestDriver}
+ * @param location - Location with latitude and longitude
  */
-export async function setGeoLocation(location) {
-  let {latitude, longitude} = location;
+export async function setGeoLocation(
+  this: XCUITestDriver,
+  location: Partial<Location>,
+): Promise<Location> {
+  const {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('appium-ios-simulator').Simulator} */ (this.device).setGeolocation(`${latitude}`, `${longitude}`);
-    return /** @type {Location} */ ({latitude, longitude, altitude: 0});
+    await (this.device as Simulator).setGeolocation(`${latitude}`, `${longitude}`);
+    return {latitude, longitude, altitude: 0};
   }
 
   if (isIos17OrNewer(this.opts)) {
@@ -88,7 +91,7 @@ export async function setGeoLocation(location) {
     const service = await services.startSimulateLocationService(this.opts.udid);
     try {
       service.setLocation(latitude, longitude);
-    } catch (e) {
+    } catch (e: any) {
       throw this.log.errorWithException(
         `Can't set the location on device '${this.opts.udid}'. Original error: ${e.message}`,
       );
@@ -97,7 +100,7 @@ export async function setGeoLocation(location) {
     }
   }
 
-  return /** @type {Location} */ ({latitude, longitude, altitude: 0});
+  return {latitude, longitude, altitude: 0};
 }
 
 /**
@@ -105,9 +108,8 @@ export async function setGeoLocation(location) {
  *
  * @throws {Error} If the device is simulator and iOS version is below 17,
  * or 'resetLocation' raises an error.
- * @this {XCUITestDriver}
  */
-export async function mobileResetLocationService() {
+export async function mobileResetLocationService(this: XCUITestDriver): Promise<void> {
   if (isIos17OrNewer(this.opts)) {
     this.log.info(`Proxying to mobile:resetSimulatedLocation method for iOS 17+`);
     await this.mobileResetSimulatedLocation();
@@ -121,7 +123,7 @@ export async function mobileResetLocationService() {
   const service = await services.startSimulateLocationService(this.opts.udid);
   try {
     service.resetLocation();
-  } catch (err) {
+  } catch (err: any) {
     throw this.log.errorWithException(
       `Failed to reset the location on the device on device '${this.opts.udid}'. ` +
         `Original error: ${err.message}`,
@@ -131,8 +133,3 @@ export async function mobileResetLocationService() {
   }
 }
 
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- * @typedef {import('./types').WDALocationInfo} WDALocationInfo
- * @typedef {import('@appium/types').Location} Location
- */

package/lib/commands/lock.ts

@@ -0,0 +1,43 @@
+import B from 'bluebird';
+import type {XCUITestDriver} from '../driver';
+
+/**
+ * Lock the device (and optionally unlock the device after a certain amount of time)
+ *
+ * @param 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
+ */
+export async function lock(
+  this: XCUITestDriver,
+  seconds?: number | string,
+): Promise<void> {
+  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
+ */
+export async function unlock(this: XCUITestDriver): Promise<void> {
+  await this.proxyCommand('/wda/unlock', 'POST');
+}
+
+/**
+ * Determine whether the device is locked
+ *
+ * @returns `true` if the device is locked, `false` otherwise
+ */
+export async function isLocked(this: XCUITestDriver): Promise<boolean> {
+  return await this.proxyCommand<any, boolean>('/wda/locked', 'GET');
+}
+