appium-xcuitest-driver 10.13.1 → 10.13.3

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

@@ -9,6 +9,9 @@ import {exec} from 'teen_process';
 import {findAPortNotInUse, checkPortStatus} from 'portscanner';
 import {Pyidevice} from '../device/clients/py-ios-device-client';
 import {errors} from 'appium/driver';
+import type {Simulator} from 'appium-ios-simulator';
+import type {XCUITestDriver} from '../driver';
+import type {CertificateList} from './types';
 
 const CONFIG_EXTENSION = 'mobileconfig';
 const HOST_PORT_RANGE = [38200, 38299];
@@ -62,11 +65,8 @@ const OPEN_SSL_PATTERN = /,\sCN\s=\s([^,]+)/;
 
 /**
  * Parses the common name of the certificate from the given string.
- *
- * @param {string} stringCertificate
- * @returns {string} The common name of the certificate
  */
-export function parseCommonName(stringCertificate) {
+export function parseCommonName(stringCertificate: string): string {
   const result = [LIBRE_SSL_PATTERN, OPEN_SSL_PATTERN].reduce((acc, r) => {
     if (acc) {
       return acc;
@@ -87,22 +87,28 @@ export function parseCommonName(stringCertificate) {
  * certificates on Simulator over CLI.
  *
  * On real devices (or simulators before Xcode SDK 11.4), Apple provides no "official" way to do this via the command line.  In such a case (and also as a fallback if CLI setup fails), this method tries to wrap the certificate into `.mobileconfig` format, then deploys the wrapped file to the internal HTTP server so that it can be opened via mobile Safari. This command then goes through the profile installation procedure by clicking the necessary buttons using WebDriverAgent.
- * @param {string} content - Base64-encoded content of the public certificate in [PEM](https://knowledge.digicert.com/quovadis/ssl-certificates/ssl-general-topics/what-is-pem-format.html) format
- * @param {string} [commonName] - Common name of the certificate. If this is not set, the command will try to parse it from the provided `content`.
- * @param {boolean} isRoot - Defines where the certificate should be installed; either the Trusted Root Store (`true`) or the Keychain (`false`). On environments other than Xcode 11.4+ Simulator, this option is ignored.
- * @returns {Promise<string|void>} The content of the generated `.mobileconfig` file as
+ * @param content - Base64-encoded content of the public certificate in [PEM](https://knowledge.digicert.com/quovadis/ssl-certificates/ssl-general-topics/what-is-pem-format.html) format
+ * @param commonName - Common name of the certificate. If this is not set, the command will try to parse it from the provided `content`.
+ * @param isRoot - Defines where the certificate should be installed; either the Trusted Root Store (`true`) or the Keychain (`false`). On environments other than Xcode 11.4+ Simulator, this option is ignored.
+ * @returns The content of the generated `.mobileconfig` file as
  * a base64-encoded string. This config might be useful for debugging purposes.  If the certificate has been successfully set via CLI, then nothing is returned.
- * @this {XCUITestDriver}
  */
-export async function mobileInstallCertificate(content, commonName, isRoot = true) {
+export async function mobileInstallCertificate(
+  this: XCUITestDriver,
+  content: string,
+  commonName?: string,
+  isRoot = true,
+): Promise<string | void> {
   if (_.isEmpty(content)) {
     throw new Error('Certificate content should not be empty');
   }
 
   if (this.isSimulator()) {
     try {
-      const methodName = isRoot ? 'addRootCertificate' : 'addCertificate';
-      await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).simctl[methodName](Buffer.from(content, 'base64').toString(), {
+      const methodName: 'addRootCertificate' | 'addCertificate' = isRoot
+        ? 'addRootCertificate'
+        : 'addCertificate';
+      await (this.device as Simulator).simctl[methodName](Buffer.from(content, 'base64').toString(), {
         raw: true,
       });
       return;
@@ -188,11 +194,12 @@ export async function mobileInstallCertificate(content, commonName, isRoot = tru
           }
         }
       } else {
-        await /** @type {import('appium-ios-simulator').Simulator} */ (this.device).openUrl(certUrl);
+        await (this.device as Simulator).openUrl(certUrl);
       }
 
       let isCertAlreadyInstalled = false;
-      if (util.compareVersions(/** @type {string} */ (this.opts.platformVersion), '>=', '12.2')) {
+      const platformVersion = this.opts.platformVersion ?? '';
+      if (util.compareVersions(platformVersion, '>=', '12.2')) {
         if (await installPost122Certificate(this, cn)) {
           await clickElement(this, Settings.Profile);
           await trustCertificateInPreferences(this, cn);
@@ -238,17 +245,19 @@ export async function mobileInstallCertificate(content, commonName, isRoot = tru
  *
  * @see https://github.com/YueChen-C/py-ios-device
  * @since 4.19.2
- * @param {string} name - Name of the profile
- * @returns {Promise<string>} Returns status acknowledgment status if
- * tht certificate is successfully removed or 'None' (basically just
- * forwards the original pyidevice output)
+ * @param name - Name of the profile
+ * @returns Status acknowledgment if
+ * the certificate is successfully removed or 'None' (forwards pyidevice output)
  * @throws {Error} If attempting to remove certificates for a simulated device or if `py-ios-device` is not installed
  * @group Real Device Only
  */
-export async function mobileRemoveCertificate(name) {
+export async function mobileRemoveCertificate(this: XCUITestDriver, name: string): Promise<string> {
   if (!this.isRealDevice()) {
     throw new errors.NotImplementedError('This extension is only supported on real devices');
   }
+  if (!this.opts.udid) {
+    throw new Error('udid capability is required');
+  }
   const client = new Pyidevice({
     udid: this.opts.udid,
     log: this.log,
@@ -263,11 +272,10 @@ export async function mobileRemoveCertificate(name) {
  * This only works _if and only if_ `py-ios-device` is installed on the same machine Appium is running on.
  * @since 4.10.0
  * @see https://github.com/YueChen-C/py-ios-device
- * @returns {Promise<import('./types').CertificateList>} An object describing the certificates installed on the real device.
+ * @returns An object describing the certificates installed on the real device.
  * @throws {Error} If attempting to list certificates for a simulated device or if `py-ios-device` is not installed
- * @this {XCUITestDriver}
  */
-export async function mobileListCertificates() {
+export async function mobileListCertificates(this: XCUITestDriver): Promise<CertificateList> {
   if (!this.isRealDevice()) {
     throw new errors.NotImplementedError('This extension is only supported on real devices');
   }
@@ -287,9 +295,9 @@ export async function mobileListCertificates() {
  * Extracts the common name of the certificate from the given buffer.
  *
  * @param {Buffer} certBuffer
- * @returns {Promise<string>} The common name of the certificate
+ * @returns The common name of the certificate
  */
-async function extractCommonName(certBuffer) {
+async function extractCommonName(certBuffer: Buffer): Promise<string> {
   const tempCert = await tempDir.open({
     prefix: 'cert',
     suffix: '.cer',
@@ -315,12 +323,12 @@ async function extractCommonName(certBuffer) {
  * for more details on such profiles.
  *
  * @param {Buffer} certBuffer - The actual content of PEM certificate encoded into NodeJS buffer
- * @param {string} commonName - Certificate's common name
+ * @param commonName - Certificate's common name
  * @returns {Object} The encoded structure of the given certificate, which is ready to be passed
  * as an argument to plist builder
  * @throws {Error} If the given certificate cannot be parsed
  */
-function toMobileConfig(certBuffer, commonName) {
+function toMobileConfig(certBuffer: Buffer, commonName: string): Record<string, any> {
   const getUUID = () => util.uuidV4().toUpperCase();
   const contentUuid = getUUID();
   return {
@@ -345,8 +353,12 @@ function toMobileConfig(certBuffer, commonName) {
   };
 }
 
-async function clickElement(driver, locator, options = {}) {
-  let element = null;
+async function clickElement(
+  driver: XCUITestDriver,
+  locator: {type: string; value: string},
+  options: {timeout?: number; skipIfInvisible?: boolean} = {},
+): Promise<boolean> {
+  let element: any = null;
   const {timeout = 5000, skipIfInvisible = false} = options;
   const lookupDelay = 500;
   try {
@@ -365,7 +377,7 @@ async function clickElement(driver, locator, options = {}) {
   return true;
 }
 
-async function installPre122Certificate(driver) {
+async function installPre122Certificate(driver: XCUITestDriver): Promise<boolean> {
   // Accept Safari alert
   await clickElement(driver, Button.Allow, {
     // certificate load might take some time on slow machines
@@ -393,7 +405,7 @@ async function installPre122Certificate(driver) {
   return true;
 }
 
-async function trustCertificateInPreferences(driver, name) {
+async function trustCertificateInPreferences(driver: XCUITestDriver, name: string): Promise<void> {
   await clickElement(driver, Settings.General);
   await clickElement(driver, Settings.About);
   const switchLocator = {
@@ -401,14 +413,12 @@ async function trustCertificateInPreferences(driver, name) {
     value: `**/XCUIElementTypeCell[\`label == '${name}'\`]/**/XCUIElementTypeSwitch`,
   };
   await retry(5, async () => {
-    await driver.mobileSwipe({
-      element: await driver.findNativeElementOrElements(
-        'class name',
-        'XCUIElementTypeTable',
-        false,
-      ),
-      direction: 'up',
-    });
+    const tableEl = await driver.findNativeElementOrElements(
+      'class name',
+      'XCUIElementTypeTable',
+      false,
+    );
+    await driver.mobileSwipe('up', undefined, tableEl);
     await clickElement(driver, Settings.Certificate_Trust_Settings, {
       timeout: 500,
     });
@@ -433,7 +443,7 @@ async function trustCertificateInPreferences(driver, name) {
   }
 }
 
-async function installPost122Certificate(driver, name) {
+async function installPost122Certificate(driver: XCUITestDriver, name: string): Promise<boolean> {
   // Accept Safari alert
   await clickElement(driver, Button.Allow, {
     // certificate load might take some time on slow machines
@@ -466,14 +476,12 @@ async function installPost122Certificate(driver, name) {
       break;
     }
 
-    await driver.mobileSwipe({
-      element: await driver.findNativeElementOrElements(
-        'class name',
-        'XCUIElementTypeTable',
-        false,
-      ),
-      direction: 'up',
-    });
+    const tableEl = await driver.findNativeElementOrElements(
+      'class name',
+      'XCUIElementTypeTable',
+      false,
+    );
+    await driver.mobileSwipe('up', undefined, tableEl);
   }
   if (!isCertFound) {
     throw new Error(`'${name}' cannot be found in the certificates list`);
@@ -498,6 +506,3 @@ async function installPost122Certificate(driver, name) {
   return true;
 }
 
-/**
- * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
- */

package/lib/commands/element.ts

@@ -0,0 +1,419 @@
+import _ from 'lodash';
+import {errors} from 'appium/driver';
+import {util} from 'appium/support';
+import type {Element, Position, Size, Rect} from '@appium/types';
+import type {XCUITestDriver} from '../driver';
+import type {AtomsElement} from './types';
+
+/**
+ * Checks whether an element is displayed.
+ *
+ * @param el - Element or element ID
+ */
+export async function elementDisplayed(this: XCUITestDriver, el: Element | string): Promise<boolean> {
+  const elementId = util.unwrapElement(el);
+  if (this.isWebContext()) {
+    const atomsElement = this.getAtomsElement(elementId);
+    return await this.executeAtom('is_displayed', [atomsElement]) as boolean;
+  }
+  return await this.proxyCommand(`/element/${elementId}/displayed`, 'GET') as boolean;
+}
+
+/**
+ * Checks whether an element is enabled.
+ *
+ * @param el - Element or element ID
+ */
+export async function elementEnabled(this: XCUITestDriver, el: Element | string): Promise<boolean> {
+  const elementId = util.unwrapElement(el);
+  if (this.isWebContext()) {
+    const atomsElement = this.getAtomsElement(elementId);
+    return await this.executeAtom('is_enabled', [atomsElement]) as boolean;
+  }
+  return await this.proxyCommand(`/element/${elementId}/enabled`, 'GET') as boolean;
+}
+
+/**
+ * Checks whether an element is selected.
+ *
+ * @param el - Element or element ID
+ */
+export async function elementSelected(this: XCUITestDriver, el: Element | string): Promise<boolean> {
+  const elementId = util.unwrapElement(el);
+  if (this.isWebContext()) {
+    const atomsElement = this.getAtomsElement(elementId);
+    return await this.executeAtom('is_selected', [atomsElement]) as boolean;
+  }
+  return await this.proxyCommand(`/element/${elementId}/selected`, 'GET') as boolean;
+}
+
+/**
+ * Gets the tag/name of an element.
+ *
+ * @param el - Element or element ID
+ */
+export async function getName(this: XCUITestDriver, el: Element | string): Promise<string> {
+  const elementId = util.unwrapElement(el);
+  if (this.isWebContext()) {
+    const atomsElement = this.getAtomsElement(elementId);
+    const script = 'return arguments[0].tagName.toLowerCase()';
+    return await this.executeAtom('execute_script', [script, [atomsElement]]) as string;
+  }
+  return await this.proxyCommand(`/element/${elementId}/name`, 'GET') as string;
+}
+
+/**
+ * Gets a native attribute (non-web) from an element.
+ *
+ * @param attribute - Attribute name
+ * @param el - Element or element ID
+ */
+export async function getNativeAttribute(
+  this: XCUITestDriver,
+  attribute: string,
+  el: Element | string,
+): Promise<string | null> {
+  if (attribute === 'contentSize') {
+    return await this.getContentSize(el);
+  }
+
+  const elementId = util.unwrapElement(el);
+  let value = await this.proxyCommand(`/element/${elementId}/attribute/${attribute}`, 'GET') as
+    | string
+    | number
+    | null
+    | undefined
+    | boolean;
+  if ([0, 1].includes(value as number)) {
+    value = !!value;
+  }
+  return _.isNull(value) || _.isString(value) ? value : JSON.stringify(value);
+}
+
+/**
+ * Gets an element attribute (web or native).
+ *
+ * @param attribute - Attribute name
+ * @param el - Element or element ID
+ */
+export async function getAttribute(
+  this: XCUITestDriver,
+  attribute: string,
+  el: Element | string,
+): Promise<string | null> {
+  const elementId = util.unwrapElement(el);
+  if (!this.isWebContext()) {
+    return await this.getNativeAttribute(attribute, elementId);
+  }
+  const atomsElement = this.getAtomsElement(elementId);
+  return await this.executeAtom('get_attribute_value', [atomsElement, attribute]) as string | null;
+}
+
+/**
+ * Gets an element property (web) or native attribute fallback.
+ *
+ * @param property - Property name
+ * @param el - Element or element ID
+ */
+export async function getProperty(
+  this: XCUITestDriver,
+  property: string,
+  el: Element | string,
+): Promise<string | null> {
+  const elementId = util.unwrapElement(el);
+  if (!this.isWebContext()) {
+    return await this.getNativeAttribute(property, elementId);
+  }
+  const atomsElement = this.getAtomsElement(elementId);
+  return await this.executeAtom('get_attribute_value', [atomsElement, property]) as string | null;
+}
+
+/**
+ * Gets the text content of an element.
+ *
+ * @param el - Element or element ID
+ */
+export async function getText(this: XCUITestDriver, el: Element | string): Promise<string> {
+  const elementId = util.unwrapElement(el);
+  if (!this.isWebContext()) {
+    return await this.proxyCommand(`/element/${elementId}/text`, 'GET') as string;
+  }
+  const atomsElement = this.getAtomsElement(elementId);
+  return await this.executeAtom('get_text', [atomsElement]) as string;
+}
+
+/**
+ * Gets the bounding rect of an element.
+ *
+ * @param el - Element or element ID
+ */
+export async function getElementRect(this: XCUITestDriver, el: Element | string): Promise<Rect> {
+  if (this.isWebContext()) {
+    const {x, y} = await this.getLocation(el);
+    const {width, height} = await this.getSize(el);
+    return {x, y, width, height};
+  }
+  const elementId = util.unwrapElement(el);
+  return await this.getNativeRect(elementId);
+}
+
+/**
+ * Gets the top-left location of an element.
+ *
+ * @param elementId - Element or element ID
+ */
+export async function getLocation(this: XCUITestDriver, elementId: Element | string): Promise<Position> {
+  const el = util.unwrapElement(elementId);
+  if (this.isWebContext()) {
+    const atomsElement = this.getAtomsElement(el);
+    const loc = await this.executeAtom('get_top_left_coordinates', [atomsElement]) as Position;
+    if (this.opts.absoluteWebLocations) {
+      const script =
+        'return [' +
+        'Math.max(window.pageXOffset,document.documentElement.scrollLeft,document.body.scrollLeft),' +
+        'Math.max(window.pageYOffset,document.documentElement.scrollTop,document.body.scrollTop)];';
+      const [xOffset, yOffset] = await this.execute(script) as [number, number];
+      loc.x += xOffset;
+      loc.y += yOffset;
+    }
+    return loc;
+  }
+  const rect = await this.getElementRect(el);
+  return {x: rect.x, y: rect.y};
+}
+
+/**
+ * Alias for getLocation.
+ *
+ * @param elementId - Element or element ID
+ */
+export async function getLocationInView(this: XCUITestDriver, elementId: Element | string): Promise<Position> {
+  return await this.getLocation(elementId);
+}
+
+/**
+ * Gets the size of an element.
+ *
+ * @param el - Element or element ID
+ */
+export async function getSize(this: XCUITestDriver, el: Element | string): Promise<Size> {
+  const elementId = util.unwrapElement(el);
+  if (this.isWebContext()) {
+    return await this.executeAtom('get_size', [this.getAtomsElement(elementId)]) as Size;
+  }
+  const rect = await this.getElementRect(elementId);
+  return {width: rect.width, height: rect.height};
+}
+
+/**
+ * Legacy alias for setValue; always types via keyboard.
+ *
+ * @param value - Value to set
+ * @param el - Element or element ID
+ */
+export async function setValueImmediate(
+  this: XCUITestDriver,
+  value: string | string[] | number,
+  el: Element | string,
+): Promise<void> {
+  this.log.info(
+    'There is currently no way to bypass typing using XCUITest. Setting value through keyboard',
+  );
+  await this.setValue(value, el);
+}
+
+/**
+ * Sets an element value (native or web).
+ *
+ * @param value - Value to set
+ * @param el - Element or element ID
+ */
+export async function setValue(
+  this: XCUITestDriver,
+  value: string | string[] | number,
+  el: Element | string,
+): Promise<void> {
+  const elementId = util.unwrapElement(el);
+  if (!this.isWebContext()) {
+    await this.proxyCommand(`/element/${elementId}/value`, 'POST', {
+      value: prepareInputValue(value),
+    });
+    return;
+  }
+
+  const atomsElement = this.getAtomsElement(elementId);
+  await this.executeAtom('click', [atomsElement]);
+
+  if (this.opts.sendKeyStrategy !== 'oneByOne') {
+    await this.setValueWithWebAtom(atomsElement, value);
+    return;
+  }
+  for (const char of prepareInputValue(value)) {
+    await this.setValueWithWebAtom(atomsElement, char);
+  }
+}
+
+/**
+ * Types text into a web element using atoms.
+ *
+ * @param atomsElement - Target atoms element
+ * @param value - Text to type
+ */
+export async function setValueWithWebAtom(
+  this: XCUITestDriver,
+  atomsElement: AtomsElement<string>,
+  value: string | string[] | number,
+): Promise<void> {
+  await this.executeAtom('type', [atomsElement, value]);
+
+  if (this.opts.skipTriggerInputEventAfterSendkeys) {
+    return;
+  }
+
+  function triggerInputEvent(input: EventTarget & {_valueTracker?: any}) {
+    const lastValue = '';
+    const event = new Event('input', {bubbles: true});
+    const tracker = input._valueTracker;
+    if (tracker) {
+      tracker.setValue(lastValue);
+    }
+    input.dispatchEvent(event);
+  }
+
+  const scriptAsString = `return (${triggerInputEvent}).apply(null, arguments)`;
+  await this.executeAtom('execute_script', [scriptAsString, [atomsElement]]);
+}
+
+/**
+ * Sends raw key sequences via WDA.
+ *
+ * @param value - Keys to send
+ */
+export async function keys(this: XCUITestDriver, value: string[] | string | number): Promise<void> {
+  await this.proxyCommand('/wda/keys', 'POST', {
+    value: prepareInputValue(value),
+  });
+}
+
+/**
+ * Clears the contents of an element.
+ *
+ * @param el - Element or element ID
+ */
+export async function clear(this: XCUITestDriver, el: Element | string): Promise<void> {
+  const elementId = util.unwrapElement(el);
+  if (this.isWebContext()) {
+    const atomsElement = this.getAtomsElement(elementId);
+    await this.executeAtom('clear', [atomsElement]);
+    return;
+  }
+  await this.proxyCommand(`/element/${elementId}/clear`, 'POST');
+}
+
+/**
+ * Gets content size for table/collection views (native only).
+ *
+ * @param el - Element or element ID
+ */
+export async function getContentSize(this: XCUITestDriver, el: Element | string): Promise<string> {
+  if (this.isWebContext()) {
+    throw new errors.NotYetImplementedError(
+      'Support for getContentSize for web context is not yet implemented. Please contact an Appium dev',
+    );
+  }
+
+  const type = await this.getAttribute('type', el);
+
+  if (type !== 'XCUIElementTypeTable' && type !== 'XCUIElementTypeCollectionView') {
+    throw new Error(
+      `Can't get content size for type '${type}', only for tables and collection views`,
+    );
+  }
+  let locator = '*';
+  if (type === 'XCUIElementTypeTable') {
+    locator = 'XCUIElementTypeCell';
+  }
+
+  let contentHeight = 0;
+  const children = await this.findElOrEls('class chain', locator, true, el);
+  if (children.length === 1) {
+    const rect = await this.getElementRect(children[0]);
+    contentHeight = rect.height;
+  } else if (children.length) {
+    switch (type) {
+      case 'XCUIElementTypeTable': {
+        const firstRect = await this.getElementRect(_.head(children) as Element);
+        const lastRect = await this.getElementRect(_.last(children) as Element);
+        contentHeight = lastRect.y + lastRect.height - firstRect.y;
+        break;
+      }
+      case 'XCUIElementTypeCollectionView': {
+        let elsInRow = 1;
+        const firstRect = await this.getElementRect(_.head(children) as Element);
+        const initialRects = [firstRect];
+        for (let i = 1; i < children.length; i++) {
+          const rect = await this.getElementRect(children[i] as Element);
+          initialRects.push(rect);
+          if (rect.y !== firstRect.y) {
+            elsInRow = i;
+            break;
+          }
+        }
+        const spaceBetweenEls =
+          initialRects[elsInRow].y -
+          initialRects[elsInRow - 1].y -
+          initialRects[elsInRow - 1].height;
+        const numRows = Math.ceil(children.length / elsInRow);
+        contentHeight = numRows * firstRect.height + spaceBetweenEls * (numRows - 1);
+        break;
+      }
+      default:
+        throw new Error(
+          `Programming error: type '${type}' was not valid but should have already been rejected`,
+        );
+    }
+  }
+  const size = await this.getSize(el);
+  const origin = await this.getLocationInView(el);
+  return JSON.stringify({
+    width: size.width,
+    height: size.height,
+    top: origin.y,
+    left: origin.x,
+    scrollableOffset: contentHeight,
+  });
+}
+
+/**
+ * Gets the native rect of an element (no web fallback).
+ *
+ * @param el - Element or element ID
+ */
+export async function getNativeRect(this: XCUITestDriver, el: Element | string): Promise<Rect> {
+  const elementId = util.unwrapElement(el);
+  return await this.proxyCommand(`/element/${elementId}/rect`, 'GET') as Rect;
+}
+
+function prepareInputValue(inp: string | string[] | number): string[] {
+  if (![_.isArray, _.isString, _.isFinite].some((f) => f(inp))) {
+    throw new Error(
+      `Only strings, numbers and arrays are supported as input arguments. ` +
+        `Received: ${JSON.stringify(inp)}`,
+    );
+  }
+
+  if (_.isArray(inp)) {
+    inp = inp.join('');
+  } else if (_.isFinite(inp)) {
+    inp = `${inp}`;
+  }
+  return [...String(inp)].map((k) => {
+    if (['\uE006', '\uE007'].includes(k)) {
+      return '\n';
+    }
+    if (['\uE003', '\ue017'].includes(k)) {
+      return '\b';
+    }
+    return k;
+  });
+}