@e2e-dev/web 0.11.1 → 0.12.0

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/closed-shadow.d.ts

@@ -61,4 +61,3 @@ export declare const CLOSED_SHADOW_SELECTOR_ENGINES: readonly {
     readonly name: string;
     readonly source: string;
 }[];
-//# sourceMappingURL=closed-shadow.d.ts.map

package/dist/closed-shadow.js

@@ -139,4 +139,3 @@ export const CLOSED_SHADOW_SELECTOR_ENGINES = [
     { name: CLOSED_SHADOW_SELECTOR_ENGINE, source: CLOSED_SHADOW_SELECTOR_ENGINE_SOURCE },
     { name: SEARCH_ROOTS_SELECTOR_ENGINE, source: SEARCH_ROOTS_SELECTOR_ENGINE_SOURCE },
 ];
-//# sourceMappingURL=closed-shadow.js.map

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 {
@@ -35,4 +35,3 @@ export declare class DialogRouter {
     dispatch(dialog: PwDialog): Promise<void>;
     private route;
 }
-//# sourceMappingURL=dialogs.d.ts.map

package/dist/dialogs.js

@@ -84,4 +84,3 @@ export class DialogRouter {
         }
     }
 }
-//# sourceMappingURL=dialogs.js.map

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
@@ -26,4 +26,3 @@ export declare function saveFromBrowser(download: Download, downloads: LeaseDown
  * save names it.
  */
 export declare function saveLocally(download: Download, file: string, unserved: string | undefined): Promise<void>;
-//# sourceMappingURL=downloads.d.ts.map

package/dist/downloads.js

@@ -71,4 +71,3 @@ export async function saveLocally(download, file, unserved) {
         throw new EngineError('ENGINE_FAILURE', `download failed: ${message(cause)}; ${unserved}`, { retryable: false, cause });
     }
 }
-//# sourceMappingURL=downloads.js.map

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';
 /**
@@ -23,4 +23,3 @@ export interface PlaywrightLiveSurface {
 /** The live surface of a handle this module created, or undefined for any other engine. */
 export declare function surfaceOf(engine: EngineHandle): PlaywrightLiveSurface | undefined;
 export declare function web(options?: WebOptions): EngineHandle;
-//# sourceMappingURL=engine.d.ts.map

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
@@ -268,4 +326,3 @@ function ownVersion() {
         return 'unknown';
     }
 }
-//# sourceMappingURL=engine.js.map

package/dist/evaluation.d.ts

@@ -5,6 +5,8 @@ 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.
  *
@@ -15,4 +17,3 @@ type EvaluationResult = {
  */
 export declare function compileEvaluation(source: string, hasArgument: boolean): (arg: unknown) => Promise<EvaluationResult>;
 export {};
-//# sourceMappingURL=evaluation.d.ts.map

package/dist/evaluation.js

@@ -1,6 +1,8 @@
 /** 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.
  *
@@ -13,7 +15,7 @@ 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' : ''}) };
         } catch (cause) {
@@ -32,4 +34,3 @@ export function compileEvaluation(source, hasArgument) {
         throw new TestError('EVALUATE_FAILED', message(cause), { cause });
     }
 }
-//# sourceMappingURL=evaluation.js.map

package/dist/in-page/read-semantics.d.ts

@@ -10,11 +10,10 @@ import type { SemanticMode, SemanticResult } from '../read-node.ts';
  * Serialized into the page by Playwright. Must stay self-contained: no outer
  * captures beyond its two arguments.
  *
- * `mode.kind === 'node'` reads exactly one element for locator reads. An
- * element no longer in its document reads as detached with its value alone:
- * a handle taken a moment earlier can point at a node the page has since
- * replaced, and what such a node reports (no boxes, so hidden) describes
- * nothing on screen.
+ * `mode.kind === 'node'` reads exactly one element for locator reads, in
+ * the selector engine's task that found it (`read-selector.ts`,
+ * `label-selector.ts`), so the element is always in its document.
+ * `mode.kind === 'hidden'` answers that one element's `states.hidden` alone.
  * `mode.kind === 'tree'` walks the subtree for one agent observation and
  * returns live element handles aligned with the flattened node list. The two
  * modes also project nodes differently; those differences are data (see
@@ -25,4 +24,3 @@ export declare const readSemanticsFunction: <Mode extends SemanticMode>(element:
     secureFieldSelector: string;
     mode: Mode;
 }) => SemanticResult<Mode>;
-//# sourceMappingURL=read-semantics.d.ts.map