craftdriver 1.7.0 → 1.8.0

package/dist/lib/browser.js

@@ -33,10 +33,12 @@ 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';
 /** Common mobile device presets */
 export const devices = {
     'iPhone 14': {
@@ -269,6 +271,7 @@ export class Browser {
     _topLevelContextTracking;
     _topLevelContextTrackingOffs = [];
     _topLevelContextCacheVersion = 0;
+    _destroyedTopLevelContextIds = new Set();
     _logs;
     _tracer;
     _storage;
@@ -481,9 +484,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 +530,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 +578,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 +648,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 +717,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 +1186,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 +1231,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);
     }
@@ -1278,7 +1330,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 +1663,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 +1716,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);
@@ -1797,6 +1875,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 +1893,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 +1982,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 +2025,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 +2035,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 +2064,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();