craftdriver 0.2.1 → 1.0.0

package/dist/lib/browser.js

@@ -3,6 +3,7 @@ import { ChromeService } from './chrome.js';
 import { FirefoxService } from './firefox.js';
 import { By } from './by.js';
 import { until } from './wait.js';
+import { DEFAULT_ELEMENT_TIMEOUT_MS, DEFAULT_NAVIGATION_TIMEOUT_MS, STATE_POLL_INTERVAL_MS, NETWORK_IDLE_SETTLE_MS, PORT_RELEASE_DELAY_MS, BIDI_CONNECT_MAX_ATTEMPTS, BIDI_CONNECT_BACKOFF_STEP_MS, EVAL_REALM_RETRY_ATTEMPTS, EVAL_REALM_RETRY_DELAY_MS, } from './timing.js';
 import { ElementHandle } from './elementHandle.js';
 import { Locator } from './locator.js';
 import { expectSelector } from './expect.js';
@@ -17,6 +18,7 @@ import { ActionsBuilder } from './actions.js';
 import { BiDiSession, SessionStateManager, } from './bidi/index.js';
 import { Frame } from './frame.js';
 import { Page } from './page.js';
+import { bidiWaitFor } from './loadState.js';
 import { BrowserContext } from './browserContext.js';
 import { Tracer } from './tracing.js';
 import { A11y } from './a11y.js';
@@ -170,18 +172,25 @@ export class Browser {
     _defaultContext;
     /** Cache of {@link BrowserContext} wrappers keyed by user-context id. */
     _contextsById = new Map();
+    /** Top-level browsing-context ids keyed to their BiDi user-context id. */
+    _topLevelContextUserContexts = new Map();
+    _topLevelContextTracking;
+    _topLevelContextTrackingOffs = [];
+    _topLevelContextCacheVersion = 0;
     _logs;
     _tracer;
     _storage;
     _a11y;
     _clock;
+    /** Browser-scoped BiDi preload scripts registered via addInitScript()/clock. */
+    _browserInitScriptIds = new Set();
     _downloadsDir;
     _driverService;
     _browserName = 'chrome';
     /** Active emulation overrides, re-applied to new top-level contexts. */
     _emulation = {};
     /** Mutable browser-level defaults. Use setDefaultTimeout() / setDefaultNavigationTimeout() to change. */
-    defaults = { timeout: 5000, navigationTimeout: 30000 };
+    defaults = { timeout: DEFAULT_ELEMENT_TIMEOUT_MS, navigationTimeout: DEFAULT_NAVIGATION_TIMEOUT_MS };
     constructor(driver) {
         this.driver = driver;
         this.keyboard = new Keyboard(this.driver);
@@ -203,6 +212,8 @@ export class Browser {
     }
     /** Returns the current default timeout. Used as a live getter passed to ElementHandle / expectSelector. */
     getDefaultTimeout = () => this.defaults.timeout;
+    hasBrowserInitScripts = () => this._browserInitScriptIds.size > 0;
+    hasDefaultNavigationInitScripts = () => this._defaultContext?._hasInitScriptsForNavigation() ?? this.hasBrowserInitScripts();
     static async launch(options = {}) {
         const name = options.browserName ?? 'chrome';
         const isFirefox = name === 'firefox';
@@ -220,7 +231,7 @@ export class Browser {
         let caps = {};
         if (isChromeFamily) {
             const chromeOptions = {
-                args: isHeadless ? ['--headless=new'] : [],
+                args: [...(isHeadless ? ['--headless=new'] : []), ...(options.args ?? [])],
                 prefs: {
                     'download.default_directory': downloadsDir,
                     'download.prompt_for_download': false,
@@ -260,6 +271,8 @@ export class Browser {
             const firefoxArgs = [];
             if (isHeadless)
                 firefoxArgs.push('-headless');
+            if (options.args?.length)
+                firefoxArgs.push(...options.args);
             caps['moz:firefoxOptions'] = {
                 args: firefoxArgs,
                 prefs: {
@@ -302,6 +315,10 @@ export class Browser {
         const wsUrl = driver.__wsUrl;
         if (wsUrl && options.enableBiDi !== false) {
             await browser.initBiDi(wsUrl);
+            if (options.captureLogs && browser.bidiSession?.isConnected()) {
+                // Arm log capture now instead of lazily on first browser.logs touch.
+                void browser.bidiSession.logs.initialize();
+            }
         }
         // Load session state if provided
         if (options.storageState) {
@@ -318,16 +335,24 @@ export class Browser {
         // Retry up to 8 times with increasing delays — Firefox may not have finished
         // binding its BiDi WebSocket yet (especially when a previous session just closed
         // on the same port, or the profile is still initialising).
-        const maxAttempts = 8;
+        const maxAttempts = BIDI_CONNECT_MAX_ATTEMPTS;
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
             try {
-                await session.connect(wsUrl);
+                await session.connect(wsUrl, {
+                    // Seed the top-level-context cache from the tree connect() already
+                    // fetched, off the subscription connect() already armed — avoids a
+                    // second getTree/subscribe round trip right after this returns.
+                    onContextTree: (contexts) => {
+                        this._topLevelContextTracking = this._startTopLevelContextTracking(contexts);
+                    },
+                });
+                await this._ensureTopLevelContextTracking().catch(() => { });
                 return; // success
             }
             catch (err) {
                 if (attempt < maxAttempts) {
                     // Back-off: 300ms, 600ms, 900ms, 1200ms …
-                    await new Promise((r) => setTimeout(r, 300 * attempt));
+                    await new Promise((r) => setTimeout(r, BIDI_CONNECT_BACKOFF_STEP_MS * attempt));
                 }
                 else {
                     // All attempts failed; fall back to Classic-only mode.
@@ -426,32 +451,30 @@ export class Browser {
     async navigateTo(url, opts) {
         this._tracer?.recordAction('navigateTo', [url, opts], url);
         const waitUntil = opts?.waitUntil ?? 'load';
-        if (this.bidiSession?.isConnected()) {
+        // Classic-first for ordinary `waitUntil: 'load'` navigations: Classic
+        // already blocks until `document.readyState === 'complete'`, so the common
+        // case avoids a BiDi round trip. Preload-backed sessions stay on BiDi
+        // because the next operation is often a BiDi script evaluation into the new
+        // document; mixing Classic navigate + immediate BiDi evaluate can race with
+        // the browser clearing old execution contexts on loaded-but-settling pages.
+        const needsBiDi = waitUntil !== 'load' || this.hasDefaultNavigationInitScripts();
+        const context = needsBiDi ? this.bidiSession?.getContext() : undefined;
+        if (context && this.bidiSession?.isConnected()) {
             const conn = this.bidiSession.getConnection();
-            const context = this.bidiSession.getContext();
-            if (!context) {
-                // No context yet — fall through to Classic
-            }
-            else {
-                // BiDi path: browsingContext.navigate with the appropriate wait
-                // 'networkidle' uses 'complete' (load) then waits for network silence
-                const bidiWait = waitUntil === 'none' ? 'none'
-                    : waitUntil === 'domcontentloaded' ? 'interactive'
-                        : 'complete'; // 'load' and 'networkidle'
-                await conn.send('browsingContext.navigate', { context, url, wait: bidiWait });
-                if (waitUntil === 'networkidle') {
-                    await this.bidiSession.network.waitForNetworkIdle({
-                        timeout: this.defaults.navigationTimeout,
-                    });
-                }
-                return;
+            const bidiWait = bidiWaitFor(waitUntil);
+            await conn.send('browsingContext.navigate', { context, url, wait: bidiWait });
+            if (waitUntil === 'networkidle') {
+                await this.bidiSession.network.waitForNetworkIdle({
+                    timeout: this.defaults.navigationTimeout,
+                });
             }
+            return;
         }
-        // Classic fallback (already waits for document.readyState === 'complete')
+        // Classic path — default 'load', or BiDi unavailable/no context yet.
         await this.driver.navigateTo(url);
         if (waitUntil === 'networkidle') {
             // Best-effort: Classic can't track network events; give it a short settle time
-            await new Promise(r => setTimeout(r, 500));
+            await new Promise(r => setTimeout(r, NETWORK_IDLE_SETTLE_MS));
         }
     }
     /**
@@ -598,7 +621,7 @@ export class Browser {
         }
         const conn = this.bidiSession.getConnection();
         // Apply across all top-level contexts in the default user context.
-        const tree = await conn.send('browsingContext.getTree', {});
+        const tree = await conn.send('browsingContext.getTree', { maxDepth: 0 });
         const tops = (tree.contexts ?? []).filter((c) => !c.parent);
         const contexts = tops.map((c) => c.context);
         const params = { contexts };
@@ -679,7 +702,7 @@ export class Browser {
             }
         }
         const conn = this.bidiSession.getConnection();
-        const tree = await conn.send('browsingContext.getTree', {});
+        const tree = await conn.send('browsingContext.getTree', { maxDepth: 0 });
         const contexts = (tree.contexts ?? []).filter((c) => !c.parent).map((c) => c.context);
         // Merge the new options into the persisted state so subsequent pages inherit.
         this._emulation = { ...this._emulation, ...options };
@@ -784,7 +807,7 @@ export class Browser {
             }
             // Classic fallback: best-effort 500ms settle
             else {
-                await new Promise(r => setTimeout(r, 500));
+                await new Promise(r => setTimeout(r, NETWORK_IDLE_SETTLE_MS));
             }
             return;
         }
@@ -829,7 +852,7 @@ export class Browser {
             const readyState = await this.driver.executeScript('return document.readyState', []);
             if (readyState === 'complete' || (target === 'interactive' && readyState === 'interactive'))
                 return;
-            await new Promise(r => setTimeout(r, 100));
+            await new Promise(r => setTimeout(r, STATE_POLL_INTERVAL_MS));
         }
         throw new CraftdriverError(ErrorCode.TIMEOUT_WAITING_LOAD, `waitForLoadState('${state}') timed out after ${timeout}ms`, { detail: { state, timeout } });
     }
@@ -846,16 +869,32 @@ export class Browser {
         // Silently abort any running trace so we don't leak the timer.
         if (this._tracer?.isRunning)
             this._tracer.abort();
+        // Whether this session had a live BiDi WebSocket. Only the Firefox+BiDi
+        // combination needs the port-release pause below; capture it before close().
+        const bidiWasActive = !!this.bidiSession;
         // Close BiDi connection first
         if (this.bidiSession) {
             await this.bidiSession.close().catch(() => { });
         }
+        this._browserInitScriptIds.clear();
+        for (const off of this._topLevelContextTrackingOffs)
+            off();
+        this._topLevelContextTrackingOffs = [];
+        this._topLevelContextTracking = undefined;
+        this._topLevelContextUserContexts.clear();
+        this._topLevelContextCacheVersion++;
         // DELETE the WebDriver session — this tells the driver service to close the browser.
         await this.driver.quit().catch(() => { });
-        // Give the browser process a moment to fully release any ports (e.g. Firefox BiDi
-        // WebSocket port 9222) before we kill the driver service. Without this pause, a
-        // subsequent launch may see a 404 when connecting to the new session's WebSocket.
-        await new Promise((r) => setTimeout(r, 500));
+        // Firefox's BiDi WebSocket binds a fixed port (9222). If we kill geckodriver
+        // before Firefox has released it, the next Firefox+BiDi launch can 404 while
+        // connecting to the new session's socket — hence this pause. Chrome has no such
+        // race: chromedriver assigns an ephemeral --remote-debugging-port=0 and our BiDi
+        // URL comes from the session's own webSocketUrl, not a fixed port. So scope the
+        // 500ms sleep to Firefox+BiDi; every other quit (all Chrome, Firefox w/o BiDi)
+        // skips straight to stopping the driver.
+        if (this._browserName === 'firefox' && bidiWasActive) {
+            await new Promise((r) => setTimeout(r, PORT_RELEASE_DELAY_MS));
+        }
         // Stop the underlying driver service (chromedriver / geckodriver)
         // so we don't leak processes between sessions.
         if (this._driverService) {
@@ -920,26 +959,36 @@ export class Browser {
         const fnSrc = typeof fn === 'function' ? fn.toString() : fn;
         if (this.bidiSession?.isConnected()) {
             const conn = this.bidiSession.getConnection();
-            const context = this.bidiSession.getContext();
-            const target = context ? { context } : {};
+            // Classic-first navigations return at readyState === 'complete', which is
+            // not a barrier the BiDi side respects: an immediately following
+            // { context } call can race the browser swapping the old realm for the
+            // new one and throw "execution contexts cleared". The error is
+            // pre-execution (script never ran, no side effects), so retry a few times,
+            // re-resolving the context each attempt. In-script errors take the
+            // result.type === 'exception' path below and are never retried here.
+            const functionDeclaration = typeof fn === 'function' ? fnSrc : `function() { ${fnSrc} }`;
+            const callArgs = typeof fn === 'function' ? args.map(serializeLocalValue) : [];
             let result;
-            if (typeof fn === 'function') {
-                result = await conn.send('script.callFunction', {
-                    functionDeclaration: fnSrc,
-                    target,
-                    arguments: args.map(serializeLocalValue),
-                    awaitPromise: true,
-                });
-            }
-            else {
-                // String form: wrap in a function so `return` statements are valid,
-                // matching the behaviour of Classic WebDriver executeScript.
-                result = await conn.send('script.callFunction', {
-                    functionDeclaration: `function() { ${fnSrc} }`,
-                    target,
-                    arguments: [],
-                    awaitPromise: true,
-                });
+            for (let attempt = 1;; attempt++) {
+                const context = this.bidiSession.getContext();
+                const target = context ? { context } : {};
+                try {
+                    result = await conn.send('script.callFunction', {
+                        functionDeclaration,
+                        target,
+                        arguments: callArgs,
+                        awaitPromise: true,
+                    });
+                    break;
+                }
+                catch (err) {
+                    if (attempt < EVAL_REALM_RETRY_ATTEMPTS &&
+                        String(err?.message).includes('execution contexts cleared')) {
+                        await new Promise(r => setTimeout(r, EVAL_REALM_RETRY_DELAY_MS));
+                        continue;
+                    }
+                    throw err;
+                }
             }
             if (result.type === 'exception') {
                 throw new CraftdriverError(ErrorCode.EVAL_THREW, `evaluate() threw an exception in the page: ${result.exceptionDetails?.text ?? 'unknown error'}`, { detail: { exception: result.exceptionDetails?.text ?? null } });
@@ -981,9 +1030,13 @@ export class Browser {
             functionDeclaration: fnSrc,
         });
         const scriptId = result.script;
+        this._browserInitScriptIds.add(scriptId);
         return {
             remove: async () => {
+                if (!this._browserInitScriptIds.has(scriptId))
+                    return;
                 await conn.send('script.removePreloadScript', { script: scriptId });
+                this._browserInitScriptIds.delete(scriptId);
             },
         };
     }
@@ -1060,7 +1113,7 @@ export class Browser {
                     },
                 };
             }
-            await new Promise(r => setTimeout(r, 100));
+            await new Promise(r => setTimeout(r, STATE_POLL_INTERVAL_MS));
         }
         throw new Error(`waitForDownload() timed out after ${timeout}ms — no file appeared in ${dir}`);
     }
@@ -1242,7 +1295,7 @@ export class Browser {
     async pages() {
         if (this.bidiSession?.isConnected()) {
             const conn = this.bidiSession.getConnection();
-            const tree = await conn.send('browsingContext.getTree', {});
+            const tree = await conn.send('browsingContext.getTree', { maxDepth: 0 });
             return (tree.contexts ?? []).map((ctx) => new Page(this.driver, ctx.context, this.getDefaultTimeout, conn, this._wrapContext(ctx.userContext ?? 'default')));
         }
         // Classic fallback: use window handles
@@ -1292,8 +1345,9 @@ export class Browser {
         const timeout = opts?.timeout ?? this.defaults.navigationTimeout;
         if (this.bidiSession?.isConnected()) {
             const conn = this.bidiSession.getConnection();
-            // Subscribe to contextCreated if not already subscribed
-            await conn.subscribe(['browsingContext.contextCreated']).catch(() => { });
+            // `browsingContext.contextCreated` is already subscribed session-wide by
+            // `BiDiSession.connect()` (which must have run for `isConnected()` to be
+            // true), so no per-call `subscribe()` round trip is needed here.
             return new Promise((resolve, reject) => {
                 const timer = setTimeout(() => {
                     off();
@@ -1325,7 +1379,7 @@ export class Browser {
                 const handle = newHandles[0];
                 return new Page(this.driver, handle, this.getDefaultTimeout);
             }
-            await new Promise(r => setTimeout(r, 100));
+            await new Promise(r => setTimeout(r, STATE_POLL_INTERVAL_MS));
         }
         throw new Error(`waitForPage() timed out after ${timeout}ms — no new tab or popup appeared`);
     }
@@ -1377,7 +1431,11 @@ export class Browser {
         if (cached)
             return cached;
         const conn = this.bidiSession.getConnection();
-        const ctx = new BrowserContext(this.driver, conn, id, this.getDefaultTimeout, () => this.defaults.navigationTimeout, { getNetwork: () => this.network, getBrowserName: () => this._browserName }, config);
+        const ctx = new BrowserContext(this.driver, conn, id, this.getDefaultTimeout, () => this.defaults.navigationTimeout, {
+            getNetwork: () => this.network,
+            getBrowserName: () => this._browserName,
+            hasBrowserInitScripts: this.hasBrowserInitScripts,
+        }, config);
         this._contextsById.set(id, ctx);
         // Evict on close so long-running suites that create many contexts don't
         // accumulate dead wrappers.
@@ -1438,6 +1496,91 @@ export class Browser {
         this._defaultContext = this._wrapContext('default');
         return this._defaultContext;
     }
+    async _ensureTopLevelContextTracking() {
+        if (!this.bidiSession?.isConnected())
+            return;
+        if (this._topLevelContextTracking)
+            return this._topLevelContextTracking;
+        this._topLevelContextTracking = this._startTopLevelContextTracking();
+        return this._topLevelContextTracking;
+    }
+    /**
+     * @param initialContexts  When provided (the normal path — passed via
+     *   `BiDiSession.connect()`'s `onContextTree` callback), `contextCreated`/
+     *   `contextDestroyed` are already subscribed as part of `connect()`'s
+     *   merged batch and the tree is already fetched — this just registers
+     *   handlers and seeds the cache from it, no extra round trip. Falls back
+     *   to its own subscribe + `getTree` when called without a pre-fetched
+     *   tree (defensive — e.g. if `_ensureTopLevelContextTracking()` is ever
+     *   reached before `initBiDi()`'s callback has run).
+     */
+    async _startTopLevelContextTracking(initialContexts) {
+        const conn = this.bidiSession.getConnection();
+        if (!initialContexts) {
+            // Defensive path only. In today's sequencing this branch is unreachable:
+            // `initBiDi()` always seeds `_topLevelContextTracking` via `connect()`'s
+            // `onContextTree` callback (with `initialContexts`) before `launch()`
+            // returns, so no external caller can reach `_ensureTopLevelContextTracking()`
+            // — and thus this arg-less path — before `connect()` has already subscribed.
+            // The `subscribe()` is kept (unlike the redundant ones dropped from the
+            // other context-tracking call sites) precisely because this branch's
+            // contract is "connect()'s subscribe may NOT have run yet"; dropping it
+            // would break that contract if a future refactor made the branch reachable.
+            await conn
+                .subscribe(['browsingContext.contextCreated', 'browsingContext.contextDestroyed'])
+                .catch(() => { });
+        }
+        const onCreated = (params) => {
+            if (params.parent)
+                return;
+            const id = params.context;
+            if (typeof id !== 'string')
+                return;
+            this._topLevelContextUserContexts.set(id, typeof params.userContext === 'string' ? params.userContext : '');
+            this._topLevelContextCacheVersion++;
+        };
+        const onDestroyed = (params) => {
+            if (params.parent)
+                return;
+            if (typeof params.context === 'string') {
+                this._topLevelContextUserContexts.delete(params.context);
+                this._topLevelContextCacheVersion++;
+            }
+        };
+        this._topLevelContextTrackingOffs.push(conn.on('browsingContext.contextCreated', onCreated));
+        this._topLevelContextTrackingOffs.push(conn.on('browsingContext.contextDestroyed', onDestroyed));
+        if (initialContexts) {
+            for (const ctx of initialContexts) {
+                if (!ctx.parent) {
+                    this._topLevelContextUserContexts.set(ctx.context, ctx.userContext ?? 'default');
+                }
+            }
+            this._topLevelContextCacheVersion++;
+        }
+        else {
+            await this._refreshTopLevelContextCache(conn).catch(() => { });
+        }
+    }
+    async _refreshTopLevelContextCache(conn) {
+        const version = this._topLevelContextCacheVersion;
+        const tree = await conn.send('browsingContext.getTree', { maxDepth: 0 });
+        if (this._topLevelContextCacheVersion === version) {
+            this._topLevelContextUserContexts.clear();
+        }
+        for (const ctx of tree.contexts ?? []) {
+            if (!ctx.parent) {
+                this._topLevelContextUserContexts.set(ctx.context, ctx.userContext ?? 'default');
+            }
+        }
+        this._topLevelContextCacheVersion++;
+    }
+    _firstDefaultTopLevelContext() {
+        for (const [id, userContext] of this._topLevelContextUserContexts) {
+            if (userContext === 'default')
+                return id;
+        }
+        return undefined;
+    }
     /**
      * Return the currently focused top-level page in `defaultContext`.
      *
@@ -1460,16 +1603,22 @@ export class Browser {
     async activePage() {
         if (this.bidiSession?.isConnected()) {
             const conn = this.bidiSession.getConnection();
-            const tree = await conn.send('browsingContext.getTree', {});
-            const tops = (tree.contexts ?? []).filter((c) => !c.parent && c.userContext === 'default');
-            if (tops.length === 0) {
+            const handle = await this.driver.getCurrentWindowHandle().catch(() => '');
+            await this._ensureTopLevelContextTracking();
+            if (handle && this._topLevelContextUserContexts.get(handle) === 'default') {
+                return new Page(this.driver, handle, this.getDefaultTimeout, conn, this.defaultContext);
+            }
+            // Events should keep the cache warm, but a cheap top-level sync covers
+            // missed startup events and direct protocol/browser changes.
+            await this._refreshTopLevelContextCache(conn);
+            if (handle && this._topLevelContextUserContexts.get(handle) === 'default') {
+                return new Page(this.driver, handle, this.getDefaultTimeout, conn, this.defaultContext);
+            }
+            const fallback = this._firstDefaultTopLevelContext();
+            if (!fallback) {
                 throw new Error('activePage(): no top-level page in the default context.');
             }
-            // Match the Classic-driver focus to disambiguate when multiple top-level
-            // pages exist in the default context (e.g. after browser.openPage()).
-            const handle = await this.driver.getCurrentWindowHandle().catch(() => '');
-            const focused = tops.find((c) => c.context === handle) ?? tops[0];
-            return new Page(this.driver, focused.context, this.getDefaultTimeout, conn, this.defaultContext);
+            return new Page(this.driver, fallback, this.getDefaultTimeout, conn, this.defaultContext);
         }
         // Classic mode: no user-context concept; just wrap the current window.
         const handle = await this.driver.getCurrentWindowHandle();