@e2e-dev/web 0.11.2 → 0.13.0

package/dist/browser.js

@@ -11,10 +11,14 @@
  * never re-implemented here: `context.app.resolveUrl` is the one place that
  * says which URLs a test may open.
  */
-import { Deadline, describePattern, EngineError, matchesText, pollCondition, rejectUnknownOptions, TestError, toTextPattern, urlMatches, validateJsonValue, } from 'e2e/engine';
+import { ConfigurationError, Deadline, describePattern, EngineError, matchesText, pollCondition, raceAbort, rejectUnknownOptions, TestError, toTextPattern, urlMatches, validateJsonValue, withTimeout, } from 'e2e/engine';
+import { classifyInputError } from './actions.js';
 import { saveDownloadsTo, saveFromBrowser, saveLocally } from './downloads.js';
 import { isTestErrorCode, message as causeMessage, translatePwError } from './support.js';
 import { compileEvaluation } from './evaluation.js';
+import { initScriptLabel, testInitScriptSource } from './init-scripts.js';
+import { lowercaseNames } from './protected-app.js';
+import { parseContinue, parseFulfill, requireNoArguments } from './route-options.js';
 import { routePatternMatches, routePatternsEqual } from './route-pattern.js';
 /**
  * Reads the body once the response is known and keeps the outcome: a body
@@ -59,8 +63,10 @@ export function createBrowserFixture(surface, context) {
     };
     /** An assertion-style budget: the given timeout or the assertion timeout, clamped to the test. */
     const deadlineFor = (timeout) => new Deadline(context.operation(timeout ?? context.timeouts.assertion).timeoutMs);
-    const currentUrl = () => surface.guard(context.operation(), 'url', async () => surface.requirePage().url());
-    const currentTitle = () => surface.guard(context.operation(), 'title', () => surface.requirePage().title());
+    /** The page URL, read within the action timeout or, for a matcher poll, within the poll's deadline. */
+    const currentUrl = (deadline) => surface.guard(context.operation(deadline?.remaining()), 'url', async () => surface.requirePage().url());
+    /** The page title, read within the action timeout or, for a matcher poll, within the poll's deadline. */
+    const currentTitle = (deadline) => surface.guard(context.operation(deadline?.remaining()), 'title', () => surface.requirePage().title());
     const expectation = createBrowserExpectation({ currentUrl, currentTitle, baseHref, deadlineFor, context });
     const browser = {
         goto(url, options) {
@@ -82,8 +88,8 @@ export function createBrowserFixture(surface, context) {
         forward: (options) => navigation(options, async (operation) => {
             await surface.requirePage().goForward({ waitUntil: 'load', timeout: operation.timeoutMs });
         }),
-        url: currentUrl,
-        title: currentTitle,
+        url: () => currentUrl(),
+        title: () => currentTitle(),
         // The same poll as `expect(browser).toHaveURL`, exposed as a wait.
         waitForURL: (url, options) => {
             rejectUnknownOptions('browser.waitForURL', options, ['timeout']);
@@ -103,6 +109,10 @@ export function createBrowserFixture(surface, context) {
             validateJsonValue(result.value, 'evaluate result');
             return result.value;
         },
+        async addInitScript(script, ...rest) {
+            const source = await testInitScriptSource(script, rest.length === 0 ? undefined : { arg: rest[0] }, (file) => surface.projectPath(file));
+            await surface.guard(context.operation(), 'addInitScript', () => surface.addInitScript(source));
+        },
         route(pattern, handler) {
             const wirePattern = toTextPattern(pattern);
             const predicate = (url) => routePatternMatches(wirePattern, url.href);
@@ -117,39 +127,62 @@ export function createBrowserFixture(surface, context) {
                     }
                     decided = true;
                 };
-                const postData = route.request().postData();
+                // Validation runs before `decide`, so a rejected option leaves the
+                // request to the abort below. A Playwright call that fails after the
+                // decision aborts too, rather than leaving the page's request pending.
+                const decideWith = async (name, act) => {
+                    decide(name);
+                    try {
+                        await act();
+                    }
+                    catch (cause) {
+                        await route.abort().catch(() => undefined);
+                        throw cause;
+                    }
+                };
+                const request = route.request();
+                const postData = request.postData();
                 const publicRoute = {
                     request: {
-                        url: route.request().url(),
-                        method: route.request().method(),
-                        headers: route.request().headers(),
+                        url: request.url(),
+                        method: request.method(),
+                        headers: request.headers(),
                         ...(postData === null ? {} : { postData }),
                     },
                     fulfill: async (response) => {
-                        decide('fulfill');
-                        await route.fulfill({
-                            status: response.status ?? 200,
-                            headers: response.headers ?? {},
-                            ...('json' in response && response.json !== undefined
-                                ? { json: response.json }
-                                : 'body' in response && response.body !== undefined
-                                    ? { body: response.body }
-                                    : { body: '' }),
-                        });
+                        const decision = parseFulfill(response, (file) => surface.projectPath(file));
+                        await decideWith('fulfill', () => route.fulfill({
+                            ...decision,
+                            ...(decision.json === undefined && decision.path === undefined && decision.body === undefined
+                                ? { body: '' }
+                                : {}),
+                        }));
+                    },
+                    continue: async (overrides) => {
+                        const { headers, ...decision } = parseContinue(overrides, request.url(), context.app.resolveUrl);
+                        // `continue` skips every route registered before this one, the
+                        // site-header route included, so it merges those headers itself.
+                        const site = surface.siteHeaders(decision.url ?? request.url());
+                        await decideWith('continue', () => route.continue({
+                            ...decision,
+                            ...(headers === undefined && site === undefined
+                                ? {}
+                                : { headers: { ...lowercaseNames(headers ?? request.headers()), ...site } }),
+                        }));
                     },
-                    continue: async () => {
-                        decide('continue');
-                        await route.fallback();
+                    fallback: async (...args) => {
+                        requireNoArguments('route.fallback', args);
+                        await decideWith('fallback', () => route.fallback());
                     },
-                    abort: async () => {
-                        decide('abort');
-                        await route.abort();
+                    abort: async (...args) => {
+                        requireNoArguments('route.abort', args);
+                        await decideWith('abort', () => route.abort());
                     },
                 };
                 try {
                     await handler(publicRoute);
                     if (!decided) {
-                        throw new TestError('ACTION_FAILED', 'route handler returned without calling fulfill, continue, or abort');
+                        throw new TestError('ACTION_FAILED', 'route handler returned without calling fulfill, continue, fallback, or abort');
                     }
                 }
                 catch (cause) {
@@ -189,13 +222,22 @@ export function createBrowserFixture(surface, context) {
             const operation = context.operation(options?.timeout);
             return surface.guard(operation, 'waitForResponse', async (currentOperation) => {
                 const response = await surface.requirePage().waitForResponse((candidate) => routePatternMatches(wirePattern, candidate.url()), { timeout: currentOperation.timeoutMs });
-                const body = await readResponseBody(response);
+                // Started now, while the browser still holds the body, and awaited
+                // only by `text` and `json` on a budget of their own: the timeout
+                // bounds the match, never a body still streaming in behind headers
+                // that already arrived.
+                const body = readResponseBody(response);
+                const text = async () => {
+                    const { signal, timeoutMs } = context.operation();
+                    const read = await raceAbort(withTimeout(body, timeoutMs, () => new TestError('ACTION_FAILED', `waitForResponse: response body did not finish within ${timeoutMs}ms`)), signal, 'waitForResponse body');
+                    return read();
+                };
                 return {
                     url: response.url(),
                     status: response.status(),
                     headers: response.headers(),
-                    json: async () => JSON.parse(await body()),
-                    text: body,
+                    json: async () => JSON.parse(await text()),
+                    text,
                 };
             });
         },
@@ -215,17 +257,24 @@ export function createBrowserFixture(surface, context) {
         setCookies(cookies) {
             const scheme = new URL(baseHref()).protocol === 'https:' ? 'https' : 'http';
             // The harness's URL rule decides which cookie targets are admitted; a
-            // domain cookie is checked as the origin it would be sent to.
-            for (const cookie of cookies) {
-                context.app.resolveUrl(cookie.url === undefined ? `${scheme}://${cookie.domain.replace(/^\./, '')}` : cookie.url);
-            }
+            // domain cookie is checked as the origin it would be sent to. The rule
+            // admits `about:blank` for navigation, which holds no cookie. A `url`
+            // cookie is set on the URL the rule resolved, so a relative one lands
+            // on the base URL the way `goto` would.
+            const targets = cookies.map((cookie) => {
+                const target = context.app.resolveUrl(cookie.url === undefined ? `${scheme}://${cookie.domain.replace(/^\./, '')}` : cookie.url);
+                if (!/^https?:/.test(target)) {
+                    throw new ConfigurationError('POLICY_DENIED', `cookie URL must be http(s): ${target}`);
+                }
+                return cookie.url === undefined
+                    ? { domain: cookie.domain, path: cookie.path ?? '/' }
+                    : { url: target };
+            });
             return surface.guard(context.operation(), 'setCookies', async () => {
-                await surface.requireContext().addCookies(cookies.map((cookie) => ({
+                await surface.requireContext().addCookies(cookies.map((cookie, index) => ({
                     name: cookie.name,
                     value: cookie.value,
-                    ...(cookie.url === undefined
-                        ? { domain: cookie.domain, path: cookie.path ?? '/' }
-                        : { url: cookie.url }),
+                    ...targets[index],
                     ...(cookie.expires !== undefined ? { expires: cookie.expires } : {}),
                     ...(cookie.httpOnly !== undefined ? { httpOnly: cookie.httpOnly } : {}),
                     ...(cookie.secure !== undefined ? { secure: cookie.secure } : {}),
@@ -283,17 +332,17 @@ export function createBrowserFixture(surface, context) {
                     return new TestError('ACTION_FAILED', `no download started within ${awaiting.waitMs}ms; the trigger resolved after ${awaiting.triggerMs}ms`, { cause });
                 }
                 return translated;
-            });
+            }, 'test-code');
         },
         keyboard: {
-            press: (key) => surface.guard(context.operation(), 'keyboard.press', () => surface.requirePage().keyboard.press(key)),
-            type: (text) => surface.guard(context.operation(), 'keyboard.type', () => surface.requirePage().keyboard.type(text)),
+            press: (key) => surface.guard(context.operation(), 'keyboard.press', () => surface.requirePage().keyboard.press(key), classifyInputError),
+            type: (text) => surface.guard(context.operation(), 'keyboard.type', () => surface.requirePage().keyboard.type(text), classifyInputError),
         },
         mouse: {
-            move: (x, y) => surface.guard(context.operation(), 'mouse.move', () => surface.requirePage().mouse.move(x, y)),
-            wheel: (deltaX, deltaY) => surface.guard(context.operation(), 'mouse.wheel', () => surface.requirePage().mouse.wheel(deltaX, deltaY)),
-            down: () => surface.guard(context.operation(), 'mouse.down', () => surface.requirePage().mouse.down()),
-            up: () => surface.guard(context.operation(), 'mouse.up', () => surface.requirePage().mouse.up()),
+            move: (x, y) => surface.guard(context.operation(), 'mouse.move', () => surface.requirePage().mouse.move(x, y), classifyInputError),
+            wheel: (deltaX, deltaY) => surface.guard(context.operation(), 'mouse.wheel', () => surface.requirePage().mouse.wheel(deltaX, deltaY), classifyInputError),
+            down: () => surface.guard(context.operation(), 'mouse.down', () => surface.requirePage().mouse.down(), classifyInputError),
+            up: () => surface.guard(context.operation(), 'mouse.up', () => surface.requirePage().mouse.up(), classifyInputError),
         },
     };
     const action = { kind: 'resource' };
@@ -313,6 +362,7 @@ export function createBrowserFixture(surface, context) {
         title: action,
         waitForURL: { ...navigationCall, verifies: true, label: (url) => String(url) },
         evaluate: action,
+        addInitScript: { ...action, label: (script) => initScriptLabel(script) },
         route: { ...action, label: (pattern) => String(pattern) },
         unroute: { ...action, label: (pattern) => String(pattern) },
         waitForResponse: { ...action, timeout: (_pattern, options) => options?.timeout, label: (pattern) => String(pattern) },
@@ -325,61 +375,74 @@ export function createBrowserFixture(surface, context) {
         mouse: { move: action, wheel: action, down: action, up: action },
     });
 }
-/** `expect(browser)` matchers: URL, title, and class polling against the assertion budget. */
+/**
+ * `expect(browser)` matchers: URL, title, and class polling against the
+ * assertion budget. Every read is bounded by the poll's deadline, so a page
+ * that stops answering ends the assertion at its own timeout, and the
+ * failure reports the last read instead of reading a hung page again.
+ */
 function createBrowserExpectation(deps, negated = false) {
-    const poll = async (api, label, condition, observed, timeout) => {
+    const poll = async (api, label, read, timeout) => {
+        const deadline = deps.deadlineFor(timeout);
+        // pollCondition calls onTimeout only after a read completed, so a sample is always there.
+        let last;
         await pollCondition({
-            deadline: deps.deadlineFor(timeout),
+            deadline,
             signal: deps.context.signal,
             negated,
-            evaluate: condition,
-            onTimeout: async () => new TestError('ASSERTION_FAILED', `expect.${negated ? 'not.' : ''}${api} failed\nexpected: ${negated ? 'not ' : ''}${label}\nobserved: ${await observed()}`),
+            evaluate: async () => {
+                last = await read(deadline);
+                return last.matches;
+            },
+            onTimeout: (cause) => new TestError('ASSERTION_FAILED', `expect.${negated ? 'not.' : ''}${api} failed\nexpected: ${negated ? 'not ' : ''}${label}\nobserved: ${last?.observed ?? 'nothing'}`, cause === undefined ? undefined : { cause }),
         });
     };
-    const validate = (api, options) => rejectUnknownOptions(`expect.${negated ? 'not.' : ''}${api}`, options, ['timeout']);
+    const validate = (api, options, keys = ['timeout']) => rejectUnknownOptions(`expect.${negated ? 'not.' : ''}${api}`, options, keys);
     return {
         get not() {
             return createBrowserExpectation(deps, !negated);
         },
         toHaveURL(expected, options) {
-            validate('toHaveURL', options);
+            validate('toHaveURL', options, ['ignoreCase', 'timeout']);
+            const ignoreCase = options?.ignoreCase;
+            if (ignoreCase !== undefined && typeof ignoreCase !== 'boolean') {
+                throw new TestError('INVALID_ARGUMENT', `expect.${negated ? 'not.' : ''}toHaveURL option ignoreCase must be a boolean`);
+            }
             const label = typeof expected === 'string' ? expected : String(expected);
             const target = deps.baseHref();
-            return poll('toHaveURL', `URL ${label}`, async () => urlMatches(await deps.currentUrl(), expected, target), async () => `URL ${await deps.currentUrl()}`, options?.timeout);
+            return poll('toHaveURL', `URL ${label}${ignoreCase === true ? ' (ignoring case)' : ''}`, async (deadline) => {
+                const url = await deps.currentUrl(deadline);
+                return { matches: urlMatches(url, expected, target, ignoreCase), observed: `URL ${url}` };
+            }, options?.timeout);
         },
         toHaveTitle(expected, options) {
             validate('toHaveTitle', options);
             const pattern = toTextPattern(expected, { exact: true });
-            return poll('toHaveTitle', `title ${describePattern(pattern)}`, async () => matchesText(await deps.currentTitle(), pattern), async () => `title ${JSON.stringify(await deps.currentTitle())}`, options?.timeout);
+            return poll('toHaveTitle', `title ${describePattern(pattern)}`, async (deadline) => {
+                const title = await deps.currentTitle(deadline);
+                return { matches: matchesText(title, pattern), observed: `title ${JSON.stringify(title)}` };
+            }, options?.timeout);
         },
         toHaveClass(target, expected, options) {
             validate('toHaveClass', options);
             const pattern = toTextPattern(expected, { exact: true });
-            return poll('toHaveClass', `class ${describePattern(pattern)}`, async () => {
-                try {
-                    const value = await target.getAttribute('class');
-                    if (value === null)
-                        return false;
-                    const normalized = value.trim().split(/\s+/).join(' ');
-                    return matchesText(normalized, pattern);
-                }
-                catch (error) {
-                    if (isTestErrorCode(error, 'LOCATOR_NOT_FOUND'))
-                        return undefined;
-                    throw error;
-                }
-            }, async () => {
+            return poll('toHaveClass', `class ${describePattern(pattern)}`, async (deadline) => {
+                let value;
                 try {
-                    const value = await target.getAttribute('class');
-                    if (value === null)
-                        return 'no class attribute';
-                    return `class ${JSON.stringify(value)}`;
+                    // A locator read takes the action timeout; the poll's deadline is the tighter bound.
+                    value = await withTimeout(target.getAttribute('class'), deadline.remaining(), () => new EngineError('OPERATION_TIMEOUT', 'class read timed out', { retryable: false }));
                 }
                 catch (error) {
                     if (isTestErrorCode(error, 'LOCATOR_NOT_FOUND'))
-                        return 'no node';
+                        return { matches: undefined, observed: 'no node' };
                     throw error;
                 }
+                if (value === null)
+                    return { matches: false, observed: 'no class attribute' };
+                return {
+                    matches: matchesText(value.trim().split(/\s+/).join(' '), pattern),
+                    observed: `class ${JSON.stringify(value)}`,
+                };
             }, options?.timeout);
         },
     };

package/dist/capture-scope.d.ts

@@ -1,5 +1,5 @@
 /** Deadline and handle ownership for one observation capture operation. */
-import type { JSHandle } from 'playwright';
+import type { JSHandle } from 'playwright-core';
 /** Releases acquired and late-arriving handles without waiting on the transport. */
 export declare class CaptureScope {
     readonly deadline: number;

package/dist/cdp-recovery.d.ts

@@ -1,5 +1,5 @@
 /** Validates a persistent CDP binding without publishing or retaining it. */
-import type { Browser, BrowserContext, Page } from 'playwright';
+import type { Browser, BrowserContext, Page } from 'playwright-core';
 import { EngineError } from 'e2e/engine';
 import { type ConnectionBudget } from './operation-budget.ts';
 export type CdpEndpointResolver = (signal: AbortSignal) => string | Promise<string>;

package/dist/cdp-selectors.d.ts

@@ -1,5 +1,5 @@
 /** Registers the engine's selector engines in a CDP default context; every locator and secure-field mask needs them. */
-import type { BrowserContext, Page } from 'playwright';
+import type { BrowserContext, Page } from 'playwright-core';
 import { type ConnectionBudget } from './operation-budget.ts';
 /**
  * Playwright 1.63 seeds custom selectors only in newly created contexts, not

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+/** The `e2e-web` command: browser installs with the Playwright version this engine pins. */
+/** What `main` writes to and spawns; tests replace them. */
+export interface CliIo {
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+    readonly run: (args: readonly string[]) => Promise<number>;
+}
+/** Runs `e2e-web` with the arguments after the command name and resolves to the exit code. */
+export declare function main(args: readonly string[], io?: CliIo): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,42 @@
+/** The `e2e-web` command: browser installs with the Playwright version this engine pins. */
+import { BROWSER_NAMES, isBrowserName } from './browser-connection.js';
+import { runPlaywrightCli } from './install.js';
+const BROWSER_ARGS = `[${BROWSER_NAMES.join('|')} ...] [--with-deps]`;
+const USAGE = `Usage: npx @e2e-dev/web install ${BROWSER_ARGS}
+       bunx @e2e-dev/web install ${BROWSER_ARGS}
+       pnpm exec e2e-web install ${BROWSER_ARGS}
+
+Installs browsers for the Playwright version @e2e-dev/web runs. Installs
+chromium when no browser is named. --with-deps also installs the system
+libraries the browsers need on Linux.
+`;
+const PROCESS_IO = {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+    run: runPlaywrightCli,
+};
+/** Runs `e2e-web` with the arguments after the command name and resolves to the exit code. */
+export async function main(args, io = PROCESS_IO) {
+    const [command, ...rest] = args;
+    if (command === 'help' || args.some((arg) => arg === '--help' || arg === '-h')) {
+        io.stdout(USAGE);
+        return 0;
+    }
+    if (command !== 'install') {
+        io.stderr(`${command === undefined ? 'missing command' : `unknown command "${command}"`}\n\n${USAGE}`);
+        return 2;
+    }
+    const options = rest.filter((arg) => arg.startsWith('-'));
+    const names = rest.filter((arg) => !arg.startsWith('-'));
+    const unknownOption = options.find((option) => option !== '--with-deps');
+    if (unknownOption !== undefined) {
+        io.stderr(`unknown option "${unknownOption}"\n\n${USAGE}`);
+        return 2;
+    }
+    const unknownBrowser = names.find((name) => !isBrowserName(name));
+    if (unknownBrowser !== undefined) {
+        io.stderr(`unknown browser "${unknownBrowser}"; expected one of ${BROWSER_NAMES.join(', ')}\n`);
+        return 2;
+    }
+    return io.run(['install', ...options, ...(names.length > 0 ? names : ['chromium'])]);
+}

package/dist/dialogs.d.ts

@@ -3,7 +3,7 @@
  * fixture; the surface owns the router so a dialog that fires before a test
  * ever touches `web` is still accounted for instead of silently dismissed.
  */
-import type { Dialog as PwDialog } from 'playwright';
+import type { Dialog as PwDialog } from 'playwright-core';
 import { ErrorLatch } from './support.ts';
 /** A native dialog as a test's handler sees it. */
 export interface Dialog {

package/dist/downloads.d.ts

@@ -5,7 +5,7 @@
  * that serves downloads names a directory on the browser's own disk; the
  * browser saves there, and the provider reads each finished file back.
  */
-import type { Download, Page } from 'playwright';
+import type { Download, Page } from 'playwright-core';
 import type { LeaseDownloads } from './provider.ts';
 /**
  * Has the browser behind `page` save the downloads of the page's context

package/dist/engine.d.ts

@@ -5,7 +5,7 @@
  * package imports the contract from `e2e/engine` and contributes the `browser`
  * fixture the way a device engine contributes `device`.
  */
-import type { BrowserContext, Page } from 'playwright';
+import type { BrowserContext, Page } from 'playwright-core';
 import { type EngineHandle } from 'e2e/engine';
 import { type WebOptions } from './surface.ts';
 /**

package/dist/engine.js

@@ -10,6 +10,8 @@ import { createRequire } from 'node:module';
 import { asBrowserProvider } from './provider.js';
 import { PlaywrightSurface } from './surface.js';
 import { createBrowserFixture } from './browser.js';
+import { validateInitScripts } from './init-scripts.js';
+import { FIELD_VALUE_CONTROL, headerProblem } from './protected-app.js';
 /** App fields only a device target reads. */
 const NATIVE_APP_KEYS = ['bundleId', 'appPath', 'launchArguments', 'permissions'];
 /** Creates one Playwright engine: one browser per worker, one context per attempt. */
@@ -46,6 +48,12 @@ export function web(options = {}) {
         validateTestIdAttribute(options.testIdAttribute);
     if (options.userAgent !== undefined)
         validateUserAgent(options.userAgent, options.headers);
+    if (options.locale !== undefined)
+        validateLocale(options.locale, options.headers);
+    if (options.timezoneId !== undefined)
+        validateTimezoneId(options.timezoneId);
+    if (options.initScripts !== undefined)
+        validateInitScripts(options.initScripts);
     if (options.screencast !== undefined)
         validateScreencast(options.screencast);
     const reconnecting = options.connect?.reconnectEndpoint !== undefined;
@@ -55,8 +63,9 @@ export function web(options = {}) {
     // A per-attempt lease rides the same persistent context as `reconnectEndpoint`, with the same limits.
     const recoverable = reconnecting || provider?.scope === 'attempt';
     const mode = provider === undefined ? 'connect.reconnectEndpoint' : `browser provider "${provider.name}" with scope "attempt"`;
-    if (recoverable && (options.headers !== undefined || options.basicAuth !== undefined || options.userAgent !== undefined)) {
-        throw new ConfigurationError('INVALID_CONFIG', `${mode} uses a persistent context; headers, basicAuth, and userAgent require a newly created context`);
+    const creationOptions = CREATION_OPTION_KEYS.filter((key) => options[key] !== undefined);
+    if (recoverable && creationOptions.length > 0) {
+        throw new ConfigurationError('INVALID_CONFIG', `${mode} uses a persistent context; ${creationOptions.join(', ')} ${creationOptions.length === 1 ? 'requires' : 'require'} a newly created context`);
     }
     const surface = new PlaywrightSurface(options);
     const handle = defineEngine({
@@ -125,7 +134,12 @@ const WEB_OPTION_KEYS = Object.keys({
     basicAuth: true,
     testIdAttribute: true,
     userAgent: true,
+    locale: true,
+    timezoneId: true,
+    initScripts: true,
 });
+/** The options applied when the engine creates a browser context, which a persistent context never is. */
+const CREATION_OPTION_KEYS = ['headers', 'basicAuth', 'userAgent', 'locale', 'timezoneId'];
 /**
  * What a persistent context rules out, named with its cause: `what` replaces
  * the browser context, which `mode` never does. A per-attempt lease starts
@@ -135,11 +149,6 @@ function persistentContextLimit(what, mode, leased) {
     const remedy = leased ? '; every attempt already starts on a fresh browser, and scope "worker" can clear one mid-test' : '';
     return new ConfigurationError('UNSUPPORTED_CAPABILITY', `${what} is unavailable with ${mode}: it replaces the browser context, and the attempt rides one persistent context${remedy}`);
 }
-/** An HTTP header field name: one or more `token` characters (RFC 9110). */
-const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
-/** A control character no HTTP field value may carry; a horizontal tab is the one the grammar allows. */
-// oxlint-disable-next-line no-control-regex -- the control characters are the point
-const FIELD_VALUE_CONTROL = /[\u0000-\u0008\u000A-\u001F\u007F]/;
 /** True for a plain object; the shape both options take. Config runs as JavaScript, so the types alone are no guard. */
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -155,15 +164,9 @@ function validateHeaders(headers) {
         throw new ConfigurationError('INVALID_CONFIG', 'web({ headers }) must be an object of header name to value');
     }
     for (const [name, value] of Object.entries(headers)) {
-        if (!HEADER_NAME.test(name)) {
-            throw new ConfigurationError('INVALID_CONFIG', `web({ headers }) has an invalid header name: "${name}"`);
-        }
-        if (typeof value !== 'string') {
-            throw new ConfigurationError('INVALID_CONFIG', `web({ headers }) header "${name}" must be a string, got ${typeof value}`);
-        }
-        if (FIELD_VALUE_CONTROL.test(value)) {
-            throw new ConfigurationError('INVALID_CONFIG', `web({ headers }) header "${name}" must not contain a control character`);
-        }
+        const problem = headerProblem(name, value);
+        if (problem !== undefined)
+            throw new ConfigurationError('INVALID_CONFIG', `web({ headers }) ${problem}`);
     }
 }
 /** Refuses credentials the browser could not present: a missing field, or a `:` in the user name (RFC 7617). */
@@ -199,6 +202,61 @@ function validateUserAgent(userAgent, headers) {
         throw new ConfigurationError('INVALID_CONFIG', 'web({ userAgent }) and a user-agent header in web({ headers }) conflict; set userAgent only');
     }
 }
+/**
+ * Refuses a locale that is not a BCP 47 tag, and one an `accept-language`
+ * header would override on the app's site while `navigator.language` kept
+ * reporting it.
+ */
+function validateLocale(locale, headers) {
+    if (typeof locale !== 'string' || locale === '' || !isLanguageTag(locale)) {
+        throw new ConfigurationError('INVALID_CONFIG', `web({ locale }) must be a BCP 47 language tag such as "de-DE", got ${JSON.stringify(locale)}`);
+    }
+    if (headers !== undefined && Object.keys(headers).some((name) => name.toLowerCase() === 'accept-language')) {
+        throw new ConfigurationError('INVALID_CONFIG', 'web({ locale }) and an accept-language header in web({ headers }) conflict; set locale only');
+    }
+}
+/**
+ * True when `tag` names a language the browser can run in: a Unicode locale
+ * `Intl.Locale` parses, other than the undetermined `und`, which Chromium
+ * refuses at context creation as it does a private-use-only tag.
+ */
+function isLanguageTag(tag) {
+    try {
+        const { language } = new Intl.Locale(tag);
+        return language !== undefined && language !== 'und';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Refuses, at config load, a time zone the browser would otherwise refuse at
+ * the first context. Best effort: Node cannot tell a miscased alias
+ * (`us/eastern`) from the real one, so the browser's own `Invalid timezone ID`
+ * stays the final word.
+ */
+function validateTimezoneId(timezoneId) {
+    if (typeof timezoneId !== 'string' || timezoneId === '' || !isTimeZone(timezoneId)) {
+        throw new ConfigurationError('INVALID_CONFIG', `web({ timezoneId }) must be an IANA time zone such as "Europe/Berlin", got ${JSON.stringify(timezoneId)}`);
+    }
+}
+/**
+ * True when `timeZone` is an IANA name `Intl` resolves, spelled with its own
+ * case. Node also takes an offset (`+01:00`) and any casing (`europe/berlin`),
+ * both of which Chromium refuses; an alias resolving to another name
+ * (`US/Eastern`) is fine.
+ */
+function isTimeZone(timeZone) {
+    if (/^[+-]/.test(timeZone))
+        return false;
+    try {
+        const resolved = new Intl.DateTimeFormat('en-US', { timeZone }).resolvedOptions().timeZone;
+        return resolved === timeZone || resolved.toLowerCase() !== timeZone.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * An attribute name the document grammar accepts (XML `Name`, ASCII): a value
  * outside it could never be on an element, so `getByTestId` would match nothing

package/dist/evaluation.d.ts

@@ -5,13 +5,18 @@ type EvaluationResult = {
     ok: false;
     message: string;
 };
+/** The `__name` helper tsx's `keepNames` output calls, declared beside test code serialized into the page. */
+export declare const KEEP_NAMES_HELPER = "const __name = (target, value) => Object.defineProperty(target, 'name', { value, configurable: true });";
 /**
  * Compiles the page-side error boundary without evaluating the caller's source in this process.
+ * The source is one expression: a function it evaluates to is called with the argument, any
+ * other value is the result.
  *
  * A function serialized with `toString()` carries whatever the loader compiled
- * it to. tsx runs esbuild with `keepNames`, which wraps every nested named
- * binding in a module-scoped `__name(target, name)` helper; the page has no
- * such helper, so the same one is declared next to the inlined source.
+ * it to. e2e before 0.17 loaded tests through tsx, whose esbuild `keepNames`
+ * wraps every nested named binding in a module-scoped `__name(target, name)`
+ * helper; the page has no such helper, so the same one is declared next to
+ * the inlined source for as long as this engine supports those runners.
  */
 export declare function compileEvaluation(source: string, hasArgument: boolean): (arg: unknown) => Promise<EvaluationResult>;
 export {};

package/dist/evaluation.js

@@ -1,21 +1,26 @@
 /** Separates exceptions thrown by trusted page code from failures of the evaluation transport. */
 import { TestError } from 'e2e/engine';
 import { message } from './support.js';
+/** The `__name` helper tsx's `keepNames` output calls, declared beside test code serialized into the page. */
+export const KEEP_NAMES_HELPER = "const __name = (target, value) => Object.defineProperty(target, 'name', { value, configurable: true });";
 /**
  * Compiles the page-side error boundary without evaluating the caller's source in this process.
+ * The source is one expression: a function it evaluates to is called with the argument, any
+ * other value is the result.
  *
  * A function serialized with `toString()` carries whatever the loader compiled
- * it to. tsx runs esbuild with `keepNames`, which wraps every nested named
- * binding in a module-scoped `__name(target, name)` helper; the page has no
- * such helper, so the same one is declared next to the inlined source.
+ * it to. e2e before 0.17 loaded tests through tsx, whose esbuild `keepNames`
+ * wraps every nested named binding in a module-scoped `__name(target, name)`
+ * helper; the page has no such helper, so the same one is declared next to
+ * the inlined source for as long as this engine supports those runners.
  */
 export function compileEvaluation(source, hasArgument) {
     try {
         return new Function('arg', `
       return (async () => {
-        const __name = (target, value) => Object.defineProperty(target, 'name', { value, configurable: true });
+        ${KEEP_NAMES_HELPER}
         try {
-          return { ok: true, value: await (${source}\n)(${hasArgument ? 'arg' : ''}) };
+          return { ok: true, value: await ((result) => typeof result === 'function' ? result(${hasArgument ? 'arg' : ''}) : result)((${source}\n)) };
         } catch (cause) {
           let message;
           try {