tape-six 1.12.0 → 1.13.0

package/README.md

@@ -427,6 +427,7 @@ 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._

package/bin/tape6-server.js

@@ -67,7 +67,7 @@ let traceCalls = false,
 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;
 };
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tape-six",
-  "version": "1.12.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",

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

@@ -74,13 +74,10 @@ export 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});

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

@@ -57,13 +57,10 @@ export 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});

package/src/runners/deno/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/node/TestWorker.js

@@ -76,14 +76,11 @@ export class TestWorker extends EventServer {
     const worker = this.idToWorker[id];
     if (!worker) return;
     if (reason === 'done') {
-      // The test already finished; worker_threads have no flush race, so just
-      // tear the worker down.
+      // worker_threads have no flush race
       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});

package/src/runners/node/worker.js

@@ -40,9 +40,7 @@ let currentReporter = null,
   pendingTerminate = false;
 
 parentPort.on('message', async msg => {
-  // 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/seq/TestWorker.js

@@ -62,10 +62,8 @@ export class TestWorker extends EventServer {
   }
   destroyTask(id, reason = 'done') {
     if (reason !== 'done') {
-      // Abort trigger (failOnce / bail / worker deadline). The test runs in this
-      // same process, so "terminate" is just reporter.terminate(): arm stopTest
-      // + fire the abort signal. The run unwinds and closes itself with 'done',
-      // where the reset below happens.
+      // same process, no force-kill — the aborted run closes itself with 'done',
+      // where the reset below happens
       this.reporter.terminate();
       return;
     }

package/src/utils/EventServer.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Teardown reason delivered to `destroyTask`:
+ * - `'done'` — the task finished; tear its worker down now.
+ * - `'failOnce'` — stop / bail-out: abort an in-flight task.
+ * - `'timeout'` — the per-worker deadline (`workerTimeout`) fired.
+ *
+ * Any reason but `'done'` means: drain cooperatively (let cleanup run),
+ * then force-kill after `graceTimeout` where the transport allows.
+ */
+export type DestroyReason = 'done' | 'failOnce' | 'timeout';
+
+/**
+ * A test event routed to the reporter — a loose bag (`type`, `test`,
+ * `name`, `marker`, `operator`, `fail`, `data`, ...). See TESTING.md.
+ */
+export type TestEvent = {[key: string]: unknown};
+
+/**
+ * The reporter surface `EventServer` needs. Structural — every tape-six
+ * reporter satisfies it.
+ */
+export interface EventServerReporter {
+  report(event: TestEvent, suppressStopTest?: boolean): void;
+  state?: {stopTest?: boolean; [key: string]: unknown} | null;
+}
+
+/**
+ * Options consumed by the base class. Runners pass their own keys through
+ * (`flags`, `importmap`, `serverUrl`, `browser`, ...) — hence the index
+ * signature.
+ */
+export interface EventServerOptions {
+  /**
+   * Cooperative-drain window in ms before a force-kill (default: 5000).
+   * CLI runners inject `TAPE6_GRACE_TIMEOUT` via `getOptions()`.
+   */
+  graceTimeout?: number;
+  /**
+   * Per-worker deadline in ms; unset or 0 disables it. CLI runners inject
+   * `TAPE6_WORKER_TIMEOUT` via `getOptions()`.
+   */
+  workerTimeout?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * Base class for test-worker drivers (the parallel/seq runners and the
+ * `tape-six-proc` / `tape-six-puppeteer` / `tape-six-playwright` siblings).
+ *
+ * Two planes: DATA (worker → reporter — the `report()`/`close()`
+ * event-ordering machinery) and CONTROL (reporter/runner → worker — a
+ * single `terminate` delivered per transport by `destroyTask`). See
+ * dev-docs/worker-control-channel.md.
+ *
+ * Subclasses implement the two transport hooks: `makeTask` and
+ * `destroyTask`.
+ */
+export class EventServer {
+  constructor(reporter: EventServerReporter, numberOfTasks?: number, options?: EventServerOptions);
+
+  reporter: EventServerReporter;
+  numberOfTasks: number;
+  options: EventServerOptions;
+
+  /** Drain window in ms before a force-kill; see `EventServerOptions.graceTimeout`. */
+  graceTimeout: number;
+  /** Per-worker deadline in ms; 0 = off; see `EventServerOptions.workerTimeout`. */
+  workerTimeout: number;
+  /**
+   * Set on the first stop / bail-out signal; every in-flight task then gets
+   * `destroyTask(id, 'failOnce')`. Tasks that finish starting later must
+   * check it themselves (a just-created worker can miss the sweep).
+   */
+  stopRequested: boolean;
+
+  /** Completion hook: called once when the last task closes. Assigned by runners. */
+  done?: () => void;
+
+  // DATA-plane bookkeeping — not a consumer surface.
+  totalTasks: number;
+  fileQueue: string[];
+  passThroughId: string | null;
+  retained: Record<string, TestEvent[]>;
+  readyQueue: TestEvent[][];
+  liveTasks: Set<string>;
+  deadlineTimers: Record<string, ReturnType<typeof setTimeout>>;
+
+  /** DATA plane: forward one worker event, preserving per-task ordering. */
+  report(id: string, event: TestEvent): void;
+  /**
+   * DATA plane: a task's stream ended — release its retained events, start
+   * the next queued file, and call `destroyTask(id, 'done')`.
+   */
+  close(id: string): void;
+
+  /** Start a worker for `fileName` now if a slot is free, else queue it. */
+  createTask(fileName: string): void;
+  /** `createTask` every file. */
+  execute(files: string[]): void;
+
+  /**
+   * Transport hook: start a worker for `fileName` and return its task id.
+   * The base implementation is a no-op returning `undefined`.
+   */
+  makeTask(fileName: string): string | null | undefined;
+  /**
+   * Transport hook (CONTROL plane): deliver `terminate` to one worker.
+   * The base implementation is a no-op; see `DestroyReason` for the
+   * expected teardown semantics.
+   */
+  destroyTask(id: string, reason?: DestroyReason): void;
+}
+
+export default EventServer;

package/src/utils/EventServer.js

@@ -1,3 +1,5 @@
+// @ts-self-types="./EventServer.d.ts"
+
 import defer from './defer.js';
 
 // Fallback used when no graceTimeout is supplied through options (e.g. the
@@ -5,15 +7,9 @@ import defer from './defer.js';
 // (TAPE6_GRACE_TIMEOUT) via getOptions(); see src/utils/config.js.
 const DEFAULT_GRACE_TIMEOUT = 5_000;
 
-// EventServer owns two planes. The DATA plane (worker -> reporter) is the
-// report()/close() event-ordering machinery. The CONTROL plane
-// (reporter/runner -> worker) is a single command, `terminate`, delivered per
-// transport by destroyTask(id, reason). Two triggers fire it:
-//   - normal completion: close() terminates the just-finished worker ('done');
-//   - stop / bail-out:   when reporter.state.stopTest is set (failOnce / bail),
-//                        every in-flight worker is terminated ('failOnce').
-// An optional per-worker wall-clock deadline (workerTimeout, Layer 2) fires the
-// same command on expiry ('timeout'). See dev-docs/worker-control-channel.md.
+// Two planes: DATA (worker -> reporter, the report()/close() event-ordering
+// machinery) and CONTROL (reporter/runner -> worker, a single `terminate`
+// delivered per transport by destroyTask). See dev-docs/worker-control-channel.md.
 export class EventServer {
   constructor(reporter, numberOfTasks = 1, options = {}) {
     this.reporter = reporter;
@@ -112,9 +108,7 @@ export class EventServer {
   execute(files) {
     files.forEach(fileName => this.createTask(fileName));
   }
-  // Spawn one worker and register it for control-plane tracking. Routes both
-  // the initial batch (createTask) and queue drains (close) so liveTasks and
-  // the optional deadline cover every task, not just the first numberOfTasks.
+  // createTask and close() both route here so liveTasks + the deadline cover every task
   #startTask(fileName) {
     const id = this.makeTask(fileName);
     if (id == null) return id;
@@ -134,9 +128,6 @@ export class EventServer {
       delete this.deadlineTimers[id];
     }
   }
-  // Terminate every in-flight worker (abort) on top of the existing "stop
-  // scheduling new files." Fires at most once per run; callers decide when a
-  // stop / bail-out signal has been observed.
   #requestStop() {
     if (this.stopRequested) return;
     this.stopRequested = true;

package/src/utils/config.js

@@ -170,9 +170,6 @@ export const getReporterFileName = type => {
 export const DEFAULT_START_TIMEOUT = 5_000;
 export const DEFAULT_GRACE_TIMEOUT = 5_000;
 
-// Read a positive-millisecond env var, falling back to `fallback` when it is
-// unset, non-numeric, non-positive, or Infinity. Always returns `fallback` in
-// the browser, where these env vars don't exist.
 const readTimeoutEnv = (name, fallback) => {
   if (runtime.name === 'browser') return fallback;
   const value = runtime.getEnvVar(name);
@@ -192,8 +189,7 @@ export const getTimeoutValue = () =>
 // allows. See dev-docs/worker-control-channel.md.
 export const getGraceTimeout = () => readTimeoutEnv('TAPE6_GRACE_TIMEOUT', DEFAULT_GRACE_TIMEOUT);
 
-// Optional wall-clock budget per worker/file (Layer 2 termination). 0 disables
-// it — the default — so a worker deadline fires only when explicitly set.
+// Optional wall-clock budget per worker/file (Layer 2 termination); 0 (default) disables it.
 export const getWorkerTimeout = () => readTimeoutEnv('TAPE6_WORKER_TIMEOUT', 0);
 
 export const flagNames = Object.fromEntries(
@@ -322,8 +318,7 @@ export const getOptions = extraOptions => {
   }
   options.parallel = parallel;
 
-  // Control-channel budgets ride along in the options bag handed to the
-  // TestWorker (EventServer). Children ignore them; only the parent acts.
+  // children ignore these; only the parent (EventServer) acts on them
   options.flags.graceTimeout = getGraceTimeout();
   options.flags.workerTimeout = getWorkerTimeout();
 

package/src/utils/control-channel.js

@@ -99,9 +99,7 @@ export const listenControlChannel = async getReporter => {
   }
   if (buffer) handleLine(buffer);
 
-  // Control-channel EOF. If no explicit terminate arrived (parent died / pipe
-  // broke), soft-terminate so a still-running test drains. Then fall through:
-  // the loop empties and the runtime exits naturally, flushing stdout.
+  // EOF — soft-terminate per the header contract
   if (!terminated) getReporter()?.terminate();
   armWatchdog(graceTimeout, getExitCode);
 };

package/web-app/TestWorker.js

@@ -89,11 +89,9 @@ export default class TestWorker extends EventServer {
       this.#removeIframe(id);
       return;
     }
-    // Cooperative drain only — in-page JS can't force-kill a hung iframe script.
-    // postMessage `terminate` so a cooperative test unwinds and runs its cleanup
-    // hooks; if it doesn't exit within graceTimeout, remove the iframe as a
-    // best-effort backstop. A driver-backed run (puppeteer / playwright) can do
-    // a real kill from Node — not wired here. See dev-docs/worker-control-channel.md.
+    // in-page JS can't force-kill a hung iframe script — iframe removal after
+    // graceTimeout is a best-effort backstop; a real kill needs a driver
+    // (puppeteer / playwright). See dev-docs/worker-control-channel.md.
     if (this.graceTimers[id]) return;
     const iframe = document.getElementById('test-iframe-' + id);
     if (!iframe) return;