appium-xcuitest-driver 10.14.2 → 10.14.3

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.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "appium-xcuitest-driver",
-      "version": "10.14.2",
+      "version": "10.14.3",
       "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.3",
   "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
- */

package/lib/commands/appearance.js

@@ -1,71 +0,0 @@
-import _ from 'lodash';
-import {util} from 'appium/support';
-
-/**
- * Set the device's UI appearance style
- *
- * @since iOS 12.0
- * @param {'dark'|'light'} style - The appearance style to set
- * @throws {Error} if the current platform does not support UI appearance changes
- * @this {XCUITestDriver}
- */
-export async function mobileSetAppearance(style) {
-  if (!['light', 'dark'].includes(_.toLower(style))) {
-    throw new Error(`The 'style' value is expected to equal either 'light' or 'dark'`);
-  }
-  if (util.compareVersions(/** @type {string} */ (this.opts.platformVersion), '<', '12.0')) {
-    throw new Error('Changing appearance is only supported since iOS 12');
-  }
-
-  if (this.isSimulator()) {
-    try {
-      return void (await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).setAppearance(style));
-    } catch (e) {
-      this.log.debug(e.stack);
-    }
-  }
-  try {
-    return void (await this.proxyCommand('/wda/device/appearance', 'POST', {name: style}, false));
-  } catch (e) {
-    this.log.debug(e.stack);
-  }
-  // Fall back to the ugly Siri workaround if the current SDK is too old
-  await this.mobileSiriCommand(`Turn ${_.toLower(style) === 'dark' ? 'on' : 'off'} dark mode`);
-}
-
-/**
- * Get the device's UI appearance style.
- *
- * @since Xcode SDK 11
- * @returns {Promise<{style: Style}>}
- * @this {XCUITestDriver}
- */
-export async function mobileGetAppearance() {
-  if (util.compareVersions(/** @type {string} */ (this.opts.platformVersion), '<', '12.0')) {
-    return {style: 'unsupported'};
-  }
-
-  /** @type {Style|undefined} */
-  let style;
-  if (this.isSimulator()) {
-    try {
-      style = /** @type {Style} */ (
-        await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).getAppearance()
-      );
-    } catch {}
-  }
-  if (!style) {
-    style = /** @type {Style} */ (
-      /** @type {any} */ (await this.proxyCommand('/wda/device/info', 'GET'))
-        ?.userInterfaceStyle ?? 'unknown'
-    );
-  }
-  return {
-    style,
-  };
-}
-
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- * @typedef {import('./types').Style} Style
- */

package/lib/commands/permissions.js

@@ -1,85 +0,0 @@
-import _ from 'lodash';
-import {PermissionService} from './enum';
-import {assertSimulator as _assertSimulator} from '../utils';
-
-const assertSimulator = (driver) => _assertSimulator.call(driver, 'Permission-related operations');
-
-/**
- * Resets the given permission for the active application under test.
- * Works for both Simulator and real devices using Xcode SDK 11.4+
- *
- * @param {PermissionService|number} 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 {Error} If permission reset fails on the device.
- * @this {XCUITestDriver}
- */
-export async function mobileResetPermission(service) {
-  if (!service) {
-    throw new Error(`The 'service' option is expected to be present`);
-  }
-  let resource;
-  if (_.isString(service)) {
-    resource = PermissionService[_.toLower(service)];
-    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 {string} bundleId - Bundle identifier of the target application
- * @param {import('./enum').PermissionService} service - Service name
- * @returns {Promise<import('./types').PermissionState>} Either 'yes', 'no', 'unset' or 'limited'
- * @throws {Error} If permission getting fails or the device is not a Simulator.
- * @this {XCUITestDriver}
- * @group Simulator Only
- */
-export async function mobileGetPermission(bundleId, service) {
-  if (!service) {
-    throw new Error(`The 'service' option is expected to be present`);
-  }
-  assertSimulator(this);
-
-  return /** @type {import('./types').PermissionState} */ (
-    await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).getPermission(
-      bundleId, String(service)
-    )
-  );
-}
-
-/**
- * Set application permission state on Simulator.
- *
- * @param {Record<Partial<import('./types').AccessRule>, import('./types').PermissionState>} access - One or more access rules to set.
- * @param {string} bundleId - Bundle identifier of the target application
- * @since Xcode SDK 11.4
- * @throws {Error} If permission setting fails or the device is not a Simulator.
- * @group Simulator Only
- * @this {XCUITestDriver}
- */
-export async function mobileSetPermissions(access, bundleId) {
-  if (!_.isPlainObject(access)) {
-    throw new Error(`The 'access' option is expected to be a map`);
-  }
-  assertSimulator(this);
-
-  await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).setPermissions(bundleId, access);
-}
-
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

package/lib/commands/timeouts.js

@@ -1,68 +0,0 @@
-/**
- * @this {XCUITestDriver}
- */
-export async function pageLoadTimeoutW3C(ms) {
-  await this.setPageLoadTimeout(this.parseTimeoutArgument(ms));
-}
-
-/**
- * @this {XCUITestDriver}
- */
-export async function pageLoadTimeoutMJSONWP(ms) {
-  await this.setPageLoadTimeout(this.parseTimeoutArgument(ms));
-}
-
-/**
- * @this {XCUITestDriver}
- */
-export async function scriptTimeoutW3C(ms) {
-  // XXX: this is synchronous
-  await this.setAsyncScriptTimeout(this.parseTimeoutArgument(ms));
-}
-
-/**
- * Alias for {@linkcode XCUITestDriver.scriptTimeoutW3C}.
- *
- * @param {number} ms - the timeout
- * @this {XCUITestDriver}
- * @deprecated Use {@linkcode XCUITestDriver.scriptTimeoutW3C} instead
- */
-export async function scriptTimeoutMJSONWP(ms) {
-  await this.asyncScriptTimeout(ms);
-}
-
-/**
- * Alias for {@linkcode XCUITestDriver.scriptTimeoutW3C}.
- *
- * @param {number} ms - the timeout
- *
- * @deprecated Use {@linkcode XCUITestDriver.scriptTimeoutW3C} instead
- * @this {XCUITestDriver}
- */
-export async function asyncScriptTimeout(ms) {
-  await this.scriptTimeoutW3C(ms);
-}
-
-/**
- * @this {XCUITestDriver}
- */
-export function setPageLoadTimeout(ms) {
-  ms = parseInt(ms, 10);
-  this.pageLoadMs = ms;
-  if (this._remote) {
-    this.remote.pageLoadMs = ms;
-  }
-  this.log.debug(`Set page load timeout to ${ms}ms`);
-}
-
-/**
- * @this {XCUITestDriver}
- */
-export function setAsyncScriptTimeout(ms) {
-  this.asyncWaitMs = ms;
-  this.log.debug(`Set async script timeout to ${ms}ms`);
-}
-
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */