tape-six 1.7.0 → 1.7.2

package/llms.txt

@@ -0,0 +1,243 @@
+# tape-six
+
+> TAP-based unit test library for modern JavaScript and TypeScript. Works in Node, Deno, Bun, and browsers.
+
+## Install
+
+npm i -D tape-six
+
+## Quick start
+
+```js
+import test from 'tape-six';
+
+test('my test', async t => {
+  t.ok(true, 'truthy value');
+  t.equal(1 + 1, 2, 'addition works');
+  t.deepEqual({a: 1}, {a: 1}, 'objects are equal');
+});
+```
+
+Run: `node my-test.js` or `npx tape6 --flags FO`
+
+## API
+
+### test(name, options, testFn)
+
+Registers a test. All three arguments are optional and can be in any order (recognized by type).
+
+- `name` (string) — test name. Defaults to function name or '(anonymous)'.
+- `options` (object) — see TestOptions below.
+- `testFn` (function) — `async (t: Tester) => void`. Can be sync or async.
+
+Returns a promise that resolves when the test finishes. Usually no need to await.
+
+Aliases: `suite`, `describe`, `it` — all are the same function.
+
+```js
+import {test, describe, it, suite} from 'tape-six';
+```
+
+#### test.skip(name, options, testFn)
+
+Registers a test that will be skipped (not executed).
+
+#### test.todo(name, options, testFn)
+
+Registers a test marked as work-in-progress. Failures are reported but not counted.
+
+#### test.asPromise(name, options, testPromiseFn)
+
+Registers a test using callback-style completion: `(t, resolve, reject) => void`.
+
+### TestOptions
+
+- `name` (string) — test name.
+- `testFn` (function) — test function.
+- `skip` (boolean) — skip this test.
+- `todo` (boolean) — mark as TODO.
+- `timeout` (number) — timeout in ms. Test is marked failed if exceeded.
+- `beforeAll` / `before` (function) — run before all embedded tests.
+- `afterAll` / `after` (function) — run after all embedded tests.
+- `beforeEach` (function) — run before each embedded test.
+- `afterEach` (function) — run after each embedded test.
+
+### Tester (the `t` object)
+
+The object passed to test functions. Provides assertions and test control.
+
+#### Properties
+
+- `t.signal` — AbortSignal, aborted when test times out. Use for cancellation.
+- `t.any` (or `t._`) — symbol for matching any value in deepEqual/match.
+
+#### Assertions (all `msg` arguments are optional)
+
+- `t.pass(msg)` — unconditional pass.
+- `t.fail(msg)` — unconditional fail.
+- `t.ok(value, msg)` — assert truthy. Aliases: `true`, `assert`.
+- `t.notOk(value, msg)` — assert falsy. Aliases: `false`, `notok`.
+- `t.error(err, msg)` — assert err is falsy. Aliases: `ifError`, `ifErr`, `iferror`.
+- `t.strictEqual(a, b, msg)` — assert `a === b`. Aliases: `is`, `equal`, `equals`, `isEqual`, `strictEquals`.
+- `t.notStrictEqual(a, b, msg)` — assert `a !== b`. Aliases: `not`, `notEqual`, `notEquals`, `isNotEqual`, `doesNotEqual`, `isUnequal`, `notStrictEquals`, `isNot`.
+- `t.looseEqual(a, b, msg)` — assert `a == b`. Alias: `looseEquals`.
+- `t.notLooseEqual(a, b, msg)` — assert `a != b`. Alias: `notLooseEquals`.
+- `t.deepEqual(a, b, msg)` — recursive strict deep equality. Aliases: `same`, `deepEquals`, `isEquivalent`.
+- `t.notDeepEqual(a, b, msg)` — assert not deeply equal. Aliases: `notSame`, `notDeepEquals`, `notEquivalent`, `notDeeply`, `isNotDeepEqual`, `isNotEquivalent`.
+- `t.deepLooseEqual(a, b, msg)` — recursive loose deep equality.
+- `t.notDeepLooseEqual(a, b, msg)` — assert not deeply loosely equal.
+- `t.throws(fn, msg)` — assert fn() throws.
+- `t.doesNotThrow(fn, msg)` — assert fn() does not throw.
+- `t.matchString(string, regexp, msg)` — assert string matches regexp.
+- `t.doesNotMatchString(string, regexp, msg)` — assert string does not match regexp.
+- `t.match(a, b, msg)` — assert a matches pattern b (structural).
+- `t.doesNotMatch(a, b, msg)` — assert a does not match pattern b.
+- `t.rejects(promise, msg)` — assert promise rejects. **Async: must await.** Alias: `doesNotResolve`.
+- `t.resolves(promise, msg)` — assert promise resolves. **Async: must await.** Alias: `doesNotReject`.
+
+#### Embedded tests (all async, should be awaited)
+
+- `await t.test(name, options, testFn)` — nested test.
+- `await t.skip(name, options, testFn)` — nested skipped test.
+- `await t.todo(name, options, testFn)` — nested TODO test.
+- `await t.asPromise(name, options, testPromiseFn)` — nested callback-style test.
+
+#### Utilities
+
+- `t.plan(n)` — declare expected assertion count (rarely needed).
+- `t.comment(msg)` — emit a comment.
+- `t.skipTest(msg)` — skip current test with a message.
+- `t.bailOut(msg)` — abort entire test suite.
+
+### Hooks
+
+Hooks can be registered as standalone functions or via test options or Tester methods.
+
+```js
+import {test, beforeAll, afterAll, beforeEach, afterEach} from 'tape-six';
+// `before` is an alias for `beforeAll`, `after` is an alias for `afterAll`.
+
+beforeAll(() => { /* runs once before all tests */ });
+afterAll(() => { /* runs once after all tests */ });
+beforeEach(() => { /* runs before each test */ });
+afterEach(() => { /* runs after each test */ });
+
+// Or inside a test:
+test('suite', async t => {
+  t.beforeAll(() => { /* before embedded tests */ });
+  t.afterAll(() => { /* after embedded tests */ });
+  t.beforeEach(() => { /* before each embedded test */ });
+  t.afterEach(() => { /* after each embedded test */ });
+
+  await t.test('inner', t => { t.pass(); });
+});
+
+// Or via test.beforeAll(), test.afterAll(), etc:
+test.beforeAll(() => { /* ... */ });
+```
+
+## Common patterns
+
+### Basic test file
+
+```js
+import test from 'tape-six';
+
+test('arithmetic', t => {
+  t.equal(2 + 2, 4, 'addition');
+  t.ok(10 > 5, 'comparison');
+});
+
+test('async operation', async t => {
+  const result = await fetchData();
+  t.ok(result, 'got result');
+  t.equal(result.status, 200, 'status is 200');
+});
+```
+
+### 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');
+});
+```
+
+### Nested tests with setup/teardown
+
+```js
+test('database tests', async t => {
+  let db;
+  t.beforeAll(async () => { db = await connect(); });
+  t.afterAll(async () => { await db.close(); });
+
+  await t.test('insert', async t => {
+    const result = await db.insert({name: 'Alice'});
+    t.ok(result.id, 'got an id');
+  });
+
+  await t.test('query', async t => {
+    const rows = await db.query('SELECT * FROM users');
+    t.ok(rows.length > 0, 'has rows');
+  });
+});
+```
+
+### Using any for partial matching
+
+```js
+test('partial match', t => {
+  const result = {id: 123, name: 'Alice', timestamp: Date.now()};
+  t.deepEqual(result, {id: 123, name: 'Alice', timestamp: t.any});
+});
+```
+
+### Using describe/it style
+
+```js
+import {describe, it} from 'tape-six';
+
+describe('my module', () => {
+  it('should work', t => {
+    t.ok(true);
+  });
+});
+```
+
+### Skip and TODO
+
+```js
+test.skip('not ready yet', t => { t.fail(); });
+test.todo('work in progress', t => { t.equal(1, 2); }); // failure not counted
+```
+
+## Running tests
+
+```bash
+node test-file.js          # run single file directly
+npx tape6 --flags FO       # run all configured tests, show failures only + fail once
+npx tape6-seq              # run sequentially (no worker threads)
+npx tape6-server --trace   # start browser test server
+```
+
+## Configuration (package.json)
+
+```json
+{
+  "scripts": {
+    "test": "tape6 --flags FO"
+  },
+  "tape6": {
+    "tests": ["/tests/test-*.*js"]
+  }
+}
+```
+
+## Links
+
+- Docs: https://github.com/uhop/tape-six/wiki
+- npm: https://www.npmjs.com/package/tape-six
+- Full LLM reference: https://github.com/uhop/tape-six/blob/master/llms-full.txt

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tape-six",
-  "version": "1.7.0",
-  "description": "The test harness for the modern JavaScript and TypeScript.",
+  "version": "1.7.2",
+  "description": "TAP-based unit test library for Node, Deno, Bun, and browsers. ES modules, TypeScript, zero dependencies.",
   "type": "module",
   "main": "index.js",
   "module": "index.js",
@@ -13,6 +13,7 @@
   },
   "bin": {
     "tape6": "bin/tape6.js",
+    "tape6-node": "bin/tape6-node.js",
     "tape6-bun": "bin/tape6-bun.js",
     "tape6-deno": "bin/tape6-deno.js",
     "tape6-seq": "bin/tape6-seq.js",
@@ -30,8 +31,8 @@
     "test:bun": "bun run ./bin/tape6-bun.js --flags FO",
     "test:deno": "deno run -A ./bin/tape6-deno.js --flags FO",
     "test:seq": "node ./bin/tape6-seq.js --flags FO",
-    "test:bun:seq": "bun run ./bin/tape6-seq.js --flags FO",
-    "test:deno:seq": "deno run -A ./bin/tape6-seq.js --flags FO",
+    "test:seq:bun": "bun run ./bin/tape6-seq.js --flags FO",
+    "test:seq:deno": "deno run -A ./bin/tape6-seq.js --flags FO",
     "test:puppeteer": "node tests/puppeteer-chrome.js",
     "test:playwright": "node tests/playwright-chrome.js",
     "ts-check": "tsc --noEmit",
@@ -49,7 +50,18 @@
     "test",
     "harness",
     "assert",
-    "browser"
+    "browser",
+    "unit-test",
+    "testing",
+    "test-runner",
+    "esm",
+    "es-modules",
+    "typescript",
+    "deno",
+    "bun",
+    "nodejs",
+    "tap-protocol",
+    "cross-runtime"
   ],
   "author": "Eugene Lazutkin <eugene.lazutkin@gmail.com> (https://www.lazutkin.com/)",
   "funding": "https://github.com/sponsors/uhop",
@@ -58,11 +70,15 @@
     "url": "https://github.com/uhop/tape-six/issues"
   },
   "homepage": "https://github.com/uhop/tape-six#readme",
+  "llms": "https://raw.githubusercontent.com/uhop/tape-six/master/llms.txt",
+  "llmsFull": "https://raw.githubusercontent.com/uhop/tape-six/master/llms-full.txt",
   "files": [
     "index.*",
     "bin",
     "web-app",
-    "src"
+    "src",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "tape6": {
     "tests": [
@@ -85,10 +101,10 @@
   },
   "devDependencies": {
     "@types/chai": "^5.2.3",
-    "@types/node": "^25.2.1",
+    "@types/node": "^25.3.0",
     "chai": "^6.2.2",
     "playwright": "^1.58.2",
-    "puppeteer": "^24.37.2",
+    "puppeteer": "^24.37.5",
     "typescript": "^5.9.3"
   }
 }

package/src/reporters/MinReporter.js

@@ -0,0 +1,37 @@
+import Reporter from './Reporter.js';
+
+const getEnvVar = name => {
+  if (typeof Deno == 'object' && Deno?.version) {
+    return Deno.env.get(name);
+  } else if (typeof Bun == 'object' && Bun?.version) {
+    return Bun.env[name];
+  } else if (typeof process == 'object' && process?.versions?.node) {
+    return process.env[name];
+  }
+  return undefined;
+};
+
+export class MinReporter extends Reporter {
+  constructor({failOnce = false, originalConsole} = {}) {
+    super({failOnce});
+    this.console = originalConsole || console;
+  }
+  report(event) {
+    event = this.state?.preprocess(event) || event;
+    const handler = Reporter.EVENT_MAP[event.type];
+    typeof handler == 'string' && this[handler]?.(event);
+    this.console.log(
+      'Test:',
+      event.test,
+      'Type:',
+      event.type,
+      'Name:',
+      event.name,
+      'Fail:',
+      event.fail
+    );
+    this.state?.postprocess(event);
+  }
+}
+
+export default MinReporter;

package/src/reporters/TTYReporter.js

@@ -58,7 +58,7 @@ export class TTYReporter extends Reporter {
     this.hasColors =
       hasColors &&
       this.output.isTTY &&
-      (typeof this.output.hasColors == 'function' ? this.output.hasColors(256) : true);
+      (typeof this.output.hasColors == 'function' ? this.output.hasColors(16) : true);
     this.renumberAsserts = renumberAsserts;
     this.failureOnly = failureOnly;
     this.showBanner = showBanner;
@@ -221,7 +221,7 @@ export class TTYReporter extends Reporter {
               paint = method === 'error' || method === 'assert' ? 'stderrPaint' : 'stdoutPaint',
               prefix = this[paint](consoleDict[method] + ':') + ' ';
             for (const line of lines) {
-              this.out(prefix + line);
+              this.out(prefix + line, this.failureOnly);
             }
           }
         }
@@ -231,7 +231,7 @@ export class TTYReporter extends Reporter {
           const lines = event.name.split(/\r?\n/),
             prefix = this.stdoutPaint('stdout:') + ' ';
           for (const line of lines) {
-            this.out(prefix + line);
+            this.out(prefix + line, this.failureOnly);
           }
         }
         break;
@@ -240,7 +240,7 @@ export class TTYReporter extends Reporter {
           const lines = event.name.split(/\r?\n/),
             prefix = this.stderrPaint('stderr:') + ' ';
           for (const line of lines) {
-            this.out(prefix + line);
+            this.out(prefix + line, this.failureOnly);
           }
         }
         break;

package/src/runners/bun/worker.js

@@ -1,8 +1,36 @@
-const reportToParent = fileName => msg => {
-  if ((msg.type === 'test' || msg.type === 'end') && !msg.test && !msg.name) {
-    msg.name = 'FILE: /' + fileName;
-  }
-  postMessage(msg);
+const DEFAULT_START_TIMEOUT = 5_000;
+
+const getTimeout = () => {
+  const timeoutValue = Bun.env.TAPE6_WORKER_START_TIMEOUT;
+  if (!timeoutValue) return DEFAULT_START_TIMEOUT;
+  let timeout = Number(timeoutValue);
+  if (isNaN(timeout) || timeout <= 0 || timeout === Infinity) timeout = DEFAULT_START_TIMEOUT;
+  return timeout;
+};
+
+const reportToParent = fileName => {
+  const timeout = getTimeout();
+  let timeoutBeforeStartId = setTimeout(() => {
+    postMessage({type: 'test', test: 0, name: 'FILE: /' + fileName});
+    postMessage({
+      name: `No tests found in ${timeout}ms`,
+      test: 0,
+      marker: new Error(),
+      operator: 'error',
+      fail: true
+    });
+    postMessage({type: 'end', test: 0, name: 'FILE: /' + fileName, fail: true});
+  }, timeout);
+  return msg => {
+    if (timeoutBeforeStartId) {
+      clearTimeout(timeoutBeforeStartId);
+      timeoutBeforeStartId = null;
+    }
+    if ((msg.type === 'test' || msg.type === 'end') && !msg.test && !msg.name) {
+      msg.name = 'FILE: /' + fileName;
+    }
+    postMessage(msg);
+  };
 };
 
 addEventListener('message', async event => {

package/src/runners/deno/worker.js

@@ -1,8 +1,36 @@
-const reportToParent = fileName => msg => {
-  if ((msg.type === 'test' || msg.type === 'end') && !msg.test && !msg.name) {
-    msg.name = 'FILE: /' + fileName;
-  }
-  postMessage(msg);
+const DEFAULT_START_TIMEOUT = 5_000;
+
+const getTimeout = () => {
+  const timeoutValue = Deno.env.get('TAPE6_WORKER_START TIMEOUT');
+  if (!timeoutValue) return DEFAULT_START_TIMEOUT;
+  let timeout = Number(timeoutValue);
+  if (isNaN(timeout) || timeout <= 0 || timeout === Infinity) timeout = DEFAULT_START_TIMEOUT;
+  return timeout;
+};
+
+const reportToParent = fileName => {
+  const timeout = getTimeout();
+  let timeoutBeforeStartId = setTimeout(() => {
+    postMessage({type: 'test', test: 0, name: 'FILE: /' + fileName});
+    postMessage({
+      name: `No tests found in ${timeout}ms`,
+      test: 0,
+      marker: new Error(),
+      operator: 'error',
+      fail: true
+    });
+    postMessage({type: 'end', test: 0, name: 'FILE: /' + fileName, fail: true});
+  }, timeout);
+  return msg => {
+    if (timeoutBeforeStartId) {
+      clearTimeout(timeoutBeforeStartId);
+      timeoutBeforeStartId = null;
+    }
+    if ((msg.type === 'test' || msg.type === 'end') && !msg.test && !msg.name) {
+      msg.name = 'FILE: /' + fileName;
+    }
+    postMessage(msg);
+  };
 };
 
 addEventListener('message', async event => {

package/src/runners/node/worker.js

@@ -1,10 +1,39 @@
+import process from 'node:process';
 import {parentPort} from 'node:worker_threads';
 
-const reportToParent = fileName => msg => {
-  if ((msg.type === 'test' || msg.type === 'end') && !msg.test && !msg.name) {
-    msg.name = 'FILE: /' + fileName;
-  }
-  parentPort.postMessage(msg);
+const DEFAULT_START_TIMEOUT = 5_000;
+
+const getTimeout = () => {
+  const timeoutValue = process.env.TAPE6_WORKER_START_TIMEOUT;
+  if (!timeoutValue) return DEFAULT_START_TIMEOUT;
+  let timeout = Number(timeoutValue);
+  if (isNaN(timeout) || timeout <= 0 || timeout === Infinity) timeout = DEFAULT_START_TIMEOUT;
+  return timeout;
+};
+
+const reportToParent = fileName => {
+  const timeout = getTimeout();
+  let timeoutBeforeStartId = setTimeout(() => {
+    parentPort.postMessage({type: 'test', test: 0, name: 'FILE: /' + fileName});
+    parentPort.postMessage({
+      name: `No tests found in ${timeout}ms`,
+      test: 0,
+      marker: new Error(),
+      operator: 'error',
+      fail: true
+    });
+    parentPort.postMessage({type: 'end', test: 0, name: 'FILE: /' + fileName, fail: true});
+  }, timeout);
+  return msg => {
+    if (timeoutBeforeStartId) {
+      clearTimeout(timeoutBeforeStartId);
+      timeoutBeforeStartId = null;
+    }
+    if ((msg.type === 'test' || msg.type === 'end') && !msg.test && !msg.name) {
+      msg.name = 'FILE: /' + fileName;
+    }
+    parentPort.postMessage(msg);
+  };
 };
 
 parentPort.on('message', async msg => {

package/src/runners/seq/TestWorker.js

@@ -4,6 +4,7 @@ import {pathToFileURL} from 'node:url';
 
 import {isStopTest} from '../../State.js';
 import EventServer from '../../utils/EventServer.js';
+import {getTimeoutValue} from '../../utils/config.js';
 import {getOriginalConsole, setCurrentReporter} from '../../utils/capture-console.js';
 import {
   clearBeforeAll,
@@ -11,7 +12,8 @@ import {
   clearBeforeEach,
   clearAfterEach,
   setReporter,
-  registerNotifyCallback
+  registerNotifyCallback,
+  unregisterNotifyCallback
 } from '../../test.js';
 import BypassReporter from './BypassReporter.js';
 
@@ -23,10 +25,16 @@ export default class TestWorker extends EventServer {
     this.testRunner = options.testRunner;
     this.counter = 0;
     this.originalConsole = getOriginalConsole() || globalThis.console;
+    this.timeout = getTimeoutValue();
+    this.timeoutId = null;
   }
   makeTask(fileName) {
     const id = String(++this.counter),
       reporter = new BypassReporter(this.reporter, event => {
+        if (this.timeoutId) {
+          clearTimeout(this.timeoutId);
+          this.timeoutId = null;
+        }
         try {
           this.report(id, event);
         } catch (error) {
@@ -39,33 +47,22 @@ export default class TestWorker extends EventServer {
     setReporter(reporter);
     setCurrentReporter(this.reporter);
     process.env.TAPE6_TEST_FILE_NAME = fileName;
-    import(new URL(fileName, baseName))
+    const url = new URL(fileName, baseName);
+    import(url)
       .then(async () => {
         const testRunner = await this.testRunner;
         registerNotifyCallback(testRunner);
-      })
-      .catch(error => {
-        this.report(id, {
-          type: 'comment',
-          name: 'fail to load: ' + (error.message || 'Worker error'),
-          test: 0
-        });
-        try {
-          this.report(id, {
-            name: String(error),
-            test: 0,
-            marker: new Error(),
-            operator: 'error',
-            fail: true,
-            data: {
-              actual: error
-            }
-          });
-        } catch (error) {
-          if (!isStopTest(error)) throw error;
+        if (this.timeoutId) {
+          clearTimeout(this.timeoutId);
+          this.timeoutId = null;
         }
-        this.close(id);
-      });
+        this.timeoutId = setTimeout(() => {
+          this.timeoutId = null;
+          unregisterNotifyCallback(testRunner);
+          this.#reportTimeout(id, fileName);
+        }, this.timeout);
+      })
+      .catch(error => this.#reportError(id, error));
     return id;
   }
   destroyTask() {
@@ -76,4 +73,51 @@ export default class TestWorker extends EventServer {
     clearBeforeEach();
     clearAfterEach();
   }
+  #reportError(id, error) {
+    this.report(id, {
+      type: 'comment',
+      name: 'fail to load: ' + (error.message || 'Worker error'),
+      test: 0
+    });
+    try {
+      this.report(id, {
+        name: String(error),
+        test: 0,
+        marker: new Error(),
+        operator: 'error',
+        fail: true,
+        data: {
+          actual: error
+        }
+      });
+    } catch (error) {
+      if (!isStopTest(error)) throw error;
+    }
+    this.close(id);
+  }
+  #reportTimeout(id, fileName) {
+    this.report(id, {
+      type: 'test',
+      test: 0,
+      name: 'FILE: /' + fileName
+    });
+    try {
+      this.report(id, {
+        name: `No tests found in ${this.timeout}ms`,
+        test: 0,
+        marker: new Error(),
+        operator: 'error',
+        fail: true
+      });
+    } catch (error) {
+      if (!isStopTest(error)) throw error;
+    }
+    this.report(id, {
+      type: 'end',
+      test: 0,
+      name: 'FILE: /' + fileName,
+      fail: true
+    });
+    this.close(id);
+  }
 }

package/src/test.js

@@ -12,7 +12,7 @@ let tests = [],
   reporter = null,
   testCounter = 0,
   isConfigured = false,
-  notifyCallback = [];
+  notifyCallback = new Set();
 
 export const getConfiguredFlag = () => isConfigured;
 export const setConfiguredFlag = value => (isConfigured = !!value);
@@ -26,10 +26,12 @@ export const registerNotifyCallback = callback => {
   if (tests.length) {
     defer(callback);
   } else {
-    notifyCallback.push(callback);
+    notifyCallback.add(callback);
   }
 };
 
+export const unregisterNotifyCallback = callback => notifyCallback.delete(callback);
+
 const testers = [];
 
 export const getTesters = () => testers;
@@ -86,9 +88,9 @@ export const test = async (name, options, testFn) => {
     isTimerSet = true;
   }
   const deferred = makeDeferred();
-  if (tests.push({options, deferred}) === 1 && notifyCallback.length) {
+  if (tests.push({options, deferred}) === 1 && notifyCallback.size) {
     for (const callback of notifyCallback) defer(callback);
-    notifyCallback = [];
+    notifyCallback = new Set();
   }
 
   return deferred.promise;