appium-xcuitest-driver 10.3.0 → 10.4.0

package/lib/commands/certificate.js

@@ -57,6 +57,232 @@ const Alert = /** @type {const} */ ({
   },
 });
 
+const LIBRE_SSL_PATTERN = /\/CN=([^\/]+)/; // eslint-disable-line no-useless-escape
+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) {
+  const result = [LIBRE_SSL_PATTERN, OPEN_SSL_PATTERN].reduce((acc, r) => {
+    if (acc) {
+      return acc;
+    }
+    const match = r.exec(stringCertificate);
+    return match?.[1];
+  }, null);
+  if (!result) {
+    throw new Error(`There is no common name value in '${stringCertificate}' output`);
+  }
+  return result;
+}
+
+/**
+ * Installs a custom certificate onto the device.
+ *
+ * Since Xcode SDK 11.4, Apple has added a dedicated `simctl` subcommand to quickly handle
+ * 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
+ * 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) {
+  if (_.isEmpty(content)) {
+    throw new Error('Certificate content should not be empty');
+  }
+
+  if (this.isSimulator()) {
+    try {
+      const methodName = isRoot ? 'addRootCertificate' : 'addCertificate';
+      await /** @type {import('../driver').Simulator} */ (this.device).simctl[methodName](Buffer.from(content, 'base64').toString(), {
+        raw: true,
+      });
+      return;
+    } catch (e) {
+      this.log.debug(e);
+      this.log.info(
+        `The certificate cannot be installed via CLI. ` + `Falling back to UI-based deployment`,
+      );
+    }
+  } else {
+    const client = new Pyidevice({
+      udid: this.opts.udid,
+      log: this.log,
+    });
+    if (await client.assertExists(false)) {
+      await client.installProfile({payload: Buffer.from(content, 'base64')});
+      return;
+    } else {
+      this.log.info(
+        'pyidevice is not installed on your system. ' +
+          'Falling back to the (slow) UI-based installation',
+      );
+    }
+  }
+
+  const tmpRoot = await tempDir.openDir();
+  const tmpPort = await findAPortNotInUse(HOST_PORT_RANGE[0], HOST_PORT_RANGE[1]);
+  const configName = `appium.${CONFIG_EXTENSION}`;
+  const configPath = path.resolve(tmpRoot, configName);
+  const tmpServer = http.createServer(async function (_, res) {
+    const configFile = await fs.readFile(configPath);
+    res.end(configFile);
+  });
+  try {
+    const certBuffer = Buffer.from(content, 'base64');
+    const cn = commonName || (await extractCommonName(certBuffer));
+    const mobileConfig = toMobileConfig(certBuffer, cn);
+    try {
+      await plist.updatePlistFile(configPath, mobileConfig, false, false);
+    } catch (err) {
+      throw new Error(
+        `Cannot store the generated config as '${configPath}'. ` +
+          `Original error: ${err.message}`,
+      );
+    }
+
+    try {
+      const host = os.hostname();
+      const certUrl = `http://${host}:${tmpPort}/${configName}`;
+      await tmpServer.listen(tmpPort);
+      try {
+        await waitForCondition(
+          async () => {
+            try {
+              return (await checkPortStatus(tmpPort, host)) === 'open';
+            } catch {
+              return false;
+            }
+          },
+          {
+            waitMs: TMPSERVER_STARTUP_TIMEOUT,
+            intervalMs: 300,
+          },
+        );
+        this.log.debug(`The temporary web server is running at http://${host}:${tmpPort}`);
+      } catch {
+        throw new Error(
+          `The temporary web server cannot be started at http://${host}:${tmpPort}.`,
+        );
+      }
+      if (this.isRealDevice()) {
+        try {
+          await this.proxyCommand('/url', 'POST', {url: certUrl});
+        } catch (err) {
+          if (this.isWebContext()) {
+            // The command above does not always work on real devices
+            await this.setUrl(certUrl);
+          } else {
+            throw err;
+          }
+        }
+      } else {
+        await /** @type {import('../driver').Simulator} */ (this.device).openUrl(certUrl);
+      }
+
+      let isCertAlreadyInstalled = false;
+      if (util.compareVersions(/** @type {string} */ (this.opts.platformVersion), '>=', '12.2')) {
+        if (await installPost122Certificate(this, cn)) {
+          await clickElement(this, Settings.Profile);
+          await trustCertificateInPreferences(this, cn);
+        } else {
+          isCertAlreadyInstalled = true;
+        }
+      } else {
+        if (await installPre122Certificate(this)) {
+          await clickElement(this, Button.Return_to_Settings);
+          await trustCertificateInPreferences(this, cn);
+        } else {
+          isCertAlreadyInstalled = true;
+        }
+      }
+      if (isCertAlreadyInstalled) {
+        this.log.info(
+          `It looks like the '${cn}' certificate has been already added to the CA root`,
+        );
+      }
+    } finally {
+      if (this.opts.bundleId) {
+        try {
+          await this.activateApp(this.opts.bundleId);
+        } catch (e) {
+          this.log.warn(
+            `Cannot restore the application '${this.opts.bundleId}'. Original error: ${e.message}`,
+          );
+        }
+      }
+    }
+
+    return (await util.toInMemoryBase64(configPath)).toString();
+  } finally {
+    await tmpServer.close();
+    await fs.rimraf(tmpRoot);
+  }
+}
+
+/**
+ * Removes installed certificates.
+ *
+ * This only works _if and only if_ `py-ios-device` is installed on the same machine Appium is running on.
+ *
+ * @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)
+ * @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) {
+  if (!this.isRealDevice()) {
+    throw new errors.NotImplementedError('This extension is only supported on real devices');
+  }
+  const client = new Pyidevice({
+    udid: this.opts.udid,
+    log: this.log,
+  });
+  await client.assertExists(true);
+  return await client.removeProfile(name);
+}
+
+/**
+ * Returns map of certificates installed on the real device.
+ *
+ * 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.
+ * @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() {
+  if (!this.isRealDevice()) {
+    throw new errors.NotImplementedError('This extension is only supported on real devices');
+  }
+  const client = new Pyidevice({
+    udid: this.opts.udid,
+    log: this.log,
+  });
+  await client.assertExists(true);
+  return await client.listProfiles();
+}
+
+
+/**
+ * Extracts the common name of the certificate from the given buffer.
+ *
+ * @param {Buffer} certBuffer
+ * @returns {Promise<string>} The common name of the certificate
+ */
 async function extractCommonName(certBuffer) {
   const tempCert = await tempDir.open({
     prefix: 'cert',
@@ -76,23 +302,6 @@ async function extractCommonName(certBuffer) {
   }
 }
 
-const LIBRE_SSL_PATTERN = /\/CN=([^\/]+)/; // eslint-disable-line no-useless-escape
-const OPEN_SSL_PATTERN = /,\sCN\s=\s([^,]+)/;
-
-export function parseCommonName(stringCertificate) {
-  const result = [LIBRE_SSL_PATTERN, OPEN_SSL_PATTERN].reduce((acc, r) => {
-    if (acc) {
-      return acc;
-    }
-    const match = r.exec(stringCertificate);
-    return match?.[1];
-  }, null);
-  if (!result) {
-    throw new Error(`There is no common name value in '${stringCertificate}' output`);
-  }
-  return result;
-}
-
 /**
  * Generates Apple's over-the-air configuration profile
  * for certificate deployment based on the given PEM certificate content.
@@ -283,204 +492,6 @@ async function installPost122Certificate(driver, name) {
   return true;
 }
 
-export default {
-  /**
-   * Installs a custom certificate onto the device.
-   *
-   * Since Xcode SDK 11.4, Apple has added a dedicated `simctl` subcommand to quickly handle
-   * 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
-   * 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}
-   */
-  async mobileInstallCertificate(content, commonName, isRoot = true) {
-    if (_.isEmpty(content)) {
-      throw new Error('Certificate content should not be empty');
-    }
-
-    if (this.isSimulator()) {
-      try {
-        const methodName = isRoot ? 'addRootCertificate' : 'addCertificate';
-        await /** @type {import('../driver').Simulator} */ (this.device).simctl[methodName](Buffer.from(content, 'base64').toString(), {
-          raw: true,
-        });
-        return;
-      } catch (e) {
-        this.log.debug(e);
-        this.log.info(
-          `The certificate cannot be installed via CLI. ` + `Falling back to UI-based deployment`,
-        );
-      }
-    } else {
-      const client = new Pyidevice({
-        udid: this.opts.udid,
-        log: this.log,
-      });
-      if (await client.assertExists(false)) {
-        await client.installProfile({payload: Buffer.from(content, 'base64')});
-        return;
-      } else {
-        this.log.info(
-          'pyidevice is not installed on your system. ' +
-            'Falling back to the (slow) UI-based installation',
-        );
-      }
-    }
-
-    const tmpRoot = await tempDir.openDir();
-    const tmpPort = await findAPortNotInUse(HOST_PORT_RANGE[0], HOST_PORT_RANGE[1]);
-    const configName = `appium.${CONFIG_EXTENSION}`;
-    const configPath = path.resolve(tmpRoot, configName);
-    const tmpServer = http.createServer(async function (_, res) {
-      const configFile = await fs.readFile(configPath);
-      res.end(configFile);
-    });
-    try {
-      const certBuffer = Buffer.from(content, 'base64');
-      const cn = commonName || (await extractCommonName(certBuffer));
-      const mobileConfig = toMobileConfig(certBuffer, cn);
-      try {
-        await plist.updatePlistFile(configPath, mobileConfig, false, false);
-      } catch (err) {
-        throw new Error(
-          `Cannot store the generated config as '${configPath}'. ` +
-            `Original error: ${err.message}`,
-        );
-      }
-
-      try {
-        const host = os.hostname();
-        const certUrl = `http://${host}:${tmpPort}/${configName}`;
-        await tmpServer.listen(tmpPort);
-        try {
-          await waitForCondition(
-            async () => {
-              try {
-                return (await checkPortStatus(tmpPort, host)) === 'open';
-              } catch {
-                return false;
-              }
-            },
-            {
-              waitMs: TMPSERVER_STARTUP_TIMEOUT,
-              intervalMs: 300,
-            },
-          );
-          this.log.debug(`The temporary web server is running at http://${host}:${tmpPort}`);
-        } catch {
-          throw new Error(
-            `The temporary web server cannot be started at http://${host}:${tmpPort}.`,
-          );
-        }
-        if (this.isRealDevice()) {
-          try {
-            await this.proxyCommand('/url', 'POST', {url: certUrl});
-          } catch (err) {
-            if (this.isWebContext()) {
-              // The command above does not always work on real devices
-              await this.setUrl(certUrl);
-            } else {
-              throw err;
-            }
-          }
-        } else {
-          await /** @type {import('../driver').Simulator} */ (this.device).openUrl(certUrl);
-        }
-
-        let isCertAlreadyInstalled = false;
-        if (util.compareVersions(/** @type {string} */ (this.opts.platformVersion), '>=', '12.2')) {
-          if (await installPost122Certificate(this, cn)) {
-            await clickElement(this, Settings.Profile);
-            await trustCertificateInPreferences(this, cn);
-          } else {
-            isCertAlreadyInstalled = true;
-          }
-        } else {
-          if (await installPre122Certificate(this)) {
-            await clickElement(this, Button.Return_to_Settings);
-            await trustCertificateInPreferences(this, cn);
-          } else {
-            isCertAlreadyInstalled = true;
-          }
-        }
-        if (isCertAlreadyInstalled) {
-          this.log.info(
-            `It looks like the '${cn}' certificate has been already added to the CA root`,
-          );
-        }
-      } finally {
-        if (this.opts.bundleId) {
-          try {
-            await this.activateApp(this.opts.bundleId);
-          } catch (e) {
-            this.log.warn(
-              `Cannot restore the application '${this.opts.bundleId}'. Original error: ${e.message}`,
-            );
-          }
-        }
-      }
-
-      return (await util.toInMemoryBase64(configPath)).toString();
-    } finally {
-      await tmpServer.close();
-      await fs.rimraf(tmpRoot);
-    }
-  },
-
-  /**
-   * Removes installed certificates.
-   *
-   * This only works _if and only if_ `py-ios-device` is installed on the same machine Appium is running on.
-   *
-   * @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)
-   * @throws {Error} If attempting to remove certificates for a simulated device or if `py-ios-device` is not installed
-   * @group Real Device Only
-   */
-  async mobileRemoveCertificate(name) {
-    if (!this.isRealDevice()) {
-      throw new errors.NotImplementedError('This extension is only supported on real devices');
-    }
-    const client = new Pyidevice({
-      udid: this.opts.udid,
-      log: this.log,
-    });
-    await client.assertExists(true);
-    return await client.removeProfile(name);
-  },
-
-  /**
-   * Returns map of certificates installed on the real device.
-   *
-   * 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.
-   * @throws {Error} If attempting to list certificates for a simulated device or if `py-ios-device` is not installed
-   * @this {XCUITestDriver}
-   */
-  async mobileListCertificates() {
-    if (!this.isRealDevice()) {
-      throw new errors.NotImplementedError('This extension is only supported on real devices');
-    }
-    const client = new Pyidevice({
-      udid: this.opts.udid,
-      log: this.log,
-    });
-    await client.assertExists(true);
-    return await client.listProfiles();
-  },
-};
-
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver
  */

package/lib/commands/clipboard.js

@@ -1,36 +1,34 @@
-export default {
-  /**
-   * Sets the primary clipboard's content on the device under test.
-   *
-   * @param {string} content - The content to be set as base64 encoded string.
-   * @param {string} [contentType=plaintext] - The type of the content to set.
-   *                                            Only `plaintext`, 'image and 'url' are supported.
-   * @this {XCUITestDriver}
-   */
-  async setClipboard(content, contentType) {
-    await this.proxyCommand('/wda/setPasteboard', 'POST', {
-      content,
-      contentType,
-    });
-  },
+/**
+ * Sets the primary clipboard's content on the device under test.
+ *
+ * @param {string} content - The content to be set as base64 encoded string.
+ * @param {string} [contentType=plaintext] - The type of the content to set.
+ *                                            Only `plaintext`, 'image and 'url' are supported.
+ * @this {XCUITestDriver}
+ */
+export async function setClipboard(content, contentType) {
+  await this.proxyCommand('/wda/setPasteboard', 'POST', {
+    content,
+    contentType,
+  });
+}
 
-  /**
-   * Gets the content of the primary clipboard on the device under test.
-   *
-   * @param {string} [contentType=plaintext] - The type of the content to get.
-   *                                            Only `plaintext`, 'image and 'url' are supported.
-   * @returns {Promise<string>} The actual clipboard content encoded into base64 string.
-   * An empty string is returned if the clipboard contains no data.
-   * @this {XCUITestDriver}
-   */
-  async getClipboard(contentType) {
-    return /** @type {string} */ (
-      await this.proxyCommand('/wda/getPasteboard', 'POST', {
-        contentType,
-      })
-    );
-  },
-};
+/**
+ * Gets the content of the primary clipboard on the device under test.
+ *
+ * @param {string} [contentType=plaintext] - The type of the content to get.
+ *                                            Only `plaintext`, 'image and 'url' are supported.
+ * @returns {Promise<string>} The actual clipboard content encoded into base64 string.
+ * An empty string is returned if the clipboard contains no data.
+ * @this {XCUITestDriver}
+ */
+export async function getClipboard(contentType) {
+  return /** @type {string} */ (
+    await this.proxyCommand('/wda/getPasteboard', 'POST', {
+      contentType,
+    })
+  );
+}
 
 /**
  * @typedef {import('../driver').XCUITestDriver} XCUITestDriver