tape-six 1.8.0 → 1.9.0

package/README.md

@@ -319,7 +319,7 @@ The following methods are available (all `msg` arguments are optional):
   - `any` — a symbol that can be used in deep equivalency asserts to match any value.
     See [deep6's any](https://github.com/uhop/deep6/wiki/any) for details.
     - `_` — an alias of `any`.
-  - `plan(n)` — sets the number of tests in the test suite. Rarely used.
+  - `plan(n)` — records the expected number of direct assertions; emits a TAP-comment diagnostic at test end if the count diverges (does not fail the test).
   - `comment(msg)` — sends a comment to the test harness. Rarely used.
   - `skipTest(...args, msg)` — skips the current test yet sends a message to the test harness.
   - `bailOut(msg)` — stops the test suite and sends a message to the test harness.
@@ -425,8 +425,9 @@ 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.9.0 _New features: `t.plan(n)` emits a TAP-comment diagnostic on mismatch, `registerTesterMethod(name, fn)` registers tester plugins idempotently. New wiki: 3rd-party library catalog and "Writing plugins" page. Removed `chai` from dev dependencies._
+- 1.8.0 _New subpath modules: `tape-six/server` (HTTP server harness) and `tape-six/response` (response reading helpers for `Response` and `IncomingMessage`)._
+- 1.7.14 _Updated vendored `deep6` to 1.2.0._
 - 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

@@ -221,7 +221,7 @@ By default tests have **no timeout**. Set `timeout` per test, or wrap a fixture
 - `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.plan(n)` — record the expected number of direct assertions. If the count diverges at test end, a `# plan != count: expected N, ran M` TAP comment is emitted (diagnostic only, doesn't fail the test). Subtest assertions don't count toward the parent's plan.
 - `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

package/index.d.ts

@@ -95,8 +95,11 @@ export declare interface Tester {
   signal: AbortSignal;
 
   /**
-   * Plans the number of assertions that will be run. Unused.
-   * @param n - The number of assertions
+   * Records the expected number of direct assertions. When the test ends, a
+   * `# plan != count: expected N, ran M` TAP comment is emitted if the count
+   * diverges. Diagnostic only — does not fail the test. Subtest assertions
+   * don't count toward the parent's plan.
+   * @param n - The expected number of assertions (non-negative integer)
    */
   plan(n: number): void;
 
@@ -1251,4 +1254,29 @@ export declare const before: typeof test.before;
  */
 export declare const after: typeof test.after;
 
+/**
+ * Idempotently install a method on `Tester.prototype` so it appears as a
+ * method on every tester instance (`t.<name>(...)`). Same name + same function
+ * is a no-op (allows duplicate side-effect imports). Same name + a different
+ * function throws so collisions surface loudly.
+ *
+ * Usage from a plugin module (e.g., `tape-six-spawn`):
+ *
+ * ```ts
+ * import {registerTesterMethod} from 'tape-six/Tester.js';
+ *
+ * declare module 'tape-six' {
+ *   interface Tester {
+ *     spawnBin(bin: string, args: string[]): Promise<{code: number; stdout: string; stderr: string}>;
+ *   }
+ * }
+ *
+ * registerTesterMethod('spawnBin', async function (bin, args) { ... });
+ * ```
+ *
+ * @param name - non-empty method name
+ * @param fn - function to install on `Tester.prototype`
+ */
+export declare const registerTesterMethod: (name: string, fn: (...args: any[]) => any) => void;
+
 export default test;

package/index.js

@@ -254,6 +254,8 @@ if (!getConfiguredFlag()) {
   registerNotifyCallback(testRunner);
 }
 
+export {registerTesterMethod} from './src/Tester.js';
+
 export {
   test,
   before,

package/llms-full.txt

@@ -10,7 +10,7 @@
 - Before/after hooks: `beforeAll`, `afterAll`, `beforeEach`, `afterEach`
 - `test()` is aliased as `suite()`, `describe()`, and `it()` for easy migration
 - When called inside a test body, top-level functions auto-delegate to the current tester
-- Compatible with `AssertionError`-based libraries like `node:assert` and `chai`
+- BYO assertion / mocking / property-based libs: `node:assert`, `chai`, `expect`, `node:test` mock, `sinon`, `fast-check`
 
 ## Quick start
 
@@ -192,7 +192,7 @@ The `Tester` object is passed to test functions. All `msg` arguments are optiona
 
 ### Miscellaneous
 
-- `plan(n)` — set expected number of assertions.
+- `plan(n)` — record expected number of direct assertions. On test end, emits a `# plan != count: expected N, ran M` TAP comment if the count diverges (diagnostic only, doesn't fail the test). Subtest assertions don't count toward the parent's plan.
 - `comment(msg)` — send a comment to the reporter.
 - `skipTest(...args, msg)` — skip current test with a message.
 - `bailOut(msg)` — abort the test suite.
@@ -257,6 +257,28 @@ test('suite', opts, async t => {
 
 Multiple hooks of the same type run in registration order (before) or reverse order (after).
 
+## Plugins
+
+Tester methods can be added via `registerTesterMethod(name, fn)`. Same name + same fn → no-op (idempotent re-import); same name + different fn → throws (loud collision detection).
+
+```js
+import {registerTesterMethod} from 'tape-six';
+
+registerTesterMethod('spawnBin', async function (bin, args) {
+  // ... implementation, can call this.equal(...), this.reporter.report({...}), etc.
+});
+
+// then in tests:
+test('cli', async t => {
+  const {code} = await t.spawnBin('node', ['-v']);
+  t.equal(code, 0);
+});
+```
+
+`Tester` is declared as an `interface` in `index.d.ts` to make TS module augmentation natural — plugins extend the interface, no full class shape needed. The built-in `t.OK()` evaluator (`src/OK.js`) uses this exact pattern.
+
+Plugin installation is **per-file**. `tape6-seq` runs all files in one process; `tape6` uses workers; `tape6-proc` (from the sister package `tape-six-proc`) uses subprocesses; browser tests run in iframes. Each isolation context has its own module graph, so a plugin import in file A is invisible to file B when they're in different contexts. Every test file that uses a plugin must import it directly. `registerTesterMethod`'s idempotency makes repeated imports safe. See [Writing plugins](https://github.com/uhop/tape-six/wiki/Writing-plugins) for the full guide.
+
 ## 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.
@@ -473,19 +495,18 @@ Browser: `http://localhost:3000/?flags=FO`
 - tape-six-puppeteer (https://www.npmjs.com/package/tape-six-puppeteer) — automates browser testing with Puppeteer.
 - tape-six-playwright (https://www.npmjs.com/package/tape-six-playwright) — automates browser testing with Playwright.
 
-## 3rd-party assertion libraries
+## 3rd-party libraries (bring-your-own)
 
-`tape-six` supports `AssertionError`-based assertions. You can use `node:assert` or `chai` inside test functions:
+`tape-six` doesn't bundle assertion / mock / property-based libraries. It catches whatever the test throws — anything throwing a node-compatible `AssertionError` (with `name`, `operator`, `actual`, `expected`) is reported as a regular assertion; other errors are reported as `UNEXPECTED EXCEPTION` (test still fails).
 
-```js
-import test from 'tape-six';
-import {assert, expect} from 'chai';
+**Verified candidates** (full per-lib examples and browser importmap snippets in the wiki):
 
-test('with chai', t => {
-  expect(1).to.be.lessThan(2);
-  assert.deepEqual([1], [1]);
-});
-```
+- `node:assert` — built-in to Node/Bun/Deno, throws `AssertionError`. Cleanest path.
+- `chai` — `expect`/`should`/`assert` styles, throws `AssertionError`. Works in browsers via importmap entry.
+- `expect` (Jest's standalone) — throws plain `Error`, not `AssertionError`. Works but failures render as `UNEXPECTED EXCEPTION` with ANSI-colored messages. Wrap negative cases in `t.throws()`.
+- `node:test` mock — built-in spies/stubs/timers via `import {mock} from 'node:test'`. Doesn't throw; assert on `spy.mock.calls` with `t.*`.
+- `sinon` — same pattern as `node:test` mock. Assert on `spy.callCount` / `spy.firstCall.args`.
+- `fast-check` — property-based testing. Throws plain `Error` on counterexample (with seed + path for repro). Wrap negative cases in `t.throws()`.
 
 ```js
 import test from 'tape-six';
@@ -497,4 +518,18 @@ test('with node:assert', t => {
 });
 ```
 
+```js
+import test from 'tape-six';
+import {mock} from 'node:test';
+
+test('with node:test mock', t => {
+  const spy = mock.fn();
+  spy(1, 2);
+  t.equal(spy.mock.calls.length, 1);
+  t.deepEqual(spy.mock.calls[0].arguments, [1, 2]);
+});
+```
+
+Wiki: [3rd-party assertion libraries](https://github.com/uhop/tape-six/wiki/3rd%E2%80%90party-assertion-libraries), [mock libraries](https://github.com/uhop/tape-six/wiki/3rd%E2%80%90party-mock-libraries), [property-based testing](https://github.com/uhop/tape-six/wiki/3rd%E2%80%90party-property-based-testing).
+
 Assertions that throw `AssertionError` are automatically caught and reported.

package/llms.txt

@@ -105,11 +105,15 @@ The object passed to test functions. Provides assertions and test control.
 
 #### Utilities
 
-- `t.plan(n)` — declare expected assertion count (rarely needed).
+- `t.plan(n)` — record expected direct-assertion count; emits a `# plan != count: expected N, ran M` TAP comment at test end on mismatch (diagnostic, doesn't fail).
 - `t.comment(msg)` — emit a comment.
 - `t.skipTest(msg)` — skip current test with a message.
 - `t.bailOut(msg)` — abort entire test suite.
 
+### Plugins
+
+- `registerTesterMethod(name, fn)` — install a method on `Tester.prototype` from a plugin module. Idempotent for same `fn`; throws on collision with a different `fn`. Plugin imports are per-file (workers / subprocesses / iframes don't share module graphs).
+
 ### Hooks
 
 Hooks can be registered as standalone functions or via test options or Tester methods.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tape-six",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "TAP-inspired unit test library for Node, Deno, Bun, and browsers. ES modules, TypeScript, zero dependencies.",
   "type": "module",
   "main": "index.js",
@@ -98,21 +98,21 @@
       "/tests/test-*.cjs",
       "/tests/cli/test-*.js"
     ],
+    "node": [
+      "/tests/node/test-*.js"
+    ],
     "browser": [
       "/tests/browser/test-*.html"
     ],
     "importmap": {
       "imports": {
         "tape-six": "../index.js",
-        "tape-six/": "../src/",
-        "chai": "../node_modules/chai/index.js"
+        "tape-six/": "../src/"
       }
     }
   },
   "devDependencies": {
-    "@types/chai": "^5.2.3",
     "@types/node": "^25.6.0",
-    "chai": "^6.2.2",
     "typescript": "^6.0.3"
   }
 }

package/src/OK.js

@@ -1,4 +1,4 @@
-import {Tester, setAliases} from './Tester.js';
+import {registerTesterMethod, setAliases} from './Tester.js';
 
 // code mostly borrowed from https://github.com/heya/ice/blob/master/assert.js under BSD-3
 
@@ -22,7 +22,7 @@ const listVariables = (code, self) => {
   return '{' + result.join(',') + '}';
 };
 
-Tester.prototype.OK = function OK(condition, msg, options) {
+const OK = function OK(condition, msg, options) {
   if (typeof condition != 'string') {
     throw new TypeError('Condition must be a string');
   }
@@ -44,4 +44,5 @@ Tester.prototype.OK = function OK(condition, msg, options) {
 }))`;
 };
 
+registerTesterMethod('OK', OK);
 setAliases('OK', 'TRUE, ASSERT');

package/src/State.js

@@ -101,6 +101,8 @@ export class State {
     this.failOnce = failOnce || parent.failOnce;
     this.offset = parent.asserts || 0;
     this.asserts = this.skipped = this.failed = 0;
+    // direct assertions in this state only — not bumped by updateParent, used by t.plan()
+    this.localAsserts = 0;
     this.stopTest = false;
     this.timer = timer || parent.timer || getTimer();
     this.startTime = this.time = time || this.timer.now();
@@ -178,6 +180,7 @@ export class State {
 
     if (event.type === 'assert' || event.type === 'assertion-error') {
       ++this.asserts;
+      ++this.localAsserts;
       event.skip && ++this.skipped;
       isFailed && ++this.failed;
       event.id = this.asserts + this.offset;

package/src/Tester.js

@@ -48,8 +48,10 @@ export class Tester {
     return this.reporter.state;
   }
 
-  plan(_n) {
-    // nothing to do
+  plan(n) {
+    if (typeof n !== 'number' || !Number.isInteger(n) || n < 0)
+      throw new TypeError('plan(n) requires a non-negative integer');
+    this.planned = n;
   }
 
   comment(msg) {
@@ -448,8 +450,28 @@ export class Tester {
 }
 Tester.prototype.any = Tester.prototype._ = any;
 
-export const setAliases = (source, aliases) =>
-  aliases.split(', ').forEach(alias => (Tester.prototype[alias] = Tester.prototype[source]));
+// 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.
+export const registerTesterMethod = (name, fn) => {
+  if (typeof name !== 'string' || !name)
+    throw new TypeError('registerTesterMethod: name must be a non-empty string');
+  if (typeof fn !== 'function') throw new TypeError('registerTesterMethod: fn must be a function');
+  if (Object.prototype.hasOwnProperty.call(Tester.prototype, name)) {
+    if (Tester.prototype[name] !== fn)
+      throw new Error(
+        `registerTesterMethod: '${name}' is already registered with a different implementation`
+      );
+    return;
+  }
+  Tester.prototype[name] = fn;
+};
+
+export const setAliases = (source, aliases) => {
+  const fn = Tester.prototype[source];
+  aliases.split(', ').forEach(alias => registerTesterMethod(alias, fn));
+};
 
 setAliases('ok', 'true, assert');
 setAliases('notOk', 'false, notok');

package/src/test.js

@@ -227,6 +227,19 @@ export const runTests = async tests => {
     await tester.dispose();
     await tester.state?.runAfterAll();
     testers.pop();
+    if (
+      tester.planned !== undefined &&
+      !tester.state?.skip &&
+      tester.state?.localAsserts !== tester.planned
+    ) {
+      tester.reporter.report({
+        type: 'comment',
+        name: `plan != count: expected ${tester.planned}, ran ${tester.state.localAsserts}`,
+        test: testNumber,
+        marker: new Error(),
+        time: tester.timer.now()
+      });
+    }
     tester.reporter.report({
       type: 'end',
       name: options.name,