@glubean/browser 0.1.2

package/dist/page.js

@@ -0,0 +1,1259 @@
+/**
+ * GlubeanBrowser and GlubeanPage — browser automation wrappers that integrate
+ * with the Glubean test context.
+ *
+ * `GlubeanBrowser` manages the Chrome connection (returned by the plugin factory).
+ * `GlubeanPage` wraps a single Puppeteer Page with auto-instrumentation:
+ * - `ctx.trace()` for every `goto()` navigation
+ * - `ctx.metric()` for page load and DOMContentLoaded timing
+ * - `ctx.log()` / `ctx.warn()` for browser console output and uncaught errors
+ * - `ctx.trace()` for in-page network requests (XHR, fetch) via CDP
+ *
+ * @module page
+ */
+import { attachNetworkTracer } from "./network.js";
+import { collectNavigationMetrics } from "./metrics.js";
+import { createWrappedLocator } from "./locator.js";
+/**
+ * Connected browser instance returned by the plugin.
+ *
+ * Call `newPage(ctx)` to create an instrumented page wired to the test context.
+ *
+ * @example
+ * ```ts
+ * const pg = await chrome.newPage(ctx);
+ * await pg.goto("/dashboard");
+ * await pg.close();
+ * ```
+ */
+export class GlubeanBrowser {
+    _getBrowser;
+    _baseUrl;
+    _options;
+    _openPages = 0;
+    _closeTimer = null;
+    /** @internal — created by the plugin factory. */
+    constructor(getBrowser, baseUrl, options) {
+        this._getBrowser = getBrowser;
+        this._baseUrl = baseUrl;
+        this._options = options;
+    }
+    /**
+     * Create a new instrumented page wired to the given test context.
+     *
+     * Each call creates a fresh browser page. Remember to call `page.close()`
+     * in your teardown (or use `test.extend()` with a lifecycle factory).
+     */
+    async newPage(ctx) {
+        if (this._closeTimer) {
+            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
+        // avoids the extra empty tab that lingers in headless: false mode.
+        const pages = await browser.pages();
+        const blank = pages.find((p) => {
+            const url = p.url();
+            return url === "about:blank" || url === "chrome://new-tab-page/";
+        });
+        const rawPage = blank ?? await browser.newPage();
+        rawPage.once("close", () => {
+            this._openPages--;
+            if (this._openPages <= 0) {
+                this._scheduleClose();
+            }
+        });
+        // Read testId lazily from the runtime global — the harness updates it
+        // before each test runs, so reading at newPage() time is always fresh.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const runtimeTestId = globalThis.__glubeanRuntime?.test?.id;
+        return GlubeanPage._create(rawPage, this._baseUrl, ctx, this._options, runtimeTestId);
+    }
+    _scheduleClose() {
+        this._closeTimer = setTimeout(async () => {
+            if (this._openPages <= 0) {
+                try {
+                    await this.close();
+                }
+                catch { /* already closed */ }
+            }
+        }, 3000);
+        // Don't let the timer keep the process alive
+        if (this._closeTimer && typeof this._closeTimer === "object" && "unref" in this._closeTimer) {
+            this._closeTimer.unref();
+        }
+    }
+    /** Disconnect from the browser without closing it. Useful for remote Chrome. */
+    async disconnect() {
+        const browser = await this._getBrowser();
+        browser.disconnect();
+    }
+    /** Close the browser and terminate the Chrome process. */
+    async close() {
+        const browser = await this._getBrowser();
+        await browser.close();
+    }
+}
+/**
+ * Instrumented browser page with auto-tracing, metrics, and console forwarding.
+ *
+ * Wraps a subset of Puppeteer's Page API. For advanced operations, use `.raw`.
+ *
+ * @example
+ * ```ts
+ * await page.goto("/login");
+ * await page.type("#email", "user@test.com");
+ * await page.click('button[type="submit"]');
+ * const title = await page.title();
+ * ```
+ */
+export class GlubeanPage {
+    /** The underlying Puppeteer Page for advanced use cases. */
+    raw;
+    _baseUrl;
+    _ctx;
+    _metricsEnabled;
+    _screenshotMode;
+    _screenshotDir;
+    _testId;
+    _actionTimeout;
+    _stepCounter = 0;
+    _networkCleanup = null;
+    constructor(page, baseUrl, ctx, metricsEnabled, screenshotMode, screenshotDir, testId, actionTimeout) {
+        this.raw = page;
+        this._baseUrl = baseUrl;
+        this._ctx = ctx;
+        this._metricsEnabled = metricsEnabled;
+        this._screenshotMode = screenshotMode;
+        this._screenshotDir = screenshotDir;
+        this._testId = testId;
+        this._actionTimeout = actionTimeout;
+    }
+    /** @internal */
+    static async _create(page, baseUrl, ctx, options, runtimeTestId) {
+        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";
+        const actionTimeout = options.actionTimeout ?? 30_000;
+        const gp = new GlubeanPage(page, baseUrl, ctx, metricsEnabled, screenshotMode, screenshotDir, testId, actionTimeout);
+        if (consoleForward) {
+            page.on("console", (msg) => {
+                const type = msg.type();
+                const text = msg.text();
+                if (type === "error") {
+                    ctx.event({
+                        type: "browser:console-error",
+                        data: { message: text, source: msg.location()?.url },
+                    });
+                    ctx.warn(false, `[browser:console] ${text}`);
+                }
+                else {
+                    ctx.log(`[browser:${type}] ${text}`);
+                }
+            });
+            page.on("pageerror", (err) => {
+                const msg = err instanceof Error ? err.message : String(err);
+                const stack = err instanceof Error ? err.stack : undefined;
+                ctx.event({
+                    type: "browser:uncaught-error",
+                    data: { message: msg, stack },
+                });
+                ctx.warn(false, `[browser:uncaught] ${msg}`);
+            });
+        }
+        if (networkTraceOpt !== false) {
+            const filterOpts = typeof networkTraceOpt === "object" ? networkTraceOpt : undefined;
+            gp._networkCleanup = await attachNetworkTracer(page, {
+                trace: (t) => ctx.trace(t),
+                include: filterOpts?.include,
+                excludePaths: filterOpts?.excludePaths,
+                filter: filterOpts?.filter,
+            });
+        }
+        // Proxy: GlubeanPage methods take priority; everything else falls through
+        // to the raw Puppeteer Page so users can call page.waitForNavigation(),
+        // page.setViewport(), page.keyboard.press(), etc. directly.
+        return new Proxy(gp, {
+            get(target, prop, receiver) {
+                if (prop in target) {
+                    const value = Reflect.get(target, prop, receiver);
+                    if (typeof value === "function")
+                        return value.bind(target);
+                    return value;
+                }
+                const rawValue = Reflect.get(target.raw, prop);
+                if (typeof rawValue === "function")
+                    return rawValue.bind(target.raw);
+                return rawValue;
+            },
+            has(target, prop) {
+                return prop in target || prop in target.raw;
+            },
+        });
+    }
+    // ── Screenshot helpers ──────────────────────────────────────────────
+    _formatTimestamp() {
+        return new Date().toISOString().replace(/[:.]/g, "").slice(0, 15);
+    }
+    _sanitizeLabel(label) {
+        return label.replace(/[^a-z0-9_-]/gi, "_").slice(0, 60);
+    }
+    async _ensureDir(dir) {
+        const { mkdir } = await import("node:fs/promises");
+        await mkdir(dir, { recursive: true });
+    }
+    async _saveScreenshot(filename, label) {
+        if (this._ctx.saveArtifact) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const buffer = (await this.raw.screenshot({
+                fullPage: true,
+                encoding: "binary",
+            }));
+            const id = await this._ctx.saveArtifact(filename, buffer, {
+                type: "screenshot",
+                mimeType: "image/png",
+            });
+            this._ctx.event({
+                type: "browser:screenshot",
+                data: { artifactId: id, label, fullPage: true },
+            });
+            return id;
+        }
+        // Legacy fallback: direct file write when saveArtifact is not available
+        const dir = `${this._screenshotDir}/${this._sanitizeLabel(this._testId)}`;
+        await this._ensureDir(dir);
+        const path = `${dir}/${filename}`;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        await this.raw.screenshot({ path, fullPage: true });
+        this._ctx.event({
+            type: "browser:screenshot",
+            data: { path, label, fullPage: true },
+        });
+        return path;
+    }
+    async _captureStep(action) {
+        if (this._screenshotMode !== "every-step")
+            return;
+        this._stepCounter++;
+        const num = String(this._stepCounter).padStart(3, "0");
+        const ts = this._formatTimestamp();
+        await this._saveScreenshot(`${num}-${this._sanitizeLabel(action)}-${ts}.png`, action);
+    }
+    async _captureFailure(action) {
+        if (this._screenshotMode === "off")
+            return;
+        this._stepCounter++;
+        const num = String(this._stepCounter).padStart(3, "0");
+        const ts = this._formatTimestamp();
+        try {
+            await this._saveScreenshot(`FAIL-${num}-${this._sanitizeLabel(action)}-${ts}.png`, `FAIL:${action}`);
+        }
+        catch {
+            // best-effort — page may be in a broken state
+        }
+    }
+    /**
+     * Capture a screenshot for a test-level failure (e.g. assertion error).
+     *
+     * Call this in the fixture's catch block to get a final-state screenshot
+     * when the test body throws.
+     */
+    async screenshotOnFailure() {
+        if (this._screenshotMode === "off")
+            return;
+        const ts = this._formatTimestamp();
+        try {
+            await this._saveScreenshot(`FAIL-final-${ts}.png`, "FAIL:final");
+        }
+        catch {
+            // best-effort
+        }
+    }
+    // ── Navigation & interaction ────────────────────────────────────────
+    /**
+     * Navigate to a URL. Relative paths are resolved against the configured `baseUrl`.
+     *
+     * Emits a `browser:goto` action and (if enabled) Navigation Timing metrics.
+     * Captures a screenshot on failure or after every step (depending on config).
+     */
+    async goto(url, options) {
+        const resolvedUrl = this._resolveUrl(url);
+        const start = Date.now();
+        let response;
+        try {
+            response = await this.raw.goto(resolvedUrl, {
+                waitUntil: options?.waitUntil ?? "load",
+            });
+        }
+        catch (err) {
+            const duration = Date.now() - start;
+            this._ctx.action({
+                category: "browser:goto",
+                target: url,
+                duration,
+                status: "error",
+                detail: { url: resolvedUrl, error: String(err) },
+            });
+            await this._captureFailure(`goto-${url}`);
+            throw err;
+        }
+        const duration = Date.now() - start;
+        const httpStatus = response?.status() ?? 0;
+        this._ctx.action({
+            category: "browser:goto",
+            target: url,
+            duration,
+            status: httpStatus >= 400 ? "error" : "ok",
+            detail: { url: resolvedUrl, httpStatus },
+        });
+        if (this._metricsEnabled) {
+            await collectNavigationMetrics(this.raw, (name, value, opts) => this._ctx.metric(name, value, opts), resolvedUrl);
+        }
+        await this._captureStep(`goto-${url}`);
+    }
+    /**
+     * Create a WrappedLocator for the given selector.
+     *
+     * The returned locator supports Puppeteer's chain methods (setTimeout,
+     * setVisibility, etc.) and auto-injects trace events and screenshots
+     * for action methods (click, fill, hover, scroll, type).
+     *
+     * @example
+     * ```ts
+     * // Chain Locator options before acting
+     * await page.locator("#submit").setTimeout(5000).click();
+     *
+     * // type() extension — Locator has no native type()
+     * await page.locator("#email").type("user@test.com");
+     * ```
+     */
+    locator(selector) {
+        const inner = this.raw.locator(selector);
+        return createWrappedLocator(inner, {
+            action: (e) => this._ctx.action(e),
+            captureStep: (label) => this._captureStep(label),
+            captureFailure: (label) => this._captureFailure(label),
+        }, selector);
+    }
+    /**
+     * Click an element matching the selector.
+     *
+     * Delegates to Puppeteer's Locator API for auto-waiting (attached, visible,
+     * enabled, stable bounding box). Emits a `browser:click` action for tracing.
+     */
+    async click(selector, options) {
+        await this.locator(selector)
+            .setTimeout(options?.timeout ?? this._actionTimeout)
+            .click();
+    }
+    /**
+     * Click an element and wait for a full-page navigation to complete.
+     *
+     * Convenience wrapper for `Promise.all([waitForNavigation, click])`.
+     * Emits a `browser:click-and-navigate` action with trace + metrics + screenshot.
+     *
+     * @example
+     * ```ts
+     * await page.clickAndNavigate("a.external-link");
+     * await page.clickAndNavigate("a.external-link", { waitUntil: "networkidle0" });
+     * ```
+     */
+    async clickAndNavigate(selector, options) {
+        const start = Date.now();
+        const timeout = options?.timeout ?? this._actionTimeout;
+        try {
+            await Promise.all([
+                this.raw.waitForNavigation({
+                    waitUntil: options?.waitUntil ?? "load",
+                    timeout,
+                }),
+                this.locator(selector).setTimeout(timeout).click(),
+            ]);
+            const duration = Date.now() - start;
+            this._ctx.action({
+                category: "browser:click-and-navigate",
+                target: selector,
+                duration,
+                status: "ok",
+                detail: { url: this.raw.url() },
+            });
+            if (this._metricsEnabled) {
+                await collectNavigationMetrics(this.raw, (name, value, opts) => this._ctx.metric(name, value, opts), this.raw.url());
+            }
+        }
+        catch (err) {
+            const duration = Date.now() - start;
+            this._ctx.action({
+                category: "browser:click-and-navigate",
+                target: selector,
+                duration,
+                status: "error",
+                detail: { error: String(err) },
+            });
+            await this._captureFailure(`clickAndNavigate-${selector}`);
+            throw err;
+        }
+        await this._captureStep(`clickAndNavigate-${selector}`);
+    }
+    /**
+     * Type text into an element matching the selector (appends — does not clear).
+     *
+     * Waits for the element to be actionable via Locator, then types using
+     * the ElementHandle. Use `fill()` to clear existing text before typing.
+     */
+    async type(selector, text, options) {
+        await this.locator(selector)
+            .setTimeout(options?.timeout ?? this._actionTimeout)
+            .type(text);
+    }
+    /**
+     * Clear an input and type a new value.
+     *
+     * Unlike `type()` which appends, `fill()` clears existing text first.
+     * Delegates to Puppeteer's Locator `fill()` for auto-waiting.
+     */
+    async fill(selector, value, options) {
+        await this.locator(selector)
+            .setTimeout(options?.timeout ?? this._actionTimeout)
+            .fill(value);
+    }
+    /**
+     * Hover over an element matching the selector.
+     *
+     * Delegates to Puppeteer's Locator `hover()` for auto-waiting.
+     */
+    async hover(selector, options) {
+        await this.locator(selector)
+            .setTimeout(options?.timeout ?? this._actionTimeout)
+            .hover();
+    }
+    /**
+     * Select option(s) from a `<select>` element by value.
+     *
+     * Waits for the element to be actionable via Locator, then selects values.
+     * Returns the array of selected values.
+     */
+    async select(selector, ...values) {
+        const start = Date.now();
+        try {
+            await this.locator(selector)
+                .setTimeout(this._actionTimeout)
+                .waitHandle();
+            const selected = await this.raw.select(selector, ...values);
+            const duration = Date.now() - start;
+            this._ctx.action({
+                category: "browser:select",
+                target: selector,
+                duration,
+                status: "ok",
+                detail: { values, selected },
+            });
+            return selected;
+        }
+        catch (err) {
+            const duration = Date.now() - start;
+            this._ctx.action({
+                category: "browser:select",
+                target: selector,
+                duration,
+                status: "timeout",
+                detail: { values, error: String(err) },
+            });
+            await this._captureFailure(`select-${selector}`);
+            throw err;
+        }
+    }
+    /**
+     * Press a keyboard key (e.g. `"Enter"`, `"Tab"`, `"Escape"`).
+     *
+     * Operates at the keyboard level — no selector or auto-wait needed.
+     */
+    async press(key, options) {
+        const start = Date.now();
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            await this.raw.keyboard.press(key, options);
+            const duration = Date.now() - start;
+            this._ctx.action({
+                category: "browser:press",
+                target: key,
+                duration,
+                status: "ok",
+            });
+        }
+        catch (err) {
+            const duration = Date.now() - start;
+            this._ctx.action({
+                category: "browser:press",
+                target: key,
+                duration,
+                status: "error",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Upload files to a `<input type="file">` element.
+     *
+     * Waits for the element to be actionable via Locator, then attaches files
+     * via `ElementHandle.uploadFile()` and dispatches a `change` event so
+     * frameworks like React/Vue pick up the file selection.
+     */
+    async upload(selector, ...filePaths) {
+        const start = Date.now();
+        try {
+            const handle = await this.locator(selector)
+                .setTimeout(this._actionTimeout)
+                .waitHandle();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            await handle.uploadFile(...filePaths);
+            // Puppeteer's uploadFile sets files via CDP but does NOT fire the
+            // native change event. React/Vue rely on it to update state.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            await handle.evaluate((el) => el.dispatchEvent(new Event("change", { bubbles: true })));
+            await handle.dispose();
+            const duration = Date.now() - start;
+            this._ctx.action({
+                category: "browser:upload",
+                target: selector,
+                duration,
+                status: "ok",
+                detail: { fileCount: filePaths.length },
+            });
+        }
+        catch (err) {
+            const duration = Date.now() - start;
+            this._ctx.action({
+                category: "browser:upload",
+                target: selector,
+                duration,
+                status: "timeout",
+                detail: { fileCount: filePaths.length, error: String(err) },
+            });
+            await this._captureFailure(`upload-${selector}`);
+            throw err;
+        }
+        await this._captureStep(`upload-${selector}`);
+    }
+    /**
+     * Click a button/element that triggers a file chooser dialog, then accept
+     * the given files. Use this when the file input is hidden and opened via
+     * a custom button — the common pattern in modern SPAs.
+     *
+     * For a visible `<input type="file">`, prefer `upload()` instead.
+     *
+     * @example
+     * ```ts
+     * await page.chooseFile("#import-csv-btn", "./fixtures/users.csv");
+     * ```
+     */
+    async chooseFile(triggerSelector, ...filePaths) {
+        const start = Date.now();
+        try {
+            const [fileChooser] = await Promise.all([
+                this.raw.waitForFileChooser({ timeout: this._actionTimeout }),
+                this.click(triggerSelector),
+            ]);
+            await fileChooser.accept(filePaths);
+            const duration = Date.now() - start;
+            this._ctx.action({
+                category: "browser:chooseFile",
+                target: triggerSelector,
+                duration,
+                status: "ok",
+                detail: { fileCount: filePaths.length },
+            });
+        }
+        catch (err) {
+            const duration = Date.now() - start;
+            this._ctx.action({
+                category: "browser:chooseFile",
+                target: triggerSelector,
+                duration,
+                status: "timeout",
+                detail: { fileCount: filePaths.length, error: String(err) },
+            });
+            await this._captureFailure(`chooseFile-${triggerSelector}`);
+            throw err;
+        }
+        await this._captureStep(`chooseFile-${triggerSelector}`);
+    }
+    /** Query a single element by selector. */
+    async $(selector) {
+        return await this.raw.$(selector);
+    }
+    /** Query all elements by selector. */
+    async $$(selector) {
+        return await this.raw.$$(selector);
+    }
+    /** Evaluate a function in the browser page context. */
+    async evaluate(fn, ...args) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await this.raw.evaluate(fn, ...args);
+    }
+    /** Take a screenshot. Returns the image as a Buffer or base64 string. */
+    async screenshot(options) {
+        return await this.raw.screenshot({
+            encoding: options?.encoding ?? "binary",
+            fullPage: options?.fullPage ?? false,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        });
+    }
+    /** Current page URL. */
+    url() {
+        return this.raw.url();
+    }
+    /** Current page title. */
+    async title() {
+        return await this.raw.title();
+    }
+    // ── Retry utility ─────────────────────────────────────────────────
+    static _POLL_MS = 100;
+    /**
+     * Poll `fn` until `check(result)` returns true, or throw after `timeout` ms.
+     * Used by all `waitFor*`, `textContent`, and `expect*` methods.
+     */
+    async _retryUntil(fn, check, errorMsg, options) {
+        const timeout = options?.timeout ?? 5_000;
+        const start = Date.now();
+        let lastVal;
+        while (Date.now() - start < timeout) {
+            try {
+                lastVal = await fn();
+                if (check(lastVal))
+                    return lastVal;
+            }
+            catch {
+                // element may not exist yet — retry
+            }
+            await new Promise((r) => setTimeout(r, GlubeanPage._POLL_MS));
+        }
+        // One final attempt
+        try {
+            lastVal = await fn();
+            if (check(lastVal))
+                return lastVal;
+        }
+        catch {
+            // fall through to error
+        }
+        throw new Error(errorMsg(lastVal));
+    }
+    // ── Phase 4: Navigation Auto-Wait ────────────────────────────────
+    /**
+     * Wait until the page URL matches `pattern` (string contains or RegExp test).
+     *
+     * @example
+     * ```ts
+     * await page.click('a[href="/dashboard"]');
+     * await page.waitForURL('/dashboard');
+     * ```
+     */
+    async waitForURL(pattern, options) {
+        const matches = (url) => typeof pattern === "string" ? url.includes(pattern) : pattern.test(url);
+        const start = Date.now();
+        try {
+            await this._retryUntil(() => Promise.resolve(this.raw.url()), matches, (lastUrl) => `waitForURL: page URL "${lastUrl}" did not match ` +
+                `"${pattern}" after ${options?.timeout ?? 5_000}ms`, { timeout: options?.timeout ?? this._actionTimeout });
+            this._ctx.action({
+                category: "browser:wait",
+                target: `URL matches ${String(pattern)}`,
+                duration: Date.now() - start,
+                status: "ok",
+            });
+        }
+        catch (err) {
+            this._ctx.action({
+                category: "browser:wait",
+                target: `URL matches ${String(pattern)}`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Wait for an element to appear, then return its `textContent`.
+     */
+    async textContent(selector, options) {
+        const start = Date.now();
+        const timeout = options?.timeout ?? this._actionTimeout;
+        try {
+            await this.raw.waitForSelector(selector, { timeout });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = await this.raw.$eval(selector, (el) => el.textContent);
+            this._ctx.action({
+                category: "browser:wait",
+                target: `textContent("${selector}")`,
+                duration: Date.now() - start,
+                status: "ok",
+            });
+            return result;
+        }
+        catch (err) {
+            this._ctx.action({
+                category: "browser:wait",
+                target: `textContent("${selector}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Wait for an element to appear, then return its `innerText`.
+     */
+    async innerText(selector, options) {
+        const start = Date.now();
+        const timeout = options?.timeout ?? this._actionTimeout;
+        try {
+            await this.raw.waitForSelector(selector, { timeout });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = await this.raw.$eval(selector, (el) => el.innerText);
+            this._ctx.action({
+                category: "browser:wait",
+                target: `innerText("${selector}")`,
+                duration: Date.now() - start,
+                status: "ok",
+            });
+            return result;
+        }
+        catch (err) {
+            this._ctx.action({
+                category: "browser:wait",
+                target: `innerText("${selector}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Wait for an element to appear, then return the value of `attr`.
+     */
+    async getAttribute(selector, attr, options) {
+        const start = Date.now();
+        const timeout = options?.timeout ?? this._actionTimeout;
+        try {
+            await this.raw.waitForSelector(selector, { timeout });
+            const result = await this.raw.$eval(selector, 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (el, a) => el.getAttribute(a), attr);
+            this._ctx.action({
+                category: "browser:wait",
+                target: `getAttribute("${selector}", "${attr}")`,
+                duration: Date.now() - start,
+                status: "ok",
+            });
+            return result;
+        }
+        catch (err) {
+            this._ctx.action({
+                category: "browser:wait",
+                target: `getAttribute("${selector}", "${attr}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Wait for an input element to appear, then return its `.value`.
+     */
+    async inputValue(selector, options) {
+        const start = Date.now();
+        const timeout = options?.timeout ?? this._actionTimeout;
+        try {
+            await this.raw.waitForSelector(selector, { timeout });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const result = await this.raw.$eval(selector, (el) => el.value ?? "");
+            this._ctx.action({
+                category: "browser:wait",
+                target: `inputValue("${selector}")`,
+                duration: Date.now() - start,
+                status: "ok",
+            });
+            return result;
+        }
+        catch (err) {
+            this._ctx.action({
+                category: "browser:wait",
+                target: `inputValue("${selector}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Check whether an element is currently visible (non-zero box, not hidden).
+     * Returns immediately — does not wait.
+     */
+    async isVisible(selector) {
+        const handle = await this.raw.$(selector);
+        if (!handle)
+            return false;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return await handle.evaluate((el) => {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const style = globalThis.getComputedStyle(el);
+                if (style.display === "none" || style.visibility === "hidden") {
+                    return false;
+                }
+                const box = el.getBoundingClientRect();
+                return box.width > 0 && box.height > 0;
+            });
+        }
+        finally {
+            await handle.dispose();
+        }
+    }
+    /**
+     * Check whether an element is currently enabled (not disabled).
+     * Returns immediately — does not wait.
+     */
+    async isEnabled(selector) {
+        const handle = await this.raw.$(selector);
+        if (!handle)
+            return false;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return await handle.evaluate((el) => {
+                if ("disabled" in el && !!el.disabled)
+                    return false;
+                return el.getAttribute("aria-disabled") !== "true";
+            });
+        }
+        finally {
+            await handle.dispose();
+        }
+    }
+    // ── Phase 5: Assertion Auto-Retry ────────────────────────────────
+    /**
+     * Assert that the page URL matches `pattern`. Retries until match or timeout.
+     *
+     * @example
+     * ```ts
+     * await page.click('button[type="submit"]');
+     * await page.expectURL('/dashboard');
+     * ```
+     */
+    async expectURL(pattern, options) {
+        const matches = (url) => typeof pattern === "string" ? url.includes(pattern) : pattern.test(url);
+        const start = Date.now();
+        try {
+            await this._retryUntil(() => Promise.resolve(this.raw.url()), matches, (lastUrl) => `expectURL: page URL "${lastUrl}" did not match ` +
+                `"${pattern}" after ${options?.timeout ?? 5_000}ms`, options);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectURL(${JSON.stringify(String(pattern))})`,
+                duration: Date.now() - start,
+                status: "ok",
+            });
+        }
+        catch (err) {
+            await this._captureFailure(`expectURL-${String(pattern)}`);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectURL(${JSON.stringify(String(pattern))})`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Assert that an element's text content matches `expected`. Retries until match or timeout.
+     *
+     * By default, text is normalized (trimmed + collapsed whitespace) and matched
+     * with `includes`. Use `exact: true` for strict equality or pass a `RegExp`
+     * for pattern matching.
+     */
+    async expectText(selector, expected, options) {
+        const normalize = (s) => s.replace(/\s+/g, " ").trim();
+        const matches = (text) => {
+            if (text === null)
+                return false;
+            if (expected instanceof RegExp)
+                return expected.test(text);
+            const norm = normalize(text);
+            const exp = normalize(expected);
+            if (options?.exact) {
+                return options?.ignoreCase
+                    ? norm.toLowerCase() === exp.toLowerCase()
+                    : norm === exp;
+            }
+            return options?.ignoreCase
+                ? norm.toLowerCase().includes(exp.toLowerCase())
+                : norm.includes(exp);
+        };
+        const start = Date.now();
+        let lastVal = null;
+        try {
+            lastVal = await this._retryUntil(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            () => this.raw.$eval(selector, (el) => el.textContent)
+                .catch(() => null), matches, (lv) => `expectText("${selector}"): expected ${JSON.stringify(expected)} ` +
+                `but received ${JSON.stringify(lv)} after ${options?.timeout ?? 5_000}ms`, options);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectText("${selector}")`,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { expected: String(expected), actual: lastVal },
+            });
+        }
+        catch (err) {
+            await this._captureFailure(`expectText-${selector}`);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectText("${selector}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: {
+                    expected: String(expected),
+                    actual: lastVal,
+                    error: String(err),
+                },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Assert that an element is visible. Retries until visible or timeout.
+     */
+    async expectVisible(selector, options) {
+        const start = Date.now();
+        try {
+            await this._retryUntil(() => this.isVisible(selector), (visible) => visible === true, () => `expectVisible("${selector}"): element was not visible ` +
+                `after ${options?.timeout ?? 5_000}ms`, options);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectVisible("${selector}")`,
+                duration: Date.now() - start,
+                status: "ok",
+            });
+        }
+        catch (err) {
+            await this._captureFailure(`expectVisible-${selector}`);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectVisible("${selector}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Assert that an element is hidden or absent. Retries until hidden or timeout.
+     */
+    async expectHidden(selector, options) {
+        const start = Date.now();
+        try {
+            await this._retryUntil(() => this.isVisible(selector), (visible) => visible === false, () => `expectHidden("${selector}"): element was still visible ` +
+                `after ${options?.timeout ?? 5_000}ms`, options);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectHidden("${selector}")`,
+                duration: Date.now() - start,
+                status: "ok",
+            });
+        }
+        catch (err) {
+            await this._captureFailure(`expectHidden-${selector}`);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectHidden("${selector}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Assert that an element has an attribute matching `expected`. Retries until match or timeout.
+     */
+    async expectAttribute(selector, attr, expected, options) {
+        const matches = (val) => {
+            if (val === null)
+                return false;
+            return typeof expected === "string"
+                ? val === expected
+                : expected.test(val);
+        };
+        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, a) => el.getAttribute(a), attr).catch(() => null), matches, (lv) => `expectAttribute("${selector}", "${attr}"): expected ${JSON.stringify(expected)} ` +
+                `but received ${JSON.stringify(lv)} after ${options?.timeout ?? 5_000}ms`, options);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectAttribute("${selector}", "${attr}")`,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { expected: String(expected), actual: lastVal },
+            });
+        }
+        catch (err) {
+            await this._captureFailure(`expectAttribute-${selector}-${attr}`);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectAttribute("${selector}", "${attr}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: {
+                    expected: String(expected),
+                    actual: lastVal,
+                    error: String(err),
+                },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Assert that the number of elements matching `selector` equals `expected`. Retries until match or timeout.
+     */
+    async expectCount(selector, expected, options) {
+        const start = Date.now();
+        let lastCount = 0;
+        try {
+            lastCount = await this._retryUntil(async () => (await this.raw.$$(selector)).length, (count) => count === expected, (lc) => `expectCount("${selector}"): expected ${expected} elements ` +
+                `but found ${lc} after ${options?.timeout ?? 5_000}ms`, options);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectCount("${selector}")`,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { expected, actual: lastCount },
+            });
+        }
+        catch (err) {
+            await this._captureFailure(`expectCount-${selector}`);
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectCount("${selector}")`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { expected, actual: lastCount, error: String(err) },
+            });
+            throw err;
+        }
+    }
+    // ── Phase 8: Network Interception & Assertions ────────────────────
+    /**
+     * Wait for a network request matching `pattern`.
+     *
+     * @param pattern URL string, RegExp, or predicate function.
+     * @returns The matched `HTTPRequest`.
+     */
+    async waitForRequest(pattern, options) {
+        const timeout = options?.timeout ?? this._actionTimeout;
+        const label = typeof pattern === "function"
+            ? "(predicate)"
+            : String(pattern);
+        const start = Date.now();
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const predicate = typeof pattern === "string"
+                ? (req) => req.url().includes(pattern)
+                : pattern instanceof RegExp
+                    ? (req) => pattern.test(req.url())
+                    : pattern;
+            const req = await this.raw.waitForRequest(predicate, { timeout });
+            this._ctx.action({
+                category: "browser:wait",
+                target: `waitForRequest(${label})`,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { url: req.url(), method: req.method() },
+            });
+            return req;
+        }
+        catch (err) {
+            this._ctx.action({
+                category: "browser:wait",
+                target: `waitForRequest(${label})`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Wait for a network response matching `pattern`.
+     *
+     * @param pattern URL string, RegExp, or predicate function.
+     * @returns The matched `HTTPResponse`.
+     */
+    async waitForResponse(pattern, options) {
+        const timeout = options?.timeout ?? this._actionTimeout;
+        const label = typeof pattern === "function"
+            ? "(predicate)"
+            : String(pattern);
+        const start = Date.now();
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const predicate = typeof pattern === "string"
+                ? (res) => res.url().includes(pattern)
+                : pattern instanceof RegExp
+                    ? (res) => pattern.test(res.url())
+                    : pattern;
+            const res = await this.raw.waitForResponse(predicate, { timeout });
+            this._ctx.action({
+                category: "browser:wait",
+                target: `waitForResponse(${label})`,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { url: res.url(), status: res.status() },
+            });
+            return res;
+        }
+        catch (err) {
+            this._ctx.action({
+                category: "browser:wait",
+                target: `waitForResponse(${label})`,
+                duration: Date.now() - start,
+                status: "timeout",
+                detail: { error: String(err) },
+            });
+            throw err;
+        }
+    }
+    /**
+     * Assert that a network response matching `pattern` satisfies `checks`.
+     *
+     * Waits for the response, then validates status and/or headers.
+     * Emits a `browser:assert` action.
+     *
+     * @example
+     * ```ts
+     * await page.click("#submit");
+     * await page.expectResponse("/api/login", { status: 200 });
+     * ```
+     */
+    async expectResponse(pattern, checks, options) {
+        const label = typeof pattern === "function"
+            ? "(predicate)"
+            : String(pattern);
+        const start = Date.now();
+        try {
+            const res = await this.waitForResponse(pattern, options);
+            const failures = [];
+            if (checks?.status !== undefined) {
+                const s = res.status();
+                const ok = typeof checks.status === "function"
+                    ? checks.status(s)
+                    : s === checks.status;
+                if (!ok)
+                    failures.push(`status ${s} did not match ${checks.status}`);
+            }
+            if (checks?.headerContains) {
+                const headers = res.headers();
+                for (const [key, expected] of Object.entries(checks.headerContains)) {
+                    const actual = headers[key.toLowerCase()];
+                    if (!actual || !actual.includes(expected)) {
+                        const display = actual ?? "(missing)";
+                        failures.push("header " + JSON.stringify(key) + ": expected " +
+                            JSON.stringify(expected) + ", got " + JSON.stringify(display));
+                    }
+                }
+            }
+            if (failures.length > 0) {
+                const msg = "expectResponse(" + label + "): " + failures.join("; ");
+                this._ctx.action({
+                    category: "browser:assert",
+                    target: "expectResponse(" + label + ")",
+                    duration: Date.now() - start,
+                    status: "error",
+                    detail: { url: res.url(), httpStatus: res.status(), failures },
+                });
+                throw new Error(msg);
+            }
+            this._ctx.action({
+                category: "browser:assert",
+                target: `expectResponse(${label})`,
+                duration: Date.now() - start,
+                status: "ok",
+                detail: { url: res.url(), httpStatus: res.status() },
+            });
+            return res;
+        }
+        catch (err) {
+            if (!(err instanceof Error && err.message.startsWith("expectResponse("))) {
+                this._ctx.action({
+                    category: "browser:assert",
+                    target: `expectResponse(${label})`,
+                    duration: Date.now() - start,
+                    status: "timeout",
+                    detail: { error: String(err) },
+                });
+            }
+            throw err;
+        }
+    }
+    /** Clean up: remove CDP listeners and close the page. */
+    async close() {
+        if (this._networkCleanup) {
+            await this._networkCleanup();
+            this._networkCleanup = null;
+        }
+        try {
+            await this.raw.close();
+        }
+        catch {
+            // page may already be closed
+        }
+        // Close leftover blank tabs so Chrome doesn't linger with an empty window.
+        try {
+            const browser = this.raw.browser();
+            const remaining = await browser.pages();
+            const allBlank = remaining.length > 0 && remaining.every((p) => {
+                const url = p.url();
+                return url === "about:blank" || url === "chrome://new-tab-page/";
+            });
+            if (allBlank) {
+                for (const p of remaining) {
+                    try {
+                        await p.close();
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+    _resolveUrl(url) {
+        if (!this._baseUrl)
+            return url;
+        if (url.startsWith("http://") || url.startsWith("https://"))
+            return url;
+        const base = this._baseUrl.endsWith("/")
+            ? this._baseUrl.slice(0, -1)
+            : this._baseUrl;
+        const path = url.startsWith("/") ? url : `/${url}`;
+        return `${base}${path}`;
+    }
+}
+//# sourceMappingURL=page.js.map