obsidian-integration-testing 11.0.0 → 12.1.0

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

@@ -63,6 +63,14 @@ export interface AppiumTransportConfig {
      * Defaults to `'md.obsidian'`.
      */
     appId?: string;
+    /**
+     * Timeout in milliseconds for Obsidian Mobile to get as far as `globalThis.app`
+     * existing after the vault is (re)opened, before the tighter
+     * {@link layoutReadyTimeoutInMilliseconds} clock starts.
+     *
+     * @default `180000`
+     */
+    appStartTimeoutInMilliseconds?: number;
     /**
      * The Appium browser/driver instance.
      * Created by the consumer via e.g. WebDriverIO's `remote()`.
@@ -84,8 +92,9 @@ export interface AppiumTransportConfig {
      */
     isSessionOwner?: boolean;
     /**
-     * Timeout in milliseconds for waiting for `app.workspace.layoutReady` after
-     * the vault is (re)opened.
+     * Timeout in milliseconds for waiting for `app.workspace.layoutReady`, counted
+     * from the moment {@link appStartTimeoutInMilliseconds} is satisfied — not from
+     * the reload, so a cold app start is not charged against it.
      *
      * @default `90000`
      */
@@ -141,8 +150,23 @@ export declare class AppiumTransport implements ObsidianTransport {
      */
     readonly isMobile = true;
     private readonly appId;
+    private readonly appStartTimeoutInMilliseconds;
     private readonly browser;
     private readonly deviceId;
+    /**
+     * The `process.on('exit')` handler that tears the channel down when nothing else will.
+     */
+    private disposeInputChannelOnExit;
+    /**
+     * The host half of the trusted-input channel: a CDP connection to the WebView, independent of the
+     * Appium session, opened lazily on first evaluate and reused (see **L39**).
+     */
+    private inputChannel;
+    /**
+     * Set once the trusted-input channel is known not to be openable here (iOS, a remote hub, no local
+     * `adb`), so the attempt is not repeated on every evaluate.
+     */
+    private isInputChannelUnavailable;
     /**
      * Tracks whether the driver is currently switched to the WebView context.
      *
@@ -201,6 +225,14 @@ export declare class AppiumTransport implements ObsidianTransport {
      * deletion so the session remains available for the owning process.
      */
     dispose(): Promise<void>;
+    /**
+     * Synchronous teardown for `process.on('exit')` handlers.
+     *
+     * Only the trusted-input channel needs it: the Appium session is the owning process's to end, and an
+     * abrupt exit is exactly when the async {@link AppiumTransport.dispose} never runs — which would strand
+     * the adb port forward on the device.
+     */
+    disposeSync(): void;
     /**
      * Evaluates a JavaScript expression inside Obsidian Mobile's WebView.
      *
@@ -258,7 +290,8 @@ export declare class AppiumTransport implements ObsidianTransport {
      * 3. Add the vault to localStorage (`mobile-external-vaults`, `mobile-selected-vault`,
      *    `enable-plugin-<path>`)
      * 4. Trigger `location.reload()` so Obsidian re-reads localStorage and opens the vault
-     * 5. Wait for `app.workspace.layoutReady`
+     * 5. Wait for `globalThis.app` to exist (the app's cold start), then — on a
+     *    separate, tighter budget — for `app.workspace.layoutReady`
      *
      * Existing vault registrations in localStorage are preserved (append, not
      * overwrite) — except the **harness's own** `temp-vault-*` registrations from
@@ -287,6 +320,19 @@ export declare class AppiumTransport implements ObsidianTransport {
      * @param vaultPath - The absolute path to the vault on the host machine.
      */
     unregisterVault(vaultPath: string): Promise<void>;
+    /**
+     * Closes the trusted-input channel, if one is open.
+     */
+    private disposeInputChannel;
+    /**
+     * Opens the trusted-input channel if it is not already open, and re-opens it if the WebView went away.
+     *
+     * Installs a `Runtime.addBinding` function on the page and services every call to it for the life of the
+     * connection. The binding is exposed on *every* execution context of the page, so it survives the
+     * `location.reload()` that {@link AppiumTransport.registerVault} performs; only a full app restart, which
+     * destroys the WebView target, needs the reconnect below.
+     */
+    private ensureInputChannel;
     /**
      * Switches the driver to the `WEBVIEW_md.obsidian` context.
      *
@@ -306,6 +352,27 @@ export declare class AppiumTransport implements ObsidianTransport {
      * @returns The device-side vault path.
      */
     private getDeviceVaultPath;
+    /**
+     * Services one input request from the renderer: inject, then resolve the renderer's promise.
+     *
+     * Every failure path still resolves that promise — with an error message the renderer re-throws — because
+     * a request that is silently dropped would hang the closure until the whole run times out, and report
+     * nothing about why.
+     *
+     * @param connection - The channel the request arrived on.
+     * @param payload - The raw JSON payload the binding was called with.
+     */
+    private handleInputRequest;
+    /**
+     * Probes the WebView once for how far Obsidian's startup has got.
+     *
+     * A probe that throws is reported as `undefined` rather than propagated: the
+     * page is mid-`location.reload()` for most of the app-start phase, and a
+     * WebView that cannot answer yet is the *expected* reading there, not an error.
+     *
+     * @returns What the probe saw, or `undefined` when it could not run.
+     */
+    private probeStartup;
     /**
      * Pushes the minimal `.obsidian/app.json` vault marker via `adb push`.
      *
@@ -334,8 +401,42 @@ export declare class AppiumTransport implements ObsidianTransport {
      * @param deviceVaultPath - The device-side vault directory path.
      */
     private removeDeviceVaultDirectory;
+    /**
+     * Drops the `process.on('exit')` handler that would otherwise close an already-closed channel, and would
+     * stack a listener per reconnect.
+     */
+    private unregisterInputChannelExitHandler;
+    /**
+     * Polls until `globalThis.app` exists in the WebView — the app has finished
+     * its cold start and Obsidian's own boot has begun.
+     *
+     * This is the **first** of the two budgets spent after `location.reload()`,
+     * and the generous one. Everything it pays for is outside Obsidian's control:
+     * the WebView reloading, and a guest that may still be optimizing packages.
+     * Keeping it separate is the point of the split — the old single wall clock
+     * started here and left the tight layout budget paying for a cold start.
+     */
+    private waitForAppStarted;
     /**
      * Polls until `app.workspace.layoutReady` is `true` in the WebView.
+     *
+     * The **second** budget, and the tight one: by the time it starts, the app is
+     * already up, so all it covers is Obsidian opening the vault and loading
+     * plugins — ~1s in practice, ≤8.4s under heavy host stress (**L19**).
      */
     private waitForLayoutReady;
+    /**
+     * Polls the WebView until a startup phase's milestone is satisfied, tracking
+     * the evidence that tells a slow Obsidian from a contended guest.
+     *
+     * Each poll costs exactly one `browser.execute` round-trip — deliberately not
+     * an {@link ensureWebViewContext} call, whose `getContexts()` runs
+     * `adb shell cat /proc/net/unix` and was measured at ~17s per **L19**. The
+     * round-trip is timed, and the slowest one is reported on timeout: a phase
+     * that ran out after a handful of probes each taking tens of seconds was
+     * starved by the guest, not by Obsidian.
+     *
+     * @param params - The phase, its budget, and the predicate that ends it.
+     */
+    private waitForStartupMilestone;
 }