@glubean/browser 0.8.4 → 0.9.0

package/dist/page.js

@@ -14,6 +14,7 @@
 import { EvidenceSession, } from "./evidence.js";
 import { collectNavigationMetrics } from "./metrics.js";
 import { createWrappedLocator } from "./locator.js";
+import { createFrame } from "./frame.js";
 import { getRuntime } from "@glubean/sdk/internal";
 // ── Module-level helpers (used by the shoot callback in _create) ──────
 /** Sanitize a string into a safe filename segment. */
@@ -60,7 +61,6 @@ export class GlubeanBrowser {
             clearTimeout(this._closeTimer);
             this._closeTimer = null;
         }
-        this._openPages++;
         const browser = await this._getBrowser();
         // Reuse the default about:blank tab instead of opening a new one.
         // When Chrome launches it always creates one blank page — reusing it
@@ -71,16 +71,31 @@ export class GlubeanBrowser {
             return url === "about:blank" || url === "chrome://new-tab-page/";
         });
         const rawPage = blank ?? await browser.newPage();
+        this._track(rawPage);
+        // Read testId lazily from the runtime carrier — the harness updates it
+        // before each test runs, so reading at newPage() time is always fresh.
+        const runtimeTestId = getRuntime()?.test?.id;
+        return GlubeanPage._create(rawPage, this._baseUrl, ctx, this._options, runtimeTestId, this);
+    }
+    /**
+     * @internal Register a raw page in the open-page accounting so the browser
+     * isn't auto-closed while it's alive. Cancels any pending close, increments
+     * the counter, and decrements (rescheduling close at zero) on page close.
+     * Used by both `newPage()` and `GlubeanPage.waitForPopup()` (popups are
+     * real pages that must keep the browser open too).
+     */
+    _track(rawPage) {
+        if (this._closeTimer) {
+            clearTimeout(this._closeTimer);
+            this._closeTimer = null;
+        }
+        this._openPages++;
         rawPage.once("close", () => {
             this._openPages--;
             if (this._openPages <= 0) {
                 this._scheduleClose();
             }
         });
-        // Read testId lazily from the runtime carrier — the harness updates it
-        // before each test runs, so reading at newPage() time is always fresh.
-        const runtimeTestId = getRuntime()?.test?.id;
-        return GlubeanPage._create(rawPage, this._baseUrl, ctx, this._options, runtimeTestId);
     }
     _scheduleClose() {
         this._closeTimer = setTimeout(async () => {
@@ -127,24 +142,77 @@ export class GlubeanPage {
     _ctx;
     _metricsEnabled;
     _actionTimeout;
+    _options;
+    _testId;
+    /** Owning browser — used to register popups in its open-page accounting. */
+    _owner;
     _evidence = null;
-    constructor(page, baseUrl, ctx, metricsEnabled, actionTimeout) {
+    _dialogHandler = null;
+    constructor(page, baseUrl, ctx, metricsEnabled, actionTimeout, options, testId, owner) {
         this.raw = page;
         this._baseUrl = baseUrl;
         this._ctx = ctx;
         this._metricsEnabled = metricsEnabled;
         this._actionTimeout = actionTimeout;
+        this._options = options;
+        this._testId = testId;
+        this._owner = owner;
     }
     /** @internal */
-    static async _create(page, baseUrl, ctx, options, runtimeTestId) {
+    static async _create(page, baseUrl, ctx, options, runtimeTestId, owner) {
         const consoleForward = options.consoleForward ?? true;
         const networkTraceOpt = options.networkTrace ?? true;
         const metricsEnabled = options.metrics ?? true;
         const screenshotMode = options.screenshot ?? "on-failure";
         const screenshotDir = options.screenshotDir ?? ".glubean/screenshots";
         const testId = runtimeTestId ?? ctx.testId ?? "unknown";
+        // ONE download dir for the whole browser — NOT per-test. `Browser.setDownloadBehavior`
+        // is browser-context-global (last call wins the path), so two concurrent instrumented
+        // pages sharing one Chrome (e.g. concurrent tests off one `browser()` fixture) must
+        // agree on the directory or one would silently repoint the other's downloads. The
+        // per-download `browser:download` evidence carries the testId for attribution instead.
+        const downloadDir = options.downloadDir ?? ".glubean/downloads";
         const actionTimeout = options.actionTimeout ?? 30_000;
-        const gp = new GlubeanPage(page, baseUrl, ctx, metricsEnabled, actionTimeout);
+        const dialogMode = options.dialogMode ?? "dismiss";
+        const gp = new GlubeanPage(page, baseUrl, ctx, metricsEnabled, actionTimeout, options, testId, owner);
+        // Native dialogs (alert/confirm/prompt/beforeunload) always emit evidence.
+        // Puppeteer auto-dismisses unhandled dialogs UNLESS a 'dialog' listener is
+        // registered — once we register one, WE are responsible for resolving
+        // every dialog (custom handler via onDialog(), else `dialogMode`).
+        page.on("dialog", (dialog) => {
+            ctx.event({
+                type: "browser:dialog",
+                data: {
+                    dialogType: dialog.type(),
+                    message: dialog.message(),
+                    defaultValue: dialog.defaultValue(),
+                },
+            });
+            const handle = async () => {
+                if (gp._dialogHandler) {
+                    await gp._dialogHandler(dialog);
+                    return;
+                }
+                if (dialogMode === "accept")
+                    await dialog.accept();
+                else
+                    await dialog.dismiss();
+            };
+            handle().catch((err) => {
+                ctx.warn(false, `[browser:dialog] failed to resolve dialog: ${String(err)}`);
+            });
+        });
+        // Popups (window.open / target=_blank) always emit evidence. Use
+        // page.waitForPopup() to also get a fully-instrumented handle to the
+        // popup itself (own evidence session: network/console/screenshots).
+        page.on("popup", (popup) => {
+            if (!popup)
+                return;
+            ctx.event({
+                type: "browser:popup",
+                data: { url: popup.url() },
+            });
+        });
         if (consoleForward) {
             page.on("console", (msg) => {
                 const type = msg.type();
@@ -213,6 +281,9 @@ export class GlubeanPage {
                 return { path: filePath };
             },
         };
+        // Downloads are always captured as evidence (like dialog/popup) — the
+        // save directory must exist before Chrome is told to use it.
+        await _ensureDir(downloadDir);
         gp._evidence = await EvidenceSession.attach(page, {
             trace: networkTraceOpt !== false ? (t) => ctx.trace(t) : undefined,
             network: filterOpts && {
@@ -222,7 +293,27 @@ export class GlubeanPage {
             },
             mocks: options.mock,
             emulate: options.emulate,
+            storageState: options.storageState,
             screenshots: screenshotsOpt,
+            downloads: {
+                dir: downloadDir,
+                onDownload: (entry, state) => {
+                    // Only terminal states are evidence — "inProgress" fires repeatedly
+                    // per download and would flood the timeline with no new information.
+                    if (state === "inProgress")
+                        return;
+                    ctx.event({
+                        type: "browser:download",
+                        data: {
+                            guid: entry.guid,
+                            url: entry.url,
+                            filename: entry.suggestedFilename,
+                            path: entry.path,
+                            state,
+                        },
+                    });
+                },
+            },
         });
         // Proxy: GlubeanPage methods take priority; everything else falls through
         // to the raw Puppeteer Page so users can call page.waitForNavigation(),
@@ -276,6 +367,239 @@ export class GlubeanPage {
     async captureScreenshot(label = "manual") {
         await this._evidence?.captureShot(label, "manual");
     }
+    // ── Storage state (cookies + localStorage) ──────────────────────────
+    /**
+     * Capture the current page's cookies + localStorage — a thin "login once,
+     * reuse the session" primitive. Pass the result to `browser({ storageState })`
+     * on a fresh page to skip a UI login flow.
+     *
+     * @example
+     * ```ts
+     * await page.fill('[data-testid="username"]', "ada");
+     * await page.click('[data-testid="login-btn"]');
+     * const state = await page.getStorageState();
+     * ```
+     */
+    async getStorageState() {
+        if (!this._evidence)
+            return {};
+        return await this._evidence.captureStorageState(this.raw);
+    }
+    // ── Dialog & popup ───────────────────────────────────────────────────
+    /**
+     * Register a handler for the next native dialogs (`alert`/`confirm`/`prompt`/
+     * `beforeunload`) on this page, overriding the plugin's `dialogMode` default.
+     * The handler MUST resolve the dialog itself (`dialog.accept()` /
+     * `dialog.dismiss()`) — Glubean will not also auto-resolve it.
+     *
+     * A `browser:dialog` evidence event is emitted for every dialog regardless
+     * of whether a handler is registered.
+     *
+     * @example
+     * ```ts
+     * page.onDialog((dialog) => dialog.accept());
+     * await page.click('[data-testid="clear-cart-btn"]'); // triggers confirm()
+     * ```
+     */
+    onDialog(handler) {
+        this._dialogHandler = handler;
+    }
+    /**
+     * Run `action`, wait for it to open a popup (`window.open()` / `target="_blank"`),
+     * and return the popup as a fully-instrumented page (its own evidence session —
+     * network trace, console forwarding, screenshots — just like the parent).
+     *
+     * A `browser:popup` evidence event is emitted for every popup regardless of
+     * whether `waitForPopup()` is used to capture it.
+     *
+     * @example
+     * ```ts
+     * const popup = await page.waitForPopup(() => page.click('[data-testid="policy-link"]'));
+     * await popup.expectText("body", "Return Policy");
+     * await popup.close();
+     * ```
+     */
+    async waitForPopup(action, options) {
+        const timeout = options?.timeout ?? this._actionTimeout;
+        const start = Date.now();
+        // Named listener + timer so BOTH are always cleaned up — a failed wait
+        // must not leave a stale `popup` listener behind (it would swallow a later
+        // popup and accumulate across repeated failed waits).
+        let timer;
+        let onPopup;
+        const popupPromise = new Promise((resolve, reject) => {
+            timer = setTimeout(() => {
+                reject(new Error(`waitForPopup: no popup opened after ${timeout}ms`));
+            }, timeout);
+            onPopup = (popup) => {
+                if (popup) {
+                    // Register the popup in the owning browser's open-page accounting
+                    // SYNCHRONOUSLY on the open event — before awaiting `action()` to
+                    // settle. Otherwise a popup that opens and closes within `action()`
+                    // would fire its `close` before `_track()` wired the decrementing
+                    // listener, permanently pinning `_openPages` above zero and
+                    // suppressing browser auto-close.
+                    this._owner?._track(popup);
+                    resolve(popup);
+                }
+                else {
+                    reject(new Error("waitForPopup: popup event fired with no page"));
+                }
+            };
+            this.raw.once("popup", onPopup);
+        });
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            if (onPopup)
+                this.raw.off("popup", onPopup);
+        };
+        try {
+            const [rawPopup] = await Promise.all([popupPromise, action()]);
+            cleanup();
+            this._ctx.action({
+                category: "browser:waitForPopup",
+                target: rawPopup.url(),
+                duration: Date.now() - start,
+                status: "ok",
+            });
+            return await GlubeanPage._create(rawPopup, this._baseUrl, this._ctx, this._options, this._testId, this._owner);
+        }
+        catch (err) {
+            cleanup();
+            this._ctx.action({
+                category: "browser:waitForPopup",
+                target: "(popup)",
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    // ── Downloads ────────────────────────────────────────────────────────
+    /**
+     * Run `action`, wait for it to produce a completed download, and return
+     * the download's metadata. A `browser:download` evidence event is emitted
+     * for every download (`completed` or `canceled`) regardless of whether
+     * `waitForDownload()` is used to capture it — like `waitForPopup()`.
+     *
+     * @example
+     * ```ts
+     * const dl = await page.waitForDownload(() => page.click('[data-testid="download-receipt"]'));
+     * ctx.assert(dl.suggestedFilename.endsWith(".txt"), "expected a .txt receipt");
+     * ```
+     */
+    async waitForDownload(action, options) {
+        const timeout = options?.timeout ?? this._actionTimeout;
+        const start = Date.now();
+        if (!this._evidence) {
+            throw new Error("waitForDownload: evidence session not attached");
+        }
+        // Register the wait BEFORE the action so a fast download can't slip past,
+        // and scope it to THIS action: if `action()` throws, abort the wait so it
+        // neither leaks a waiter nor gets satisfied by a later, unrelated download.
+        const ac = new AbortController();
+        const waitPromise = this._evidence.waitForDownload(timeout, ac.signal);
+        try {
+            await action();
+        }
+        catch (err) {
+            ac.abort();
+            await waitPromise.catch(() => { }); // settle the aborted wait; swallow its rejection
+            this._ctx.action({
+                category: "browser:waitForDownload",
+                target: "(download)",
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+        try {
+            const entry = await waitPromise;
+            this._ctx.action({
+                category: "browser:waitForDownload",
+                target: entry.suggestedFilename,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { url: entry.url, path: entry.path },
+            });
+            return entry;
+        }
+        catch (err) {
+            this._ctx.action({
+                category: "browser:waitForDownload",
+                target: "(download)",
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    // ── iframe ───────────────────────────────────────────────────────────
+    /**
+     * Locate an `<iframe>` matching `selector` and return its content frame,
+     * wrapped with the same locator API as `GlubeanPage` (`byTestId`/`byText`/
+     * `byRole`/`byLabel`, `click`/`fill`/`type`/`hover`, `expectVisible`/
+     * `expectText`/`expectHidden`).
+     *
+     * CDP already handles the execution-context switch into the frame (that's
+     * Puppeteer's own `Frame` machinery) — this method is purely the
+     * encapsulation-layer half: locator ergonomics scoped to the frame instead
+     * of the top-level page.
+     *
+     * @example
+     * ```ts
+     * const policy = await page.frame('[data-testid="policy-frame"]');
+     * await policy.expectText("body", "Return Policy");
+     * ```
+     */
+    async frame(selector, options) {
+        const timeout = options?.timeout ?? this._actionTimeout;
+        const start = Date.now();
+        try {
+            const handle = await this.raw.waitForSelector(selector, { timeout });
+            if (!handle) {
+                throw new Error(`frame("${selector}"): element not found`);
+            }
+            // try/finally so the handle is disposed even if contentFrame() throws.
+            let contentFrame;
+            try {
+                contentFrame = await handle.contentFrame();
+            }
+            finally {
+                await handle.dispose();
+            }
+            if (!contentFrame) {
+                throw new Error(`frame("${selector}"): element matched but is not an <iframe> (no content frame)`);
+            }
+            this._ctx.action({
+                category: "browser:frame",
+                target: selector,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { url: contentFrame.url() },
+            });
+            return createFrame(contentFrame, {
+                action: (e) => this._ctx.action(e),
+                captureStep: (label) => this._evidence?.captureShot(label, "step") ?? Promise.resolve(),
+                captureFailure: (label) => this._evidence?.captureShot(label, "failure") ?? Promise.resolve(),
+            }, this._actionTimeout);
+        }
+        catch (err) {
+            this._ctx.action({
+                category: "browser:frame",
+                target: selector,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            await this._evidence?.captureShot(`frame-${selector}`, "failure");
+            throw err;
+        }
+    }
     // ── Navigation & interaction ────────────────────────────────────────
     /**
      * Navigate to a URL. Relative paths are resolved against the configured `baseUrl`.
@@ -340,7 +664,7 @@ export class GlubeanPage {
             action: (e) => this._ctx.action(e),
             captureStep: (label) => this._evidence?.captureShot(label, "step") ?? Promise.resolve(),
             captureFailure: (label) => this._evidence?.captureShot(label, "failure") ?? Promise.resolve(),
-        }, selector);
+        }, selector, this.raw);
     }
     /**
      * Locate an element by its `data-testid` attribute.
@@ -1124,6 +1448,82 @@ export class GlubeanPage {
             throw err;
         }
     }
+    /**
+     * Assert that a checkbox/radio's `.checked` state matches `expected`.
+     * Retries until match or timeout.
+     *
+     * @param expected — desired `.checked` value. @default true
+     */
+    async expectChecked(selector, expected = true, options) {
+        const start = Date.now();
+        let lastVal = null;
+        try {
+            lastVal = await this._retryUntil(() => this.raw.$eval(selector, 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (el) => Boolean(el.checked)).catch(() => null), (val) => val === expected, (lv) => `expectChecked("${selector}"): expected checked=${expected} ` +
+                `but received checked=${JSON.stringify(lv)} after ${options?.timeout ?? 5_000}ms`, options);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectChecked("${selector}")`,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { expected, actual: lastVal },
+            });
+        }
+        catch (err) {
+            await this._evidence?.captureShot(`expectChecked-${selector}`, "failure");
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectChecked("${selector}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { expected, actual: lastVal, error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Assert that an input/textarea/select's `.value` matches `expected`.
+     * Retries until match or timeout. For text content of non-form elements,
+     * use `expectText()` instead.
+     */
+    async expectValue(selector, expected, options) {
+        const matches = (val) => {
+            if (val === null)
+                return false;
+            return expected instanceof RegExp ? expected.test(val) : val === expected;
+        };
+        const start = Date.now();
+        let lastVal = null;
+        try {
+            lastVal = await this._retryUntil(() => this.raw.$eval(selector, 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (el) => (el.value ?? "")).catch(() => null), matches, (lv) => `expectValue("${selector}"): expected ${JSON.stringify(expected)} ` +
+                `but received ${JSON.stringify(lv)} after ${options?.timeout ?? 5_000}ms`, options);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectValue("${selector}")`,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { expected: String(expected), actual: lastVal },
+            });
+        }
+        catch (err) {
+            await this._evidence?.captureShot(`expectValue-${selector}`, "failure");
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectValue("${selector}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: {
+                    expected: String(expected),
+                    actual: lastVal,
+                    error: String(err),
+                },
+            });
+            throw err;
+        }
+    }
     // ── Phase 8: Network Interception & Assertions ────────────────────
     /**
      * Wait for a network request matching `pattern`.