craftdriver 0.2.2 → 1.0.1

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,11 +18,13 @@ 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';
 import { Clock } from './clock.js';
 import { CraftdriverError, ErrorCode } from './errors.js';
+import { clickWithFastPath } from './clickFastPath.js';
 /** Common mobile device presets */
 export const devices = {
     'iPhone 14': {
@@ -180,13 +183,15 @@ export class Browser {
     _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);
@@ -208,6 +213,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';
@@ -225,7 +232,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,
@@ -265,6 +272,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: {
@@ -307,6 +316,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) {
@@ -323,17 +336,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.
@@ -432,32 +452,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));
         }
     }
     /**
@@ -790,7 +808,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;
         }
@@ -835,7 +853,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 } });
     }
@@ -852,10 +870,14 @@ 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 = [];
@@ -864,10 +886,16 @@ export class Browser {
         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) {
@@ -932,26 +960,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 } });
@@ -993,9 +1031,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);
             },
         };
     }
@@ -1072,7 +1114,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}`);
     }
@@ -1304,8 +1346,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();
@@ -1337,7 +1380,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`);
     }
@@ -1389,7 +1432,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.
@@ -1458,11 +1505,32 @@ export class Browser {
         this._topLevelContextTracking = this._startTopLevelContextTracking();
         return this._topLevelContextTracking;
     }
-    async _startTopLevelContextTracking() {
+    /**
+     * @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();
-        await conn
-            .subscribe(['browsingContext.contextCreated', 'browsingContext.contextDestroyed'])
-            .catch(() => { });
+        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;
@@ -1482,7 +1550,17 @@ export class Browser {
         };
         this._topLevelContextTrackingOffs.push(conn.on('browsingContext.contextCreated', onCreated));
         this._topLevelContextTrackingOffs.push(conn.on('browsingContext.contextDestroyed', onDestroyed));
-        await this._refreshTopLevelContextCache(conn).catch(() => { });
+        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;
@@ -1551,8 +1629,8 @@ export class Browser {
         if (this._tracer?.isRunning)
             this._tracer.recordAction('click', undefined, selectorToString(selector));
         const by = typeof selector === 'string' ? By.css(selector) : selector;
-        const el = await this.driver.wait(until.elementIsVisible(by), { timeout: opts?.timeout ?? this.defaults.timeout });
-        await el.click();
+        const timeout = opts?.timeout ?? this.defaults.timeout;
+        await clickWithFastPath(() => this.driver.findElement(by), (remaining) => this.driver.wait(until.elementIsVisible(by), { timeout: remaining }), timeout);
     }
     async fill(selector, text, opts) {
         if (this._tracer?.isRunning)