@e2e-dev/web 0.11.1 → 0.12.0

package/README.md

@@ -11,14 +11,13 @@ seam with no privilege either way.
 ## Install
 
 ```bash
-npm install --save-dev e2e @e2e-dev/web playwright
+npm install --save-dev e2e @e2e-dev/web
 ```
 
-Bring your own Playwright: `playwright` is a peer dependency (`>=1.63.0 <2`),
-not something this package installs. An app that already depends on Playwright
-keeps its version, one copy in `node_modules`, and one browser cache. A version
-outside the range may be rejected by your package manager as an unmet peer
-(npm's `ERESOLVE`), so upgrade `playwright` within the range.
+This package depends on `playwright-core` pinned to an exact version, so the
+engine always runs the Playwright it was tested against. An app that depends
+on Playwright itself keeps its own copy; the two share a browser cache only
+when their versions match.
 
 ```ts title="e2e.config.ts"
 import type { E2EConfig } from 'e2e';
@@ -41,7 +40,10 @@ target, so a test can `requires: ['browser']`. Browser options:
 `BrowserProvider` that leases hosted browsers, see below), `viewport`
 (`{ width, height }`; default 1280x720), `testIdAttribute` (the attribute
 `getByTestId` and a node's `testId` read; default `data-testid`), `userAgent`
-(the `User-Agent` every attempt sends and `navigator.userAgent` reports), and
+(the `User-Agent` every attempt sends and `navigator.userAgent` reports),
+`locale` and `timezoneId` (the language and time zone every attempt runs in,
+such as `de-DE` and `Europe/Berlin`), `initScripts` (scripts every document
+runs before the page's own), and
 `connect` — attach to a remote browser over CDP instead of launching a local
 one.
 
@@ -71,7 +73,7 @@ engine verifies the default context ID and active page target ID, clears stale
 references, and never repeats a dispatched operation. A missing target fails
 the attempt. The host owns deleting the remote browser after cleanup.
 
-This mode does not support `headers`, `basicAuth`, `userAgent`, context reset, or session
+This mode does not support `headers`, `basicAuth`, `userAgent`, `locale`, `timezoneId`, context reset, or session
 state capture and restore. Recording resumes after reconnect, but a segment
 lost during the disconnect remains unavailable. See the
 [Playwright reference](../../docs/reference/web.mdx#recovering-a-cdp-transport)
@@ -131,9 +133,13 @@ In CI, install browsers as their own step instead, so the cost is visible and
 cacheable:
 
 ```bash
-npx playwright install chromium --with-deps
+npx @e2e-dev/web install chromium --with-deps
 ```
 
+It downloads the browsers for the Playwright version this package pins, the
+ones the engine launches. Under pnpm, run the bin by name:
+`pnpm exec e2e-web install chromium --with-deps`.
+
 `--with-deps` also installs the system libraries a slim container image lacks.
 
 ## Documentation

package/dist/.build.json

@@ -1 +1 @@
-{"version":"0.11.1"}
+{"version":"0.12.0"}

package/dist/actions.d.ts

@@ -1,5 +1,5 @@
 /** Locator action dispatch for the Playwright engine. */
-import type { Page } from 'playwright';
+import type { Page } from 'playwright-core';
 import { type LocatorAction, type NodeRef, type PointerAction, type ViewportPoint } from 'e2e/engine';
 import { type ActionTarget } from './support.ts';
 /**
@@ -20,4 +20,3 @@ export declare function dispatchPointerAction(page: Page, at: ViewportPoint, act
  * committed, or an engine fault.
  */
 export declare function classifyActionError(rawCause: unknown, action: LocatorAction): Error;
-//# sourceMappingURL=actions.d.ts.map

package/dist/actions.js

@@ -1,12 +1,63 @@
 /** Locator action dispatch for the Playwright engine. */
 import { EngineError } from 'e2e/engine';
-import { asActionable, isClassified, isPwTimeout, message, nearestPixel, performElementSwipe, performPointDrag, performPointerDrag, performViewportSwipe, POST_DISPATCH_PATTERN, } from './support.js';
+import { asActionable, isClassified, isNavigationRace, isPwTimeout, message, nearestPixel, performElementSwipe, performPointDrag, performPointerDrag, performViewportSwipe, POST_DISPATCH_PATTERN, } from './support.js';
 /** How long a long press holds the button when the action names no duration. */
 const DEFAULT_LONG_PRESS_MS = 500;
 /** The keys a click holds, as Playwright's `modifiers` takes them; the contract spells them the same. */
 function heldKeys(action) {
     return action.modifiers === undefined ? {} : { modifiers: [...action.modifiers] };
 }
+/** Playwright's words for an element handle whose element left the DOM. */
+const DETACHED_PATTERN = /element (is |was )?(detached|not attached)/i;
+/**
+ * Sets a checkbox, switch, or radio to `checked` with one click, as
+ * Playwright's `check` does, apart from the read after the click: a control
+ * that is gone by then (an app that swaps a picked radio for its selected
+ * view, or navigates on change) took the click, so the action is done, where
+ * Playwright reports it detached as if the click never happened. Whatever
+ * took its place is not read: the next observation or assertion shows it,
+ * as it does after a tap. The reads and the click share one element, so the state before and after the click
+ * is one control's.
+ */
+async function setChecked(target, checked, timeout) {
+    const deadline = Date.now() + timeout;
+    // Playwright reads a timeout of 0 as no timeout at all.
+    const remaining = () => Math.max(1, deadline - Date.now());
+    const element = target.kind === 'element' ? target.element : await target.locator.elementHandle({ timeout });
+    const verb = checked ? 'check' : 'uncheck';
+    try {
+        if ((await element.isChecked()) === checked)
+            return;
+        if (!checked && (await isRadio(element))) {
+            throw new EngineError('NOT_ACTIONABLE', 'uncheck cannot clear a radio button; select another radio in its group', {
+                retryable: false,
+            });
+        }
+        await element.click({ timeout: remaining() });
+        let after;
+        try {
+            after = await element.isChecked();
+        }
+        catch (cause) {
+            if (DETACHED_PATTERN.test(message(cause)) || isNavigationRace(cause))
+                return;
+            throw cause;
+        }
+        if (after !== checked) {
+            throw new EngineError('NOT_ACTIONABLE', `${verb} clicked the control but its checked state did not change`, {
+                retryable: false,
+            });
+        }
+    }
+    finally {
+        if (target.kind === 'locator')
+            void element.dispose().catch(() => undefined);
+    }
+}
+/** Whether a checkable element is a radio, which a click can select but never clear. */
+function isRadio(element) {
+    return element.evaluate((node) => (node instanceof HTMLInputElement && node.type === 'radio') || node.getAttribute('role') === 'radio');
+}
 /**
  * Dispatches one deterministic locator action onto a Playwright target with the
  * platform's own actionability checks. `lookup` resolves the second ref of a
@@ -39,10 +90,8 @@ export async function dispatchLocatorAction(target, action, timeout, lookup) {
             await locator.press(action.key, { timeout });
             return;
         case 'check':
-            await locator.check({ timeout });
-            return;
         case 'uncheck':
-            await locator.uncheck({ timeout });
+            await setChecked(target, action.kind === 'check', timeout);
             return;
         case 'focus':
             // ElementHandle.focus takes no timeout: the element is already resolved.
@@ -177,7 +226,7 @@ export function classifyActionError(rawCause, action) {
     if (/strict mode violation/i.test(text)) {
         return new EngineError('ENGINE_FAILURE', text, { retryable: false, cause });
     }
-    if (/element (is |was )?(detached|not attached)/i.test(text)) {
+    if (DETACHED_PATTERN.test(text)) {
         return new EngineError('NODE_STALE', text, { retryable: true, cause });
     }
     if (/Timeout .*exceeded/i.test(text) || isPwTimeout(rawCause)) {
@@ -191,4 +240,3 @@ export function classifyActionError(rawCause, action) {
     }
     return new EngineError('ENGINE_FAILURE', text, { retryable: false, cause });
 }
-//# sourceMappingURL=actions.js.map

package/dist/attempt-session.d.ts

@@ -1,4 +1,4 @@
-import type { Browser, BrowserContext, BrowserContextOptions, Page } from 'playwright';
+import type { Browser, BrowserContext, BrowserContextOptions, Page } from 'playwright-core';
 import { type EngineCleanupContext, type OperationContext, type VideoSegment, type ViewportSize } from 'e2e/engine';
 import { type CdpEndpointResolver, type SessionBinding } from './cdp-recovery.ts';
 import { RefRegistry } from './refs.ts';
@@ -109,4 +109,3 @@ export declare class AttemptSession {
     private finalize;
 }
 export {};
-//# sourceMappingURL=attempt-session.d.ts.map

package/dist/attempt-session.js

@@ -345,4 +345,3 @@ export class AttemptSession {
         }
     }
 }
-//# sourceMappingURL=attempt-session.js.map

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './cli.js';
+process.exitCode = await main(process.argv.slice(2));

package/dist/browser-connection.d.ts

@@ -1,7 +1,11 @@
 /** Shares one browser process connection across a worker's attempts. */
-import type { Browser } from 'playwright';
-import { chromium } from 'playwright';
-export type BrowserName = 'chromium' | 'firefox' | 'webkit';
+import type { Browser } from 'playwright-core';
+import { chromium } from 'playwright-core';
+/** Every browser the engine launches, in the order the CLI lists them. */
+export declare const BROWSER_NAMES: readonly ['chromium', 'firefox', 'webkit'];
+export type BrowserName = (typeof BROWSER_NAMES)[number];
+/** Whether `name` is a browser the engine launches. */
+export declare function isBrowserName(name: string): name is BrowserName;
 /**
  * Launching a browser process costs hundreds of milliseconds; per-attempt
  * isolation lives in browser contexts, so every attempt a worker runs can
@@ -31,4 +35,3 @@ export declare function browserType(name: BrowserName): typeof chromium;
  * detaches the CDP session without killing the remote process the host owns.
  */
 export declare function connectCdp(endpoint: string, timeoutMs: number): Promise<Browser>;
-//# sourceMappingURL=browser-connection.d.ts.map

package/dist/browser-connection.js

@@ -1,6 +1,12 @@
 /** Shares one browser process connection across a worker's attempts. */
-import { chromium, firefox, selectors, webkit } from 'playwright';
+import { chromium, firefox, selectors, webkit } from 'playwright-core';
 import { SELECTOR_ENGINES } from './selector-engines.js';
+/** Every browser the engine launches, in the order the CLI lists them. */
+export const BROWSER_NAMES = ['chromium', 'firefox', 'webkit'];
+/** Whether `name` is a browser the engine launches. */
+export function isBrowserName(name) {
+    return BROWSER_NAMES.includes(name);
+}
 /**
  * Playwright's default SIGINT handler closes the browser and exits the
  * process, and its SIGTERM handler closes the browser. A terminal Ctrl-C
@@ -94,4 +100,3 @@ function registerSelectorEngines() {
     selectorEngines ??= Promise.all(SELECTOR_ENGINES.map(({ name, source }) => selectors.register(name, new Function(`return ${source};`)()))).then(() => undefined);
     return selectorEngines;
 }
-//# sourceMappingURL=browser-connection.js.map

package/dist/browser.d.ts

@@ -15,20 +15,44 @@ import type { ActionOptions, Expectable, JsonValue, Locator, Screen, TextMatch }
 import { type EngineFixtureContext } from 'e2e/engine';
 import type { DialogHandler } from './dialogs.ts';
 import type { PlaywrightSurface } from './surface.ts';
-/** `json` or `body`, never both; neither fulfills with an empty body. */
+/**
+ * One of `json`, `body`, or `path`, or none for an empty body. `path` names a
+ * file relative to the project root; its `Content-Type` follows its
+ * extension unless `contentType` or a `content-type` header sets one.
+ */
 export type RouteFulfillResponse = {
     status?: number;
     headers?: Record<string, string>;
+    /** Sets the `Content-Type` response header. */
+    contentType?: string;
 } & ({
     json: JsonValue;
     body?: never;
+    path?: never;
 } | {
     body: string;
     json?: never;
+    path?: never;
+} | {
+    path: string;
+    json?: never;
+    body?: never;
 } | {
     body?: never;
     json?: never;
+    path?: never;
 });
+/** What `continue` changes about the request before it goes to the network. */
+export interface RouteContinueOverrides {
+    /** Resolved against the base URL like `goto`; must keep the request's scheme. */
+    url?: string;
+    /** Request method. */
+    method?: string;
+    /** Replaces every request header; the configured `headers` for the app's site are added on top. */
+    headers?: Record<string, string>;
+    /** Request body. */
+    postData?: string;
+}
 export interface WebRoute {
     /** The intercepted request. */
     readonly request: {
@@ -39,8 +63,10 @@ export interface WebRoute {
     };
     /** Fulfills the intercepted request once. */
     fulfill(response: RouteFulfillResponse): Promise<void>;
-    /** Continues the intercepted request once. */
-    continue(): Promise<void>;
+    /** Sends the intercepted request to the network once, skipping every other route. */
+    continue(overrides?: RouteContinueOverrides): Promise<void>;
+    /** Hands the intercepted request to the route registered before this one, or the network when none matches. */
+    fallback(): Promise<void>;
     /** Aborts the intercepted request once. */
     abort(): Promise<void>;
 }
@@ -51,9 +77,9 @@ export interface WebResponse {
     readonly status: number;
     /** Response headers, lower-cased names. */
     readonly headers: Readonly<Record<string, string>>;
-    /** Parses the response body as JSON; rejects with `ACTION_FAILED` when the body could not be read. */
+    /** Waits for the body and parses it as JSON; rejects with `ACTION_FAILED` when the body could not be read. */
     json<T = unknown>(): Promise<T>;
-    /** Reads the response body as text; rejects with `ACTION_FAILED` when the body could not be read. */
+    /** Waits for the body and reads it as text; rejects with `ACTION_FAILED` when the body could not be read. */
     text(): Promise<string>;
 }
 export interface CookieFields {
@@ -83,8 +109,9 @@ export type Cookie = CookieFields & ({
 export interface BrowserExpectation {
     /** Inverts the matcher. */
     readonly not: BrowserExpectation;
-    /** Waits for the current URL to match. */
+    /** Waits for the current URL to match; `ignoreCase` compares a string case-insensitively and adds the `i` flag to a RegExp, `false` removes it. */
     toHaveURL(expected: string | RegExp, options?: {
+        ignoreCase?: boolean;
         timeout?: number;
     }): Promise<void>;
     /** Waits for the current title to match. */
@@ -146,6 +173,16 @@ export interface Browser extends Expectable<BrowserExpectation> {
     evaluate<T extends JsonValue>(fn: string | (() => T | Promise<T>)): Promise<T>;
     /** Evaluates trusted test code with one required JSON-safe argument. */
     evaluate<T extends JsonValue, Arg extends JsonValue>(fn: string | ((arg: Arg) => T | Promise<T>), arg: Arg): Promise<T>;
+    /**
+     * Adds a script every document runs before the page's own, from the next
+     * navigation on: JavaScript source, a `{ path }` relative to the project
+     * root, or a function.
+     */
+    addInitScript(script: string | {
+        path: string;
+    } | (() => unknown)): Promise<void>;
+    /** Adds an init script function called with one JSON argument. */
+    addInitScript<Arg extends JsonValue>(script: (arg: Arg) => unknown, arg: Arg): Promise<void>;
     /** Adds an attempt-scoped network route. */
     route(pattern: string | RegExp, handler: (route: WebRoute) => void | Promise<void>): Promise<void>;
     /** Removes matching attempt-scoped routes. */
@@ -197,4 +234,3 @@ export interface Browser extends Expectable<BrowserExpectation> {
 }
 /** Builds the `browser` fixture for one attempt over the shared surface. */
 export declare function createBrowserFixture(surface: PlaywrightSurface, context: EngineFixtureContext): Browser;
-//# sourceMappingURL=browser.d.ts.map

package/dist/browser.js

@@ -11,10 +11,13 @@
  * 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, 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 { 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
@@ -85,7 +88,10 @@ export function createBrowserFixture(surface, context) {
         url: currentUrl,
         title: currentTitle,
         // The same poll as `expect(browser).toHaveURL`, exposed as a wait.
-        waitForURL: (url, options) => expectation.toHaveURL(url, options),
+        waitForURL: (url, options) => {
+            rejectUnknownOptions('browser.waitForURL', options, ['timeout']);
+            return expectation.toHaveURL(url, options);
+        },
         locator: (selector) => context.locator({ kind: 'selector', selector: requireSelector('browser.locator', selector) }),
         frameLocator: (selector) => frameScreen(context, [requireSelector('browser.frameLocator', selector)]),
         async evaluate(fn, arg) {
@@ -100,6 +106,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);
@@ -114,39 +124,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 () => {
-                        decide('continue');
-                        await route.fallback();
+                    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 } }),
+                        }));
                     },
-                    abort: async () => {
-                        decide('abort');
-                        await route.abort();
+                    fallback: async (...args) => {
+                        requireNoArguments('route.fallback', args);
+                        await decideWith('fallback', () => route.fallback());
+                    },
+                    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) {
@@ -186,13 +219,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,
                 };
             });
         },
@@ -212,17 +254,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 } : {}),
@@ -310,6 +359,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) },
@@ -333,20 +383,28 @@ function createBrowserExpectation(deps, negated = false) {
             onTimeout: async () => new TestError('ASSERTION_FAILED', `expect.${negated ? 'not.' : ''}${api} failed\nexpected: ${negated ? 'not ' : ''}${label}\nobserved: ${await observed()}`),
         });
     };
+    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, ['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 () => urlMatches(await deps.currentUrl(), expected, target, ignoreCase), async () => `URL ${await deps.currentUrl()}`, 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);
         },
         toHaveClass(target, expected, options) {
+            validate('toHaveClass', options);
             const pattern = toTextPattern(expected, { exact: true });
             return poll('toHaveClass', `class ${describePattern(pattern)}`, async () => {
                 try {
@@ -395,4 +453,3 @@ function frameScreen(context, frames) {
         frameLocator: (selector) => frameScreen(context, [...frames, requireSelector('frameLocator', selector)]),
     });
 }
-//# sourceMappingURL=browser.js.map

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;
@@ -18,4 +18,3 @@ export declare class CaptureScope {
     /** Refuses further work after cancellation, expiry, or completion. */
     check(): void;
 }
-//# sourceMappingURL=capture-scope.d.ts.map

package/dist/capture-scope.js

@@ -58,4 +58,3 @@ export class CaptureScope {
 function captureTimeout() {
     return new EngineError('OPERATION_TIMEOUT', 'observation capture timed out', { retryable: false });
 }
-//# sourceMappingURL=capture-scope.js.map

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>;
@@ -26,4 +26,3 @@ export declare function attachPersistent(resolve: CdpEndpointResolver, budget: C
     readonly identity: PersistentIdentity;
 }>;
 export {};
-//# sourceMappingURL=cdp-recovery.d.ts.map

package/dist/cdp-recovery.js

@@ -81,4 +81,3 @@ export async function attachPersistent(resolve, budget, previous) {
         signal.removeEventListener('abort', detach);
     }
 }
-//# sourceMappingURL=cdp-recovery.js.map

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
@@ -12,4 +12,3 @@ import { type ConnectionBudget } from './operation-budget.ts';
 export declare function registerCdpSelectors(context: BrowserContext, budget: ConnectionBudget): Promise<void>;
 /** Existing closed roots cannot be recovered if their document loaded without the tracking hook. */
 export declare function requireCdpShadowTracking(page: Page, budget: ConnectionBudget): Promise<void>;
-//# sourceMappingURL=cdp-selectors.d.ts.map

package/dist/cdp-selectors.js

@@ -49,4 +49,3 @@ export async function requireCdpShadowTracking(page, budget) {
         throw new EngineError('ENGINE_FAILURE', 'CDP recovery failed: closed shadow root tracking is unavailable after a document changed while disconnected; locators and secure-field masks need it', { retryable: false });
     }
 }
-//# sourceMappingURL=cdp-selectors.js.map

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>;