tape-six 1.11.0 → 1.13.0

package/README.md

@@ -427,6 +427,8 @@ Test output can be controlled by flags. See [Supported flags](https://github.com
 
 The most recent releases:
 
+- 1.13.0 _TypeScript declarations for the `EventServer`._
+- 1.12.0 _`tape6-server` is now pluggable, embeddable server for hermetic integration tests, runtime plugin registration, and an opt-in HTTP/2 mode._
 - 1.11.0 _Invariant host hooks for the new zero-dependency `tape-six-invariant` companion package. Workaround for a Deno 2.9.0 `node_modules/.bin` symlink regression._
 - 1.10.1 _A workaround for a Bun's bug with streams._
 - 1.10.0 _Worker control channel stops in-flight workers, draining cleanup before a force-kill._

package/TESTING.md

@@ -649,7 +649,7 @@ In this example, running `tape6` on Node will execute tests matching `/tests/nod
 
 ## Browser testing
 
-Browser tests use `tape6-server`, a static file server bundled with `tape-six` that provides a web UI for running tests.
+Browser tests use `tape6-server`, a pluggable test server bundled with `tape-six` that serves static files and provides a web UI for running tests. Fixture plugins can be mounted under URL prefixes (`--plugin`, the `tape6.server.plugins` config, or `PUT /--plugins` at runtime), the core is embeddable in tests via `createTestServer()` from `tape-six/test-server.js`, and `--h2` switches to HTTP/2 (Node-only). See the [tape6-server wiki page](https://github.com/uhop/tape-six/wiki/Utility-%E2%80%90-tape6%E2%80%90server) for the plugin contract.
 
 ### Setup
 

package/bin/tape6-server.js

@@ -1,26 +1,11 @@
 #!/usr/bin/env node
 
-import http from 'node:http';
-import fs from 'node:fs';
-import path from 'node:path';
 import process from 'node:process';
 import {fileURLToPath} from 'node:url';
 
-import {
-  getConfig,
-  resolveTests,
-  resolvePatterns,
-  printVersion,
-  printHelp
-} from '../src/utils/config.js';
-import {startServer} from '../src/server.js';
-
-const fsp = fs.promises;
-
-const toPosix = files =>
-  path.sep === path.win32.sep
-    ? files.map(f => f.replaceAll(path.win32.sep, path.posix.sep))
-    : files;
+import {printVersion, printHelp} from '../src/utils/config.js';
+import {createTestServer} from '../src/test-server.js';
+import {detectColors, makePaint} from '../src/test-server/trace.js';
 
 const showSelf = () => {
   const self = new URL(import.meta.url);
@@ -32,17 +17,23 @@ const showSelf = () => {
   process.exit(0);
 };
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
-  printHelp('tape6-server', 'Static file server for browser testing', 'tape6-server [options]', [
+  printHelp('tape6-server', 'Pluggable test server for browser testing', 'tape6-server [options]', [
+    ['--plugin path', 'Register a plugin module (repeatable)'],
+    ['--h2', 'Serve HTTPS with HTTP/2 (+ HTTP/1.1 via ALPN); Node only'],
+    ['--no-remote-plugins', 'Disable PUT/DELETE on /--plugins'],
     ['--trace', 'Enable request trace logging'],
     ['--self', 'Print the path to this script and exit'],
     ['--help, -h', 'Show this help message and exit'],
     ['--version, -v', 'Show version and exit']
   ]);
   console.log('\nEnvironment:');
-  console.log('  HOST          Server hostname (default: localhost)');
-  console.log('  PORT          Server port (default: 3000)');
-  console.log('  SERVER_ROOT   Root directory for serving files (default: cwd)');
-  console.log('  WEBAPP_PATH   Path to the web app directory');
+  console.log('  HOST            Server hostname (default: localhost)');
+  console.log('  PORT            Server port (default: 3000)');
+  console.log('  SERVER_ROOT     Root directory for serving files (default: cwd)');
+  console.log('  WEBAPP_PATH     Path to the web app directory');
+  console.log('  TAPE6_PROTOCOL  Protocol: h1 or h2 (default: h1)');
+  console.log('  TAPE6_CERT      Path to a TLS certificate (h2)');
+  console.log('  TAPE6_KEY       Path to its private key (h2)');
   process.exit(0);
 }
 if (process.argv.includes('--version') || process.argv.includes('-v')) {
@@ -51,198 +42,79 @@ if (process.argv.includes('--version') || process.argv.includes('-v')) {
 }
 if (process.argv.includes('--self')) showSelf();
 
-const mimeTable = {
-    css: 'text/css',
-    csv: 'text/csv',
-    eot: 'application/vnd.ms-fontobject',
-    gif: 'image/gif',
-    html: 'text/html',
-    ico: 'image/vnd.microsoft.icon',
-    jpg: 'image/jpeg',
-    js: 'text/javascript',
-    json: 'application/json',
-    otf: 'font/otf',
-    png: 'image/png',
-    svg: 'image/svg+xml',
-    ttf: 'font/ttf',
-    txt: 'text/plain',
-    webp: 'image/webp',
-    woff: 'font/woff',
-    woff2: 'font/woff2',
-    xml: 'application/xml'
-  },
-  defaultMime = 'application/octet-stream',
-  rootFolder = process.env.SERVER_ROOT || process.cwd(),
-  traceCalls = process.argv.includes('--trace'),
-  hasColors =
-    process.stdout.isTTY &&
-    (typeof process.stdout.hasColors == 'function' ? process.stdout.hasColors() : true);
-
-let webAppPath = process.env.WEBAPP_PATH;
-if (!webAppPath) {
-  const url = import.meta.url;
-  if (!/^file:\/\//i.test(url))
-    throw Error('Cannot identify the location of the web application. Use WEBAPP_PATH.');
-  webAppPath = path.relative(
-    rootFolder,
-    path.join(path.dirname(fileURLToPath(url)), '../web-app/')
-  );
-  if (path.sep === path.win32.sep)
-    webAppPath = webAppPath.replaceAll(path.win32.sep, path.posix.sep);
-}
-
-const mimeAliases = {mjs: 'js', cjs: 'js', htm: 'html', jpeg: 'jpg'};
-Object.keys(mimeAliases).forEach(name => (mimeTable[name] = mimeTable[mimeAliases[name]]));
-
-const join = (...args) => args.map(value => value || '').join(''),
-  paint = hasColors
-    ? (prefix, suffix = '\x1B[39m') =>
-        text =>
-          join(prefix, text, suffix)
-    : () => text => text,
-  grey = paint('\x1B[2;37m', '\x1B[22;39m'),
-  red = paint('\x1B[41;97m', '\x1B[49;39m'),
-  green = paint('\x1B[32m'),
-  yellow = paint('\x1B[93m'),
-  blue = paint('\x1B[44;97m', '\x1B[49;39m');
-
-const link = (url, text = url) => paint('\x1B]8;;' + url + '\x1B\\', '\x1B]8;;\x1B\\')(text);
-
-const sendFile = (req, res, fileName, ext, justHeaders) => {
-  if (!ext) {
-    ext = path.extname(fileName).toLowerCase();
-  }
-  let mime = ext && mimeTable[ext.substring(1)];
-  if (!mime || typeof mime != 'string') {
-    mime = defaultMime;
-  }
-  res.writeHead(200, {'Content-Type': mime});
-  if (justHeaders) {
-    res.end();
-  } else {
-    fs.createReadStream(fileName).pipe(res);
-  }
-  traceCalls && console.log(green('200') + ' ' + grey(req.method) + ' ' + grey(req.url));
-};
-
-const sendJson = (req, res, json, justHeaders) => {
-  res.writeHead(200, {'Content-Type': 'application/json'});
-  if (justHeaders) {
-    res.end();
-  } else {
-    res.end(JSON.stringify(json));
-  }
-  traceCalls && console.log(green('200') + ' ' + grey(req.method) + ' ' + grey(req.url));
-};
-
-const sendRedirect = (req, res, to, code = 307) => {
-  res.writeHead(code, {Location: to});
-  res.end();
-  traceCalls && console.log(blue(code) + ' ' + grey(req.method) + ' ' + grey(req.url));
-};
-
-const bailOut = (req, res, code = 404) => {
-  res.writeHead(code).end();
-  traceCalls && console.log(red(code) + ' ' + grey(req.method) + ' ' + grey(req.url));
-};
-
-const server = http.createServer(async (req, res) => {
-  const method = req.method.toUpperCase();
-  if (method !== 'GET' && method !== 'HEAD') return bailOut(req, res, 405);
-
-  const url = new URL(req.url, 'http://' + req.headers.host);
-  if (url.pathname === '/--tests') {
-    return sendJson(
-      req,
-      res,
-      toPosix(await resolveTests(rootFolder, 'browser')),
-      method === 'HEAD'
-    );
-  }
-  if (url.pathname === '/--patterns') {
-    return sendJson(
-      req,
-      res,
-      toPosix(await resolvePatterns(rootFolder, url.searchParams.getAll('q'))),
-      method === 'HEAD'
-    );
-  }
-  if (url.pathname === '/--importmap') {
-    const cfg = await getConfig(rootFolder);
-    return sendJson(req, res, cfg.importmap || {imports: {}}, method === 'HEAD');
-  }
-  if (url.pathname === '/favicon.ico') {
-    const faviconFile = path.join(rootFolder, webAppPath, 'favicon.ico');
-    const stat = await fsp.stat(faviconFile).catch(() => null);
-    if (stat && stat.isFile()) return sendFile(req, res, faviconFile, '.ico', method === 'HEAD');
-    return bailOut(req, res);
-  }
-  if (url.pathname === '/' || url.pathname === '/index' || url.pathname === '/index.html') {
-    url.pathname = webAppPath;
-    return sendRedirect(req, res, url.href);
-  }
-
-  if (path.normalize(url.pathname).includes('..')) return bailOut(req, res, 403);
-
-  const fileName = path.join(rootFolder, url.pathname),
-    ext = path.extname(fileName).toLowerCase(),
-    stat = await fsp.stat(fileName).catch(() => null);
-  if (stat && stat.isFile()) return sendFile(req, res, fileName, ext, method === 'HEAD');
-
-  if (stat && stat.isDirectory()) {
-    if (fileName.length && fileName[fileName.length - 1] == path.sep) {
-      const altFile = path.join(fileName, 'index.html'),
-        stat = await fsp.stat(altFile).catch(() => null);
-      if (stat && stat.isFile()) return sendFile(req, res, altFile, '.html', method === 'HEAD');
-    } else {
-      url.pathname += path.posix.sep;
-      return sendRedirect(req, res, url.href);
+const plugins = [];
+let traceCalls = false,
+  h2 = false,
+  remotePlugins = true;
+{
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; ++i) {
+    const arg = args[i];
+    if (arg === '--trace') {
+      traceCalls = true;
+    } else if (arg === '--h2') {
+      h2 = true;
+    } else if (arg === '--no-remote-plugins') {
+      remotePlugins = false;
+    } else if (arg === '--plugin') {
+      if (++i < args.length) plugins.push(args[i]);
+    } else if (arg.startsWith('--plugin=')) {
+      plugins.push(arg.substring('--plugin='.length));
     }
-    return bailOut(req, res);
-  }
-
-  if (!ext && fileName.length && fileName[fileName.length - 1] != path.sep) {
-    const altFile = fileName + '.html',
-      stat = await fsp.stat(altFile).catch(() => null);
-    if (stat && stat.isFile()) return sendFile(req, res, altFile, '.html', method === 'HEAD');
   }
-
-  bailOut(req, res);
-});
-
-server.on('clientError', (error, socket) => {
-  if (error.code === 'ECONNRESET' || !socket.writable) return;
-  socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
-});
+}
 
 const normalizePort = val => {
   const port = parseInt(val);
   if (isNaN(port)) return val; // named pipe
-  if (port >= 0) return port; // port number
+  if (port >= 0) return port;
   return false;
 };
 
 const portToString = port => (typeof port === 'string' ? 'pipe' : 'port') + ' ' + port;
 
 const host = process.env.HOST || 'localhost',
-  port = normalizePort(process.env.PORT || '3000');
+  port = normalizePort(process.env.PORT || '3000'),
+  rootFolder = process.env.SERVER_ROOT || process.cwd(),
+  protocol = h2 ? 'h2' : process.env.TAPE6_PROTOCOL || undefined;
+
+const hasColors = detectColors(),
+  paint = makePaint(hasColors),
+  grey = paint('\x1B[2;37m', '\x1B[22;39m'),
+  red = paint('\x1B[41;97m', '\x1B[49;39m'),
+  yellow = paint('\x1B[93m');
+
+const link = (url, text = url) => paint('\x1B]8;;' + url + '\x1B\\', '\x1B]8;;\x1B\\')(text);
 
 try {
-  await startServer(server, {host, port});
-  const bind = portToString(port);
+  const testServer = await createTestServer({
+    rootFolder,
+    webAppPath: process.env.WEBAPP_PATH,
+    host,
+    port,
+    protocol,
+    plugins,
+    remotePlugins,
+    trace: traceCalls
+  });
+  const bind = portToString(testServer.port);
   console.log(
     grey('Listening on ') +
       yellow(host || 'all network interfaces') +
+      yellow(' (' + testServer.protocol + ')') +
       grey(' at ') +
       yellow(bind) +
       grey(', serving static files from ') +
       yellow(rootFolder)
   );
-  if (host && bind) {
+  const mounted = testServer.plugins();
+  if (mounted.length) {
     console.log(
-      grey('Open ') + link('http://' + host + ':' + port + '/') + grey(' in your browser')
+      grey('Plugins: ') +
+        yellow(mounted.map(p => p.name + (p.prefix ? ' (' + p.prefix + ')' : '')).join(', '))
     );
   }
+  console.log(grey('Open ') + link(testServer.base + '/') + grey(' in your browser'));
   console.log();
 } catch (error) {
   if (error.syscall === 'listen') {

package/index.d.ts

@@ -8,11 +8,7 @@
  * - `null` or any primitive — strict equality.
  */
 export type AssertionMatcher =
-  | (new (...args: any[]) => Error)
-  | RegExp
-  | ((value: unknown) => boolean)
-  | object
-  | null;
+  (new (...args: any[]) => Error) | RegExp | ((value: unknown) => boolean) | object | null;
 
 /**
  * Test options

package/index.js

@@ -175,9 +175,7 @@ const init = async () => {
 
   if (isBrowser && typeof window.addEventListener == 'function') {
     // Control plane: the parent page posts `tape6-terminate` to drain a running
-    // test (failOnce / bail / worker deadline). The reporter arms stopTest +
-    // fires the abort signal so the test unwinds. There is no in-page
-    // force-kill — see dev-docs/worker-control-channel.md.
+    // test; there is no in-page force-kill — see dev-docs/worker-control-channel.md.
     window.addEventListener('message', event => {
       if (event.data?.type === 'tape6-terminate') getReporter()?.terminate();
     });

package/llms-full.txt

@@ -335,21 +335,100 @@ Sequential in-process runner. Same options as `tape6` but no threads.
 
 ### tape6-server
 
-Web server for browser testing:
+Pluggable test server for browser testing: static files + web UI + fixture plugins.
 
 ```bash
 tape6-server [options...]
 ```
 
+- `--plugin path` — register a plugin module (repeatable; path relative to the server root).
+- `--h2` — serve HTTPS with HTTP/2 + HTTP/1.1 via ALPN (Node-only server mode).
+- `--no-remote-plugins` — disable `PUT`/`DELETE` on `/--plugins`.
 - `--trace` — enable request trace logging.
 - `--self` — print the path to this script and exit.
 - `--help`, `-h` — show help message and exit.
 - `--version`, `-v` — show version and exit.
 
 Configured via environment variables: `HOST` (default: localhost), `PORT` (default: 3000),
-`SERVER_ROOT` (default: cwd), `WEBAPP_PATH`.
+`SERVER_ROOT` (default: cwd), `WEBAPP_PATH`, `TAPE6_PROTOCOL` (`h1`/`h2`),
+`TAPE6_CERT`/`TAPE6_KEY` (TLS cert/key paths for h2; auto-generates a self-signed cert via
+openssl when omitted).
 Navigate to `http://localhost:3000` for the web UI.
 
+Request routing: reserved control endpoints (`/--tests`, `/--patterns`, `/--importmap`,
+`/--plugins`) → plugins by longest prefix → static files (GET/HEAD only; plugins see all verbs).
+
+## Test server plugins and embedding
+
+Fixture plugins let real-wire tests (streaming, SSE, stateful ETag resources, upload sinks)
+run against `tape6-server`. A plugin module default-exports an async factory returning a
+handler record:
+
+```js
+export default async function fixtures(api, options) {
+  // api: {rootFolder, config, base, protocol, log, trace}
+  return {
+    name: 'fixtures', // registry key (defaults to the module/function name)
+    prefix: '/--fixtures/', // claimed namespace, longest-prefix routed
+    fetch(request, api) {
+      // WHATWG Request → Response | (async) iterable | undefined (= pass to the next plugin)
+      return Response.json({ok: true});
+    },
+    close() {} // optional teardown: runs on deregistration and server shutdown
+  };
+}
+```
+
+- Request bodies are Web streams (`duplex: 'half'`); `Response` stream bodies are written
+  unbuffered; client disconnect fires `request.signal`.
+- `fetch` may return an (async) iterable instead of a `Response`: `Uint8Array` chunks pass
+  through, strings are UTF-8 encoded, other values become JSONL lines. A module may
+  default-export a bare (async) generator function:
+
+```js
+export default async function* numbers({url}) {
+  const n = Number(new URL(url).searchParams.get('n')) || 10;
+  for (let i = 0; i < n; ++i) yield {n: i}; // streamed as application/x-ndjson
+}
+```
+
+- `raw(req, res, api)` is an escape hatch on raw Node objects; returning exactly `false`
+  passes the request on.
+- A tiny reference plugin ships in-tree: `tape-six/test-server/plugins/echo.js` mounts
+  `/--echo` and reflects method/query/headers/body as JSON.
+
+Registration channels:
+
+- **Static:** `package.json` → `"tape6": {"server": {"plugins": ["path", {"module": "path", "options": {}}]}}`
+  or the repeatable `--plugin` CLI flag.
+- **Dynamic (wire):** `GET /--plugins` lists `{name, prefix, source}`; `PUT /--plugins` with
+  `{"module": "path", "options": {}}` mounts a module (resolved against the server root and
+  contained to it; re-PUT replaces by name and closes the old instance); `DELETE
+  /--plugins/<name>` deregisters. Disable mutations with `--no-remote-plugins`.
+
+Embedding (hermetic Node/Bun/Deno integration tests; kernel-assigned ports make parallel test
+files collision-free):
+
+```js
+import {createTestServer, withTestServer} from 'tape-six/test-server.js';
+
+const {base, close} = await createTestServer({rootFolder, plugins: [myPlugin], port: 0});
+// ... fetch(base + '/--fixtures/...') ...
+await close();
+
+// or scoped:
+await withTestServer({rootFolder, plugins: [myPlugin]}, async base => {
+  // server closes when the handler settles
+});
+```
+
+Inline plugins (factories, records, generator functions) are accepted in the `plugins` array
+and via `server.register(spec)`. Other config keys under `tape6.server`: `protocol`
+(`"h1"`/`"h2"`), `cert`/`key` (TLS paths), `remotePlugins` (boolean), `webAppPath`.
+
+Stateful fixtures should key state by an explicit `scope` (query param or `X-Scope` header)
+minted per test, so parallel workers sharing one server don't collide.
+
 ### Runtime-specific runners
 
 - `tape6-node` — Node.js runner.
@@ -389,6 +468,8 @@ Browser: `http://localhost:3000/?flags=FO`
 - `TAPE6_TEST_FILE_NAME` — set by runners to identify the current test file.
 - `TAPE6_GRACE_TIMEOUT` — ms a worker gets to drain (run cleanup, flush) after the runner asks it to stop, before being force-killed (default: 5000).
 - `TAPE6_WORKER_TIMEOUT` — per-file wall-clock budget in ms; on expiry the runner stops that worker (default: 0, disabled). The complement to the per-test `timeout` option: this one can stop a worker that ignores `t.signal`.
+- `TAPE6_PROTOCOL` — test server protocol: `h1` (default) or `h2`.
+- `TAPE6_CERT` / `TAPE6_KEY` — TLS certificate/key paths for the test server's h2 mode.
 
 ## Browser testing
 

package/llms.txt

@@ -235,6 +235,25 @@ npx tape6-seq              # run sequentially (no worker threads)
 npx tape6-server --trace   # start browser test server
 ```
 
+### Test server (fixtures + embedding)
+
+`tape6-server` is pluggable: fixture plugins mount under URL prefixes (`--plugin path`,
+config `tape6.server.plugins`, or `PUT /--plugins` at runtime) and handle requests with a
+WHATWG `fetch(request) → Response | (async) iterable | undefined` contract; an (async)
+generator function streams JSONL. `--h2` switches to HTTPS with HTTP/2 (Node-only). For
+hermetic integration tests embed it on an OS-assigned port:
+
+```js
+import {createTestServer, withTestServer} from 'tape-six/test-server.js';
+
+await withTestServer({plugins: [myPlugin]}, async base => {
+  const res = await fetch(base + '/--fixtures/data?n=3');
+  // ...
+});
+```
+
+Full plugin contract: llms-full.txt § Test server plugins and embedding.
+
 ## Environment variables
 
 - `TAPE6_FLAGS` — flags string.
@@ -245,6 +264,8 @@ npx tape6-server --trace   # start browser test server
 - `TAPE6_TEST_FILE_NAME` — set by runners to identify the current test file.
 - `TAPE6_GRACE_TIMEOUT` — ms a worker gets to drain (run cleanup, flush) after the runner asks it to stop, before being force-killed (default: 5000).
 - `TAPE6_WORKER_TIMEOUT` — per-file wall-clock budget in ms; on expiry the runner stops that worker (default: 0, disabled). Complements the per-test `timeout` option: this one can stop a worker that ignores `t.signal`.
+- `TAPE6_PROTOCOL` — test server protocol: `h1` (default) or `h2`.
+- `TAPE6_CERT` / `TAPE6_KEY` — TLS certificate/key paths for the test server's h2 mode.
 
 ## Configuration (package.json)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tape-six",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "TAP-inspired unit test library for Node, Deno, Bun, and browsers. ES modules, TypeScript, zero dependencies.",
   "type": "module",
   "main": "index.js",
@@ -103,7 +103,8 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^26.0.1",
+    "@types/node": "^26.1.0",
+    "prettier": "^3.9.4",
     "typescript": "^6.0.3"
   }
 }

package/src/State.js

@@ -184,9 +184,8 @@ export class State {
       typeof event.diffTime !== 'number' && (event.diffTime = event.time - this.startTime);
     }
 
-    // Stack walking is only needed when the event will be reported as a failure.
-    // Reporters (TapReporter, TTYReporter) only read event.at / event.stackList
-    // inside `if (event.fail)` blocks, so for passing assertions this is wasted work.
+    // reporters read event.at / event.stackList only for failures — stack
+    // walking on passing assertions is wasted work
     if (isFailed) {
       if (
         event.type === 'assert' &&

package/src/Tester.js

@@ -460,10 +460,7 @@ export class Tester {
 }
 Tester.prototype.any = Tester.prototype._ = any;
 
-// Idempotent registration of a method on Tester.prototype. Same name + same
-// function → no-op; same name + different function → throws. Lets plugins
-// extend the tester (e.g., spawnBin, withTempDir, waitFor) without colliding
-// silently when two of them claim the same name.
+// plugin extension point — a same-name collision must fail loudly, not silently override
 export const registerTesterMethod = (name, fn) => {
   if (typeof name !== 'string' || !name)
     throw new TypeError('registerTesterMethod: name must be a non-empty string');

package/src/reporters/Reporter.js

@@ -15,9 +15,6 @@ export class Reporter {
     this.terminating = false;
   }
 
-  // Emit one record to stdout, mirroring console.log's arguments. On Bun,
-  // console.log to a subprocess-piped stdout is lossy / stalls under load, so route
-  // through process.stdout.write there; Node/Deno keep the proven console.log path.
   writeOut(...args) {
     if (isBun) {
       process.stdout.write(args.map(a => (typeof a == 'string' ? a : String(a))).join(' ') + '\n');
@@ -34,14 +31,9 @@ export class Reporter {
     this.state?.abort();
   }
 
-  // Control plane: a `terminate` command reached this worker (failOnce / bail
-  // drain, or a worker deadline). Arm stopTest and fire the abort signal across
-  // the live state chain so a running test unwinds — StopTest at the next
-  // assertion, t.signal rejects signal-aware awaits — and remember it so any
-  // test that starts afterwards stops at its first assertion too (closing the
-  // race where `terminate` lands while the worker is still starting up). The
-  // test's cleanup (finally / afterEach / afterAll) still runs. See
-  // dev-docs/worker-control-channel.md.
+  // `terminating` is remembered so a test that starts after the terminate stops
+  // too — closes the race where `terminate` lands mid-startup. Cleanup
+  // (finally / afterEach / afterAll) still runs. See dev-docs/worker-control-channel.md.
   terminate() {
     this.terminating = true;
     for (let state = this.state; state; state = state.parent) {
@@ -61,8 +53,7 @@ export class Reporter {
       timer: this.timer
     });
     ++this.depth;
-    // A terminate landed before this test started — stop it at its first
-    // assertion rather than letting it run to completion.
+    // a terminate landed before this test started
     if (this.terminating) {
       this.state.stopTest = true;
       this.state.abort();

package/src/runners/bun/TestWorker.js

@@ -5,7 +5,7 @@ import EventServer from '../../utils/EventServer.js';
 const srcName = new URL('../../', import.meta.url),
   baseName = Bun.pathToFileURL(Bun.cwd + sep);
 
-export default class TestWorker extends EventServer {
+export class TestWorker extends EventServer {
   constructor(reporter, numberOfTasks = globalThis.navigator?.hardwareConcurrency || 1, options) {
     super(reporter, numberOfTasks, options);
     this.counter = 0;
@@ -74,13 +74,10 @@ export default class TestWorker extends EventServer {
     const worker = this.idToWorker[id];
     if (!worker) return;
     if (reason === 'done') {
-      // The test already finished; just tear the worker down.
       this.#kill(id);
       return;
     }
-    // Cooperative drain (abort): ask the child to fire its abort signal and run
-    // cleanup hooks, then force-kill as a backstop after graceTimeout in case
-    // the test ignores the signal and never settles.
+    // force-kill backstop: the test may ignore the abort signal and never settle
     if (this.graceTimers[id]) return; // already draining
     try {
       worker.postMessage({type: 'terminate', reason});
@@ -102,3 +99,5 @@ export default class TestWorker extends EventServer {
     }
   }
 }
+
+export default TestWorker;

package/src/runners/bun/worker.js

@@ -38,9 +38,7 @@ let currentReporter = null,
 
 addEventListener('message', async event => {
   const msg = event.data;
-  // Control plane: drain on `terminate`. The reporter arms stopTest + fires the
-  // abort signal so a running test unwinds (cleanup runs); a terminate that
-  // lands before the reporter exists is remembered and applied at startup.
+  // a terminate can land before the reporter exists — remember it, apply at startup
   if (msg?.type === 'terminate') {
     pendingTerminate = true;
     currentReporter?.terminate();

package/src/runners/deno/TestWorker.js

@@ -6,7 +6,7 @@ import EventServer from '../../utils/EventServer.js';
 const srcName = new URL('../../', import.meta.url),
   baseName = pathToFileURL(Deno.cwd() + sep);
 
-export default class TestWorker extends EventServer {
+export class TestWorker extends EventServer {
   constructor(reporter, numberOfTasks = globalThis.navigator?.hardwareConcurrency || 1, options) {
     super(reporter, numberOfTasks, options);
     this.counter = 0;
@@ -57,13 +57,10 @@ export default class TestWorker extends EventServer {
     const worker = this.idToWorker[id];
     if (!worker) return;
     if (reason === 'done') {
-      // The test already finished; just tear the worker down.
       this.#kill(id);
       return;
     }
-    // Cooperative drain (abort): ask the child to fire its abort signal and run
-    // cleanup hooks, then force-kill as a backstop after graceTimeout in case
-    // the test ignores the signal and never settles.
+    // force-kill backstop: the test may ignore the abort signal and never settle
     if (this.graceTimers[id]) return; // already draining
     try {
       worker.postMessage({type: 'terminate', reason});
@@ -85,3 +82,5 @@ export default class TestWorker extends EventServer {
     }
   }
 }
+
+export default TestWorker;