obsidian-integration-testing 8.1.2 → 8.2.0

package/README.md

@@ -703,7 +703,7 @@ Runs tests against Obsidian Mobile on an Android emulator or real device via App
    adb shell appops set md.obsidian MANAGE_EXTERNAL_STORAGE allow
    ```
 
-4. Install [Appium](https://appium.io/) and the [UiAutomator2 driver](https://github.com/appium/appium-uiautomator2-driver):
+4. (Optional) Install [Appium](https://appium.io/) and the [UiAutomator2 driver](https://github.com/appium/appium-uiautomator2-driver):
 
    ```bash
    npm install -g appium
@@ -712,7 +712,7 @@ Runs tests against Obsidian Mobile on an Android emulator or real device via App
 
    > [!NOTE]
    >
-   > You do not need to start the Appium server manually — the test framework auto-starts it if it is not already running.
+   > This step is optional. You do not need to start the Appium server manually — the test framework auto-starts it if it is not already running, and by default it also **auto-installs** Appium (globally) and the UiAutomator2 driver when they are missing. Set `shouldAutoInstallAppiumDependencies: false` to manage the Appium toolchain yourself and skip the global install.
 
 5. Configure vitest:
 
@@ -735,18 +735,19 @@ Runs tests against Obsidian Mobile on an Android emulator or real device via App
 
 Besides the required `appiumUrl` and `avdName`, the transport accepts these optional knobs (all with sensible defaults):
 
-| Option                                        | Purpose                                                                                                         | Default                |
-| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------- |
-| `appId`                                       | App package (Android) or bundle ID (iOS).                                                                       | `'md.obsidian'`        |
-| `appiumStartTimeoutInMilliseconds`            | Max wait for the auto-started Appium server to become ready; only when the harness auto-starts it.              | `180000`               |
-| `deviceIdleTimeoutInMilliseconds`             | Max wait after boot for a started emulator to go idle before the session; avoids inflated cold setup. 0 skips.  | `60000`                |
-| `isAppiumConsoleVisible`                      | Show the auto-started Appium server console window and live output. Hidden and quiet by default.                | `false`                |
-| `isEmulatorVisible`                           | Show the auto-started emulator window. Hidden (`-no-window`, headless) by default so it never steals focus.     | `false`                |
-| `layoutReadyTimeoutInMilliseconds`            | Max wait for `app.workspace.layoutReady` after the vault (re)opens; raise on slow emulators.                    | `90000`                |
-| `sessionConnectionRetryTimeoutInMilliseconds` | Max wait to establish the Appium session (UiAutomator2 install + app launch); the dominant startup cost.        | `180000`               |
-| `shouldAutoStartAppium`                       | Auto-start the Appium server when it is not already reachable.                                                  | `true`                 |
-| `vaultBasePath`                               | Base device path where Obsidian stores vaults.                                                                  | `'/sdcard/Documents/'` |
-| `webviewTimeoutInMilliseconds`                | Max wait for the WebView context after the Appium session starts.                                               | `60000`                |
+| Option                                        | Purpose                                                                                                          | Default                |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `appId`                                       | App package (Android) or bundle ID (iOS).                                                                        | `'md.obsidian'`        |
+| `appiumStartTimeoutInMilliseconds`            | Max wait for the auto-started Appium server to become ready; only when the harness auto-starts it.               | `180000`               |
+| `deviceIdleTimeoutInMilliseconds`             | Max wait after boot for a started emulator to go idle before the session; avoids inflated cold setup. 0 skips.   | `60000`                |
+| `isAppiumConsoleVisible`                      | Show the auto-started Appium server console window and live output. Hidden and quiet by default.                 | `false`                |
+| `isEmulatorVisible`                           | Show the auto-started emulator window. Hidden (`-no-window`, headless) by default so it never steals focus.      | `false`                |
+| `layoutReadyTimeoutInMilliseconds`            | Max wait for `app.workspace.layoutReady` after the vault (re)opens; raise on slow emulators.                     | `90000`                |
+| `sessionConnectionRetryTimeoutInMilliseconds` | Max wait to establish the Appium session (UiAutomator2 install + app launch); the dominant startup cost.         | `180000`               |
+| `shouldAutoInstallAppiumDependencies`         | Auto-install missing Appium + the UiAutomator2 driver before auto-starting the server (global `npm install -g`). | `true`                 |
+| `shouldAutoStartAppium`                       | Auto-start the Appium server when it is not already reachable.                                                   | `true`                 |
+| `vaultBasePath`                               | Base device path where Obsidian stores vaults.                                                                   | `'/sdcard/Documents/'` |
+| `webviewTimeoutInMilliseconds`                | Max wait for the WebView context after the Appium session starts.                                                | `60000`                |
 
 > [!NOTE]
 >

package/dist/lib/cjs/appium-dependencies.cjs

@@ -0,0 +1,48 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var appium_dependencies_exports = {};
+__export(appium_dependencies_exports, {
+  UIAUTOMATOR2_DRIVER_NAME: () => UIAUTOMATOR2_DRIVER_NAME,
+  checkIsAppiumDriverInstalled: () => checkIsAppiumDriverInstalled,
+  resolveShouldAutoInstallAppiumDependencies: () => resolveShouldAutoInstallAppiumDependencies
+});
+module.exports = __toCommonJS(appium_dependencies_exports);
+const UIAUTOMATOR2_DRIVER_NAME = "uiautomator2";
+function checkIsAppiumDriverInstalled(params) {
+  let parsed;
+  try {
+    parsed = JSON.parse(params.driverListJson);
+  } catch {
+    return false;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return false;
+  }
+  return params.driverName in parsed;
+}
+function resolveShouldAutoInstallAppiumDependencies(options) {
+  return options.shouldAutoInstallAppiumDependencies ?? true;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  UIAUTOMATOR2_DRIVER_NAME,
+  checkIsAppiumDriverInstalled,
+  resolveShouldAutoInstallAppiumDependencies
+});
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vc3JjL2FwcGl1bS1kZXBlbmRlbmNpZXMudHMiXSwKICAic291cmNlc0NvbnRlbnQiOiBbIi8qKlxuICogQGZpbGVcbiAqXG4gKiBQdXJlIGhlbHBlcnMgZm9yIGRlY2lkaW5nIHdoZXRoZXIgdGhlIGhhcm5lc3MgbXVzdCBhdXRvLWluc3RhbGwgdGhlIEFwcGl1bVxuICogZGVwZW5kZW5jaWVzICh0aGUgYHVpYXV0b21hdG9yMmAgZHJpdmVyKSBiZWZvcmUgaXQgYXV0by1zdGFydHMgdGhlIEFwcGl1bVxuICogc2VydmVyLCBwbHVzIHJlc29sdmluZyB0aGUgYXV0by1pbnN0YWxsIG9wdC1vdXQgZnJvbSB0aGUgdHJhbnNwb3J0IG9wdGlvbnMuXG4gKiBLZXB0IHNlcGFyYXRlIGZyb20gdGhlIGludGVncmF0aW9uLW9ubHkgYHRyYW5zcG9ydC1mYWN0b3J5YCBzbyB0aGUgcGFyc2luZyBhbmRcbiAqIGRlZmF1bHQgcmVzb2x1dGlvbiBzdGF5IHVuaXQtdGVzdGFibGUgKHRoZSBmYWN0b3J5IGl0c2VsZiBzaGVsbHMgb3V0IHRvIGBucG1gXG4gKiAvIGBucHhgIGFuZCBpcyBleGNsdWRlZCBmcm9tIHVuaXQgdGVzdHMpLlxuICovXG5cbmltcG9ydCB0eXBlIHsgT2JzaWRpYW5BbmRyb2lkQXBwaXVtVHJhbnNwb3J0T3B0aW9ucyB9IGZyb20gJy4vdHJhbnNwb3J0LW9wdGlvbnMuY2pzJztcblxuLyoqXG4gKiBUaGUgQXBwaXVtIGRyaXZlciBuYW1lIHJlcXVpcmVkIHRvIGF1dG9tYXRlIE9ic2lkaWFuIE1vYmlsZSBvbiBBbmRyb2lkLlxuICovXG5leHBvcnQgY29uc3QgVUlBVVRPTUFUT1IyX0RSSVZFUl9OQU1FID0gJ3VpYXV0b21hdG9yMic7XG5cbi8qKlxuICogUGFyYW1ldGVycyBmb3Ige0BsaW5rIGNoZWNrSXNBcHBpdW1Ecml2ZXJJbnN0YWxsZWR9LlxuICovXG5leHBvcnQgaW50ZXJmYWNlIENoZWNrSXNBcHBpdW1Ecml2ZXJJbnN0YWxsZWRQYXJhbXMge1xuICAvKipcbiAgICogUmF3IHN0ZG91dCBvZiBgYXBwaXVtIGRyaXZlciBsaXN0IC0taW5zdGFsbGVkIC0tanNvbmAgXHUyMDE0IGEgSlNPTiBvYmplY3Qga2V5ZWRcbiAgICogYnkgaW5zdGFsbGVkIGRyaXZlciBuYW1lIChge31gIHdoZW4gbm9uZSBhcmUgaW5zdGFsbGVkKS5cbiAgICovXG4gIHJlYWRvbmx5IGRyaXZlckxpc3RKc29uOiBzdHJpbmc7XG5cbiAgLyoqIFRoZSBkcml2ZXIgbmFtZSB0byBsb29rIGZvciAoZS5nLiB7QGxpbmsgVUlBVVRPTUFUT1IyX0RSSVZFUl9OQU1FfSkuICovXG4gIHJlYWRvbmx5IGRyaXZlck5hbWU6IHN0cmluZztcbn1cblxuLyoqXG4gKiBEZWNpZGVzIHdoZXRoZXIgYSBnaXZlbiBBcHBpdW0gZHJpdmVyIGlzIGluc3RhbGxlZCwgZnJvbSB0aGUgcmF3IEpTT04gb3V0cHV0XG4gKiBvZiBgYXBwaXVtIGRyaXZlciBsaXN0IC0taW5zdGFsbGVkIC0tanNvbmAuXG4gKlxuICogYC0taW5zdGFsbGVkYCByZXN0cmljdHMgdGhlIGxpc3RpbmcgdG8gaW5zdGFsbGVkIGRyaXZlcnMsIHNvIGEgZHJpdmVyIGlzXG4gKiBwcmVzZW50IGV4YWN0bHkgd2hlbiBpdHMgbmFtZSBpcyBhIGtleSBvZiB0aGUgcGFyc2VkIG9iamVjdC4gTWFsZm9ybWVkIG9yXG4gKiBub24tb2JqZWN0IG91dHB1dCAoYW4gZW1wdHkgc3RyaW5nLCBhIGxvZyBsaW5lIHRoYXQgbGVha2VkIG9udG8gc3Rkb3V0LCBhXG4gKiBKU09OIHByaW1pdGl2ZSwgYG51bGxgKSBpcyB0cmVhdGVkIGFzIFwibm90IGluc3RhbGxlZFwiIHNvIHRoZSBjYWxsZXIgcHJvY2VlZHNcbiAqIHRvIGluc3RhbGwgXHUyMDE0IHRoZSBpbnN0YWxsIGNvbW1hbmQgaXMgb25seSBpc3N1ZWQgd2hlbiB0aGlzIHJldHVybnMgYGZhbHNlYC5cbiAqXG4gKiBAcGFyYW0gcGFyYW1zIC0gVGhlIHNhbXBsZWQgZHJpdmVyLWxpc3Qgb3V0cHV0IGFuZCB0aGUgZHJpdmVyIG5hbWUgdG8gY2hlY2suXG4gKiBAcmV0dXJucyBgdHJ1ZWAgd2hlbiB0aGUgZHJpdmVyIGlzIGxpc3RlZCBhcyBpbnN0YWxsZWQuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBjaGVja0lzQXBwaXVtRHJpdmVySW5zdGFsbGVkKHBhcmFtczogQ2hlY2tJc0FwcGl1bURyaXZlckluc3RhbGxlZFBhcmFtcyk6IGJvb2xlYW4ge1xuICBsZXQgcGFyc2VkOiB1bmtub3duO1xuICB0cnkge1xuICAgIHBhcnNlZCA9IEpTT04ucGFyc2UocGFyYW1zLmRyaXZlckxpc3RKc29uKTtcbiAgfSBjYXRjaCB7XG4gICAgcmV0dXJuIGZhbHNlO1xuICB9XG5cbiAgaWYgKHR5cGVvZiBwYXJzZWQgIT09ICdvYmplY3QnIHx8IHBhcnNlZCA9PT0gbnVsbCkge1xuICAgIHJldHVybiBmYWxzZTtcbiAgfVxuXG4gIHJldHVybiBwYXJhbXMuZHJpdmVyTmFtZSBpbiBwYXJzZWQ7XG59XG5cbi8qKlxuICogUmVzb2x2ZXMgd2hldGhlciB0aGUgaGFybmVzcyBtYXkgYXV0by1pbnN0YWxsIG1pc3NpbmcgQXBwaXVtIGRlcGVuZGVuY2llcyxcbiAqIGFwcGx5aW5nIHRoZSBkZWZhdWx0IHdoZW4gdGhlIG9wdGlvbiBpcyBvbWl0dGVkLlxuICpcbiAqIFRoaXMgb25seSBnb3Zlcm5zIHRoZSBtYWNoaW5lLW11dGF0aW5nIGluc3RhbGwgc3RlcCAoYSBnbG9iYWwgYG5wbSBpbnN0YWxsIC1nXG4gKiBhcHBpdW1gIGFuZCBhbiBgYXBwaXVtIGRyaXZlciBpbnN0YWxsYCk7IGl0IGlzIGEgbm8tb3AgdW5sZXNzIHRoZSBoYXJuZXNzIGlzXG4gKiBhbHNvIGF1dG8tc3RhcnRpbmcgdGhlIEFwcGl1bSBzZXJ2ZXIgKHtAbGlua1xuICogT2JzaWRpYW5BbmRyb2lkQXBwaXVtVHJhbnNwb3J0T3B0aW9ucy5zaG91bGRBdXRvU3RhcnRBcHBpdW19KS4gU2V0IGl0IHRvXG4gKiBgZmFsc2VgIHRvIG1hbmFnZSB0aGUgQXBwaXVtIHRvb2xjaGFpbiB5b3Vyc2VsZi5cbiAqXG4gKiBAcGFyYW0gb3B0aW9ucyAtIFRoZSBBbmRyb2lkIEFwcGl1bSB0cmFuc3BvcnQgb3B0aW9ucy5cbiAqIEByZXR1cm5zIFdoZXRoZXIgbWlzc2luZyBBcHBpdW0gZGVwZW5kZW5jaWVzIG1heSBiZSBhdXRvLWluc3RhbGxlZC5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHJlc29sdmVTaG91bGRBdXRvSW5zdGFsbEFwcGl1bURlcGVuZGVuY2llcyhcbiAgb3B0aW9uczogT2JzaWRpYW5BbmRyb2lkQXBwaXVtVHJhbnNwb3J0T3B0aW9uc1xuKTogYm9vbGVhbiB7XG4gIHJldHVybiBvcHRpb25zLnNob3VsZEF1dG9JbnN0YWxsQXBwaXVtRGVwZW5kZW5jaWVzID8/IHRydWU7XG59XG4iXSwKICAibWFwcGluZ3MiOiAiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQWdCTyxNQUFNLDJCQUEyQjtBQTZCakMsU0FBUyw2QkFBNkIsUUFBcUQ7QUFDaEcsTUFBSTtBQUNKLE1BQUk7QUFDRixhQUFTLEtBQUssTUFBTSxPQUFPLGNBQWM7QUFBQSxFQUMzQyxRQUFRO0FBQ04sV0FBTztBQUFBLEVBQ1Q7QUFFQSxNQUFJLE9BQU8sV0FBVyxZQUFZLFdBQVcsTUFBTTtBQUNqRCxXQUFPO0FBQUEsRUFDVDtBQUVBLFNBQU8sT0FBTyxjQUFjO0FBQzlCO0FBZU8sU0FBUywyQ0FDZCxTQUNTO0FBQ1QsU0FBTyxRQUFRLHVDQUF1QztBQUN4RDsiLAogICJuYW1lcyI6IFtdCn0K

package/dist/lib/cjs/appium-dependencies.d.cts

@@ -0,0 +1,55 @@
+/**
+ * @file
+ *
+ * Pure helpers for deciding whether the harness must auto-install the Appium
+ * dependencies (the `uiautomator2` driver) before it auto-starts the Appium
+ * server, plus resolving the auto-install opt-out from the transport options.
+ * Kept separate from the integration-only `transport-factory` so the parsing and
+ * default resolution stay unit-testable (the factory itself shells out to `npm`
+ * / `npx` and is excluded from unit tests).
+ */
+import type { ObsidianAndroidAppiumTransportOptions } from './transport-options.cjs';
+/**
+ * The Appium driver name required to automate Obsidian Mobile on Android.
+ */
+export declare const UIAUTOMATOR2_DRIVER_NAME = "uiautomator2";
+/**
+ * Parameters for {@link checkIsAppiumDriverInstalled}.
+ */
+export interface CheckIsAppiumDriverInstalledParams {
+    /**
+     * Raw stdout of `appium driver list --installed --json` — a JSON object keyed
+     * by installed driver name (`{}` when none are installed).
+     */
+    readonly driverListJson: string;
+    /** The driver name to look for (e.g. {@link UIAUTOMATOR2_DRIVER_NAME}). */
+    readonly driverName: string;
+}
+/**
+ * Decides whether a given Appium driver is installed, from the raw JSON output
+ * of `appium driver list --installed --json`.
+ *
+ * `--installed` restricts the listing to installed drivers, so a driver is
+ * present exactly when its name is a key of the parsed object. Malformed or
+ * non-object output (an empty string, a log line that leaked onto stdout, a
+ * JSON primitive, `null`) is treated as "not installed" so the caller proceeds
+ * to install — the install command is only issued when this returns `false`.
+ *
+ * @param params - The sampled driver-list output and the driver name to check.
+ * @returns `true` when the driver is listed as installed.
+ */
+export declare function checkIsAppiumDriverInstalled(params: CheckIsAppiumDriverInstalledParams): boolean;
+/**
+ * Resolves whether the harness may auto-install missing Appium dependencies,
+ * applying the default when the option is omitted.
+ *
+ * This only governs the machine-mutating install step (a global `npm install -g
+ * appium` and an `appium driver install`); it is a no-op unless the harness is
+ * also auto-starting the Appium server ({@link
+ * ObsidianAndroidAppiumTransportOptions.shouldAutoStartAppium}). Set it to
+ * `false` to manage the Appium toolchain yourself.
+ *
+ * @param options - The Android Appium transport options.
+ * @returns Whether missing Appium dependencies may be auto-installed.
+ */
+export declare function resolveShouldAutoInstallAppiumDependencies(options: ObsidianAndroidAppiumTransportOptions): boolean;

package/dist/lib/cjs/library.cjs

@@ -21,7 +21,7 @@ __export(library_exports, {
   LIBRARY_VERSION: () => LIBRARY_VERSION
 });
 module.exports = __toCommonJS(library_exports);
-const LIBRARY_VERSION = false ? "dev" : "8.1.1";
+const LIBRARY_VERSION = false ? "dev" : "8.1.2";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   LIBRARY_VERSION