@specific.dev/spectest 0.68.0 → 0.70.0

package/dist/harness/tls-terminator.js

@@ -0,0 +1,199 @@
+/**
+ * The :443 TLS terminator — one listener, for the life of the harness.
+ *
+ * ## Why this exists
+ *
+ * Ingress certificates are minted *while tests run*: a fake that
+ * provisions a database hands the app a CA-trusted `https://<new-host>/`
+ * endpoint, and that hostname did not exist a second earlier. Bun fixes a
+ * server's TLS configuration at `Bun.serve` time — `reload({ tls })` is
+ * accepted and then ignored (re-measured on Bun 1.4.0: the added
+ * `serverName` still gets the first entry's leaf) — so for as long as
+ * :443 was a `Bun.serve`, every new certificate meant swapping the
+ * listener.
+ *
+ * **No listener swap can be made safe.** Binding the replacement first
+ * under SO_REUSEPORT and draining the original with `stop(false)` saves a
+ * request that is already *in flight*, and that is all it saves: measured
+ * on Bun 1.4.0, `stop(false)` sends FIN to an **idle kept-alive
+ * connection within 1–2 ms**. A client that writes a request into that
+ * socket in the same instant gets `SocketError: other side closed`
+ * (`UND_ERR_SOCKET` under undici), and Node's `fetch` does not retry it.
+ * That is a flake in whatever unrelated test happened to be talking
+ * through the ingress — never in the one that provisioned the service —
+ * and it is why the app under test would die far from any ingress code.
+ *
+ * So the listener must stop being swapped, which means the certificate
+ * must be chosen **per handshake** rather than baked into the socket.
+ * That is what every real server does, and under Bun it is reachable
+ * through `node:tls`'s `SNICallback` (verified working on Bun 1.4.0:
+ * adding an entry to the table is served on the next handshake, with no
+ * restart and no effect on any established connection).
+ *
+ * ## The shape, and why it is a byte pipe
+ *
+ * The terminator does TLS and *nothing else*: it accepts on :443, picks a
+ * leaf by SNI, and pipes the decrypted stream to a plaintext `Bun.serve`
+ * bound on loopback. Everything downstream — routing, fakes,
+ * interceptors, reverse-proxying, and `server.upgrade()` WebSocket
+ * bridging — is the same `Bun.serve` code that already serves :80, run
+ * unchanged. Terminating HTTP here instead (`node:https`, `(req, res)`)
+ * would have meant reimplementing the WebSocket bridge against a
+ * different API, which is exactly the kind of trade this change exists to
+ * avoid: one flake removed, another introduced somewhere subtler.
+ *
+ * Measured cost of the extra hop on this host (Bun 1.4.0, undici client,
+ * 50 MB bodies): ~11 % fewer small requests per second, download
+ * throughput unchanged, upload ~500 MB/s against ~800 MB/s direct. Ingress
+ * traffic in a test VM is nowhere near either bound.
+ *
+ * ## Recovering the client's address
+ *
+ * The plaintext server's peer is the terminator, so `server.requestIP()`
+ * reports loopback and `x-forwarded-for` would lose the caller. The
+ * upstream socket's *source port* is unique among live connections, so the
+ * terminator records `source port → real client address` for the life of
+ * each connection and {@link TlsTerminator.clientIpFor} hands it back.
+ * Verified end to end: a client connecting from 127.0.0.2 is reported as
+ * 127.0.0.2 by the plaintext server behind the pipe.
+ */
+import net from "node:net";
+import tls from "node:tls";
+/**
+ * Start the terminator. Resolves once :443 is accepting, so a caller can
+ * register the hostname in DNS immediately afterwards and know the port is
+ * live.
+ */
+/**
+ * Is this the ordinary end of a connection rather than a fault? A peer
+ * that goes away mid-stream, or a half-finished handshake, is routine on a
+ * listener that fronts browsers.
+ */
+function isRoutineDisconnect(err) {
+    const code = err?.code;
+    return (code === "ECONNRESET" ||
+        code === "EPIPE" ||
+        code === "ERR_STREAM_PREMATURE_CLOSE" ||
+        code === "ECONNABORTED");
+}
+export function startTlsTerminator(opts) {
+    // Parsing a PEM into a SecureContext is the expensive half of choosing a
+    // certificate, and the table is stable — cache by the certificate's own
+    // bytes so a handshake is a Map lookup. Keyed on the PEM rather than the
+    // hostname so a re-minted leaf for the same name cannot be served stale.
+    const contexts = new Map();
+    const contextFor = (leaf) => {
+        let ctx = contexts.get(leaf.cert);
+        if (!ctx) {
+            ctx = tls.createSecureContext({ cert: leaf.cert, key: leaf.key });
+            contexts.set(leaf.cert, ctx);
+        }
+        return ctx;
+    };
+    const warn = (message, err) => {
+        // A client hanging up is not a fault, and this listener carries every
+        // browser in the VM: Chromium opens speculative connections and drops
+        // them, a fetch is abandoned when its test ends, and each of those
+        // arrives here as a reset. Logging them would bury the boot log a user
+        // reads with `spectest env logs` in noise that means nothing.
+        if (isRoutineDisconnect(err))
+            return;
+        if (opts.onWarning)
+            opts.onWarning(message, err);
+        // eslint-disable-next-line no-console
+        else
+            console.warn(`[ingress] ${message}:`, err);
+    };
+    /** upstream source port → the address the TLS client connected from. */
+    const clientIpByUpstreamPort = new Map();
+    const live = new Set();
+    // A default leaf is only ever used for a client that sends no SNI at
+    // all; `SNICallback` decides every other handshake. This mirrors what
+    // Bun did with the first entry of its `tls` array.
+    const fallback = opts.certFor(undefined);
+    const server = tls.createServer({
+        ...(fallback ? { cert: fallback.cert, key: fallback.key } : {}),
+        SNICallback: (serverName, cb) => {
+            const leaf = opts.certFor(serverName) ?? fallback;
+            // No certificate at all is a handshake we cannot complete. Answer
+            // with the fallback context rather than an error so the client
+            // gets a certificate-mismatch alert it can report, which is the
+            // same thing it saw when Bun served the first entry.
+            cb(null, leaf ? contextFor(leaf) : undefined);
+        },
+    }, (client) => {
+        // No idle timeout anywhere on the ingress path: it fronts app
+        // endpoints that legitimately take minutes (a deploy), and a
+        // timeout here would surface as a truncated response with no
+        // explanation.
+        client.setTimeout(0);
+        live.add(client);
+        // Nothing reads from `client` until `pipe` below, so a socket that
+        // is written to before the upstream is connected stays paused and
+        // its bytes are buffered rather than dropped — which is the normal
+        // case, since a client sends its first request the instant the
+        // handshake completes.
+        const upstream = net.connect(opts.upstreamPort, "127.0.0.1");
+        upstream.setTimeout(0);
+        upstream.setNoDelay(true);
+        client.setNoDelay(true);
+        let recordedPort;
+        upstream.on("connect", () => {
+            recordedPort = upstream.localPort;
+            if (recordedPort !== undefined && client.remoteAddress) {
+                clientIpByUpstreamPort.set(recordedPort, client.remoteAddress);
+            }
+            // `pipe` carries backpressure and the half-close in both
+            // directions, which is what a WebSocket bridge and a streamed
+            // upload each need.
+            client.pipe(upstream);
+            upstream.pipe(client);
+        });
+        const teardown = () => {
+            if (recordedPort !== undefined)
+                clientIpByUpstreamPort.delete(recordedPort);
+            live.delete(client);
+            client.destroy();
+            upstream.destroy();
+        };
+        client.on("error", (err) => {
+            warn("tls client connection failed", err);
+            teardown();
+        });
+        upstream.on("error", (err) => {
+            warn(`ingress upstream :${opts.upstreamPort} failed`, err);
+            teardown();
+        });
+        client.on("close", teardown);
+        upstream.on("close", teardown);
+    });
+    // A client that aborts mid-handshake, or offers a protocol version we
+    // do not speak, emits this. It must be handled: an unhandled 'error' on
+    // a net server is thrown, and taking the daemon down over one bad
+    // handshake would be a far worse failure than the one being fixed.
+    server.on("tlsClientError", (err) => warn("tls handshake failed", err));
+    server.on("error", (err) => warn(`tls listener :${opts.port} failed`, err));
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port, opts.hostname, () => {
+            server.removeListener("error", reject);
+            resolve({
+                port: opts.port,
+                clientIpFor: (upstreamPort) => upstreamPort === undefined ? undefined : clientIpByUpstreamPort.get(upstreamPort),
+                connectionCount: () => live.size,
+                close: () => {
+                    try {
+                        server.close();
+                    }
+                    catch (err) {
+                        warn("closing the tls listener failed", err);
+                    }
+                    for (const sock of [...live])
+                        sock.destroy();
+                    live.clear();
+                    clientIpByUpstreamPort.clear();
+                },
+            });
+        });
+    });
+}

package/dist/index.js

@@ -713,7 +713,7 @@ function buildLocatorMatchers(loc, negated, message) {
         // The last error a probe threw, kept for the failure message: a matcher
         // whose read waits for the element (textContent, inputValue, isEnabled …)
         // reports a missing element as a playwright timeout, and that — not
-        // "got <error: Timeout 5000ms exceeded …>" — is the sentence to fail with.
+        // "got <error: Timeout 10000ms exceeded …>" — is the sentence to fail with.
         let probeError;
         for (;;) {
             let satisfied;
@@ -753,8 +753,8 @@ function buildLocatorMatchers(loc, negated, message) {
             }
             if (Date.now() >= deadline) {
                 // The deadline, not the stopwatch: every one of these polled until it
-                // ran out, and "(waited 5s)" is both what the author set and the same
-                // number twice in a row — a measured 4_987ms is neither.
+                // ran out, and "(waited 10s)" is both what the author set and the same
+                // number twice in a row — a measured 9_987ms is neither.
                 const msg = (await elementFailure(probeError)) ??
                     `${describe(actual)} (waited ${formatWaited(budget)})`;
                 const sourceSeq = await probe.settle(matcher, Date.now() - started, msg, settleOpts);

package/dist/locator-errors.js

@@ -1,7 +1,7 @@
 // Readable failures for locator steps.
 //
 // Playwright reports every unmet actionability wait the same way: a
-// `TimeoutError` whose message is "Timeout 5000ms exceeded." with the real
+// `TimeoutError` whose message is "Timeout 10000ms exceeded." with the real
 // story — did the element exist at all? was it disabled? did something cover
 // it? — buried in a call log below it. A test that clicks a button that is not
 // on the page therefore fails with a sentence about OUR deadline, which reads

package/dist/locator.d.ts

@@ -3,11 +3,16 @@ import type { RecordableFields } from "./browser.js";
 import type { Wrapped } from "./inspect.js";
 import { type HintTarget } from "./locator-hints.js";
 /** Default deadline for a locator action/read's target to become actionable.
- *  Playwright's own default is 30s — far too slow-failing for tests; 5s
- *  matches the pre-Playwright behavior. A per-call `{ timeout }` overrides it;
- *  `undefined` falls through to the context default (also set to this in
- *  browser.ts's `newViewContext`). Navigations keep a longer deadline. */
-export declare const DEFAULT_ACTION_TIMEOUT_MS = 5000;
+ *  Playwright's own default is 30s — far too slow-failing for tests. This was
+ *  5s (the pre-Playwright behavior) until 2026-09-03, and 5s turned out to be
+ *  about one page load: a real app under a full VM fan-out took 1.8-2.0s for a
+ *  full navigation plus its client data chain on a quiet box, and 4x that on
+ *  the tail, so a step that was correct and merely late failed. 10s still
+ *  fails fast enough to be useful and leaves room for the tail. A per-call
+ *  `{ timeout }` overrides it; `undefined` falls through to the context
+ *  default (also set to this in browser.ts's `newViewContext`). Navigations
+ *  keep a longer deadline. */
+export declare const DEFAULT_ACTION_TIMEOUT_MS = 10000;
 export interface GetByTextOptions {
     /** Whole-string, case-sensitive match instead of the default
      *  case-insensitive substring. Ignored when the query is a RegExp. */

package/dist/locator.js

@@ -27,11 +27,16 @@ import { formatHints, nearMissHints } from "./locator-hints.js";
 import { resolveExistingProjectPath } from "./project-files.js";
 import { truncateUtf8 } from "./recorder.js";
 /** Default deadline for a locator action/read's target to become actionable.
- *  Playwright's own default is 30s — far too slow-failing for tests; 5s
- *  matches the pre-Playwright behavior. A per-call `{ timeout }` overrides it;
- *  `undefined` falls through to the context default (also set to this in
- *  browser.ts's `newViewContext`). Navigations keep a longer deadline. */
-export const DEFAULT_ACTION_TIMEOUT_MS = 5_000;
+ *  Playwright's own default is 30s — far too slow-failing for tests. This was
+ *  5s (the pre-Playwright behavior) until 2026-09-03, and 5s turned out to be
+ *  about one page load: a real app under a full VM fan-out took 1.8-2.0s for a
+ *  full navigation plus its client data chain on a quiet box, and 4x that on
+ *  the tail, so a step that was correct and merely late failed. 10s still
+ *  fails fast enough to be useful and leaves room for the tail. A per-call
+ *  `{ timeout }` overrides it; `undefined` falls through to the context
+ *  default (also set to this in browser.ts's `newViewContext`). Navigations
+ *  keep a longer deadline. */
+export const DEFAULT_ACTION_TIMEOUT_MS = 10_000;
 // Brand + chain carrier. Both are `Symbol.for` keys so `JSON.stringify` drops
 // them (locators are never serialized) while runtime code can still detect a
 // locator and read a nested one's chain during lowering.
@@ -401,7 +406,7 @@ export function makeLocator(backend, strategy, chain) {
         return formatHints(await nearMissHints(page, target));
     };
     // Every terminal op runs through this: playwright's actionability timeouts
-    // say "Timeout 5000ms exceeded" and hide what actually went wrong in a call
+    // say "Timeout 10000ms exceeded" and hide what actually went wrong in a call
     // log, so they are rewritten into a sentence naming the element and its
     // state (see locator-errors.ts), and a failure that found NO element asks
     // the page what it does hold. Applied INSIDE `pageOp`, so the recorded step

package/dist/terminal.js

@@ -28,6 +28,9 @@
 import { Terminal as XtermHeadless } from "@xterm/headless";
 import { recordTerminalStep, reserveEvent, truncateUtf8 } from "./recorder.js";
 import { wrap } from "./inspect.js";
+// One default deadline for "wait until the app shows it", whichever surface
+// the author is watching — see the constant for why it is what it is.
+import { DEFAULT_ACTION_TIMEOUT_MS } from "./locator.js";
 // Cap on cumulative output we keep in memory. The asciicast frames
 // grow separately (they live on the session record) and aren't bounded
 // here. Matches `TERMINAL_OUTPUT_CAP_BYTES` in daemon.ts.
@@ -421,7 +424,7 @@ export async function openTerminal(args) {
             return renderScreen();
         },
         async waitFor(description, matcher, waitOpts) {
-            const timeoutMs = waitOpts?.timeoutMs ?? 5_000;
+            const timeoutMs = waitOpts?.timeoutMs ?? DEFAULT_ACTION_TIMEOUT_MS;
             const intervalMs = waitOpts?.intervalMs ?? 100;
             const t = Date.now();
             const resv = reserveEvent();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.68.0",
+  "version": "0.70.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser.ts

@@ -1943,7 +1943,7 @@ function buildBackend(
       arg?: unknown,
       options: { timeout?: number; polling?: number } = {},
     ): Promise<Wrapped<T>> {
-      const timeoutMs = options.timeout ?? 5_000;
+      const timeoutMs = options.timeout ?? DEFAULT_ACTION_TIMEOUT_MS;
       const intervalMs = options.polling ?? 100;
       const src = typeof fn === "string" ? fn : fn.toString();
       const t = truncateUtf8(src);