@zukhruf/testing 0.3.18 → 0.3.20

package/README.md

@@ -10,6 +10,7 @@ Each area has its own import path, so a test loads only the drivers it uses. The
 
 | Import                        | Gives                                                                                   | Needs                    |
 | ----------------------------- | --------------------------------------------------------------------------------------- | ------------------------ |
+| `@zukhruf/testing/node`       | Native `test`, `it`, `suite`, `describe` with `.each`                                   |                          |
 | `@zukhruf/testing/async`      | `timebox`, `settleWithin`                                                               |                          |
 | `@zukhruf/testing/docker`     | `Docker`, `Container`, `ServiceContainer`, `DockerVolume`, `DockerDirectory`, `TestRun` | Docker CLI               |
 | `@zukhruf/testing/postgres`   | `Postgres`                                                                              | Docker CLI               |
@@ -23,6 +24,46 @@ Each area has its own import path, so a test loads only the drivers it uses. The
 | `@zukhruf/testing/http`       | `HttpServer`                                                                            |                          |
 | `@zukhruf/testing/streams`    | `StreamHarness`                                                                         |                          |
 
+## Parameterized tests
+
+Import `test` or `it` from `@zukhruf/testing/node` to repeat native test declarations over a table. Use `suite` or `describe` for suites across implementations or configurations.
+
+```ts
+import { describe, test } from '@zukhruf/testing/node';
+
+void test.each(
+  [
+    { name: 'integer', input: '42', expected: 42 },
+    { name: 'decimal', input: '1.5', expected: 1.5 },
+  ],
+  (row) =>
+    test(row.name, { timeout: 1_000 }, (t) => {
+      t.assert.equal(Number(row.input), row.expected);
+    }),
+);
+
+void describe.each(['utf8', 'utf16le'] as const, (encoding) =>
+  describe(encoding, () => {
+    test('round-trips text', (t) => {
+      t.assert.equal(
+        Buffer.from('hello', encoding).toString(encoding),
+        'hello',
+      );
+    });
+  }),
+);
+```
+
+Both methods accept `(rows, register)`. The rows are a readonly array; scalars, objects, tuples, and factories keep their inferred types. `register(row, index)` must return the native `test()` or `suite()` promise. Names, options, modifiers, and contexts belong to that native call. An empty table or a callback that returns no promise throws during registration.
+
+Call native `test()` or `suite()` directly in the callback in your test file. This preserves Node's declaration location for reports, navigation, and saved-failure reruns. The earlier `(rows, name, [options], body)` prototype registered inside the shared helper and has been removed because those locations collided across files.
+
+Inside an asynchronous parent test, `await test.each(...)` to keep that parent alive until its subtests finish. Call `t.test()` in the registration callback when using the parent's assertion plan. Node controls subtest concurrency through the parent. Inside a suite, native declaration promises fulfill immediately. Acquire and dispose fixtures inside each test body.
+
+These are the original native function objects with an added property: `test === it` and `suite === describe`. Their extended types are available through this import, without globally augmenting `node:test`. This area imports only Node built-ins.
+
+TAP, spec, simultaneous JUnit output, name filtering, skip/TODO reasons, failure exit status, default snapshots, and saved-failure reruns across multiple files are covered by this area's tests. Snapshots belong to the test entry file. Rerun regression tests check actual body execution through persistent failures, a subsequent fix, and replay of the passing results.
+
 ## Docker
 
 A `Docker` is the engine the Docker CLI selects. It resolves the engine once, on first use, and every handle it returns keeps that engine. It supports local Unix sockets, Docker Desktop's named pipe on Windows (`npipe://`), and SSH engines (`ssh://`).

package/dist/node/index.d.ts

@@ -0,0 +1,13 @@
+import { suite as nodeSuite, test as nodeTest } from 'node:test';
+/** Calls register synchronously for each row and waits for every native declaration. */
+declare function each<Row>(rows: readonly Row[], register: (row: Row, index: number) => Promise<void>): Promise<void>;
+/** Return a native test() call from the callback to preserve its declaration location. */
+export declare const test: typeof nodeTest & {
+    each: typeof each;
+};
+/** Return a native suite() call from the callback; acquire resources inside its tests. */
+export declare const suite: typeof nodeSuite & {
+    each: typeof each;
+};
+export { suite as describe, test as it };
+//# sourceMappingURL=index.d.ts.map

package/dist/node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGjE,wFAAwF;AACxF,iBAAS,IAAI,CAAC,GAAG,EACf,IAAI,EAAE,SAAS,GAAG,EAAE,EACpB,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACnD,OAAO,CAAC,IAAI,CAAC,CAWf;AAED,0FAA0F;AAC1F,eAAO,MAAM,IAAI;;CAAoC,CAAC;AACtD,0FAA0F;AAC1F,eAAO,MAAM,KAAK;;CAAqC,CAAC;AACxD,OAAO,EAAE,KAAK,IAAI,QAAQ,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC"}

package/dist/node/index.js

@@ -0,0 +1,20 @@
+import { suite as nodeSuite, test as nodeTest } from 'node:test';
+import { isPromise } from 'node:util/types';
+/** Calls register synchronously for each row and waits for every native declaration. */
+function each(rows, register) {
+    if (rows.length === 0)
+        throw new Error('each() requires at least one case');
+    return Promise.all(rows.map((row, index) => {
+        const registration = register(row, index);
+        if (!isPromise(registration)) {
+            throw new TypeError('each() callback must return test() or suite()');
+        }
+        return registration;
+    })).then(() => undefined);
+}
+/** Return a native test() call from the callback to preserve its declaration location. */
+export const test = Object.assign(nodeTest, { each });
+/** Return a native suite() call from the callback; acquire resources inside its tests. */
+export const suite = Object.assign(nodeSuite, { each });
+export { suite as describe, test as it };
+//# sourceMappingURL=index.js.map

package/dist/node/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,wFAAwF;AACxF,SAAS,IAAI,CACX,IAAoB,EACpB,QAAoD;IAEpD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IAC5E,OAAO,OAAO,CAAC,GAAG,CAChB,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QACtB,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,SAAS,CAAC,+CAA+C,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,YAAY,CAAC;IACtB,CAAC,CAAC,CACH,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;AAC1B,CAAC;AAED,0FAA0F;AAC1F,MAAM,CAAC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AACtD,0FAA0F;AAC1F,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AACxD,OAAO,EAAE,KAAK,IAAI,QAAQ,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zukhruf/testing",
-  "version": "0.3.18",
+  "version": "0.3.20",
   "description": "Disposable fixtures for integration tests: Docker containers and database servers, SQLite and DuckDB databases, HTTP servers and streams. A supervisor removes what a killed test run left behind.",
   "license": "MIT",
   "repository": {
@@ -29,6 +29,12 @@
   },
   "exports": {
     "./package.json": "./package.json",
+    "./node": {
+      "@zukhruf/source": "./src/node/index.ts",
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js",
+      "default": "./dist/node/index.js"
+    },
     "./async": {
       "@zukhruf/source": "./src/async/index.ts",
       "types": "./dist/async/index.d.ts",