obsidian-integration-testing 5.6.0 → 6.2.0

package/dist/lib/esm/transport-options.d.mts

@@ -13,6 +13,18 @@ export interface ObsidianAndroidAppiumTransportOptions {
      * Defaults to `'md.obsidian'`
      */
     readonly appId?: string;
+    /**
+     * Timeout in milliseconds for the auto-started Appium server to become ready
+     * (its `/status` endpoint to respond).
+     *
+     * Only applies when the harness auto-starts the Appium server
+     * ({@link shouldAutoStartAppium}); ignored when attaching to an
+     * already-running server. On a cold machine the `npx appium` server can take
+     * a while to finish booting, so raise this if startup times out.
+     *
+     * @default `180000`
+     */
+    readonly appiumStartTimeoutInMilliseconds?: number;
     /**
      * The Appium server URL (e.g. `'http://localhost:4723'`).
      */
@@ -35,6 +47,68 @@ export interface ObsidianAndroidAppiumTransportOptions {
      * factory skips emulator startup and attaches to the existing session.
      */
     readonly deviceId?: string;
+    /**
+     * Timeout in milliseconds for waiting, after `sys.boot_completed`, for a
+     * harness-started emulator to become idle before the Appium session is
+     * established.
+     *
+     * `sys.boot_completed` fires *before* the guest is actually idle: package
+     * optimization and system services keep churning, so establishing the session
+     * immediately makes every one of UiAutomator2's serialized `adb` round-trips
+     * contend with that work and inflates session establishment ~3x. The factory
+     * instead waits until the boot animation has stopped and the package manager
+     * is serving, proceeding early once idle or after this budget (best-effort — a
+     * timeout logs a warning and proceeds). Set `0` to skip the wait. Only applies
+     * to a harness-started emulator, not a reused one.
+     *
+     * @default `60000`
+     */
+    readonly deviceIdleTimeoutInMilliseconds?: number;
+    /**
+     * Whether the auto-started Appium server console window is shown.
+     *
+     * When `false` (the default), the `npx appium` server process is spawned with
+     * its console window hidden (`windowsHide`), so it never steals focus. Ignored
+     * when attaching to an already-running Appium server ({@link shouldAutoStartAppium}
+     * `false`, or the server already reachable). Set `true` to see the server log window.
+     *
+     * @default `false`
+     */
+    readonly isAppiumConsoleVisible?: boolean;
+    /**
+     * Whether the auto-started Android emulator window is shown on screen.
+     *
+     * When `false` (the default), the emulator is started with `-no-window`
+     * (headless), so it never steals focus. Ignored when reusing an already-running
+     * device (nothing is launched to hide). Set `true` to watch the emulator UI.
+     *
+     * @default `false`
+     */
+    readonly isEmulatorVisible?: boolean;
+    /**
+     * Timeout in milliseconds for waiting for `app.workspace.layoutReady` after
+     * the vault is (re)opened.
+     *
+     * Registering a vault triggers a full Obsidian re-init (`location.reload()`
+     * reopens the vault and reloads every plugin — the heaviest startup step). On
+     * a cold-booted or under-provisioned emulator that init can take a while, so
+     * this budget is the largest of the transport timeouts. Raise it further if
+     * releases still flake on slow CI emulators.
+     *
+     * @default `90000`
+     */
+    readonly layoutReadyTimeoutInMilliseconds?: number;
+    /**
+     * Timeout in milliseconds for establishing the Appium session (WebDriverIO
+     * `remote()` — UiAutomator2 server install + app launch).
+     *
+     * This is the largest and most load-sensitive step of the Android setup:
+     * on a cold or contended emulator it dominates startup and can take a few
+     * minutes. Raise it if session establishment times out under load.
+     *
+     * @default `180000`
+     */
+    readonly sessionConnectionRetryTimeoutInMilliseconds?: number;
     /**
      * An existing Appium session ID to reattach to.
      *
@@ -113,6 +187,21 @@ export interface ObsidianCdpTransportOptions {
      * @default `undefined`
      */
     readonly isHarnessOwnedInstance?: boolean | undefined;
+    /**
+     * Whether the owned desktop Obsidian window is shown on screen.
+     *
+     * When `false` (the default), the harness launches the owned instance with
+     * keep-alive Chromium flags and moves its window **off-screen** once Electron's
+     * remote bridge is available, so the run never steals focus or pops a window in
+     * front of you. Off-screen (not minimized) keeps the renderer live, so
+     * `setTimeout`, `requestAnimationFrame`, `:hover`, and trusted input behave
+     * identically to a visible window. Set `true` to watch the window (e.g. when
+     * debugging). Ignored in attach mode ({@link port} set) — the harness never
+     * moves the user's own running window.
+     *
+     * @default `false`
+     */
+    readonly isObsidianAppVisible?: boolean;
     /**
      * Pins the **Electron shell** (installer build) the owned instance runs.
      *

package/dist/lib/esm/visibility.d.mts

@@ -0,0 +1,61 @@
+/**
+ * @file
+ *
+ * Pure resolution of the process-visibility options — whether the launched
+ * desktop Obsidian window, Android emulator window, and Appium server console
+ * are shown on screen. All three surfaces are **hidden by default** (`is*Visible`
+ * is `false` when omitted) so an integration run never steals focus or pops
+ * windows in front of the user.
+ *
+ * Kept separate from the integration-only launch/spawn code (`transport-factory`,
+ * `transport-desktop-cdp`, `obsidian-instance`, all excluded from unit tests) so
+ * the hidden-by-default resolution stays unit-testable — those launchers need a
+ * real Obsidian / emulator / Appium server.
+ */
+/**
+ * Chromium switches passed to a **hidden** owned desktop instance.
+ *
+ * The harness hides the window by moving it **off-screen** (not minimizing it).
+ * An off-screen window still reports `visibilityState: 'visible'` to Chromium, so
+ * `setTimeout`, `requestAnimationFrame`, `:hover`, and trusted input all keep
+ * working exactly as when visible — but only if Chromium never decides to
+ * background it. These flags guarantee that: native occlusion tracking is
+ * disabled and the timer/renderer backgrounding heuristics are switched off, so
+ * an off-screen (or covered) renderer is never throttled or frozen.
+ *
+ * A *minimized* window, by contrast, freezes `requestAnimationFrame` regardless
+ * of any flag (there is no surface to composite), which is why the harness moves
+ * the window off-screen rather than minimizing it.
+ */
+export declare const OWNED_HIDDEN_LAUNCH_FLAGS: string[];
+/**
+ * Resolves the extra Chromium launch args for an owned desktop instance: the
+ * {@link OWNED_HIDDEN_LAUNCH_FLAGS} when the window is hidden (the default), or
+ * an empty list when it is visible.
+ *
+ * @param isObsidianAppVisible - The resolved option value (omitted → hidden).
+ * @returns The extra launch args (possibly empty).
+ */
+export declare function resolveOwnedHiddenLaunchArgs(isObsidianAppVisible?: boolean): string[];
+/**
+ * Whether the auto-started Appium server console window should be hidden.
+ *
+ * @param isAppiumConsoleVisible - The resolved option value (omitted → hidden).
+ * @returns `true` when the console window should be hidden (the default).
+ */
+export declare function shouldHideAppiumConsole(isAppiumConsoleVisible?: boolean): boolean;
+/**
+ * Whether the auto-started Android emulator window should be hidden
+ * (via the emulator's `-no-window` flag).
+ *
+ * @param isEmulatorVisible - The resolved option value (omitted → hidden).
+ * @returns `true` when the emulator window should be hidden (the default).
+ */
+export declare function shouldHideEmulatorWindow(isEmulatorVisible?: boolean): boolean;
+/**
+ * Whether the owned desktop Obsidian window should be hidden (moved off-screen).
+ *
+ * @param isObsidianAppVisible - The resolved option value (omitted → hidden).
+ * @returns `true` when the window should be hidden (the default).
+ */
+export declare function shouldHideObsidianApp(isObsidianAppVisible?: boolean): boolean;

package/dist/lib/esm/visibility.mjs

@@ -0,0 +1,26 @@
+const OWNED_HIDDEN_LAUNCH_FLAGS = [
+  "--disable-features=CalculateNativeWinOcclusion",
+  "--disable-background-timer-throttling",
+  "--disable-backgrounding-occluded-windows",
+  "--disable-renderer-backgrounding"
+];
+function resolveOwnedHiddenLaunchArgs(isObsidianAppVisible) {
+  return shouldHideObsidianApp(isObsidianAppVisible) ? [...OWNED_HIDDEN_LAUNCH_FLAGS] : [];
+}
+function shouldHideAppiumConsole(isAppiumConsoleVisible) {
+  return !(isAppiumConsoleVisible ?? false);
+}
+function shouldHideEmulatorWindow(isEmulatorVisible) {
+  return !(isEmulatorVisible ?? false);
+}
+function shouldHideObsidianApp(isObsidianAppVisible) {
+  return !(isObsidianAppVisible ?? false);
+}
+export {
+  OWNED_HIDDEN_LAUNCH_FLAGS,
+  resolveOwnedHiddenLaunchArgs,
+  shouldHideAppiumConsole,
+  shouldHideEmulatorWindow,
+  shouldHideObsidianApp
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vc3JjL3Zpc2liaWxpdHkudHMiXSwKICAic291cmNlc0NvbnRlbnQiOiBbIi8qKlxuICogQGZpbGVcbiAqXG4gKiBQdXJlIHJlc29sdXRpb24gb2YgdGhlIHByb2Nlc3MtdmlzaWJpbGl0eSBvcHRpb25zIFx1MjAxNCB3aGV0aGVyIHRoZSBsYXVuY2hlZFxuICogZGVza3RvcCBPYnNpZGlhbiB3aW5kb3csIEFuZHJvaWQgZW11bGF0b3Igd2luZG93LCBhbmQgQXBwaXVtIHNlcnZlciBjb25zb2xlXG4gKiBhcmUgc2hvd24gb24gc2NyZWVuLiBBbGwgdGhyZWUgc3VyZmFjZXMgYXJlICoqaGlkZGVuIGJ5IGRlZmF1bHQqKiAoYGlzKlZpc2libGVgXG4gKiBpcyBgZmFsc2VgIHdoZW4gb21pdHRlZCkgc28gYW4gaW50ZWdyYXRpb24gcnVuIG5ldmVyIHN0ZWFscyBmb2N1cyBvciBwb3BzXG4gKiB3aW5kb3dzIGluIGZyb250IG9mIHRoZSB1c2VyLlxuICpcbiAqIEtlcHQgc2VwYXJhdGUgZnJvbSB0aGUgaW50ZWdyYXRpb24tb25seSBsYXVuY2gvc3Bhd24gY29kZSAoYHRyYW5zcG9ydC1mYWN0b3J5YCxcbiAqIGB0cmFuc3BvcnQtZGVza3RvcC1jZHBgLCBgb2JzaWRpYW4taW5zdGFuY2VgLCBhbGwgZXhjbHVkZWQgZnJvbSB1bml0IHRlc3RzKSBzb1xuICogdGhlIGhpZGRlbi1ieS1kZWZhdWx0IHJlc29sdXRpb24gc3RheXMgdW5pdC10ZXN0YWJsZSBcdTIwMTQgdGhvc2UgbGF1bmNoZXJzIG5lZWQgYVxuICogcmVhbCBPYnNpZGlhbiAvIGVtdWxhdG9yIC8gQXBwaXVtIHNlcnZlci5cbiAqL1xuXG4vKipcbiAqIENocm9taXVtIHN3aXRjaGVzIHBhc3NlZCB0byBhICoqaGlkZGVuKiogb3duZWQgZGVza3RvcCBpbnN0YW5jZS5cbiAqXG4gKiBUaGUgaGFybmVzcyBoaWRlcyB0aGUgd2luZG93IGJ5IG1vdmluZyBpdCAqKm9mZi1zY3JlZW4qKiAobm90IG1pbmltaXppbmcgaXQpLlxuICogQW4gb2ZmLXNjcmVlbiB3aW5kb3cgc3RpbGwgcmVwb3J0cyBgdmlzaWJpbGl0eVN0YXRlOiAndmlzaWJsZSdgIHRvIENocm9taXVtLCBzb1xuICogYHNldFRpbWVvdXRgLCBgcmVxdWVzdEFuaW1hdGlvbkZyYW1lYCwgYDpob3ZlcmAsIGFuZCB0cnVzdGVkIGlucHV0IGFsbCBrZWVwXG4gKiB3b3JraW5nIGV4YWN0bHkgYXMgd2hlbiB2aXNpYmxlIFx1MjAxNCBidXQgb25seSBpZiBDaHJvbWl1bSBuZXZlciBkZWNpZGVzIHRvXG4gKiBiYWNrZ3JvdW5kIGl0LiBUaGVzZSBmbGFncyBndWFyYW50ZWUgdGhhdDogbmF0aXZlIG9jY2x1c2lvbiB0cmFja2luZyBpc1xuICogZGlzYWJsZWQgYW5kIHRoZSB0aW1lci9yZW5kZXJlciBiYWNrZ3JvdW5kaW5nIGhldXJpc3RpY3MgYXJlIHN3aXRjaGVkIG9mZiwgc29cbiAqIGFuIG9mZi1zY3JlZW4gKG9yIGNvdmVyZWQpIHJlbmRlcmVyIGlzIG5ldmVyIHRocm90dGxlZCBvciBmcm96ZW4uXG4gKlxuICogQSAqbWluaW1pemVkKiB3aW5kb3csIGJ5IGNvbnRyYXN0LCBmcmVlemVzIGByZXF1ZXN0QW5pbWF0aW9uRnJhbWVgIHJlZ2FyZGxlc3NcbiAqIG9mIGFueSBmbGFnICh0aGVyZSBpcyBubyBzdXJmYWNlIHRvIGNvbXBvc2l0ZSksIHdoaWNoIGlzIHdoeSB0aGUgaGFybmVzcyBtb3Zlc1xuICogdGhlIHdpbmRvdyBvZmYtc2NyZWVuIHJhdGhlciB0aGFuIG1pbmltaXppbmcgaXQuXG4gKi9cbmV4cG9ydCBjb25zdCBPV05FRF9ISURERU5fTEFVTkNIX0ZMQUdTID0gW1xuICAnLS1kaXNhYmxlLWZlYXR1cmVzPUNhbGN1bGF0ZU5hdGl2ZVdpbk9jY2x1c2lvbicsXG4gICctLWRpc2FibGUtYmFja2dyb3VuZC10aW1lci10aHJvdHRsaW5nJyxcbiAgJy0tZGlzYWJsZS1iYWNrZ3JvdW5kaW5nLW9jY2x1ZGVkLXdpbmRvd3MnLFxuICAnLS1kaXNhYmxlLXJlbmRlcmVyLWJhY2tncm91bmRpbmcnXG5dO1xuXG4vKipcbiAqIFJlc29sdmVzIHRoZSBleHRyYSBDaHJvbWl1bSBsYXVuY2ggYXJncyBmb3IgYW4gb3duZWQgZGVza3RvcCBpbnN0YW5jZTogdGhlXG4gKiB7QGxpbmsgT1dORURfSElEREVOX0xBVU5DSF9GTEFHU30gd2hlbiB0aGUgd2luZG93IGlzIGhpZGRlbiAodGhlIGRlZmF1bHQpLCBvclxuICogYW4gZW1wdHkgbGlzdCB3aGVuIGl0IGlzIHZpc2libGUuXG4gKlxuICogQHBhcmFtIGlzT2JzaWRpYW5BcHBWaXNpYmxlIC0gVGhlIHJlc29sdmVkIG9wdGlvbiB2YWx1ZSAob21pdHRlZCBcdTIxOTIgaGlkZGVuKS5cbiAqIEByZXR1cm5zIFRoZSBleHRyYSBsYXVuY2ggYXJncyAocG9zc2libHkgZW1wdHkpLlxuICovXG5leHBvcnQgZnVuY3Rpb24gcmVzb2x2ZU93bmVkSGlkZGVuTGF1bmNoQXJncyhpc09ic2lkaWFuQXBwVmlzaWJsZT86IGJvb2xlYW4pOiBzdHJpbmdbXSB7XG4gIHJldHVybiBzaG91bGRIaWRlT2JzaWRpYW5BcHAoaXNPYnNpZGlhbkFwcFZpc2libGUpID8gWy4uLk9XTkVEX0hJRERFTl9MQVVOQ0hfRkxBR1NdIDogW107XG59XG5cbi8qKlxuICogV2hldGhlciB0aGUgYXV0by1zdGFydGVkIEFwcGl1bSBzZXJ2ZXIgY29uc29sZSB3aW5kb3cgc2hvdWxkIGJlIGhpZGRlbi5cbiAqXG4gKiBAcGFyYW0gaXNBcHBpdW1Db25zb2xlVmlzaWJsZSAtIFRoZSByZXNvbHZlZCBvcHRpb24gdmFsdWUgKG9taXR0ZWQgXHUyMTkyIGhpZGRlbikuXG4gKiBAcmV0dXJucyBgdHJ1ZWAgd2hlbiB0aGUgY29uc29sZSB3aW5kb3cgc2hvdWxkIGJlIGhpZGRlbiAodGhlIGRlZmF1bHQpLlxuICovXG5leHBvcnQgZnVuY3Rpb24gc2hvdWxkSGlkZUFwcGl1bUNvbnNvbGUoaXNBcHBpdW1Db25zb2xlVmlzaWJsZT86IGJvb2xlYW4pOiBib29sZWFuIHtcbiAgcmV0dXJuICEoaXNBcHBpdW1Db25zb2xlVmlzaWJsZSA/PyBmYWxzZSk7XG59XG5cbi8qKlxuICogV2hldGhlciB0aGUgYXV0by1zdGFydGVkIEFuZHJvaWQgZW11bGF0b3Igd2luZG93IHNob3VsZCBiZSBoaWRkZW5cbiAqICh2aWEgdGhlIGVtdWxhdG9yJ3MgYC1uby13aW5kb3dgIGZsYWcpLlxuICpcbiAqIEBwYXJhbSBpc0VtdWxhdG9yVmlzaWJsZSAtIFRoZSByZXNvbHZlZCBvcHRpb24gdmFsdWUgKG9taXR0ZWQgXHUyMTkyIGhpZGRlbikuXG4gKiBAcmV0dXJucyBgdHJ1ZWAgd2hlbiB0aGUgZW11bGF0b3Igd2luZG93IHNob3VsZCBiZSBoaWRkZW4gKHRoZSBkZWZhdWx0KS5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHNob3VsZEhpZGVFbXVsYXRvcldpbmRvdyhpc0VtdWxhdG9yVmlzaWJsZT86IGJvb2xlYW4pOiBib29sZWFuIHtcbiAgcmV0dXJuICEoaXNFbXVsYXRvclZpc2libGUgPz8gZmFsc2UpO1xufVxuXG4vKipcbiAqIFdoZXRoZXIgdGhlIG93bmVkIGRlc2t0b3AgT2JzaWRpYW4gd2luZG93IHNob3VsZCBiZSBoaWRkZW4gKG1vdmVkIG9mZi1zY3JlZW4pLlxuICpcbiAqIEBwYXJhbSBpc09ic2lkaWFuQXBwVmlzaWJsZSAtIFRoZSByZXNvbHZlZCBvcHRpb24gdmFsdWUgKG9taXR0ZWQgXHUyMTkyIGhpZGRlbikuXG4gKiBAcmV0dXJucyBgdHJ1ZWAgd2hlbiB0aGUgd2luZG93IHNob3VsZCBiZSBoaWRkZW4gKHRoZSBkZWZhdWx0KS5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIHNob3VsZEhpZGVPYnNpZGlhbkFwcChpc09ic2lkaWFuQXBwVmlzaWJsZT86IGJvb2xlYW4pOiBib29sZWFuIHtcbiAgcmV0dXJuICEoaXNPYnNpZGlhbkFwcFZpc2libGUgPz8gZmFsc2UpO1xufVxuIl0sCiAgIm1hcHBpbmdzIjogIkFBOEJPLE1BQU0sNEJBQTRCO0FBQUEsRUFDdkM7QUFBQSxFQUNBO0FBQUEsRUFDQTtBQUFBLEVBQ0E7QUFDRjtBQVVPLFNBQVMsNkJBQTZCLHNCQUEwQztBQUNyRixTQUFPLHNCQUFzQixvQkFBb0IsSUFBSSxDQUFDLEdBQUcseUJBQXlCLElBQUksQ0FBQztBQUN6RjtBQVFPLFNBQVMsd0JBQXdCLHdCQUEyQztBQUNqRixTQUFPLEVBQUUsMEJBQTBCO0FBQ3JDO0FBU08sU0FBUyx5QkFBeUIsbUJBQXNDO0FBQzdFLFNBQU8sRUFBRSxxQkFBcUI7QUFDaEM7QUFRTyxTQUFTLHNCQUFzQixzQkFBeUM7QUFDN0UsU0FBTyxFQUFFLHdCQUF3QjtBQUNuQzsiLAogICJuYW1lcyI6IFtdCn0K

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obsidian-integration-testing",
-  "version": "5.6.0",
+  "version": "6.2.0",
   "description": "Simplifies integration testing of Obsidian plugins.",
   "keywords": [
     "obsidian",
@@ -172,10 +172,10 @@
     "czg": "^1.13.1",
     "dprint": "^0.55.1",
     "esbuild": "^0.28.1",
-    "eslint": "^10.6.0",
+    "eslint": "^10.7.0",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import-x": "^4.17.1",
-    "eslint-plugin-jsdoc": "^63.0.12",
+    "eslint-plugin-jsdoc": "^63.0.13",
     "eslint-plugin-perfectionist": "^5.10.0",
     "eslint-plugin-tsdoc": "^0.5.2",
     "globals": "^17.7.0",