appium-xcuitest-driver 10.14.2 → 10.14.4

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/{notifications.js → notifications.ts}

@@ -1,5 +1,8 @@
 import {errors} from 'appium/driver';
 import _ from 'lodash';
+import type {XCUITestDriver} from '../driver';
+import type {PushPayload, NotificationType} from './types';
+import type {Simulator} from 'appium-ios-simulator';
 
 /**
  * Simulates push notification delivery to a simulated device.
@@ -7,12 +10,16 @@ import _ from 'lodash';
  * **Only "remote" push notifications are supported.** VoIP, Complication, File Provider, and other types are unsupported.
  *
  * Supported in Xcode SDK 11.4+.
- * @param {string} bundleId - The bundle identifier of the target application
- * @param {import('./types').PushPayload} payload - Valid push payload.
+ *
+ * @param bundleId - The bundle identifier of the target application
+ * @param payload - Valid push payload.
  * @group Simulator Only
- * @this {XCUITestDriver}
  */
-export async function mobilePushNotification(bundleId, payload) {
+export async function mobilePushNotification(
+  this: XCUITestDriver,
+  bundleId: string,
+  payload: PushPayload,
+): Promise<void> {
   if (!this.isSimulator()) {
     throw new Error('This extension only works on Simulator');
   }
@@ -34,7 +41,7 @@ export async function mobilePushNotification(bundleId, payload) {
         `Got ${JSON.stringify(payload.aps)} instead`,
     );
   }
-  return await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).pushNotification({
+  await (this.device as Simulator).pushNotification({
     ...payload,
     'Simulator Target Bundle': bundleId,
   });
@@ -47,20 +54,21 @@ export async function mobilePushNotification(bundleId, payload) {
  * [`XCTNSNotificationExpectation`](https://developer.apple.com/documentation/xctest/xctnsnotificationexpectation?language=objc) and
  * [`XCTDarwinNotificationExpectation`](https://developer.apple.com/documentation/xctest/xctdarwinnotificationexpectation?language=objc) entities.
  *
- * @param {string} name - The name of the notification to expect
- * @param {import('./types').NotificationType} type - Which notification type to expect.
- * @param {number} timeoutSeconds - For how long to wait until the notification is delivered (in float seconds).
+ * @param name - The name of the notification to expect
+ * @param type - Which notification type to expect.
+ * @param timeoutSeconds - For how long to wait until the notification is delivered (in float seconds).
  * @throws A [`TimeoutError`](https://www.selenium.dev/selenium/docs/api/javascript/module/selenium-webdriver/lib/error_exports_TimeoutError.html) if the expected notification has not been delivered within the given timeout.
- * @this {XCUITestDriver}
  */
-export async function mobileExpectNotification(name, type = 'plain', timeoutSeconds = 60) {
-  return await this.proxyCommand('/wda/expectNotification', 'POST', {
+export async function mobileExpectNotification(
+  this: XCUITestDriver,
+  name: string,
+  type: NotificationType = 'plain',
+  timeoutSeconds: number = 60,
+): Promise<void> {
+  await this.proxyCommand('/wda/expectNotification', 'POST', {
     name,
     type,
     timeout: timeoutSeconds,
   });
 }
 
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

package/lib/commands/permissions.ts

@@ -0,0 +1,90 @@
+import _ from 'lodash';
+import {PermissionService} from './enum';
+import {assertSimulator as _assertSimulator} from '../utils';
+import type {XCUITestDriver} from '../driver';
+import type {PermissionState} from './types';
+import type {Simulator} from 'appium-ios-simulator';
+
+/**
+ * Resets the given permission for the active application under test.
+ * Works for both Simulator and real devices using Xcode SDK 11.4+
+ *
+ * @param service - One of the available service names. This could also be an integer protected resource identifier; see [this list](https://developer.apple.com/documentation/xctest/xcuiprotectedresource?language=objc)
+ * @throws If permission reset fails on the device.
+ */
+export async function mobileResetPermission(
+  this: XCUITestDriver,
+  service: PermissionService | number,
+): Promise<void> {
+  if (!service) {
+    throw new Error(`The 'service' option is expected to be present`);
+  }
+  let resource: number;
+  if (_.isString(service)) {
+    resource = PermissionService[_.toLower(service) as keyof typeof PermissionService];
+    if (!resource) {
+      throw new Error(
+        `The 'service' value must be one of ` + `${JSON.stringify(_.keys(PermissionService))}`,
+      );
+    }
+  } else if (_.isInteger(service)) {
+    resource = service;
+  } else {
+    throw new Error(
+      `The 'service' value must be either a string or an integer. ` +
+        `'${service}' is passed instead`,
+    );
+  }
+
+  await this.proxyCommand('/wda/resetAppAuth', 'POST', {resource});
+}
+
+/**
+ * Gets application permission state on a simulated device.
+ *
+ * **This method requires [WIX applesimutils](https://github.com/wix/AppleSimulatorUtils) to be installed on the Appium server host.**
+ *
+ * @param bundleId - Bundle identifier of the target application
+ * @param service - Service name
+ * @returns Either 'yes', 'no', 'unset' or 'limited'
+ * @throws If permission getting fails or the device is not a Simulator.
+ * @group Simulator Only
+ */
+export async function mobileGetPermission(
+  this: XCUITestDriver,
+  bundleId: string,
+  service: PermissionService,
+): Promise<PermissionState> {
+  if (!service) {
+    throw new Error(`The 'service' option is expected to be present`);
+  }
+  assertSimulator(this);
+
+  return await (this.device as Simulator).getPermission(
+    bundleId, String(service)
+  ) as PermissionState;
+}
+
+/**
+ * Set application permission state on Simulator.
+ *
+ * @param access - One or more access rules to set.
+ * @param bundleId - Bundle identifier of the target application
+ * @since Xcode SDK 11.4
+ * @throws If permission setting fails or the device is not a Simulator.
+ * @group Simulator Only
+ */
+export async function mobileSetPermissions(
+  this: XCUITestDriver,
+  access: Record<string, PermissionState>,
+  bundleId: string,
+): Promise<void> {
+  if (!_.isPlainObject(access)) {
+    throw new Error(`The 'access' option is expected to be a map`);
+  }
+  assertSimulator(this);
+
+  await (this.device as Simulator).setPermissions(bundleId, access);
+}
+
+const assertSimulator = (driver: XCUITestDriver) => _assertSimulator.call(driver, 'Permission-related operations');

package/lib/commands/{proxy-helper.js → proxy-helper.ts}

@@ -1,12 +1,13 @@
 import {errors, routeToCommandName} from 'appium/driver';
 import B from 'bluebird';
+import type {XCUITestDriver} from '../driver';
 
 const GET = 'GET';
 const POST = 'POST';
 const DELETE = 'DELETE';
-const SUPPORTED_METHODS = Object.freeze(new Set(/** @type {const} */ ([GET, POST, DELETE])));
+const SUPPORTED_METHODS = Object.freeze(new Set([GET, POST, DELETE] as const));
 
-const WDA_ROUTES = /** @type {const} */ ({
+const WDA_ROUTES = {
   '/wda/screen': {
     GET: 'getScreenInfo',
   },
@@ -43,22 +44,30 @@ const WDA_ROUTES = /** @type {const} */ ({
   '/wda/locked': {
     GET: 'isLocked',
   },
-});
+} as const;
+
+export type AllowedHttpMethod = 'GET' | 'POST' | 'DELETE';
 
 /**
  * Proxies a command to WebDriverAgent
- * @template [TReq=any]
- * @template [TRes=unknown]
- * @param {string} url
- * @param {AllowedHttpMethod} method
- * @param {TReq} [body]
- * @param {boolean} isSessionCommand
- * @this {import('../driver').XCUITestDriver}
- * @returns {Promise<TRes>}
+ *
+ * @template TReq - Request body type
+ * @template TRes - Response type
+ * @param url - The endpoint URL
+ * @param method - HTTP method to use
+ * @param body - Optional request body
+ * @param isSessionCommand - Whether this is a session command (default: true)
+ * @returns Promise resolving to the response
  */
-export async function proxyCommand(url, method, body, isSessionCommand = true) {
+export async function proxyCommand<TReq = any, TRes = unknown>(
+  this: XCUITestDriver,
+  url: string,
+  method: AllowedHttpMethod,
+  body?: TReq,
+  isSessionCommand: boolean = true,
+): Promise<TRes> {
   if (this.shutdownUnexpectedly) {
-    return /** @type {TRes} */ (undefined);
+    return undefined as TRes;
   }
 
   if (!url) {
@@ -83,12 +92,12 @@ export async function proxyCommand(url, method, body, isSessionCommand = true) {
   }
 
   if (!timeout) {
-    return /** @type {TRes} */ (await proxy.command(url, method, body));
+    return await proxy.command(url, method, body) as TRes;
   }
 
   this.log.debug(`Setting custom timeout to ${timeout} ms for '${cmdName}' command`);
   try {
-    return /** @type {TRes} */ (await B.resolve(proxy.command(url, method, body)).timeout(timeout));
+    return await B.resolve(proxy.command(url, method, body)).timeout(timeout) as TRes;
   } catch (e) {
     if (!(e instanceof B.Promise.TimeoutError)) {
       throw e;
@@ -102,18 +111,9 @@ export async function proxyCommand(url, method, body, isSessionCommand = true) {
   }
 }
 
-/**
- * @param {string} endpoint
- * @param {AllowedHttpMethod} method
- * @returns {string|undefined}
- */
-function wdaRouteToCommandName(endpoint, method) {
+function wdaRouteToCommandName(endpoint: string, method: AllowedHttpMethod): string | undefined {
   if (endpoint in WDA_ROUTES) {
-    return WDA_ROUTES[endpoint][method];
+    return WDA_ROUTES[endpoint as keyof typeof WDA_ROUTES]?.[method];
   }
 }
 
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- * @typedef {'GET'|'POST'|'DELETE'} AllowedHttpMethod
- */

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

@@ -1,4 +1,6 @@
 import { errors } from 'appium/driver';
+import type {XCUITestDriver} from '../driver';
+import type {Simulator} from 'appium-ios-simulator';
 
 /**
  * List of subcommands for `simctl` we provide as mobile simctl command.
@@ -27,19 +29,33 @@ const SUBCOMMANDS_HAS_DEVICE = [
   'terminate',
   'ui',
   'uninstall'
-];
+] as const;
+
+export interface SimctlExecResponse {
+  /** The output of standard out. */
+  stdout: string;
+  /** The output of standard error. */
+  stderr: string;
+  /** Return code. */
+  code: number;
+}
 
 /**
  * Run the given command with arguments as `xcrun simctl` subcommand.
  * This method works behind the 'simctl' security flag.
- * @this {XCUITestDriver}
- * @param {string} command Subcommand to run with `xcrun simctl`
- * @param {string[]} [args=[]] arguments for the subcommand. The arguments should be after <device> in the help.
- * @param {number|undefined} timeout - The maximum number of milliseconds
- * @returns {Promise<SimctlExecResponse>}
- * @throws {Error} If the simctl subcommand command returns non-zero return code, or the given subcommand was invalid.
+ *
+ * @param command - Subcommand to run with `xcrun simctl`. Must be one of the supported commands.
+ * @param args - Arguments for the subcommand. The arguments should be after <device> in the help.
+ * @param timeout - The maximum number of milliseconds
+ * @returns The execution result with stdout, stderr, and return code
+ * @throws If the simctl subcommand command returns non-zero return code, or the given subcommand was invalid.
  */
-export async function mobileSimctl(command, args = [], timeout = undefined) {
+export async function mobileSimctl(
+  this: XCUITestDriver,
+  command: string,
+  args: string[] = [],
+  timeout?: number,
+): Promise<SimctlExecResponse> {
   if (!this.isSimulator()) {
     throw new errors.UnsupportedOperationError(`Only simulator is supported.`);
   }
@@ -48,13 +64,13 @@ export async function mobileSimctl(command, args = [], timeout = undefined) {
     throw new errors.InvalidArgumentError(`Unknown device or simulator UDID: '${this.opts.udid}'`);
   }
 
-  if (!SUBCOMMANDS_HAS_DEVICE.includes(command)) {
+  if (!(SUBCOMMANDS_HAS_DEVICE as readonly string[]).includes(command)) {
     throw new errors.InvalidArgumentError(`The given command '${command}' is not supported. ` +
       `Available subcommands are ${SUBCOMMANDS_HAS_DEVICE.join(',')}`);
   }
 
-  const result = await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).simctl.exec(
-    command,
+  const result = await (this.device as Simulator).simctl.exec(
+    command as typeof SUBCOMMANDS_HAS_DEVICE[number],
     {args: [this.opts.udid, ...args], timeout}
   );
   return {
@@ -64,13 +80,3 @@ export async function mobileSimctl(command, args = [], timeout = undefined) {
   };
 }
 
-/**
- * @typedef {Object} SimctlExecResponse
- * @property {string} stdout The output of standard out.
- * @property {string} stderr The output of standard error.
- * @property {number} code Return code.
- */
-
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

package/lib/commands/timeouts.ts

@@ -0,0 +1,95 @@
+import type {XCUITestDriver} from '../driver';
+
+/**
+ * Sets the page load timeout using W3C protocol.
+ *
+ * @param ms - Timeout in milliseconds
+ */
+export async function pageLoadTimeoutW3C(
+  this: XCUITestDriver,
+  ms: number,
+): Promise<void> {
+  await this.setPageLoadTimeout(this.parseTimeoutArgument(ms));
+}
+
+/**
+ * Sets the page load timeout using MJSONWP protocol.
+ *
+ * @param ms - Timeout in milliseconds
+ */
+export async function pageLoadTimeoutMJSONWP(
+  this: XCUITestDriver,
+  ms: number,
+): Promise<void> {
+  await this.setPageLoadTimeout(this.parseTimeoutArgument(ms));
+}
+
+/**
+ * Sets the async script timeout using W3C protocol.
+ *
+ * @param ms - Timeout in milliseconds
+ */
+export async function scriptTimeoutW3C(
+  this: XCUITestDriver,
+  ms: number,
+): Promise<void> {
+  // XXX: this is synchronous
+  await this.setAsyncScriptTimeout(this.parseTimeoutArgument(ms));
+}
+
+/**
+ * Alias for {@linkcode XCUITestDriver.scriptTimeoutW3C}.
+ *
+ * @param ms - The timeout in milliseconds
+ * @deprecated Use {@linkcode XCUITestDriver.scriptTimeoutW3C} instead
+ */
+export async function scriptTimeoutMJSONWP(
+  this: XCUITestDriver,
+  ms: number,
+): Promise<void> {
+  await this.asyncScriptTimeout(ms);
+}
+
+/**
+ * Alias for {@linkcode XCUITestDriver.scriptTimeoutW3C}.
+ *
+ * @param ms - The timeout in milliseconds
+ * @deprecated Use {@linkcode XCUITestDriver.scriptTimeoutW3C} instead
+ */
+export async function asyncScriptTimeout(
+  this: XCUITestDriver,
+  ms: number,
+): Promise<void> {
+  await this.scriptTimeoutW3C(ms);
+}
+
+/**
+ * Sets the page load timeout.
+ *
+ * @param ms - Timeout in milliseconds
+ */
+export function setPageLoadTimeout(
+  this: XCUITestDriver,
+  ms: number,
+): void {
+  ms = parseInt(String(ms), 10);
+  this.pageLoadMs = ms;
+  if (this._remote) {
+    this.remote.pageLoadMs = ms;
+  }
+  this.log.debug(`Set page load timeout to ${ms}ms`);
+}
+
+/**
+ * Sets the async script timeout.
+ *
+ * @param ms - Timeout in milliseconds
+ */
+export function setAsyncScriptTimeout(
+  this: XCUITestDriver,
+  ms: number,
+): void {
+  this.asyncWaitMs = ms;
+  this.log.debug(`Set async script timeout to ${ms}ms`);
+}
+

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "appium-xcuitest-driver",
-  "version": "10.14.2",
+  "version": "10.14.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-xcuitest-driver",
-      "version": "10.14.2",
+      "version": "10.14.4",
       "license": "Apache-2.0",
       "dependencies": {
         "@appium/strongbox": "^1.0.0-rc.1",
@@ -692,9 +692,9 @@
       }
     },
     "node_modules/appium-ios-remotexpc": {
-      "version": "0.21.1",
-      "resolved": "https://registry.npmjs.org/appium-ios-remotexpc/-/appium-ios-remotexpc-0.21.1.tgz",
-      "integrity": "sha512-E3dJxiZQEivGLRWMkFZMd3PSc1eT8V4uhJ/xAtwZxrIKYHYIVEvWeDQ6YHydGu9Jq1soX2aZFfBgfHIPeE8SSg==",
+      "version": "0.24.1",
+      "resolved": "https://registry.npmjs.org/appium-ios-remotexpc/-/appium-ios-remotexpc-0.24.1.tgz",
+      "integrity": "sha512-LJ83A/cHx+CFOX9yGLoG+bsfgYiJdN1PSBDDe7FkZ/C6DGTi+5zvDxOwaBSLmhgEh6uae40EGK8/FbFiKwR4Kg==",
       "license": "Apache-2.0",
       "optional": true,
       "dependencies": {

package/package.json

@@ -8,7 +8,7 @@
     "xcuitest",
     "xctest"
   ],
-  "version": "10.14.2",
+  "version": "10.14.4",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {

package/lib/commands/alert.js

@@ -1,88 +0,0 @@
-/**
- * @this {XCUITestDriver}
- */
-export async function getAlertText() {
-  return /** @type {string|null} */ (await this.proxyCommand('/alert/text', 'GET'));
-}
-
-/**
- * @param {string} value
- * @this {XCUITestDriver}
- * @returns {Promise<void>}
- */
-export async function setAlertText(value) {
-  await this.proxyCommand('/alert/text', 'POST', {value});
-}
-
-/**
- * @param { {buttonLabel?: string} } opts
- * @returns {Promise<void>}
- * @this {XCUITestDriver}
- */
-export async function postAcceptAlert(opts = {}) {
-  await this.proxyCommand('/alert/accept', 'POST', toAlertParams(opts));
-}
-
-/**
- * @param { {buttonLabel?: string} } opts
- * @returns {Promise<void>}
- * @this {XCUITestDriver}
- */
-export async function postDismissAlert(opts = {}) {
-  await this.proxyCommand('/alert/dismiss', 'POST', toAlertParams(opts));
-}
-
-/**
- * @internal
- * @this {XCUITestDriver}
- * @returns {Promise<string[]>} The list of button labels
- */
-export async function getAlertButtons() {
-  return /** @type {string[]} */ (await this.proxyCommand('/wda/alert/buttons', 'GET'));
-}
-
-/**
- * Tries to apply the given action to the currently visible alert.
- *
- * @param {AlertAction} action - The actual action to apply.
- * @param {string} [buttonLabel] - The name of the button used to perform the chosen alert action. Only makes sense if the action is `accept` or `dismiss`.
- * @returns {Promise<string[]|void>} If `action` is `getButtons`, a list of alert button labelsp; otherwise nothing.
- * @remarks This should really be separate commands.
- * @this {XCUITestDriver}
- */
-export async function mobileHandleAlert(action, buttonLabel) {
-  switch (action) {
-    case 'accept':
-      return await this.postAcceptAlert({buttonLabel});
-    case 'dismiss':
-      return await this.postDismissAlert({buttonLabel});
-    case 'getButtons':
-      return await this.getAlertButtons();
-    default:
-      throw new Error(
-        `The 'action' value should be either 'accept', 'dismiss' or 'getButtons'. ` +
-          `'${action}' is provided instead.`,
-      );
-  }
-}
-
-/**
- *
- * @param { {buttonLabel?: string} } opts
- * @returns { {name?: string} }
- */
-function toAlertParams(opts = {}) {
-  const params = {};
-  if (opts.buttonLabel) {
-    params.name = opts.buttonLabel;
-  }
-  return params;
-}
-
-/**
- * @typedef {'accept'|'dismiss'|'getButtons'} AlertAction
- */
-
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */