playwright-browser-harness 0.2.0 → 0.3.0

package/README.md

@@ -22,11 +22,11 @@ their versions. `@sqlite.org/sqlite-wasm` is *not* a dependency; it is only a
 fixture/consumer dep when you test wasm-SQLite.
 
 `buffer` is an **optional peerDependency** — only needed (and only installed) when
-you bundle web3 / Node-dependency-heavy code with `nodePolyfills` (see
-[Bundling web3 / Node-dependency-heavy code](#bundling-web3--node-dependency-heavy-code)):
+you ask for the `'buffer'` Node polyfill (see
+[Explicit Node polyfills](#explicit-node-polyfills)):
 
 ```bash
-pnpm add -D buffer   # only if you use nodePolyfills
+pnpm add -D buffer   # only if you use nodePolyfills: ['buffer', ...]
 ```
 
 ## tsconfig (required)
@@ -101,39 +101,58 @@ esbuild) **or** `prebuilt` (prebuilt dir); `coi` (default `true`), `worker`,
 `wasmDirs`, `assets`, plus the bundling escape-hatches `nodePolyfills` and
 `esbuild` (see below).
 
-## Bundling web3 / Node-dependency-heavy code
+## Explicit Node polyfills
 
 Many web3 / crypto libraries (ethereumjs, tevm, and anything pulling in
 `readable-stream` / `safe-buffer`) transitively `import 'buffer'` and touch
-`process` / `global`. esbuild's `platform:'browser'` will **not** resolve those,
-so the bundle fails with `Could not resolve "buffer"`. The harness gives you two
-opt-in escape-hatches, both **off/empty by default** (existing consumers are
-unchanged):
+`process` / `global` / `events` / `stream`. esbuild's `platform:'browser'` will
+**not** resolve those, so the bundle fails with `Could not resolve "buffer"`.
+
+There is **no** catch-all preset. A named "web3" preset is a leaky abstraction:
+it would shim `buffer`/`process`/`global` but not `events`/`stream`/`util`, so
+you'd fall back to the `esbuild` escape-hatch anyway. Instead you **declare
+exactly what you need**.
+
+### `nodePolyfills?: ('buffer' | 'process' | 'global')[]` (default `[]`)
+
+The three Node builtins the harness can shim **itself**, with zero opinions.
+Each entry is a **self-contained** fragment — `['buffer']` shims ONLY buffer; it
+does **not** touch `process` or `global`. `[]` or omitted = nothing.
+
+| entry | what it does |
+|---|---|
+| `'buffer'`  | alias `buffer` / `node:buffer` → the [`buffer`](https://www.npmjs.com/package/buffer) npm package, and inject a `Buffer` global (also assigned onto `globalThis`). Requires the optional `buffer` peer dep (`pnpm add -D buffer`). |
+| `'process'` | inject a minimal `process` stub: `{env:{}, browser:true, version:'', nextTick}`. |
+| `'global'`  | set `define: { global: 'globalThis' }`. |
+
+**Anything beyond these three** (`events`, `stream`, `util`, `crypto`, …) is the
+consumer's job via the [`esbuild`](#esbuild-escape-hatch--esbuild--plugins-inject-define-alias-loader-external-tsconfig-)
+pass-through below.
+
+#### Copy-paste recipe: ethereumjs / tevm
+
+A typical web3 EVM tree needs all three builtins **plus** `events`/`stream`
+aliased through the escape hatch:
 
 ```ts
 const h = await mountHarness(page, {
   cut,
-  coi: false,                 // pure-compute EVM → no SharedArrayBuffer needed
-  nodePolyfills: 'web3',       // alias buffer, inject Buffer, shim process, define global
-  esbuild: {                   // pass-through merged into the internal esbuild build
-    alias: {events: 'events', stream: 'stream-browserify'}, // any extra builtins
+  coi: false,                              // pure-compute EVM → no SharedArrayBuffer needed
+  nodePolyfills: ['buffer', 'process', 'global'], // the harness's three builtins
+  esbuild: {
+    // everything the harness intentionally does NOT preset:
+    alias: {events: 'events', stream: 'stream-browserify'},
   },
 });
 ```
 
-### `nodePolyfills?: boolean | 'web3'` (default `false`)
-
-When enabled it:
-
-- aliases `buffer` / `node:buffer` → the [`buffer`](https://www.npmjs.com/package/buffer) npm package,
-- injects a `Buffer` global (also assigned onto `globalThis`),
-- provides a minimal `process` stub: `{env:{}, browser:true, version:'', nextTick}`,
-- sets `define: { global: 'globalThis' }`.
+```bash
+pnpm add -D buffer events stream-browserify
+```
 
-`true` and `'web3'` are equivalent today (the string leaves room for future
-presets). **Install the optional `buffer` peer dep** when you opt in
-(`pnpm add -D buffer`). web3 / crypto libraries usually need this; plain DOM /
-storage code does not.
+> **Migrating from 0.2.0** — `nodePolyfills` shipped in 0.2.0 as `true | 'web3'`.
+> That form was **removed** (clean break; 0.2.0 had ≈no users). Replace
+> `true` / `'web3'` with `['buffer', 'process', 'global']`.
 
 ### esbuild escape hatch — `esbuild?: { plugins?, inject?, define?, alias?, loader?, external?, tsconfig? }`
 
@@ -148,17 +167,17 @@ winning; arrays concatenated **after** the built-ins). The harness's own
 | key | merge behaviour |
 |---|---|
 | `plugins` | concatenated **after** the built-in `__CUT_MODULE__` resolver |
-| `inject` | concatenated after the `nodePolyfills` injects (if any) |
+| `inject` | concatenated after the `nodePolyfills` injects (the chosen builtins, if any) |
 | `define` / `alias` | shallow-merged, **consumer key wins** |
 | `loader` | merged **over** `{'.wasm':'copy'}` (e.g. add `{'.svg':'dataurl'}`) |
 | `external` | as given |
 | `tsconfig` | path to a tsconfig esbuild should honour |
 
-#### Node polyfills recipe (the common case)
+#### Doing it entirely by hand (no `nodePolyfills`)
 
-The quickest path is the `nodePolyfills` preset above. To do it by hand (or to
-extend it), alias `buffer` to the npm package and inject a `Buffer`/`process`
-shim via the escape hatch:
+`nodePolyfills` is just sugar for these three fragments. If you'd rather not use
+it at all (e.g. you want one custom shim module), alias `buffer` to the npm
+package and inject a `Buffer`/`process` shim purely via the escape hatch:
 
 ```ts
 const h = await mountHarness(page, {

package/dist/build.mjs

@@ -23,71 +23,128 @@ import { existsSync } from 'node:fs';
 const here = dirname(fileURLToPath(import.meta.url));
 
 /**
- * Build the `nodePolyfills` preset (esbuild fragments) for browser bundles of
- * web3/crypto code whose dependency trees reach for Node builtins.
+ * Explicit, composable Node-builtin polyfill fragments.
  *
- * Many EVM / crypto libraries (ethereumjs, tevm, anything pulling
- * `readable-stream`/`safe-buffer`) transitively `import 'buffer'` and touch
- * `process` / `global`, which esbuild's `platform:'browser'` will NOT resolve —
- * the bundle fails with `Could not resolve "buffer"`. This opt-in preset:
- *   - aliases `buffer` / `node:buffer` to the `buffer` npm package,
- *   - injects a `Buffer` global (so `Buffer.from(...)` works without an import),
- *   - shims a minimal `process` (`{env,browser,version,nextTick}`),
- *   - defines `global` → `globalThis`.
+ * There is intentionally NO catch-all "web3" preset: a named preset is a leaky
+ * abstraction — it would shim `buffer`/`process`/`global` but not
+ * `events`/`stream`/`util`/`crypto`, so consumers fall back to the `esbuild`
+ * escape-hatch anyway. Instead the harness exposes exactly the three builtins it
+ * can shim with zero opinions, and each maps to a self-contained fragment:
  *
- * `buffer` is an optional/peer dependency: the consumer installs it when they
- * opt in (and the harness's own ethereumjs fixture pulls it in for the test).
+ *   - 'buffer'  → alias `buffer`/`node:buffer` to the `buffer` npm package +
+ *                 inject a `Buffer` shim that also assigns `globalThis.Buffer`.
+ *   - 'process' → inject a minimal `process` stub `{env,browser,version,nextTick}`.
+ *   - 'global'  → define `{ global: 'globalThis' }`.
  *
- * @param {string} outdir directory to write the generated `process` shim into
- * @returns {Promise<{alias: Record<string,string>, inject: string[], define: Record<string,string>}>}
+ * Anything else (`events`, `stream`, `util`, `crypto`, …) is the consumer's job
+ * via the `esbuild: { alias, inject, define, plugins }` pass-through.
+ *
+ * Each helper returns an esbuild *fragment* (`{alias?, inject?, define?}`) so a
+ * consumer can compose them with their own esbuild opts. `buffer` is an
+ * optional/peer dependency: the consumer installs it when they opt into the
+ * `'buffer'` polyfill.
+ *
+ * @typedef {'buffer'|'process'|'global'} NodePolyfill
  */
-async function nodePolyfillsPreset(outdir) {
-  // Resolve the `buffer` npm package from the consumer's install. We resolve
-  // the *bare specifier* so esbuild aliases `buffer`/`node:buffer` to it.
-  // (We don't hard-require it here — esbuild will surface a clear error if the
-  // consumer enabled nodePolyfills without installing `buffer`.)
-  const bufferPkg = 'buffer';
-
-  // A tiny `process` shim written next to the bundle and injected as a global.
-  // Kept minimal on purpose: env bag, browser flag, empty version, and a
-  // microtask-based nextTick — enough for readable-stream/safe-buffer & friends.
-  const procShim = join(outdir, '__process-shim.js');
-  await writeFile(
-    procShim,
-    [
-      'const process = {',
-      '  env: {},',
-      '  browser: true,',
-      "  version: '',",
-      '  nextTick: (cb, ...args) => Promise.resolve().then(() => cb(...args)),',
-      '};',
-      'export { process };',
-      'export default process;',
-    ].join('\n'),
-  );
 
-  // A tiny module that re-exports `Buffer` from the `buffer` package so esbuild
-  // can `inject` it as the `Buffer` global. We ALSO assign it onto `globalThis`
-  // so libraries that reach for `globalThis.Buffer` / `window.Buffer` at runtime
-  // (not just an unqualified `Buffer` identifier) find it too. GOTCHA: esbuild's
-  // `inject` only provides a top-level *binding* in modules that reference the
-  // name — it does not set a real global — so this explicit assignment is what
-  // makes `globalThis.Buffer` truthy in-page.
-  const bufShim = join(outdir, '__buffer-shim.js');
-  await writeFile(
-    bufShim,
-    [
-      "import { Buffer } from 'buffer';",
-      'if (typeof globalThis !== "undefined" && !globalThis.Buffer) globalThis.Buffer = Buffer;',
-      'export { Buffer };',
-    ].join('\n'),
+/**
+ * Build a single Node-polyfill fragment by name. Self-contained: passing
+ * `'buffer'` shims ONLY buffer, etc. Unknown names throw with a clear message.
+ *
+ * @param {NodePolyfill} name which builtin to shim
+ * @param {string} outdir directory to write any generated shim modules into
+ * @returns {Promise<{alias?: Record<string,string>, inject?: string[], define?: Record<string,string>}>}
+ */
+export async function nodePolyfill(name, outdir) {
+  if (name === 'buffer') {
+    // Resolve the `buffer` npm package from the consumer's install via its bare
+    // specifier so esbuild aliases `buffer`/`node:buffer` to it. (We don't
+    // hard-require it here — esbuild surfaces a clear error if the consumer
+    // asked for the 'buffer' polyfill without installing `buffer`.)
+    const bufferPkg = 'buffer';
+    // A tiny module that re-exports `Buffer` from the `buffer` package so esbuild
+    // can `inject` it as the `Buffer` global. We ALSO assign it onto `globalThis`
+    // so libraries that reach for `globalThis.Buffer` / `window.Buffer` at
+    // runtime (not just an unqualified `Buffer` identifier) find it too. GOTCHA:
+    // esbuild's `inject` only provides a top-level *binding* in modules that
+    // reference the name — it does not set a real global — so this explicit
+    // assignment is what makes `globalThis.Buffer` truthy in-page.
+    const bufShim = join(outdir, '__buffer-shim.js');
+    await writeFile(
+      bufShim,
+      [
+        "import { Buffer } from 'buffer';",
+        'if (typeof globalThis !== "undefined" && !globalThis.Buffer) globalThis.Buffer = Buffer;',
+        'export { Buffer };',
+      ].join('\n'),
+    );
+    return {
+      alias: { buffer: bufferPkg, 'node:buffer': bufferPkg },
+      inject: [bufShim],
+    };
+  }
+
+  if (name === 'process') {
+    // A tiny `process` shim written next to the bundle and injected as a global.
+    // Kept minimal on purpose: env bag, browser flag, empty version, and a
+    // microtask-based nextTick — enough for readable-stream/safe-buffer & co.
+    const procShim = join(outdir, '__process-shim.js');
+    await writeFile(
+      procShim,
+      [
+        'const process = {',
+        '  env: {},',
+        '  browser: true,',
+        "  version: '',",
+        '  nextTick: (cb, ...args) => Promise.resolve().then(() => cb(...args)),',
+        '};',
+        'export { process };',
+        'export default process;',
+      ].join('\n'),
+    );
+    return { inject: [procShim] };
+  }
+
+  if (name === 'global') {
+    return { define: { global: 'globalThis' } };
+  }
+
+  throw new Error(
+    `nodePolyfill: unknown polyfill ${JSON.stringify(name)} — valid values are 'buffer', 'process', 'global'.`,
   );
+}
 
-  return {
-    alias: { buffer: bufferPkg, 'node:buffer': bufferPkg },
-    inject: [bufShim, procShim],
-    define: { global: 'globalThis' },
-  };
+/**
+ * The set of builtins the harness can shim itself, as a reusable/testable map of
+ * `name → (outdir) => fragment`. Exposed so a consumer can compose individual
+ * fragments with their own esbuild opts without going through `buildBundle`.
+ *
+ * @type {Record<NodePolyfill, (outdir: string) => Promise<{alias?: Record<string,string>, inject?: string[], define?: Record<string,string>}>>}
+ */
+export const nodePolyfills = {
+  buffer: (outdir) => nodePolyfill('buffer', outdir),
+  process: (outdir) => nodePolyfill('process', outdir),
+  global: (outdir) => nodePolyfill('global', outdir),
+};
+
+/**
+ * Compose the requested Node-polyfill fragments into a single
+ * `{alias, inject, define}` bundle. Order-stable; later entries' alias/define
+ * keys win on clash (none do today since the three fragments are disjoint).
+ *
+ * @param {NodePolyfill[]} names
+ * @param {string} outdir
+ * @returns {Promise<{alias: Record<string,string>, inject: string[], define: Record<string,string>}>}
+ */
+async function composeNodePolyfills(names, outdir) {
+  const out = { alias: {}, inject: [], define: {} };
+  for (const name of names) {
+    const frag = await nodePolyfill(name, outdir);
+    if (frag.alias) Object.assign(out.alias, frag.alias);
+    if (frag.inject) out.inject.push(...frag.inject);
+    if (frag.define) Object.assign(out.define, frag.define);
+  }
+  return out;
 }
 
 /**
@@ -99,10 +156,13 @@ async function nodePolyfillsPreset(outdir) {
  * @param {string[]} [opts.assets]  explicit absolute file paths to copy verbatim
  *   into outdir (e.g. sqlite3-opfs-async-proxy.js, which the OPFS VFS spawns by
  *   URL relative to the worker bundle and esbuild does NOT trace).
- * @param {boolean|'web3'} [opts.nodePolyfills] opt-in Node-builtin polyfills for
- *   web3/crypto code (aliases `buffer`/`node:buffer`, injects `Buffer`, shims
- *   `process`, defines `global`). Default off. `true` and `'web3'` are
- *   equivalent today (the string leaves room for future presets).
+ * @param {Array<'buffer'|'process'|'global'>} [opts.nodePolyfills] explicit,
+ *   composable list of Node builtins the harness shims itself. `['buffer']`
+ *   shims ONLY buffer; `[]` or omitted = nothing. Each entry is self-contained:
+ *   'buffer' aliases `buffer`/`node:buffer` + injects a `Buffer` global,
+ *   'process' injects a minimal `process` stub, 'global' defines
+ *   `{global:'globalThis'}`. There is NO catch-all preset; everything beyond
+ *   these three (events, stream, util, crypto, …) goes through `opts.esbuild`.
  * @param {object} [opts.esbuild] esbuild pass-through merged into the internal
  *   build. Consumer values take precedence; arrays are concatenated AFTER the
  *   built-ins so the `__CUT_MODULE__` resolver, the page-entry entry point, and
@@ -121,9 +181,16 @@ export async function buildBundle({
   worker,
   wasmDirs = [],
   assets = [],
-  nodePolyfills = false,
+  nodePolyfills = [],
   esbuild: esbuildOpts = {},
 }) {
+  if (!Array.isArray(nodePolyfills)) {
+    throw new TypeError(
+      `buildBundle: \`nodePolyfills\` must be an array of 'buffer' | 'process' | 'global' ` +
+        `(got ${JSON.stringify(nodePolyfills)}). The 0.2.0 \`true\`/'web3' form was removed; ` +
+        `migrate to e.g. ['buffer','process','global'].`,
+    );
+  }
   await rm(outdir, { recursive: true, force: true });
   await mkdir(outdir, { recursive: true });
 
@@ -139,10 +206,13 @@ export async function buildBundle({
     },
   };
 
-  // Opt-in Node-builtin polyfill preset (default off). Produces alias/inject/
-  // define fragments that are merged UNDER the consumer's explicit esbuild opts
-  // (so the consumer can still override any specific key).
-  const preset = nodePolyfills ? await nodePolyfillsPreset(outdir) : null;
+  // Compose the explicitly-requested Node-builtin polyfill fragments (default
+  // none). Produces alias/inject/define merged UNDER the consumer's explicit
+  // esbuild opts (so the consumer can still override any specific key).
+  const preset =
+    nodePolyfills.length > 0
+      ? await composeNodePolyfills(nodePolyfills, outdir)
+      : null;
 
   const {
     plugins: userPlugins = [],
@@ -162,7 +232,7 @@ export async function buildBundle({
     target: 'es2022',
     platform: 'browser',
     sourcemap: true,
-    // Merge order: built-ins → preset → consumer. Consumer wins on key clashes
+    // Merge order: built-ins → polyfills → consumer. Consumer wins on key clashes
     // (define/alias/loader) and runs last (plugins). Arrays are concatenated.
     plugins: [cutResolver, ...userPlugins],
     inject: [...(preset?.inject ?? []), ...userInject],

package/dist/driver.d.ts

@@ -55,7 +55,7 @@ export interface MountOptions {
     entry?: string;
     /**
      * Skip esbuild entirely and treat `cut`/`entry` as a prebuilt `.js` module
-     * (see `entry`). Default `false` (the esbuild path). `worker`/`nodePolyfills`/
+     * (see `entry`). Default `false` (the esbuild path). `worker` / `nodePolyfills` /
      * `esbuild` options are ignored in this mode.
      */
     noBundle?: boolean;
@@ -69,23 +69,40 @@ export interface MountOptions {
      *  async proxy js). */
     assets?: string[];
     /**
-     * Opt-in Node-builtin polyfills for browser bundles of web3 / crypto code
-     * (ethereumjs, tevm, anything pulling `readable-stream` / `safe-buffer`).
-     * Default **off** — existing consumers are unaffected.
+     * Explicit, composable Node-builtin polyfills. Declare exactly what your
+     * code-under-test needs — there is **no** catch-all preset. Default `[]`
+     * (nothing); omitted is the same as `[]`.
      *
-     * When enabled it aliases `buffer` / `node:buffer` to the `buffer` npm
-     * package, injects a `Buffer` global, shims a minimal `process`
-     * (`{ env: {}, browser: true, version: '', nextTick }`), and sets
-     * `define: { global: 'globalThis' }`. Requires the optional `buffer`
-     * dependency to be installed. `true` and `'web3'` are equivalent today.
+     * The three builtins the harness can shim itself (with zero opinions):
+     *   - `'buffer'`  — alias `buffer` / `node:buffer` to the [`buffer`] npm
+     *     package and inject a `Buffer` global (also assigned onto `globalThis`).
+     *     Requires the optional `buffer` peer dependency to be installed.
+     *   - `'process'` — inject a minimal `process` stub
+     *     (`{ env: {}, browser: true, version: '', nextTick }`).
+     *   - `'global'`  — set `define: { global: 'globalThis' }`.
+     *
+     * Each entry is self-contained: `['buffer']` shims ONLY buffer and does NOT
+     * touch `process` or `global`. Anything beyond these three (`events`,
+     * `stream`, `util`, `crypto`, …) is your job via `esbuild.{alias,inject,
+     * define,plugins}` below.
+     *
+     * web3 / crypto trees (ethereumjs, tevm, anything pulling `readable-stream` /
+     * `safe-buffer`) typically want `['buffer','process','global']` plus an
+     * `esbuild.alias` for `events`/`stream`. See README "Explicit Node polyfills".
+     *
+     * **Migration from 0.2.0:** the old `true` / `'web3'` form was removed (clean
+     * break — 0.2.0 had ~no users). Replace `true`/`'web3'` with
+     * `['buffer','process','global']`.
+     *
+     * [`buffer`]: https://www.npmjs.com/package/buffer
      */
-    nodePolyfills?: boolean | 'web3';
+    nodePolyfills?: Array<'buffer' | 'process' | 'global'>;
     /**
      * esbuild pass-through merged into the harness's internal browser build.
      * Consumer values take precedence; arrays are concatenated AFTER the
      * built-ins, so the `__CUT_MODULE__` resolver and the `.wasm` copy loader
      * always remain. Combine with `nodePolyfills` for web3 code that still needs
-     * an extra alias/define.
+     * extra builtins (e.g. `alias: { events: 'events', stream: 'stream-browserify' }`).
      */
     esbuild?: {
         plugins?: import('esbuild').Plugin[];

package/dist/driver.js

@@ -47,7 +47,7 @@ export async function mountHarness(page, opts) {
             worker: opts.worker,
             wasmDirs: opts.wasmDirs ?? [],
             assets: opts.assets ?? [],
-            nodePolyfills: opts.nodePolyfills ?? false,
+            nodePolyfills: opts.nodePolyfills ?? [],
             esbuild: opts.esbuild ?? {},
         });
         const srv = await startServer({ root: outdir, coi: opts.coi ?? true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-browser-harness",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Playwright harness that bundles your code, serves it under a COOP/COEP-toggleable server, drives it in a real browser, and returns structured results/timings — for testing real browser-storage persistence (IndexedDB/OPFS), cross-origin isolation, Workers, and perf that Node can't fake. Importable machinery + a tiny `init` CLI for the per-project files.",
   "license": "MIT",