@e2e-dev/web 0.11.2 → 0.13.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.2"}
+{"version":"0.13.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';
 /**
@@ -13,10 +13,16 @@ export declare function dispatchLocatorAction(target: ActionTarget, action: Loca
  * behind it: no actionability wait, because there is no element to wait on,
  * and the page decides what the gesture lands on, as it does for a person.
  */
-export declare function dispatchPointerAction(page: Page, at: ViewportPoint, action: PointerAction): Promise<void>;
+export declare function dispatchPointerAction(page: Page, at: ViewportPoint, action: PointerAction, signal?: AbortSignal): Promise<void>;
+/** Translates the failure of an input operation with no element behind it: a pointer action at a point, or a keystroke. */
+export declare function classifyInputError(cause: unknown, label: string): Error;
 /**
  * Classifies a failed action onto the error contract (see the table above
  * `POST_DISPATCH_PATTERN` in support.ts): stale, not actionable, possibly
- * committed, or an engine fault.
+ * committed, or an engine fault. A strict mode violation is a located match
+ * that turned ambiguous: stale like a detached one before any input, so the
+ * runner locates again and reports the ambiguity or acts on the one match
+ * left; possibly committed once input went out, as the second side of a drag
+ * resolves after the press.
  */
 export declare function classifyActionError(rawCause: unknown, action: LocatorAction): Error;

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, translatePwError, } 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.
@@ -102,7 +151,7 @@ export async function dispatchLocatorAction(target, action, timeout, lookup) {
  * behind it: no actionability wait, because there is no element to wait on,
  * and the page decides what the gesture lands on, as it does for a person.
  */
-export async function dispatchPointerAction(page, at, action) {
+export async function dispatchPointerAction(page, at, action, signal) {
     const { mouse } = page;
     const point = nearestPixel(at);
     switch (action.kind) {
@@ -122,9 +171,11 @@ export async function dispatchPointerAction(page, at, action) {
             await mouse.move(point.x, point.y);
             return;
         case 'dragTo':
+            await performPointDrag(mouse, point, action.target, undefined, signal);
+            return;
         case 'swipeTo':
             // A swipe along a path is a pointer drag on a document platform.
-            await performPointDrag(mouse, point, action.target);
+            await performPointDrag(mouse, point, action.target, action.durationMs, signal);
             return;
         case 'swipe':
             // The pointer moves to the point first so the scrollable under it receives the wheel.
@@ -133,6 +184,23 @@ export async function dispatchPointerAction(page, at, action) {
             return;
     }
 }
+/**
+ * An input operation the operation deadline cut off: Playwright never
+ * answered, so whether the input reached the page is unknown, and it must not
+ * be repeated blindly.
+ */
+function inputCutOff(cause, label) {
+    if (!(cause instanceof EngineError) || cause.code !== 'OPERATION_TIMEOUT')
+        return undefined;
+    return new EngineError('ACTION_MAY_HAVE_COMMITTED', `${label} timed out before the page answered; its input may have been dispatched`, {
+        retryable: false,
+        cause,
+    });
+}
+/** Translates the failure of an input operation with no element behind it: a pointer action at a point, or a keystroke. */
+export function classifyInputError(cause, label) {
+    return inputCutOff(cause, label) ?? translatePwError(cause, label);
+}
 /**
  * Whether a failure of this action may carry the value it was given. A
  * sensitive fill's plaintext must never leave the engine: its message is
@@ -167,17 +235,27 @@ function actionabilitySummary(text) {
 /**
  * Classifies a failed action onto the error contract (see the table above
  * `POST_DISPATCH_PATTERN` in support.ts): stale, not actionable, possibly
- * committed, or an engine fault.
+ * committed, or an engine fault. A strict mode violation is a located match
+ * that turned ambiguous: stale like a detached one before any input, so the
+ * runner locates again and reports the ambiguity or acts on the one match
+ * left; possibly committed once input went out, as the second side of a drag
+ * resolves after the press.
  */
 export function classifyActionError(rawCause, action) {
+    const cut = inputCutOff(rawCause, action.kind);
+    if (cut !== undefined)
+        return cut;
     if (isClassified(rawCause))
         return rawCause;
     const text = redactSensitive(message(rawCause), action);
     const cause = isSensitive(action) ? undefined : rawCause;
     if (/strict mode violation/i.test(text)) {
-        return new EngineError('ENGINE_FAILURE', text, { retryable: false, cause });
+        if (POST_DISPATCH_PATTERN.test(text)) {
+            return new EngineError('ACTION_MAY_HAVE_COMMITTED', `${action.kind} matched more than one element after its input was dispatched: ${text}`, { retryable: false, cause });
+        }
+        return new EngineError('NODE_STALE', text, { retryable: true, 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)) {

package/dist/attempt-session.d.ts

@@ -1,6 +1,7 @@
-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 { type OperationBound } from './operation-budget.ts';
 import { RefRegistry } from './refs.ts';
 import type { LeaseRecording } from './provider.ts';
 import type { WebScreencastOptions } from './surface.ts';
@@ -57,8 +58,8 @@ export declare class AttemptSession {
     private invalidate;
     /** Opens a context for this attempt, publishing only after its handlers are installed. */
     start(signal: AbortSignal): Promise<void>;
-    /** Shares one reconnect, then dispatches once with the time that remains. */
-    run<T>(operation: OperationContext, label: string, work: (operation: OperationContext) => Promise<T>): Promise<T>;
+    /** Shares one reconnect, then dispatches once with the time that remains, bounded by the operation's budget unless it runs test code. */
+    run<T>(operation: OperationContext, label: string, work: (operation: OperationContext) => Promise<T>, bound?: OperationBound): Promise<T>;
     /** Owns a candidate through configuration and recording setup, then publishes it once. */
     private transition;
     /** Creates the attempt's active page and records its exact target before exposing it. */

package/dist/attempt-session.js

@@ -3,7 +3,7 @@ import { mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { EngineError, raceAbort, withinCleanupBudget } from 'e2e/engine';
 import { attachPersistent, recoveryFailed, targetIdentity } from './cdp-recovery.js';
-import { connectionAbort, withConnectionBudget } from './operation-budget.js';
+import { connectionAbort, withConnectionBudget, withOperationDeadline } from './operation-budget.js';
 import { RefRegistry } from './refs.js';
 import { ProviderVideo } from './provider-video.js';
 import { invalidState, translatePwError } from './support.js';
@@ -83,8 +83,8 @@ export class AttemptSession {
             return binding;
         }));
     }
-    /** Shares one reconnect, then dispatches once with the time that remains. */
-    async run(operation, label, work) {
+    /** Shares one reconnect, then dispatches once with the time that remains, bounded by the operation's budget unless it runs test code. */
+    async run(operation, label, work, bound = 'deadline') {
         const signal = AbortSignal.any([operation.signal, this.lifetime.signal]);
         if (signal.aborted)
             throw connectionAbort(signal, label);
@@ -92,23 +92,26 @@ export class AttemptSession {
             throw this.state.error;
         const persistent = this.options.persistent;
         const reconnect = (this.state.kind === 'pending' || (this.state.kind === 'ready' && !this.state.binding.browser.isConnected()));
-        if (persistent === undefined || !reconnect)
-            return raceAbort(() => work({ ...operation, signal }), signal, label);
-        return withConnectionBudget({ ...operation, signal }, label, async (remaining) => {
-            if (this.state.kind === 'pending') {
-                await raceAbort(this.state.work, remaining().signal, 'CDP recovery');
-            }
-            else {
+        const endsAt = Date.now() + operation.timeoutMs;
+        // Recovery is the engine's own work, so the deadline bounds it whatever the operation runs.
+        if (persistent !== undefined && reconnect) {
+            await withConnectionBudget({ signal, timeoutMs: operation.timeoutMs }, label, async (remaining) => {
+                if (this.state.kind === 'pending') {
+                    await raceAbort(this.state.work, remaining().signal, 'CDP recovery');
+                    return;
+                }
                 const previous = this.current();
                 this.observed = false;
                 await this.transition(previous, remaining(), async () => {
                     await this.video.pageClosing();
                     return attachPersistent(persistent.reconnect, remaining(), previous.identity);
                 }, true);
-            }
-            const current = remaining();
-            return raceAbort(() => work({ ...operation, ...current }), current.signal, label);
-        });
+            });
+        }
+        const left = endsAt - Date.now();
+        if (left <= 0)
+            throw new EngineError('OPERATION_TIMEOUT', `${label} timed out`, { retryable: false });
+        return withOperationDeadline({ signal, timeoutMs: left }, label, (remaining) => work({ ...operation, ...remaining() }), bound);
     }
     /** Owns a candidate through configuration and recording setup, then publishes it once. */
     async transition(previous, budget, open, recover = false) {

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

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

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. */
@@ -142,10 +169,20 @@ export interface Browser extends Expectable<BrowserExpectation> {
     locator(selector: string): Locator;
     /** Creates a screen query scope inside one iframe. */
     frameLocator(selector: string): FrameScreen;
-    /** Evaluates trusted test code in the page. */
+    /** Evaluates trusted test code in the page: a function, or a string expression whose value is returned, called first if it is a function. */
     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. */