craftdriver 1.6.0 → 1.8.0

package/dist/lib/browser.js

@@ -33,9 +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': {
@@ -268,6 +271,7 @@ export class Browser {
     _topLevelContextTracking;
     _topLevelContextTrackingOffs = [];
     _topLevelContextCacheVersion = 0;
+    _destroyedTopLevelContextIds = new Set();
     _logs;
     _tracer;
     _storage;
@@ -480,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) {
@@ -516,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) {
@@ -549,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
             }
@@ -617,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;
     }
@@ -680,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);
@@ -1134,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(() => { });
@@ -1178,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);
     }
@@ -1277,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);
@@ -1610,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();
@@ -1656,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);
@@ -1796,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.');
@@ -1805,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;
     }
     /**
@@ -1886,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++;
             }
@@ -1921,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');
             }
         }
@@ -1928,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;
@@ -1957,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();
@@ -2109,6 +2220,61 @@ export class Browser {
             await fs.writeFile(opts.path, buf);
         return buf;
     }
+    /**
+     * Assert that a screenshot matches a baseline PNG on disk, auto-retrying
+     * until it matches or `timeout` elapses. Returns the match result on success;
+     * throws `VisualMismatchError` (code `VISUAL_MISMATCH`) carrying the final
+     * actual and diff PNG buffers on failure.
+     *
+     * Baselines are managed for you, WebdriverIO-style:
+     * - **Missing** (`expectedPath` doesn't exist): the screenshot is captured
+     *   until it settles, written as the new baseline, and the assertion passes
+     *   (`result.baseline === 'created'`). This is always on — no flag required.
+     * - **Matches**: passes (`result.baseline === 'matched'`).
+     * - **Differs**: throws `VisualMismatchError` — unless
+     *   `CRAFTDRIVER_UPDATE_VISUAL_BASELINES=true`, in which case the baseline is
+     *   overwritten with the new screenshot and the assertion passes
+     *   (`result.baseline === 'updated'`). Creates and updates are reported to
+     *   stderr; behaviour is identical locally and in CI.
+     *
+     * A baseline that is present but unreadable/corrupt stays a hard error even
+     * under update mode — it is never overwritten. Comparison supports per-channel
+     * RGB tolerance plus max different-pixel count and percentage; anti-aliasing
+     * can optionally be ignored. `screenshot.fullPage` requires BiDi and is
+     * mutually exclusive with `screenshot.selector`.
+     *
+     * @example
+     * // First run creates 'baselines/home.png'; later runs assert against it.
+     * await browser.expectScreenshot('baselines/home.png', {
+     *   screenshot: { fullPage: true },
+     *   maxDiffPixels: 100,
+     * });
+     */
+    async expectScreenshot(expectedPath, options = {}) {
+        // Parsed before the first capture so a malformed value fails fast.
+        const update = shouldUpdateVisualBaselines(process.env.CRAFTDRIVER_UPDATE_VISUAL_BASELINES);
+        const scope = options.screenshot;
+        const capture = (remainingMs) => {
+            if (scope && 'selector' in scope && scope.selector !== undefined) {
+                // Bound the element-visibility wait by the remaining assertion time so
+                // one capture can't ignore the outer deadline. The wait still evaluates
+                // visibility at least once even at 0 ms (see WebDriverWait.until), so a
+                // present element is captured without extending the deadline.
+                return this.screenshot({ selector: scope.selector, timeout: remainingMs });
+            }
+            if (scope && 'fullPage' in scope && scope.fullPage === true) {
+                return this.screenshot({ fullPage: true });
+            }
+            return this.screenshot();
+        };
+        return runExpectScreenshot({
+            expectedPath,
+            options,
+            defaultTimeout: this.defaults.timeout,
+            capture,
+            update,
+        });
+    }
     expect(selector) {
         const by = typeof selector === 'string' ? By.css(selector) : selector;
         return expectSelector(this.driver, by, this.getDefaultTimeout);