tape-six 1.7.13 → 1.8.0

package/README.md

@@ -4,7 +4,7 @@
 [npm-url]: https://npmjs.org/package/tape-six
 
 `tape-six` is a [TAP](https://en.wikipedia.org/wiki/Test_Anything_Protocol)-based library for unit tests.
-It is written in the modern JavaScript for the modern JavaScript and works in [Node](https://nodejs.org/), [Deno](https://deno.land/), [Bun](https://bun.sh/) and browsers. **Zero runtime dependencies.**
+Written in modern JavaScript for modern JavaScript runtimes — works in [Node](https://nodejs.org/), [Deno](https://deno.land/), [Bun](https://bun.sh/), and browsers. **Zero runtime dependencies.**
 
 It runs ES modules (`import`-based code) natively and supports CommonJS modules transparently using the built-in [ESM](https://nodejs.org/api/esm.html).
 
@@ -425,6 +425,8 @@ Test output can be controlled by flags. See [Supported flags](https://github.com
 
 The most recent releases:
 
+- 1.8.0 _New subpath modules `tape-six/server` (withServer/startServer/setupServer — ephemeral HTTP server harness with port-busy-rejects-not-hangs lifecycle, plus a hook helper for suite-shared servers) and `tape-six/response` (asText/asJson/asBytes/header/headers — reading helpers that work uniformly on W3C Response and Node http.IncomingMessage). Cross-runtime via `node:http` (Node, Bun, Deno). `bin/tape6-server.js` migrated to use `startServer` and `process.exitCode`. `node:` protocol prefix consistently applied to all Node built-in imports; added `types: ["node"]` to tsconfig._
+- 1.7.14 _Updated vendored `deep6` to 1.2.0: added `URL` support (unifier/walker/cloner + processors), named exports alongside default exports, fast path for naked objects, performance optimizations, improved TS typings, removed CommonJS build._
 - 1.7.13 _Replaced `process.exit()` / `Deno.exit()` with `process.exitCode` in test runners and `index.js` for graceful stdout flushing. Updated dependencies, GitHub Actions._
 - 1.7.12 _Added `--help`/`-h` and `--version`/`-v` options to all CLI utilities. Added flag documentation to help output._
 - 1.7.11 _Documentation consistency: added missing sequential test commands to AI docs, fixed test glob references._

package/TESTING.md

@@ -110,29 +110,55 @@ test.todo('in progress', t => {
 
 All `msg` arguments are optional. If omitted, a generic message is used.
 
-| Method                               | Checks                          | Common aliases                   |
-| ------------------------------------ | ------------------------------- | -------------------------------- |
-| `t.pass(msg)`                        | Unconditional pass              |                                  |
-| `t.fail(msg)`                        | Unconditional fail              |                                  |
-| `t.ok(val, msg)`                     | `val` is truthy                 | `true`, `assert`                 |
-| `t.notOk(val, msg)`                  | `val` is falsy                  | `false`, `notok`                 |
-| `t.error(err, msg)`                  | `err` is falsy                  | `ifError`, `ifErr`               |
-| `t.equal(a, b, msg)`                 | `a === b`                       | `is`, `strictEqual`, `isEqual`   |
-| `t.notEqual(a, b, msg)`              | `a !== b`                       | `not`, `notStrictEqual`, `isNot` |
-| `t.deepEqual(a, b, msg)`             | Deep strict equality            | `same`, `isEquivalent`           |
-| `t.notDeepEqual(a, b, msg)`          | Not deeply equal                | `notSame`, `notEquivalent`       |
-| `t.looseEqual(a, b, msg)`            | `a == b`                        |                                  |
-| `t.notLooseEqual(a, b, msg)`         | `a != b`                        |                                  |
-| `t.deepLooseEqual(a, b, msg)`        | Deep loose equality             |                                  |
-| `t.notDeepLooseEqual(a, b, msg)`     | Not deeply loosely equal        |                                  |
-| `t.throws(fn, msg)`                  | `fn()` throws                   |                                  |
-| `t.doesNotThrow(fn, msg)`            | `fn()` does not throw           |                                  |
-| `t.matchString(str, re, msg)`        | `str` matches `re`              |                                  |
-| `t.doesNotMatchString(str, re, msg)` | `str` doesn't match `re`        |                                  |
-| `t.match(a, b, msg)`                 | Structural pattern match        |                                  |
-| `t.doesNotMatch(a, b, msg)`          | No structural match             |                                  |
-| `t.rejects(promise, msg)`            | Promise rejects (**await it**)  | `doesNotResolve`                 |
-| `t.resolves(promise, msg)`           | Promise resolves (**await it**) | `doesNotReject`                  |
+| Method                               | Checks                            | Common aliases                   |
+| ------------------------------------ | --------------------------------- | -------------------------------- |
+| `t.pass(msg)`                        | Unconditional pass                |                                  |
+| `t.fail(msg)`                        | Unconditional fail                |                                  |
+| `t.ok(val, msg)`                     | `val` is truthy                   | `true`, `assert`                 |
+| `t.notOk(val, msg)`                  | `val` is falsy                    | `false`, `notok`                 |
+| `t.error(err, msg)`                  | `err` is falsy                    | `ifError`, `ifErr`               |
+| `t.equal(a, b, msg)`                 | `a === b`                         | `is`, `strictEqual`, `isEqual`   |
+| `t.notEqual(a, b, msg)`              | `a !== b`                         | `not`, `notStrictEqual`, `isNot` |
+| `t.deepEqual(a, b, msg)`             | Deep strict equality              | `same`, `isEquivalent`           |
+| `t.notDeepEqual(a, b, msg)`          | Not deeply equal                  | `notSame`, `notEquivalent`       |
+| `t.looseEqual(a, b, msg)`            | `a == b`                          |                                  |
+| `t.notLooseEqual(a, b, msg)`         | `a != b`                          |                                  |
+| `t.deepLooseEqual(a, b, msg)`        | Deep loose equality               |                                  |
+| `t.notDeepLooseEqual(a, b, msg)`     | Not deeply loosely equal          |                                  |
+| `t.throws(fn, m?, msg)`              | `fn()` throws (matches `m?`)      |                                  |
+| `t.doesNotThrow(fn, msg)`            | `fn()` does not throw             |                                  |
+| `t.matchString(str, re, msg)`        | `str` matches `re`                |                                  |
+| `t.doesNotMatchString(str, re, msg)` | `str` doesn't match `re`          |                                  |
+| `t.match(a, b, msg)`                 | Structural pattern match          |                                  |
+| `t.doesNotMatch(a, b, msg)`          | No structural match               |                                  |
+| `t.rejects(promise, m?, msg)`        | Rejects (matches `m?`) — `await`  | `doesNotResolve`                 |
+| `t.resolves(promise, m?, msg)`       | Resolves (matches `m?`) — `await` | `doesNotReject`                  |
+
+### Matching errors and resolved values
+
+`t.throws`, `t.rejects`, and `t.resolves` accept an optional **matcher** as their second argument. If the second argument is a string, it's still treated as the message (backward compatible).
+
+```js
+t.throws(() => parse(''), TypeError); // Error subclass — instanceof
+t.throws(() => parse(''), /unexpected end/); // RegExp on error.message
+t.throws(
+  () => parse(''),
+  e => e.code === 'EPARSE'
+); // predicate
+t.throws(() => parse(''), {code: 'EPARSE'}); // deep6 object pattern
+await t.rejects(fetchData(), TypeError, 'wrong type');
+await t.resolves(fetchData(), {status: 200}); // matches resolved value
+```
+
+Matcher rules:
+
+- **Error subclass** (a function whose prototype is Error) → `instanceof` check.
+- **RegExp** → tested against `error.message` for `Error` instances, otherwise against `String(value)`.
+- **Function** (non-Error-class) → predicate; truthy return = match.
+- **Object** (non-null, non-RegExp) → uses deep6's `match()` for partial structural matching.
+- **`null` or any primitive** → strict equality.
+
+Falsy reasons (`null`, `0`, `false`, `''`, `NaN`) are correctly handled: `Promise.reject(null)` is still a rejection, and `throw 0` is still a throw.
 
 ### Async assertions
 
@@ -145,6 +171,69 @@ test('async asserts', async t => {
 });
 ```
 
+### Wildcards in deep equality
+
+Use `t.any` (or its alias `t._`) inside an expected value to accept any value at that position. Useful for non-deterministic fields like timestamps or generated IDs:
+
+```js
+test('partial match', t => {
+  const result = {id: 123, name: 'Alice', createdAt: new Date()};
+  t.deepEqual(result, {id: t.any, name: 'Alice', createdAt: t.any});
+});
+```
+
+### Async cancellation with `t.signal`
+
+`t.signal` is an `AbortSignal` that fires when the test ends, times out, or is stopped. Pass it to long-running async work so it cancels cleanly:
+
+```js
+test('aborts on test end', async t => {
+  const res = await fetch(url, {signal: t.signal});
+  t.equal(res.status, 200);
+});
+```
+
+### Test options
+
+`test(name, options, fn)` accepts an options object. Type-recognition makes the form flexible (any of `test(opts, fn)`, `test(name, fn)`, `test(name, opts, fn)` is valid).
+
+| Option                 | Effect                                                     |
+| ---------------------- | ---------------------------------------------------------- |
+| `name`                 | Test name (overrides positional)                           |
+| `timeout`              | Milliseconds; test fails and `t.signal` aborts if exceeded |
+| `skip`                 | Skip the test (does not run)                               |
+| `todo`                 | Run, but failures don't count                              |
+| `beforeAll` / `before` | Run once before the test's first embedded test             |
+| `afterAll` / `after`   | Run once after the test's last embedded test               |
+| `beforeEach`           | Run before each embedded test                              |
+| `afterEach`            | Run after each embedded test                               |
+
+```js
+test('with timeout', {timeout: 5000}, async t => {
+  await longOperation();
+});
+```
+
+By default tests have **no timeout**. Set `timeout` per test, or wrap a fixture suite to apply it broadly.
+
+### Other tester methods
+
+- `t.comment(msg)` — emit a TAP comment line.
+- `t.skipTest(msg)` — skip the **current** test from inside it (e.g. when a precondition isn't met at runtime).
+- `t.bailOut(msg)` — stop the entire run. Catastrophic; use sparingly.
+- `t.plan(n)` — currently a documented no-op kept for migration compatibility from `tape` and `node:test`.
+- `t.OK(expr, msg)` (aliases `t.TRUE`, `t.ASSERT`) — returns a code string for `eval()` that asserts an expression and dumps the values of the top-level identifiers in the expression on failure. Useful for compact arithmetic/state checks. Not usable in CSP-restricted contexts (uses `eval`).
+
+  ```js
+  test('OK evaluator', t => {
+    const a = 1,
+      b = 2,
+      c = 'three';
+    eval(t.OK('a + b + c === "3three"'));
+    // on failure, the report includes: {a: 1, b: 2, c: "three"}
+  });
+  ```
+
 ### Nested (embedded) tests
 
 Tests can be nested. The preferred way is `t.test()` because it makes the delegation explicit. Top-level `test()`/`it()` are equivalent inside a test body — they auto-delegate to the current tester:
@@ -246,6 +335,127 @@ test('suite B', dbOpts, async t => {
 });
 ```
 
+## Testing HTTP code
+
+Two subpath modules ship for tests that need HTTP-shaped fixtures. Both work on Node, Bun, and Deno via `node:http`. Browsers don't get them — running an HTTP server inside a webpage isn't a use case.
+
+> **Placement matters.** Test files that import `tape-six/server`, `tape-six/response`, or any other node-only API (e.g. `node:http`, `node:fs`, `node:child_process`) **must not** match a `tape6.tests` pattern that's universal to all environments — the browser worker would try to load them and fail with `Worker error` on the missing built-in. Put them in a CLI-only location (e.g. `tests/cli/test-*.js`) and add the matching glob to `tape6.cli` so it covers Node/Bun/Deno but not browsers. See [Configuring test discovery](#configuring-test-discovery).
+
+### `tape-six/server` — server harness
+
+```js
+import {withServer, startServer, setupServer} from 'tape-six/server';
+```
+
+Three exports for three lifetimes. `withServer` is the per-test scoped resource (95% case). `startServer` is the procedural primitive. `setupServer` registers `beforeAll`/`afterAll` for suite-shared servers.
+
+**Per-test server** — start before the test body, tear down in `finally`:
+
+```js
+import test from 'tape-six';
+import {withServer} from 'tape-six/server';
+
+test('GET / returns 200', t =>
+  withServer(myHandler, async base => {
+    const res = await fetch(`${base}/`);
+    t.equal(res.status, 200);
+  }));
+```
+
+`myHandler` is a `(req, res) => void` callback (`http.RequestListener`). `base` is the bound URL, e.g. `"http://127.0.0.1:54321"`. Default host is `'127.0.0.1'` (explicit IPv4); pass `{host, port}` to override.
+
+`withServer` handles the symmetric case where the test makes requests directly. It's also the right tool when the SUT is something else (a CLI spawned in a subprocess) and the handler is a mock — the test body just looks different:
+
+```js
+test('CLI hits the API correctly', t =>
+  withServer(mockApi, async base => {
+    const result = await spawnCli({env: {API_URL: base}});
+    t.equal(result.exitCode, 0);
+    t.equal(recordedRequests.length, 1);
+  }));
+```
+
+Either side may be the SUT. The names `serverHandler` / `clientHandler` reflect role on the wire, not which side is being tested.
+
+**Suite-shared server** — register hooks once, share across many tests:
+
+```js
+import test, {beforeEach} from 'tape-six';
+import {setupServer} from 'tape-six/server';
+
+let recorded;
+const server = setupServer((req, res) => {
+  recorded.push({method: req.method, url: req.url});
+  res.writeHead(204).end();
+});
+beforeEach(() => {
+  recorded = [];
+});
+
+test('records exactly one request', async t => {
+  await fetch(`${server.base}/foo`);
+  t.equal(recorded.length, 1);
+});
+
+test('records the path correctly', async t => {
+  await fetch(`${server.base}/bar`);
+  t.equal(recorded[0].url, '/bar');
+});
+```
+
+The returned handle has live getters — `server.base` reads the current state on each access. **Don't destructure** at module load (`const {base} = setupServer(...)`); `base` is `undefined` until `beforeAll` runs. Per-test state reset (the `recorded = []` above) is user-side via your own `beforeEach`; `setupServer` owns the server lifecycle, you own state.
+
+**Procedural primitive** — for multi-phase tests or non-test code:
+
+```js
+import http from 'node:http';
+import {startServer} from 'tape-six/server';
+
+const lc = await startServer(http.createServer(handler), {host, port});
+try {
+  // ... lc.base, lc.port, lc.host ...
+} finally {
+  await lc.close();
+}
+```
+
+`startServer` accepts a fully-constructed server (so the caller can attach `'clientError'` listeners or configure TLS first). It races `'listening'` against `'error'` so port-busy / `EACCES` rejects with the original error rather than hanging — the failure mode existing helpers across the ecosystem suffer from on busy CI machines.
+
+`close()` is idempotent and calls `server.closeAllConnections()` (when available, Node 18.2+) so keep-alive sockets from `fetch` don't delay teardown.
+
+### `tape-six/response` — response reading helpers
+
+```js
+import {asText, asJson, asBytes, header, headers} from 'tape-six/response';
+```
+
+Five reading helpers that work uniformly on both W3C `Response` (from `fetch`) and Node `http.IncomingMessage` (from `http.request`).
+
+```js
+import test from 'tape-six';
+import {withServer} from 'tape-six/server';
+import {asJson, header} from 'tape-six/response';
+
+test('GET / returns JSON', t =>
+  withServer(handler, async base => {
+    const res = await fetch(`${base}/`);
+    t.equal(res.status, 200);
+    t.match(header(res, 'content-type'), /^application\/json/);
+    const body = await asJson(res);
+    t.deepEqual(body, {ok: true});
+  }));
+```
+
+| Helper              | Returns                  | Notes                               |
+| ------------------- | ------------------------ | ----------------------------------- |
+| `asText(res)`       | `Promise<string>`        | UTF-8                               |
+| `asJson(res)`       | `Promise<unknown>`       | parses JSON                         |
+| `asBytes(res)`      | `Promise<Uint8Array>`    | raw bytes                           |
+| `header(res, name)` | `string \| null`         | case-insensitive single-header read |
+| `headers(res)`      | `Record<string, string>` | all headers, lowercase keys         |
+
+For status code, just use `res.status` (W3C `Response`) or `res.statusCode` (Node `IncomingMessage`) directly — no helper needed.
+
 ## Migrating from other test frameworks
 
 `tape-six` supports `describe`/`it` and `before`/`after` aliases. When called inside a test body, all top-level functions automatically delegate to the current tester. This means migration from Mocha, Jest, or `node:test` is nearly mechanical — change the import and swap assertions.
@@ -400,30 +610,6 @@ Note: you can also keep using `node:assert` inside tape-six tests — `Assertion
 | `expect(a).to.be.ok` (Chai)         | `t.ok(a)` or keep `expect`                        |
 | `expect(fn).to.throw()` (Chai)      | `t.throws(fn)` or keep `expect`                   |
 
-### Wildcard matching with `t.any`
-
-Use `t.any` (or `t._`) in deep equality checks to match any value:
-
-```js
-test('partial match', t => {
-  const result = {id: 123, name: 'Alice', createdAt: new Date()};
-  t.deepEqual(result, {id: 123, name: 'Alice', createdAt: t.any});
-});
-```
-
-### Testing exceptions
-
-```js
-test('errors', async t => {
-  t.throws(() => {
-    throw new Error('boom');
-  }, 'should throw');
-  t.doesNotThrow(() => 42, 'should not throw');
-  await t.rejects(Promise.reject(new Error('fail')), 'should reject');
-  await t.resolves(Promise.resolve(42), 'should resolve');
-});
-```
-
 ### 3rd-party assertion libraries
 
 `tape-six` catches `AssertionError` automatically. You can use `chai` or `node:assert`:
@@ -514,6 +700,18 @@ Common combinations: `FO` (failures only + stop at first), `FOT` (+ show time).
 
 When multiple `--flags` are given, the last one wins. To see which files are being run (overriding `--flags FO` from a script), append `--flags fo` — lowercase disables the flags.
 
+### Other CLI options
+
+| Option            | Effect                                                                |
+| ----------------- | --------------------------------------------------------------------- |
+| `--par N`         | Limit `tape6` to `N` parallel workers (default: number of CPU cores). |
+| `--info`          | Print the resolved test config (file lists, env, importmap) and exit. |
+| `--self`          | Print the path to the runner's own entry script (used in scripts).    |
+| `--help`, `-h`    | Show usage.                                                           |
+| `--version`, `-v` | Show version.                                                         |
+
+Options that take a value accept both space-separated (`--par 4`) and `=`-separated (`--par=4`) forms.
+
 ### Environment variables
 
 - `TAPE6_FLAGS` — flags string (alternative to `--flags`).
@@ -521,6 +719,7 @@ When multiple `--flags` are given, the last one wins. To see which files are bei
 - `TAPE6_TAP` — force TAP output format.
 - `TAPE6_JSONL` — force JSONL output format.
 - `TAPE6_MIN` — force minimal output format.
+- `TAPE6_WORKER_START_TIMEOUT` — milliseconds to wait for a worker to register its first test before declaring "no tests found". Default: `5000`. Bump this (e.g., `60000`) for tests with heavy `beforeAll` work like Docker container spawn or large fixture loads.
 
 ## Configuring test discovery
 

package/bin/tape6-server.js

@@ -13,6 +13,7 @@ import {
   printVersion,
   printHelp
 } from '../src/utils/config.js';
+import {startServer} from '../src/server.js';
 
 const fsp = fs.promises;
 
@@ -241,24 +242,8 @@ const portToString = port => (typeof port === 'string' ? 'pipe' : 'port') + ' '
 const host = process.env.HOST || 'localhost',
   port = normalizePort(process.env.PORT || '3000');
 
-server.listen(port, host);
-
-server.on('error', error => {
-  if (error.syscall !== 'listen') throw error;
-  const bind = portToString(port);
-  switch (error.code) {
-    case 'EACCES':
-      console.log(red('Error: ') + yellow(bind) + red(' requires elevated privileges') + '\n');
-      process.exit(1);
-    case 'EADDRINUSE':
-      console.log(red('Error: ') + yellow(bind) + red(' is already in use') + '\n');
-      process.exit(1);
-  }
-  throw error;
-});
-
-server.on('listening', () => {
-  //const addr = server.address();
+try {
+  await startServer(server, {host, port});
   const bind = portToString(port);
   console.log(
     grey('Listening on ') +
@@ -274,4 +259,19 @@ server.on('listening', () => {
     );
   }
   console.log();
-});
+} catch (error) {
+  if (error.syscall === 'listen') {
+    const bind = portToString(port);
+    if (error.code === 'EACCES') {
+      console.log(red('Error: ') + yellow(bind) + red(' requires elevated privileges') + '\n');
+      process.exitCode = 1;
+    } else if (error.code === 'EADDRINUSE') {
+      console.log(red('Error: ') + yellow(bind) + red(' is already in use') + '\n');
+      process.exitCode = 1;
+    } else {
+      throw error;
+    }
+  } else {
+    throw error;
+  }
+}

package/index.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Matcher accepted by `throws`, `rejects`, and `resolves`.
+ *
+ * - An `Error` subclass — checks `instanceof`.
+ * - A `RegExp` — tested against the error's `message` (or `String(value)` for non-Errors).
+ * - A predicate function — called with the value; truthy return = match.
+ * - An object pattern — uses deep6's `match` for structural matching.
+ * - `null` or any primitive — strict equality.
+ */
+export type AssertionMatcher =
+  | (new (...args: any[]) => Error)
+  | RegExp
+  | ((value: unknown) => boolean)
+  | object
+  | null;
+
 /**
  * Test options
  */
@@ -501,6 +517,19 @@ export declare interface Tester {
    * @param message - Optional message to display if the assertion fails
    */
   throws(fn: () => void, message?: string): void;
+  /**
+   * Asserts that `fn` throws an error matching `matcher`.
+   * `matcher` may be:
+   * - an `Error` subclass (checks `instanceof`)
+   * - a `RegExp` (tested against the error's message, or `String(error)` for non-Errors)
+   * - a predicate function (called with the thrown value; truthy return = match)
+   * - an object pattern (uses deep6's `match`)
+   * - `null` or any primitive (strict equality)
+   * @param fn - The function to test
+   * @param matcher - The matcher to apply to the thrown value
+   * @param message - Optional message to display if the assertion fails
+   */
+  throws(fn: () => void, matcher: AssertionMatcher, message?: string): void;
 
   /**
    * Asserts that `fn` does not throw an error.
@@ -547,6 +576,14 @@ export declare interface Tester {
    * @param message - Optional message to display if the assertion fails
    */
   rejects(promise: Promise<unknown>, message?: string): Promise<void>;
+  /**
+   * Asserts that `promise` is rejected with a reason matching `matcher`.
+   * See `throws` for the `matcher` semantics.
+   * @param promise - The promise to test
+   * @param matcher - The matcher to apply to the rejection reason
+   * @param message - Optional message to display if the assertion fails
+   */
+  rejects(promise: Promise<unknown>, matcher: AssertionMatcher, message?: string): Promise<void>;
 
   /**
    * Asserts that `promise` is resolved.
@@ -554,6 +591,14 @@ export declare interface Tester {
    * @param message - Optional message to display if the assertion fails
    */
   resolves(promise: Promise<unknown>, message?: string): Promise<void>;
+  /**
+   * Asserts that `promise` is resolved with a value matching `matcher`.
+   * See `throws` for the `matcher` semantics (applied to the resolved value).
+   * @param promise - The promise to test
+   * @param matcher - The matcher to apply to the resolved value
+   * @param message - Optional message to display if the assertion fails
+   */
+  resolves(promise: Promise<unknown>, matcher: AssertionMatcher, message?: string): Promise<void>;
 
   /**
    * Returns a code as a string for evaluation that checks if the condition is truthy.
@@ -818,6 +863,17 @@ export declare interface Tester {
    * @param message - Optional message to display if the assertion fails
    */
   doesNotResolve(promise: Promise<unknown>, message?: string): Promise<void>;
+  /**
+   * Asserts that `promise` is rejected with a reason matching `matcher`. Alias of `rejects`.
+   * @param promise - The promise to test
+   * @param matcher - The matcher to apply to the rejection reason
+   * @param message - Optional message to display if the assertion fails
+   */
+  doesNotResolve(
+    promise: Promise<unknown>,
+    matcher: AssertionMatcher,
+    message?: string
+  ): Promise<void>;
 
   /**
    * Asserts that `promise` is resolved. Alias of `resolves`.
@@ -825,6 +881,17 @@ export declare interface Tester {
    * @param message - Optional message to display if the assertion fails
    */
   doesNotReject(promise: Promise<unknown>, message?: string): Promise<void>;
+  /**
+   * Asserts that `promise` is resolved with a value matching `matcher`. Alias of `resolves`.
+   * @param promise - The promise to test
+   * @param matcher - The matcher to apply to the resolved value
+   * @param message - Optional message to display if the assertion fails
+   */
+  doesNotReject(
+    promise: Promise<unknown>,
+    matcher: AssertionMatcher,
+    message?: string
+  ): Promise<void>;
 
   /**
    * Returns a code as a string for evaluation that checks if the condition is truthy.

package/llms-full.txt

@@ -257,6 +257,108 @@ test('suite', opts, async t => {
 
 Multiple hooks of the same type run in registration order (before) or reverse order (after).
 
+## Subpath modules
+
+Two helper modules ship as separate subpath imports for tests that need HTTP-shaped fixtures. Both are cross-runtime (Node, Bun, Deno via `node:http`); browsers don't need them because running an HTTP server inside a webpage isn't a use case.
+
+### tape-six/server — HTTP server harness
+
+```js
+import {withServer, startServer, setupServer} from 'tape-six/server';
+```
+
+#### `withServer(serverHandler, clientHandler, opts?)` — scoped resource (95% case)
+
+Spins up an `http.Server` with `serverHandler`, runs `clientHandler` with the bound base URL, tears down in `finally`. Cleanup runs whether `clientHandler` resolves, rejects, or throws synchronously. Returns whatever `clientHandler` returns.
+
+```js
+test('GET / returns 200', t =>
+  withServer(handler, async base => {
+    const res = await fetch(`${base}/`);
+    t.equal(res.status, 200);
+  }));
+```
+
+`serverHandler` is the per-request callback Node invokes on each incoming request. `clientHandler` is the per-scope test body, called once with `(base, lifecycle)` — naming reflects role on the wire (server side / client side), not which side is the SUT. Either side may be the code under test.
+
+`clientHandler` may make HTTP requests itself (`fetch(base)`-style), or set up a separate SUT that does (e.g., a spawned CLI given `${base}` as its endpoint env var), or do neither (multi-phase setup + assertions).
+
+#### `startServer(server, opts?)` — procedural primitive
+
+For multi-phase tests that span the lifecycle, or non-test code (e.g. `bin/tape6-server`) that wants long-term control. Accepts a fully-constructed `http.Server` (so callers can attach `'clientError'` handlers, configure TLS, etc., before listen).
+
+```js
+const lc = await startServer(http.createServer(handler), {host, port});
+// ... use lc.base ...
+await lc.close();
+```
+
+Returns a lifecycle handle:
+
+- `server` — the underlying `http.Server`.
+- `base` — bound base URL, e.g. `"http://127.0.0.1:54321"`.
+- `port` — actual bound port (OS-assigned when `port: 0`).
+- `host` — bound host.
+- `close()` — idempotent. Calls `server.closeAllConnections()` (when available) so keep-alive sockets don't delay teardown.
+
+Races `'listening'` against `'error'`: port-busy / `EACCES` rejects with the original error rather than hanging. Existing helpers across the toolkit ecosystem don't do this and have hung CI machines as a result.
+
+#### `setupServer(serverHandler, opts?)` — hook helper
+
+Registers `beforeAll` (start) and `afterAll` (close) and returns a live-getter handle for suite-shared servers:
+
+```js
+const server = setupServer(handler);
+
+test('first', async t => {
+  const res = await fetch(`${server.base}/foo`);
+});
+
+test('second', async t => {
+  const res = await fetch(`${server.base}/bar`);
+});
+```
+
+The returned object is `Object.freeze`d and uses property getters that read the live lifecycle. Don't destructure at module load (`const {base} = setupServer(...)`) — `base` is `undefined` until `beforeAll` runs.
+
+State reset stays user-side. For mock-server scenarios that need per-test state clearing, compose your own `beforeEach`:
+
+```js
+const server = setupServer((req, res) => {
+  recorded.push({method: req.method, url: req.url});
+  res.writeHead(204).end();
+});
+let recorded;
+beforeEach(() => { recorded = []; });
+```
+
+`setupServer` owns the suite lifecycle; the caller owns suite state.
+
+#### Options
+
+```ts
+interface ServerOptions {
+  host?: string;  // default '127.0.0.1' — explicit IPv4 avoids dual-stack ambiguity
+  port?: number;  // default 0 — OS-assigned
+}
+```
+
+### tape-six/response — HTTP response helpers
+
+Reading helpers that work uniformly with both `Response` (fetch results) and Node `http.IncomingMessage`:
+
+```js
+import {asText, asJson, asBytes, header, headers} from 'tape-six/response';
+```
+
+- `asText(res)` → `Promise<string>` — body as UTF-8.
+- `asJson(res)` → `Promise<unknown>` — body parsed as JSON.
+- `asBytes(res)` → `Promise<Uint8Array>` — body as raw bytes.
+- `header(res, name)` → `string | null` — case-insensitive single-header read. Array-valued `IncomingMessage` headers (e.g. `set-cookie`) are joined with `, `.
+- `headers(res)` → `Record<string, string>` — all headers as a plain object with lowercase keys.
+
+For status code, just use `res.status` — same on both `Response` and `IncomingMessage`.
+
 ## Configuring tests
 
 Configuration is read from `tape6.json` or the `"tape6"` section of `package.json`: