tape-six 1.6.0 → 1.7.1

package/README.md

@@ -6,9 +6,9 @@
 `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.
 
-It runs ES modules (`import`-based code) natively and supports CommonJS modules transparently using built-in [ESM](https://nodejs.org/api/esm.html).
+It runs ES modules (`import`-based code) natively and supports CommonJS modules transparently using the built-in [ESM](https://nodejs.org/api/esm.html).
 
-It can run TypeScript code with modern versions of Node, Bun and Deno without transpilation. Obviously TS bindings are included.
+It can run TypeScript code with modern versions of Node, Bun and Deno **without transpilation**. Obviously TS bindings are included.
 
 Individual test files can be executed directly with `node`, `deno`, `bun` without a need for a special test runner utility. It facilitates debugging and improves testing.
 
@@ -33,7 +33,7 @@ with existing unit test libraries:
 - Tests should work with ES modules natively.
   - What if I want to debug some CommonJS code with Node? No problem, it just works.
 - Tests should work with TypeScript natively.
-  - It just workss: modern runtimes (Node, Deno, Bun) support running TypeScript natively without transpilation by ignoring type information and running the code directly.
+  - It just works: modern runtimes (Node, Deno, Bun) support running TypeScript natively without transpilation by ignoring type information and running the code directly.
 - The [DX](https://en.wikipedia.org/wiki/User_experience#Developer_experience) in browsers are usually abysmal.
   - Both console-based debugging and a UI to navigate results are properly supported.
   - Integration with browser automation tools is supported for automated testing.
@@ -99,11 +99,29 @@ And:
 
 <img width="240" height="329" alt="image" src="https://github.com/user-attachments/assets/f3d8ac65-9e6a-499d-837f-0271146da1de" />
 
+## Project structure
+
+```
+tape-six/
+├── index.js          # Main entry point, exports test, hooks, aliases
+├── index.d.ts        # TypeScript definitions for the public API
+├── package.json      # Package config; "tape6" section configures test discovery
+├── bin/              # CLI utilities: tape6, tape6-server, tape6-node, tape6-bun, tape6-deno, tape6-seq
+├── src/              # Source code (test engine, reporters, runners, utilities)
+├── web-app/          # Browser test UI application
+├── tests/            # Test files
+├── ts-tests/         # TypeScript test files
+├── wiki/             # GitHub wiki documentation (submodule)
+└── vendors/          # Git submodules (deep6)
+```
+
 ## Docs
 
 The documentation can be found in the [wiki](https://github.com/uhop/tape-six/wiki).
 See how it can be used in [tests/](https://github.com/uhop/tape-six/tree/master/tests).
 
+For AI assistants: see [llms.txt](https://github.com/uhop/tape-six/blob/master/llms.txt) and [llms-full.txt](https://github.com/uhop/tape-six/blob/master/llms-full.txt) for LLM-optimized documentation.
+
 The whole API is based on two objects: `test` and `Tester`.
 
 ### `test`
@@ -247,6 +265,8 @@ The following methods are available (all `msg` arguments are optional):
     - `notStrictEquals()` &mdash; an alias of `notStrictEqual()`.
     - `doesNotEqual()` &mdash; an alias of `notStrictEqual()`.
     - `isUnequal()` &mdash; an alias of `notStrictEqual()`.
+    - `isNotEqual()` &mdash; an alias of `notStrictEqual()`.
+    - `isNot()` &mdash; an alias of `notStrictEqual()`.
   - `looseEqual(a, b, msg)` &mdash; asserts that `a` and `b` are loosely equal.
     - Loose equality is defined as `a == b`.
     - `looseEquals()` &mdash; an alias of `looseEqual()`.
@@ -290,6 +310,7 @@ The following methods are available (all `msg` arguments are optional):
 - Miscellaneous:
   - `any` &mdash; returns the `any` object. It can be used in deep equivalency asserts to match any value.
     See [deep6's any](https://github.com/uhop/deep6/wiki/any) for details.
+    - `_` &mdash; an alias of `any`.
   - `plan(n)` &mdash; sets the number of tests in the test suite. Rarely used.
   - `comment(msg)` &mdash; sends a comment to the test harness. Rarely used.
   - `skipTest(...args, msg)` &mdash; skips the current test yet sends a message to the test harness.
@@ -316,6 +337,10 @@ test('Sample test', async t => {
 });
 ```
 
+### Before/after hooks
+
+`tape-six` supports scope-based before/after hooks: `beforeAll`, `afterAll`, `beforeEach`, `afterEach`, which can be used to set-up and tear-down a proper environment for tests. Read all about it in [before and after hooks](https://github.com/uhop/tape-six/wiki/Before-and-after-hooks).
+
 ### Running tests
 
 It is super easy to run tests:
@@ -328,7 +353,7 @@ It is super easy to run tests:
    3. Or you can run them in a browser!
 4. Profit!
 
-If you have a lot of tests, you can organize them using multiple files and directories.
+If you have a lot of tests, you can organize them using multiple files and directories (see configuration below).
 `tape-six` provides multiple test runners that can run them in different environments.
 
 Tests can run in parallel using multiple threads to speed up the whole process.
@@ -341,6 +366,12 @@ tape6 --par 1 # run one test at a time
 
 If you want to run tests in separate processes, check out [tape-six-proc](https://www.npmjs.com/package/tape-six-proc). Why do you want to do that? When tests have to modify globals or use single-threaded binary extensions.
 
+If you want to run tests sequentially without expenses of threads and processes, you can use the `tape6-seq` command, which uses the same options and configuration as `tape6`:
+
+```bash
+tape6-seq
+```
+
 ### Configuring test runners
 
 TLDR version &mdash; add to your `package.json`:
@@ -380,29 +411,10 @@ Test output can be controlled by flags. See [Supported flags](https://github.com
 
 The most recent releases:
 
+- 1.7.1 _Added AI support, added timeout to start test runners, fixed some bugs in the sequential test runner._
+- 1.7.0 _New features: after/before hooks for tests, aliases for `suite()`, `describe()`, `it()`, `tape6-seq` &mdash; an in-process sequential test runner. Improvements: stricter monochrome detection, refactoring, bugfixes, updated dev dependencies and the documentation._
 - 1.6.0 _New features: support for `AssertionError` and 3rd-party assertion libraries based on it like `node:assert` and `chai`, support for `console.assert()`, support for `signal` to cancel asynchronous operations, tests wait for embedded tests, improved reporting of errors, updated dev dependencies._
 - 1.5.1 _Better support for stopping parallel tests, better support for "failed to load" errors._
 - 1.5.0 _Internal refactoring (moved state to reporters), added type identification of values in the DOM and TTY reporters, multiple minor fixes._
-- 1.4.5 _Internal: added flags support for custom test runners._
-- 1.4.4 _Refreshed the lock file._
-- 1.4.3 _Updated dev dependencies + a minor bugfix._
-- 1.4.2 _Improved documentation._
-- 1.4.1 _Added browser automation support._
-- 1.4.0 _Added a high-level helper `OK()` for evaluating simple expressions._
-- 1.3.5 _Minor improvements, better docs._
-- 1.3.4 _Minor bugfixes and improvements._
-- 1.3.3 _Added a way to hide console/streams output, better support for file tests, better TTY formatting._
-- 1.3.2 _Internal refactoring (capture console calls), updated dependencies._
-- 1.3.1 _Bugfix for web browser using JSONL reporter._
-- 1.3.0 _Bugfixes, updated dependencies, new feature: proxied console calls._
-- 1.2.0 _Updated dependencies + added an optional prefix for JSON lines._
-- 1.1.2 _Updated dependencies._
-- 1.1.1 _Technical re-release with the missing `index.d.ts` file._
-- 1.1.0 _Added TypeScript support._
-- 1.0.4 _Bugfix for platform-specific tests, old platforms, minor updates to accommodate Deno 2, updated dev deps._
-- 1.0.3 _Minor update to accommodate changes in Bun and updated dev deps._
-- 1.0.2 _Bugfix for Deno using the JSONL reporter._
-- 1.0.1 _Technical release: added more links._
-- 1.0.0 _The first official release._
 
 For more info consult full [release notes](https://github.com/uhop/tape-six/wiki/Release-notes).

package/bin/tape6-bun.js

@@ -5,13 +5,14 @@ import {fileURLToPath} from 'node:url';
 import {
   resolveTests,
   resolvePatterns,
-  getReporter as getReporterType
+  getReporterFileName,
+  getReporterType
 } from '../src/utils/config.js';
 
 import {getReporter, setReporter} from '../src/test.js';
 import {selectTimer} from '../src/utils/timer.js';
 
-import TestWorker from '../src/bun/TestWorker.js';
+import TestWorker from '../src/runners/bun/TestWorker.js';
 
 const options = {},
   rootFolder = Bun.cwd;
@@ -89,20 +90,19 @@ const config = () => {
   if (!parallel) parallel = globalThis.navigator?.hardwareConcurrency || 1;
 };
 
-const reporters = {
-  jsonl: 'JSONLReporter.js',
-  tap: 'TapReporter.js',
-  tty: 'TTYReporter.js'
-};
-
 const init = async () => {
   const currentReporter = getReporter();
   if (!currentReporter) {
     const reporterType = getReporterType(),
-      reporterFile = reporters[reporterType] || reporters.tty,
+      reporterFile = getReporterFileName(reporterType),
       CustomReporter = (await import('../src/reporters/' + reporterFile)).default,
-      customOptions =
-        reporterType === 'tap' ? {useJson: true, hasColors: !options.monochrome} : options,
+      hasColors = !(
+        options.monochrome ||
+        Bun.env.NO_COLOR ||
+        Bun.env.NODE_DISABLE_COLORS ||
+        Bun.env.FORCE_COLOR === '0'
+      ),
+      customOptions = reporterType === 'tap' ? {useJson: true, hasColors} : {...options, hasColors},
       customReporter = new CustomReporter(customOptions);
     setReporter(customReporter);
   }

package/bin/tape6-deno.js

@@ -5,13 +5,14 @@ import {fileURLToPath} from 'node:url';
 import {
   resolveTests,
   resolvePatterns,
-  getReporter as getReporterType
+  getReporterFileName,
+  getReporterType
 } from '../src/utils/config.js';
 
 import {getReporter, setReporter} from '../src/test.js';
 import {selectTimer} from '../src/utils/timer.js';
 
-import TestWorker from '../src/deno/TestWorker.js';
+import TestWorker from '../src/runners/deno/TestWorker.js';
 
 const options = {},
   rootFolder = Deno.cwd();
@@ -89,20 +90,19 @@ const config = () => {
   if (!parallel) parallel = globalThis.navigator?.hardwareConcurrency || 1;
 };
 
-const reporters = {
-  jsonl: 'JSONLReporter.js',
-  tap: 'TapReporter.js',
-  tty: 'TTYReporter.js'
-};
-
 const init = async () => {
   const currentReporter = getReporter();
   if (!currentReporter) {
     const reporterType = getReporterType(),
-      reporterFile = reporters[reporterType] || reporters.tty,
+      reporterFile = getReporterFileName(reporterType),
       CustomReporter = (await import('../src/reporters/' + reporterFile)).default,
-      customOptions =
-        reporterType === 'tap' ? {useJson: true, hasColors: !options.monochrome} : options,
+      hasColors = !(
+        options.monochrome ||
+        Deno.env.get('NO_COLOR') ||
+        Deno.env.get('NODE_DISABLE_COLORS') ||
+        Deno.env.get('FORCE_COLOR') === '0'
+      ),
+      customOptions = reporterType === 'tap' ? {useJson: true, hasColors} : {...options, hasColors},
       customReporter = new CustomReporter(customOptions);
     setReporter(customReporter);
   }

package/bin/tape6-node.js

@@ -6,13 +6,14 @@ import {fileURLToPath} from 'node:url';
 import {
   resolveTests,
   resolvePatterns,
-  getReporter as getReporterType
+  getReporterFileName,
+  getReporterType
 } from '../src/utils/config.js';
 
 import {getReporter, setReporter} from '../src/test.js';
 import {selectTimer} from '../src/utils/timer.js';
 
-import TestWorker from '../src/node/TestWorker.js';
+import TestWorker from '../src/runners/node/TestWorker.js';
 
 const options = {},
   rootFolder = process.cwd();
@@ -90,20 +91,19 @@ const config = () => {
   if (!parallel) parallel = globalThis.navigator?.hardwareConcurrency || 1;
 };
 
-const reporters = {
-  jsonl: 'JSONLReporter.js',
-  tap: 'TapReporter.js',
-  tty: 'TTYReporter.js'
-};
-
 const init = async () => {
   const currentReporter = getReporter();
   if (!currentReporter) {
     const reporterType = getReporterType(),
-      reporterFile = reporters[reporterType] || reporters.tty,
+      reporterFile = getReporterFileName(reporterType),
       CustomReporter = (await import('../src/reporters/' + reporterFile)).default,
-      customOptions =
-        reporterType === 'tap' ? {useJson: true, hasColors: !options.monochrome} : options,
+      hasColors = !(
+        options.monochrome ||
+        process.env.NO_COLOR ||
+        process.env.NODE_DISABLE_COLORS ||
+        process.env.FORCE_COLOR === '0'
+      ),
+      customOptions = reporterType === 'tap' ? {useJson: true, hasColors} : {...options, hasColors},
       customReporter = new CustomReporter(customOptions);
     setReporter(customReporter);
   }
@@ -124,6 +124,11 @@ const main = async () => {
     console.error('UNHANDLED ERROR:', origin, error)
   );
 
+  if (!files.length) {
+    console.log('No files found.');
+    process.exit(1);
+  }
+
   const reporter = getReporter(),
     worker = new TestWorker(reporter, parallel, options);
 

package/bin/tape6-runner.js

@@ -7,6 +7,7 @@ const runtimeFiles = {
   node: 'tape6-node.js',
   deno: 'tape6-deno.js',
   bun: 'tape6-bun.js',
+  seq: 'tape6-seq.js',
   server: 'tape6-server.js',
   runner: 'tape6-runner.js',
   main: 'tape6.js'

package/bin/tape6-seq.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+import {fileURLToPath} from 'node:url';
+
+import {
+  resolveTests,
+  resolvePatterns,
+  getReporterFileName,
+  getReporterType
+} from '../src/utils/config.js';
+
+import {getReporter, setReporter, setConfiguredFlag, testRunner} from '../src/test.js';
+import {selectTimer} from '../src/utils/timer.js';
+
+import TestWorker from '../src/runners/seq/TestWorker.js';
+
+setConfiguredFlag(true);
+
+const options = {},
+  rootFolder = process.cwd();
+
+let flags = '',
+  files = [];
+
+const showSelf = () => {
+  const self = new URL(import.meta.url);
+  if (self.protocol === 'file:') {
+    console.log(fileURLToPath(self));
+  } else {
+    console.log(self);
+  }
+  process.exit(0);
+};
+
+const config = () => {
+  if (process.argv.includes('--self')) showSelf();
+
+  const optionNames = {
+    f: 'failureOnly',
+    t: 'showTime',
+    b: 'showBanner',
+    d: 'showData',
+    o: 'failOnce',
+    n: 'showAssertNumber',
+    m: 'monochrome',
+    c: 'dontCaptureConsole',
+    h: 'hideStreams'
+  };
+
+  for (let i = 2; i < process.argv.length; ++i) {
+    const arg = process.argv[i];
+    if (arg == '-f' || arg == '--flags') {
+      if (++i < process.argv.length) {
+        flags += process.argv[i];
+      }
+      continue;
+    }
+    if (arg == '-p' || arg == '--par') {
+      // skip
+      ++i;
+      continue;
+    }
+    files.push(arg);
+  }
+
+  flags = (process.env.TAPE6_FLAGS || '') + flags;
+  for (let i = 0; i < flags.length; ++i) {
+    const option = flags[i].toLowerCase(),
+      name = optionNames[option];
+    if (typeof name == 'string') options[name] = option !== flags[i];
+  }
+  options.flags = flags;
+};
+
+const init = async () => {
+  const currentReporter = getReporter();
+  if (!currentReporter) {
+    const reporterType = getReporterType(),
+      reporterFile = getReporterFileName(reporterType),
+      CustomReporter = (await import('../src/reporters/' + reporterFile)).default,
+      hasColors = !(
+        options.monochrome ||
+        process.env.NO_COLOR ||
+        process.env.NODE_DISABLE_COLORS ||
+        process.env.FORCE_COLOR === '0'
+      ),
+      customOptions = reporterType === 'tap' ? {useJson: true, hasColors} : {...options, hasColors},
+      customReporter = new CustomReporter(customOptions);
+    setReporter(customReporter);
+  }
+
+  if (files.length) {
+    files = await resolvePatterns(rootFolder, files);
+  } else {
+    files = await resolveTests(rootFolder, 'node');
+  }
+};
+
+const main = async () => {
+  config();
+  await init();
+  await selectTimer();
+
+  const console = globalThis.console;
+
+  process.on('uncaughtException', (error, origin) =>
+    console.error('UNHANDLED ERROR:', origin, error)
+  );
+
+  const reporter = getReporter(),
+    worker = new TestWorker(reporter, 1, {...options, testRunner});
+
+  reporter.report({type: 'test', test: 0});
+
+  await new Promise(resolve => {
+    worker.done = () => resolve();
+    worker.execute(files);
+  });
+
+  const hasFailed = reporter.state && reporter.state.failed > 0;
+
+  reporter.report({
+    type: 'end',
+    test: 0,
+    fail: hasFailed
+  });
+
+  process.exit(hasFailed ? 1 : 0);
+};
+
+main().catch(error => console.error('ERROR:', error));