@e2e-dev/web 0.11.2 → 0.13.0

package/dist/surface.js

@@ -10,7 +10,7 @@ import { mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { EngineError, raceAbort, TestError, withinCleanupBudget, } from 'e2e/engine';
 import { matchesText } from 'e2e/engine';
-import { classifyActionError, dispatchLocatorAction, dispatchPointerAction } from './actions.js';
+import { classifyActionError, classifyInputError, dispatchLocatorAction, dispatchPointerAction } from './actions.js';
 import { BrowserConnection, connectCdp } from './browser-connection.js';
 import { AttemptSession } from './attempt-session.js';
 import { LeasedBrowsers } from './provider.js';
@@ -20,11 +20,12 @@ import { applyPostSteps, frameSelectors, projectExpression } from './locators.js
 import { ROOT_NODE_ID, toSemanticNode } from './observation.js';
 import { captureObservation } from './observation-capture.js';
 import { maskOptions, secureFieldMasks } from './observe.js';
-import { connectionAbort } from './operation-budget.js';
+import { connectionAbort, withOperationDeadline } from './operation-budget.js';
 import { CLOSED_SHADOW_ROOTS_INIT_SCRIPT } from './closed-shadow.js';
+import { ConfiguredInitScripts } from './init-scripts.js';
 import { SECURE_FIELD_SELECTOR } from './read-node.js';
 import { readSelector, takeReadsFunction } from './read-selector.js';
-import { httpCredentials, installSiteHeaders, lowercaseNames } from './protected-app.js';
+import { httpCredentials, installSiteHeaders, lowercaseNames, siteHeadersFor } from './protected-app.js';
 import { RefRegistry } from './refs.js';
 import { cancelled, DEFAULT_VIEWPORT, ErrorLatch, invalidState, message, navigationStaleOr, performViewportSwipe, sanitizeFilename, staleOr, translatePwError, } from './support.js';
 /** Browser launch budget when the harness init budget is not otherwise expressed. */
@@ -62,7 +63,13 @@ export class PlaywrightSurface {
     basicAuth;
     testIdAttribute;
     userAgent;
+    locale;
+    timezoneId;
+    configuredInitScripts;
+    /** The attempt's init scripts, configured then added, applied to each context the attempt opens. */
+    initScripts = [];
     app = {};
+    projectRoot = '';
     headed = false;
     artifactsDir = '';
     artifactCounter = 0;
@@ -83,6 +90,9 @@ export class PlaywrightSurface {
         this.basicAuth = options.basicAuth;
         this.testIdAttribute = options.testIdAttribute ?? DEFAULT_TEST_ID_ATTRIBUTE;
         this.userAgent = options.userAgent;
+        this.locale = options.locale;
+        this.timezoneId = options.timezoneId;
+        this.configuredInitScripts = new ConfiguredInitScripts(options.initScripts ?? []);
     }
     // --- lifecycle ---
     /**
@@ -90,14 +100,16 @@ export class PlaywrightSurface {
      * leases the run's browsers from a provider. A CDP attach uses the
      * remote's browser, so only a local launch needs the browser here. The
      * download narrates through `info.log` and is bounded by the run's
-     * interrupt alone, never by a launch budget.
+     * interrupt alone, never by a launch budget. Init scripts are read first
+     * so a missing file fails the run before any worker starts.
      */
     async prepare(info) {
+        await this.configuredInitScripts.load(info.projectRoot);
         if (this.leases !== undefined)
             return this.leases.prepare(info);
         if (this.connect !== undefined)
             return;
-        await ensureBrowsersInstalled([this.browserName], { env: info.env, signal: info.signal, log: info.log });
+        await ensureBrowsersInstalled([this.browserName], { env: info.env, signal: info.signal, log: info.log, headed: info.headed });
     }
     /** Releases the browsers `prepare` leased; a local launch or a `connect` has nothing to release. */
     async finish(info) {
@@ -106,13 +118,20 @@ export class PlaywrightSurface {
     /** Provisions the shared browser once per worker: a local launch, or a CDP attach. */
     async init(info) {
         this.app = info.app;
+        this.projectRoot = info.projectRoot;
         this.headed = info.headed;
         this.leases?.init(info);
         // The browser was installed in `prepare`; a launch or attach is the one
         // boot step left that can outlive a launch budget, and it honours the
-        // init signal.
-        if (!this.persistent)
-            await this.acquireBrowser(info.signal);
+        // init signal. A failed init-script read throws only after the launch
+        // settles, so `dispose` owns the browser.
+        const settled = await Promise.allSettled([
+            this.configuredInitScripts.load(info.projectRoot),
+            this.persistent ? undefined : this.acquireBrowser(info.signal),
+        ]);
+        for (const outcome of settled)
+            if (outcome.status === 'rejected')
+                throw outcome.reason;
     }
     /** Whether attempts ride a persistent remote context, provisioned per attempt, instead of contexts on one shared browser. */
     get persistent() {
@@ -217,9 +236,11 @@ export class PlaywrightSurface {
         this.artifactsDir = context.artifactsDir;
         this.artifactCounter = 0;
         const routes = [];
+        const initScripts = this.configuredInitScripts.forAttempt();
         this.latch = new ErrorLatch();
         const dialogs = new DialogRouter(this.latch);
         this.routes = routes;
+        this.initScripts = initScripts;
         this.dialogs = dialogs;
         const session = new AttemptSession({
             artifactsDir: context.artifactsDir,
@@ -231,10 +252,14 @@ export class PlaywrightSurface {
                 acceptDownloads: true,
                 ...(credentials === undefined ? {} : { httpCredentials: credentials }),
                 ...(this.userAgent === undefined ? {} : { userAgent: this.userAgent }),
+                ...(this.locale === undefined ? {} : { locale: this.locale }),
+                ...(this.timezoneId === undefined ? {} : { timezoneId: this.timezoneId }),
                 ...(this.headers === undefined ? {} : { serviceWorkers: 'block' }),
             },
             configure: async (target) => {
                 await target.addInitScript(CLOSED_SHADOW_ROOTS_INIT_SCRIPT);
+                for (const script of initScripts)
+                    await target.addInitScript(script);
                 target.setDefaultTimeout(CONTEXT_DEFAULT_TIMEOUT_MS);
                 target.on('dialog', (dialog) => { void dialogs.dispatch(dialog); });
                 await installSiteHeaders(target, this.app.site, this.headers);
@@ -303,6 +328,12 @@ export class PlaywrightSurface {
             throw invalidState('no attempt is running');
         return this.session;
     }
+    /** Adds one attempt-scoped init script to the current context, for every document it creates from now on. */
+    async addInitScript(source) {
+        const context = this.requireContext();
+        this.initScripts.push(source);
+        await context.addInitScript(source);
+    }
     // --- network routes shared with the browser fixture ---
     /** Registers one attempt-scoped route on the current context. */
     async route(predicate, handler) {
@@ -310,6 +341,14 @@ export class PlaywrightSurface {
         this.routes.push({ predicate, handler });
         await context.route(predicate, handler);
     }
+    /** The configured headers a request to `url` carries, lowercased; `undefined` off the app's site. */
+    siteHeaders(url) {
+        return siteHeadersFor(url, this.app.site, this.headers);
+    }
+    /** Resolves a file a test names against the project root, as config paths do, never `process.cwd()`. */
+    projectPath(file) {
+        return path.resolve(this.projectRoot, file);
+    }
     /** Removes one registered route from the attempt and the current context. */
     async unroute(predicate, handler) {
         const context = this.requireContext();
@@ -356,16 +395,18 @@ export class PlaywrightSurface {
      * The single entry of every operation: rethrows an error latched on an
      * unawaited path, refuses a cancelled operation, races `fn` against the
      * operation signal so an abort mid-call surfaces as `CANCELLED` instead of
-     * waiting out Playwright, and translates raw errors at the contract
+     * waiting out Playwright, bounds it by the operation's budget so a call a
+     * hung page never answers is `OPERATION_TIMEOUT`, and translates raw errors at the contract
      * boundary. `translate` overrides the default translation for operations
-     * with a documented retryable failure mode.
+     * with a documented retryable failure mode; `bound` is `test-code` for an
+     * operation that runs the test's own code, which the deadline never cuts.
      */
-    async guard(operation, label, fn, translate = translatePwError) {
+    async guard(operation, label, fn, translate = translatePwError, bound = 'deadline') {
         this.latch.throwPending();
         try {
             return this.session === undefined
-                ? await raceAbort(() => fn(operation), operation.signal, label)
-                : await this.session.run(operation, label, fn);
+                ? await withOperationDeadline(operation, label, (remaining) => fn({ ...operation, ...remaining() }), bound)
+                : await this.session.run(operation, label, fn, bound);
         }
         catch (cause) {
             throw translate(cause, label);
@@ -480,7 +521,7 @@ export class PlaywrightSurface {
             return matches.map(({ raw, index }) => {
                 const pinned = handles?.[index];
                 // A single match keeps the strict locator, so a ref that turns
-                // ambiguous between locate and perform fails loud instead of acting
+                // ambiguous between locate and perform is stale instead of acting
                 // on whichever element is first.
                 const locator = reads.length === 1 ? projected.locator : projected.locator.nth(index);
                 const id = refs.storeLocated(pinned === undefined ? { kind: 'locator', locator } : { kind: 'element', element: pinned });
@@ -506,10 +547,10 @@ export class PlaywrightSurface {
     }
     /** One pointer action at a viewport point in CSS pixels, with nothing resolved behind it; see `dispatchPointerAction`. */
     performAt(point, action, operation) {
-        return this.guard(operation, `${action.kind} at point`, () => {
+        return this.guard(operation, `${action.kind} at point`, (currentOperation) => {
             this.requireSession().requireObservation();
-            return dispatchPointerAction(this.requirePage(), point, action);
-        });
+            return dispatchPointerAction(this.requirePage(), point, action, currentOperation.signal);
+        }, classifyInputError);
     }
     /**
      * Types into whatever holds focus. Keystrokes into a document body are
@@ -539,14 +580,14 @@ export class PlaywrightSurface {
                 checkpoint();
             }
             await page.keyboard.type(text);
-        });
+        }, classifyInputError);
     }
     /** Sends one key to whatever holds focus, in the contract's key grammar Playwright shares. */
     pressKey(key, operation) {
         return this.guard(operation, 'keyboard.press', () => {
             this.requireSession().requireObservation();
             return this.requirePage().keyboard.press(key);
-        });
+        }, classifyInputError);
     }
     /**
      * Refuses focused typing when nothing that takes keystrokes has focus, in

package/dist/video.d.ts

@@ -13,7 +13,7 @@
  * timestamps on it. The first segment is `video/video.webm`; later ones are
  * `video/video-part<n>.webm`. Without a recording, every hook here is a no-op.
  */
-import type { Page } from 'playwright';
+import type { Page } from 'playwright-core';
 import { type VideoFile, type VideoSegment } from 'e2e/engine';
 import type { WebScreencastOptions } from './surface.ts';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@e2e-dev/web",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "Web engine for e2e agentic end-to-end testing, built on Playwright",
   "keywords": [
     "e2e",
@@ -39,25 +39,29 @@
       "default": "./dist/index.js"
     }
   },
+  "bin": {
+    "e2e-web": "./dist/bin.js"
+  },
   "files": [
     "dist",
     "NOTICE"
   ],
+  "dependencies": {
+    "playwright-core": "1.63.0"
+  },
   "peerDependencies": {
-    "e2e": ">=0.15.0 <1",
-    "playwright": ">=1.63.0 <2"
+    "e2e": ">=0.18.0 <1"
   },
   "devDependencies": {
     "@types/node": "26.6.2",
-    "e2e": "0.16.0",
+    "e2e": "0.18.0",
     "@types/pngjs": "6.0.5",
     "pngjs": "7.0.0",
-    "playwright": "1.63.0",
     "typescript": "7.0.2",
     "vitest": "5.0.1"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": "^22.22.3 || >=24.8.0"
   },
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc --project tsconfig.build.json && node ../../scripts/stamp-dist.ts",