craftdriver 1.7.0 → 1.9.0

package/dist/lib/browser.js

@@ -12,7 +12,7 @@ import { resolveLaunchTarget } from './launchTarget.js';
 import { parseRemoteEndpoint, buildRemoteCapabilities, redactUrlForLog } from './remote.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 { 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, } from './timing.js';
 import { ElementHandle } from './elementHandle.js';
 import { Locator } from './locator.js';
 import { expectSelector } from './expect.js';
@@ -33,10 +33,13 @@ import { Tracer } from './tracing.js';
 import { A11y } from './a11y.js';
 import { Clock } from './clock.js';
 import { CraftdriverError, ErrorCode } from './errors.js';
+import { parseSessionState, hasNonEmptySessionStorage, isSessionStateEmpty, storageStateDetail, } from './sessionStateValidation.js';
 import { clickWithFastPath } from './clickFastPath.js';
 import { fillWithFastPath } from './fillFastPath.js';
 import { clearWithFastPath } from './clearFastPath.js';
 import { runExpectScreenshot, shouldUpdateVisualBaselines } from './visual/index.js';
+import { publicPageInitScript } from './initScript.js';
+import { withRealmRetry } from './bidi/evaluate.js';
 /** Common mobile device presets */
 export const devices = {
     'iPhone 14': {
@@ -269,6 +272,7 @@ export class Browser {
     _topLevelContextTracking;
     _topLevelContextTrackingOffs = [];
     _topLevelContextCacheVersion = 0;
+    _destroyedTopLevelContextIds = new Set();
     _logs;
     _tracer;
     _storage;
@@ -481,9 +485,19 @@ export class Browser {
             if (wsUrl && bidiRequested) {
                 await browser.initBiDi(wsUrl);
             }
-            // Load session state if provided
-            if (options.storageState) {
-                await browser.loadState(options.storageState);
+            if (options.storageState !== undefined) {
+                const protocol = browser.bidiSession?.isConnected() ? 'bidi' : 'classic';
+                const errorContext = { operation: 'Browser.launch', browserName: name, protocol };
+                const state = await parseSessionState(options.storageState, errorContext);
+                if (browser.bidiSession?.isConnected()) {
+                    await browser.defaultContext._loadStorageState(state, 'Browser.launch');
+                }
+                else if (!isSessionStateEmpty(state)) {
+                    throw new CraftdriverError(ErrorCode.UNSUPPORTED, 'non-empty storageState cannot be restored at WebDriver Classic launch', {
+                        detail: storageStateDetail(errorContext, 'capability', { partialApplied: false }),
+                        hint: 'Enable BiDi, or launch first, navigate to the sole origin, then call browser.loadState().',
+                    });
+                }
             }
         }
         catch (err) {
@@ -517,8 +531,23 @@ export class Browser {
             if (wsUrl && target.bidiRequested) {
                 await browser.initBiDi(wsUrl);
             }
-            if (options.storageState) {
-                await browser.loadState(options.storageState);
+            if (options.storageState !== undefined) {
+                const protocol = browser.bidiSession?.isConnected() ? 'bidi' : 'classic';
+                const errorContext = {
+                    operation: 'Browser.launch',
+                    browserName: target.browserName,
+                    protocol,
+                };
+                const state = await parseSessionState(options.storageState, errorContext);
+                if (browser.bidiSession?.isConnected()) {
+                    await browser.defaultContext._loadStorageState(state, 'Browser.launch');
+                }
+                else if (!isSessionStateEmpty(state)) {
+                    throw new CraftdriverError(ErrorCode.UNSUPPORTED, 'non-empty storageState cannot be restored at WebDriver Classic launch', {
+                        detail: storageStateDetail(errorContext, 'capability', { partialApplied: false }),
+                        hint: 'Enable BiDi, or launch first, navigate to the sole origin, then call browser.loadState().',
+                    });
+                }
             }
         }
         catch (err) {
@@ -550,6 +579,8 @@ export class Browser {
                         this._topLevelContextTracking = this._startTopLevelContextTracking(contexts);
                     },
                 });
+                session.network.setInternalContextPredicate((context) => this._isInternalContextId(context));
+                session.logs.setInternalContextPredicate((context) => this._isInternalContextId(context));
                 await this._ensureTopLevelContextTracking().catch(() => { });
                 return; // success
             }
@@ -618,7 +649,13 @@ export class Browser {
      */
     get storage() {
         if (!this._storage) {
-            this._storage = new SessionStateManager(this.driver, this.bidiSession?.isConnected() ? this.bidiSession.getConnection() : null);
+            this._storage = new SessionStateManager(this.driver, this.bidiSession?.isConnected() ? this.bidiSession.getConnection() : null, undefined, {
+                browserName: this._browserName,
+                protocol: this.bidiSession?.isConnected() ? 'bidi' : 'classic',
+                runSerializedRestore: this.bidiSession?.isConnected()
+                    ? (task) => this.defaultContext._runSerializedRestore(task)
+                    : undefined,
+            });
         }
         return this._storage;
     }
@@ -681,8 +718,23 @@ export class Browser {
     /**
      * Load session state from file
      */
-    async loadState(path) {
-        return this.storage.loadState(path);
+    async loadState(source) {
+        const protocol = this.bidiSession?.isConnected() ? 'bidi' : 'classic';
+        const state = await parseSessionState(source, {
+            operation: 'browser.loadState',
+            browserName: this._browserName,
+            protocol,
+        });
+        // BiDi with no sessionStorage → the validated hydrator (multi-origin, no
+        // active page required). Otherwise (Classic, or sessionStorage present) take
+        // the active-page path, which restores a single origin matching the active
+        // page and can carry sessionStorage.
+        if (this.bidiSession?.isConnected() && !hasNonEmptySessionStorage(state)) {
+            await this.defaultContext._loadStorageState(state, 'browser.loadState');
+        }
+        else {
+            await this.storage.setState(state, 'browser.loadState');
+        }
     }
     async _runTracedAction(name, args, selector, run) {
         const actionIndex = this._tracer?.recordAction(name, args, selector);
@@ -1135,6 +1187,7 @@ export class Browser {
         this._topLevelContextTrackingOffs = [];
         this._topLevelContextTracking = undefined;
         this._topLevelContextUserContexts.clear();
+        this._destroyedTopLevelContextIds.clear();
         this._topLevelContextCacheVersion++;
         // DELETE the WebDriver session — this tells the driver service to close the browser.
         await this.driver.quit().catch(() => { });
@@ -1179,7 +1232,7 @@ export class Browser {
                 'Tracing relies on BiDi events; Classic WebDriver does not expose them.', { detail: { browserName: this._browserName, feature: 'startTrace' } });
         }
         if (!this._tracer) {
-            this._tracer = new Tracer(this, this.bidiSession.getConnection(), this._engine);
+            this._tracer = new Tracer(this, this.bidiSession.getConnection(), this._engine, (context) => this._isInternalContextId(context));
         }
         await this._tracer.start(opts);
     }
@@ -1212,8 +1265,9 @@ export class Browser {
      */
     async evaluate(fn, ...args) {
         const fnSrc = typeof fn === 'function' ? fn.toString() : fn;
-        if (this.bidiSession?.isConnected()) {
-            const conn = this.bidiSession.getConnection();
+        const bidiSession = this.bidiSession;
+        if (bidiSession?.isConnected()) {
+            const conn = bidiSession.getConnection();
             // 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
@@ -1223,28 +1277,16 @@ export class Browser {
             // 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;
-            for (let attempt = 1;; attempt++) {
-                const context = this.bidiSession.getContext();
+            const result = await withRealmRetry(() => {
+                const context = 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;
-                }
-            }
+                return conn.send('script.callFunction', {
+                    functionDeclaration,
+                    target,
+                    arguments: callArgs,
+                    awaitPromise: true,
+                });
+            });
             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 } });
             }
@@ -1278,7 +1320,7 @@ export class Browser {
         const conn = this.bidiSession.getConnection();
         const fnSrc = typeof fnOrSrc === 'function' ? fnOrSrc.toString() : `() => { ${fnOrSrc} }`;
         const result = await conn.send('script.addPreloadScript', {
-            functionDeclaration: fnSrc,
+            functionDeclaration: publicPageInitScript(fnSrc),
         });
         const scriptId = result.script;
         this._browserInitScriptIds.add(scriptId);
@@ -1611,7 +1653,14 @@ export class Browser {
             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')));
+            const pages = [];
+            for (const ctx of tree.contexts ?? []) {
+                const owner = this._wrapContext(ctx.userContext ?? 'default');
+                if (await owner._isInternalPageContext(ctx.context))
+                    continue;
+                pages.push(new Page(this.driver, ctx.context, this.getDefaultTimeout, conn, owner));
+            }
+            return pages;
         }
         // Classic fallback: use window handles
         const handles = await this.driver.getWindowHandles();
@@ -1657,19 +1706,38 @@ export class Browser {
             // `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) => {
+                let settled = false;
                 const timer = setTimeout(() => {
+                    settled = true;
                     off();
                     reject(new Error(`waitForPage() timed out after ${timeout}ms`));
                 }, timeout);
                 const off = conn.on('browsingContext.contextCreated', (params) => {
                     // Only top-level contexts have no parent
                     if (!params.parent) {
-                        clearTimeout(timer);
-                        off();
-                        resolve(new Page(this.driver, params.context, this.getDefaultTimeout, conn, this._wrapContext(params.userContext ?? 'default')));
+                        const id = params.context;
+                        const owner = this._wrapContext(params.userContext ?? 'default');
+                        void owner._isInternalPageContext(id).then((internal) => {
+                            if (internal || settled)
+                                return;
+                            settled = true;
+                            clearTimeout(timer);
+                            off();
+                            resolve(new Page(this.driver, id, this.getDefaultTimeout, conn, owner));
+                        }).catch((err) => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            clearTimeout(timer);
+                            off();
+                            reject(err);
+                        });
                     }
                 });
                 action().catch((err) => {
+                    if (settled)
+                        return;
+                    settled = true;
                     clearTimeout(timer);
                     off();
                     reject(err);
@@ -1758,7 +1826,7 @@ export class Browser {
      *
      * @example
      * // Skip the login UI in every test by reusing a saved session.
-     * const ctx = await browser.newContext({ storageState: 'auth/alice.json' });
+     * const ctx = await browser.newContext({ storageState: '.auth/alice.json' });
      * const page = await ctx.newPage({ url: 'https://app.example.com/dashboard' });
      *
      * @example
@@ -1797,6 +1865,15 @@ export class Browser {
         });
         return ctx;
     }
+    _isInternalContextId(context) {
+        if (typeof context !== 'string')
+            return false;
+        for (const ctx of this._contextsById.values()) {
+            if (ctx._isInternalPageId(context))
+                return true;
+        }
+        return false;
+    }
     async newContext(opts) {
         this.requireBiDi('newContext()', 'newContext() requires BiDi (enableBiDi: true). ' +
             'WebDriver Classic has no concept of user contexts.');
@@ -1806,17 +1883,25 @@ export class Browser {
             baseURL: opts?.baseURL,
             extraHTTPHeaders: opts?.extraHTTPHeaders,
         });
-        if (opts?.storageState !== undefined) {
-            await ctx.loadStorageState(opts.storageState);
-        }
-        // Apply identity & device emulation options. Each setter is `userContexts`-scoped,
-        // so future pages in this context inherit automatically.
-        if (opts?.locale !== undefined)
-            await ctx.setLocale(opts.locale);
-        if (opts?.timezoneId !== undefined)
-            await ctx.setTimezone(opts.timezoneId);
-        if (opts?.geolocation !== undefined)
-            await ctx.setGeolocation(opts.geolocation);
+        try {
+            if (opts?.storageState !== undefined) {
+                await ctx._loadStorageState(opts.storageState, 'browser.newContext');
+            }
+            // Apply identity & device emulation options. Each setter is `userContexts`-scoped,
+            // so future pages in this context inherit automatically.
+            if (opts?.locale !== undefined)
+                await ctx.setLocale(opts.locale);
+            if (opts?.timezoneId !== undefined)
+                await ctx.setTimezone(opts.timezoneId);
+            if (opts?.geolocation !== undefined)
+                await ctx.setGeolocation(opts.geolocation);
+        }
+        catch (err) {
+            // Restore/emulation failed — tear the just-created context down so a
+            // rejected newContext() never leaves an orphaned user context behind.
+            await ctx.close().catch(() => { });
+            throw err;
+        }
         return ctx;
     }
     /**
@@ -1887,13 +1972,21 @@ export class Browser {
             const id = params.context;
             if (typeof id !== 'string')
                 return;
-            this._topLevelContextUserContexts.set(id, typeof params.userContext === 'string' ? params.userContext : '');
-            this._topLevelContextCacheVersion++;
+            const userContext = typeof params.userContext === 'string' ? params.userContext : 'default';
+            this._destroyedTopLevelContextIds.delete(id);
+            const owner = this._wrapContext(userContext);
+            void owner._isInternalPageContext(id).then((internal) => {
+                if (internal || this._destroyedTopLevelContextIds.has(id))
+                    return;
+                this._topLevelContextUserContexts.set(id, userContext);
+                this._topLevelContextCacheVersion++;
+            }).catch(() => { });
         };
         const onDestroyed = (params) => {
             if (params.parent)
                 return;
             if (typeof params.context === 'string') {
+                this._destroyedTopLevelContextIds.add(params.context);
                 this._topLevelContextUserContexts.delete(params.context);
                 this._topLevelContextCacheVersion++;
             }
@@ -1922,6 +2015,9 @@ export class Browser {
         }
         for (const ctx of tree.contexts ?? []) {
             if (!ctx.parent) {
+                const owner = this._wrapContext(ctx.userContext ?? 'default');
+                if (await owner._isInternalPageContext(ctx.context))
+                    continue;
                 this._topLevelContextUserContexts.set(ctx.context, ctx.userContext ?? 'default');
             }
         }
@@ -1929,7 +2025,7 @@ export class Browser {
     }
     _firstDefaultTopLevelContext() {
         for (const [id, userContext] of this._topLevelContextUserContexts) {
-            if (userContext === 'default')
+            if (userContext === 'default' && !this._isInternalContextId(id))
                 return id;
         }
         return undefined;
@@ -1958,13 +2054,17 @@ export class Browser {
             const conn = this.bidiSession.getConnection();
             const handle = await this.driver.getCurrentWindowHandle().catch(() => '');
             await this._ensureTopLevelContextTracking();
-            if (handle && this._topLevelContextUserContexts.get(handle) === 'default') {
+            if (handle &&
+                this._topLevelContextUserContexts.get(handle) === 'default' &&
+                !this._isInternalContextId(handle)) {
                 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') {
+            if (handle &&
+                this._topLevelContextUserContexts.get(handle) === 'default' &&
+                !this._isInternalContextId(handle)) {
                 return new Page(this.driver, handle, this.getDefaultTimeout, conn, this.defaultContext);
             }
             const fallback = this._firstDefaultTopLevelContext();
@@ -2171,7 +2271,14 @@ export class Browser {
     }
     find(selector) {
         const by = typeof selector === 'string' ? By.css(selector) : selector;
-        return new ElementHandle(this.driver, by, this.getDefaultTimeout);
+        return new ElementHandle(this.driver, by, this.getDefaultTimeout).withBiDi(() => {
+            if (!this.bidiSession?.isConnected())
+                return undefined;
+            const contextId = this.bidiSession.getContext();
+            return contextId
+                ? { connection: this.bidiSession.getConnection(), contextId }
+                : undefined;
+        });
     }
     /**
      * Return a lazy, chainable `Locator` for the given selector.
@@ -2179,7 +2286,14 @@ export class Browser {
      */
     locator(selector) {
         const by = typeof selector === 'string' ? By.css(selector) : selector;
-        return new Locator(this.driver, by, this.getDefaultTimeout);
+        return new Locator(this.driver, by, this.getDefaultTimeout).withBiDi(() => {
+            if (!this.bidiSession?.isConnected())
+                return undefined;
+            const contextId = this.bidiSession.getContext();
+            return contextId
+                ? { connection: this.bidiSession.getConnection(), contextId }
+                : undefined;
+        });
     }
     /**
      * Return snapshot `ElementHandle`s for all elements matching `selector` at call time.
@@ -2188,28 +2302,35 @@ export class Browser {
     async findAll(selector) {
         const by = typeof selector === 'string' ? By.css(selector) : selector;
         const webElements = await this.driver.findElements(by);
-        return webElements.map((we) => ElementHandle.fromWebElement(this.driver, we, this.getDefaultTimeout));
+        return webElements.map((we) => ElementHandle.fromWebElement(this.driver, we, this.getDefaultTimeout).withBiDi(() => {
+            if (!this.bidiSession?.isConnected())
+                return undefined;
+            const contextId = this.bidiSession.getContext();
+            return contextId
+                ? { connection: this.bidiSession.getConnection(), contextId }
+                : undefined;
+        }));
     }
     getByRole(role, opts) {
-        return new ElementHandle(this.driver, By.role(role, opts), this.getDefaultTimeout);
+        return this.find(By.role(role, opts));
     }
     getByText(text, opts) {
-        return new ElementHandle(this.driver, By.text(text, opts), this.getDefaultTimeout);
+        return this.find(By.text(text, opts));
     }
     getByLabel(text, opts) {
-        return new ElementHandle(this.driver, By.labelText(text, opts), this.getDefaultTimeout);
+        return this.find(By.labelText(text, opts));
     }
     getByPlaceholder(text, opts) {
-        return new ElementHandle(this.driver, By.placeholder(text, opts), this.getDefaultTimeout);
+        return this.find(By.placeholder(text, opts));
     }
     getByTestId(id) {
-        return new ElementHandle(this.driver, By.testId(id), this.getDefaultTimeout);
+        return this.find(By.testId(id));
     }
     getByAltText(text, opts) {
-        return new ElementHandle(this.driver, By.altText(text, opts), this.getDefaultTimeout);
+        return this.find(By.altText(text, opts));
     }
     getByTitle(text, opts) {
-        return new ElementHandle(this.driver, By.title(text, opts), this.getDefaultTimeout);
+        return this.find(By.title(text, opts));
     }
     // Keyboard controller and enum for nicer usage: browser.keyboard.press(Key.Enter)
     keyboard;