tape-six 1.3.4 → 1.4.0

package/README.md

@@ -4,8 +4,13 @@
 [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.
+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 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.
 
 Why `tape-six`? It was supposed to be named `tape6` but `npm` does not allow names "similar"
 to existing packages. Instead of eliminating name-squatting they force to use unintuitive and
@@ -16,7 +21,7 @@ unmemorable names. That's why all internal names, environment variables, and pub
 Why another library? Working on projects written in modern JS (with modules) I found several problems
 with existing unit test libraries:
 
-- In my opinion unit test files should be directly executable with `node`, `deno`, `bun`, browsers
+- In my opinion unit test files should be directly executable with Node, Bun, Deno, browsers
   (with a trivial HTML file to load a test file) without a need for a special test runner utility,
   which wraps and changes my beautiful code.
   - Debugging my tests should be trivial. It should not be different from debugging any regular file.
@@ -24,11 +29,11 @@ with existing unit test libraries:
   - I want to debug my code, not dependencies I've never heard about.
   - I want to see where a problem happens, not some guts of a test harness.
 - Tests should work with ES modules natively.
-  - What if I want to debug some CommonJS code with Node? Fret not! Modules can import CommonJS files directly.
-    But not the other way around (yet). And it helps to test how module users can use your beautiful
-    CommonJS package.
+  - 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.
 - 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 should be properly supported.
+  - Both console-based debugging and a UI to navigate results are properly supported.
 
 ## Docs
 
@@ -43,6 +48,11 @@ The whole API is based on two objects: `test` and `Tester`.
 
 ```js
 import test from 'tape-six';
+// import {test} from 'tape-six';
+
+// CommonJS:
+// const {test} = require('tape-six');
+// const {default: test} = require('tape-six');
 ```
 
 This function registers a test suite. Available options:
@@ -50,13 +60,14 @@ This function registers a test suite. Available options:
 - `async test(name, options, testFn)` — registers a test suite to be executed asynchronously.
   The returned promise is resolved when the test suite is finished.
   - In most cases no need to wait for the returned promise.
-  - The test function has the following signature: `testFn(tester)`
-- `test.skip(name, options, testFn)` — registers a test suite to be skipped.
+  - The test function has the following signature: `async testFn(tester)`
+    - The function can be synchronous or asynchronous.
+- `async test.skip(name, options, testFn)` — registers a test suite to be skipped.
   - It is used to mark a test suite to be skipped. It will not be executed.
-- `test.todo(name, options, testFn)` — registers a test suite that is marked as work in progress.
+- `async test.todo(name, options, testFn)` — registers a test suite that is marked as work in progress.
   - Tests in this suite will be executed, errors will be reported but not counted as failures.
   - It is used to mark tests for incomplete features under development.
-- `test.asPromise(name, options, testPromiseFn)` — registers a test suite to be executed asynchronously
+- `async test.asPromise(name, options, testPromiseFn)` — registers a test suite to be executed asynchronously
   using the callback-style API to notify that the test suite is finished.
   - The test function has a different signature: `testPromiseFn(tester, resolve, reject)`.
 
@@ -68,19 +79,22 @@ The arguments mentioned above are:
   - `todo` — if `true`, the test suite will be marked as work in progress.
   - `name` — the optional name of the test suite. If not provided, it will be set to the name of the test function or `'(anonymous)'`.
     - Can be overridden by the `name` argument.
-  - `testFn` — the optional test function to be executed.
-    - Can be overridden by the `testFn` argument.
   - `timeout` — the optional timeout in milliseconds. It is used for asynchronous tests.
     - If the timeout is exceeded, the test suite will be marked as failed.
     - **Important:** JavaScript does not provide a generic way to cancel asynchronous operations.
       When the timeout is exceeded, `tape6` will stop waiting for the test to finish,
       but it will continue running in the background.
     - The default: no timeout.
-  - `testFn` — the test function to be executed. It will be called with the `tester` object.
-    The result will be ignored.
-    - This function can be an asynchronous one or return a promise.
-  - `testPromiseFn` — the test function to be executed. It will be called with the `tester` object
-    and two callbacks: `resolve` and `reject` modeled on the [Promise API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise).
+  - `testFn` — the optional test function to be executed (see below).
+    - Can be overridden by the `testFn` argument.
+  - `testPromiseFn` — the optional callback-based test function to be executed.
+    - Can be overridden by the `testPromiseFn` argument.
+- `testFn` — a test function to be executed. It will be called with the `tester` object.
+  The result will be ignored.
+  - This function can be synchronous or asynchronous.
+- `testPromiseFn` — a callback-based test function to be executed (see below). It will be called with the `tester` object and two callbacks: `resolve` and `reject` modeled on the [Promise API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise).
+  - Value supplied to `resolve()` will be ignored.
+  - Value supplied to `reject()` will be used as the error message.
 
 Given all that `test` and its helpers can be called like this:
 
@@ -111,6 +125,32 @@ test({
 });
 ```
 
+Examples of callback-based tests:
+
+```js
+test.asPromise(name, options, testPromiseFn);
+test.asPromise(name, testPromiseFn);
+test.asPromise(testPromiseFn);
+test.asPromise(name, options);
+test.asPromise(options, testPromiseFn);
+test.asPromise(options);
+
+// examples:
+test.asPromise('foo', (t, resolve, reject) => {
+  t.pass();
+  const result = someAsyncOperationAsPromise();
+  result.then(resolve).catch(reject);
+});
+
+test.asPromise('bar', async (t, resolve, reject) => {
+  const nodeStream = fs.createWriteStream('bar.txt');
+  nodeStream.on('error', reject);
+  nodeStream.on('finish', resolve);
+  nodeStream.write('hello');
+  nodeStream.end();
+});
+```
+
 ### `Tester`
 
 `Tester` helps to do asserts and provides an interface between a test suite and the test harness.
@@ -190,6 +230,10 @@ The following methods are available (all `msg` arguments are optional):
   - `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.
+- Evaluators:
+  - `OK(condition, msg, options)` — a high-level helper for evaluating simple expressions.
+    - _Available since 1.4.0._
+    - See [Tester](https://github.com/uhop/tape-six/wiki/Tester) for description and examples.
 
 In all cases, the `msg` message is optional. If it is not provided, some suitable generic message will be used.
 
@@ -216,15 +260,49 @@ It is super easy to run tests:
 2. Write a test. For example, you named it `test.js`.
 3. Run the test: `node test.js`
    1. Or: `bun run test.js`
-   2. Or: `deno run -A test.js`
+   2. Or: `deno run -A test.js` (you can use appropriate permissions).
    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.
 `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.
+
+```bash
+tape6         # run tests in parallel using all available threads
+tape6 --par 4 # run tests in parallel using 4 threads
+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.
+
 ### Configuring test runners
 
+TLDR version — add to your `package.json`:
+
+```jsonc
+{
+  // ...
+  "scripts": {
+    "test": "tape6 --flags FO",
+    "start": "tape6-server --trace"
+  }
+  // ...
+  "tape6": {
+    "tests": ["/tests/test-*.*js"],
+    "importmap": {
+      "imports": {
+        "tape-six": "/node_modules/tape-six/index.js",
+        "tape-six/": "/node_modules/tape-six/src/",
+        "my-package": "/index.js",
+        "my-package/": "/src/"
+      }
+    }
+  }
+}
+```
+
 See [set-up tests](https://github.com/uhop/tape-six/wiki/Set-up-tests) for details.
 
 ### Command-line utilities
@@ -232,10 +310,14 @@ See [set-up tests](https://github.com/uhop/tape-six/wiki/Set-up-tests) for detai
 - [tape6](https://github.com/uhop/tape-six/wiki/Utility-%E2%80%90-tape6) — the main utility of the package to run tests in different environments.
 - [tape6-server](https://github.com/uhop/tape-six/wiki/Utility-%E2%80%90-tape6-server) — a custom web server with a web application that helps running tests in browsers.
 
+Test output can be controlled by flags. See [Supported flags](https://github.com/uhop/tape-six/wiki/Supported-flags) for details.
+
 ## Release notes
 
 The most recent releases:
 
+- 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._
@@ -250,18 +332,5 @@ The most recent releases:
 - 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._
-- 0.12.3 _Technical release: exposed internal classes for external utilities._
-- 0.12.2 _Fixed a minor serialization issue._
-- 0.12.1 _Minor Deno-related refactoring, fixed the way tests are triggered._
-- 0.12.0 _Removed data to avoid serializing non-serializable objects._
-- 0.11.0 _Minor improvements to the server: temporary redirects, a hyperlink to the web app._
-- 0.10.0 _Refactored test runners, refactored stopping tests on failure, added JSONL reporter, fixed bugs._
-- 0.9.6 _Updated deps._
-- 0.9.5 _Updated the lock file._
-- 0.9.4 _Updated deps. Added test runners for Bun and Deno._
-- 0.9.3 _Made TTY reporter work with non-TTY streams._
-- 0.9.2 _Fixed Windows runner._
-- 0.9.1 _More updates related to renaming `tape6` ⇒ `tape-six`._
-- 0.9.0 _Initial release._
 
 For more info consult full [release notes](https://github.com/uhop/tape-six/wiki/Release-notes).

package/bin/tape6-deno.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env -S deno run --allow-read --allow-env --ext=js
+#!/usr/bin/env -S deno run --allow-all --ext=js
 
 import {fileURLToPath} from 'node:url';
 

package/index.d.ts

@@ -345,6 +345,25 @@ export declare interface Test {
    */
   resolves(promise: Promise<unknown>, message?: string): Promise<void>;
 
+  /**
+   * Returns a code as a string for evaluation that checks if the condition is truthy.
+   * @param condition - The JS condition to check as a string
+   * @param message - Message to display if the assertion fails
+   * @param options - Optional options object. `self` is the name of the tester argument, which should be used in the code. Default: `"t"`.
+   */
+  OK(condition: string, message: string, options?: {self?: string}): string;
+  /**
+   * Returns a code as a string for evaluation that checks if the condition is truthy.
+   * @param condition - The JS condition to check as a string
+   * @param options - Optional options object. `self` is the name of the tester argument, which should be used in the code. Default: `"t"`.
+   */
+  OK(condition: string, options: {self?: string}): string;
+  /**
+   * Returns a code as a string for evaluation that checks if the condition is truthy.
+   * @param condition - The JS condition to check as a string
+   */
+  OK(condition: string): string;
+
   // aliases
 
   /**
@@ -601,6 +620,44 @@ export declare interface Test {
    * @param message - Optional message to display if the assertion fails
    */
   doesNotReject(promise: Promise<unknown>, message?: string): Promise<void>;
+
+  /**
+   * Returns a code as a string for evaluation that checks if the condition is truthy.
+   * @param condition - The JS condition to check as a string
+   * @param message - Message to display if the assertion fails
+   * @param options - Optional options object. `self` is the name of the tester argument, which should be used in the code. Default: `"t"`.
+   */
+  TRUE(condition: string, message: string, options?: {self?: string}): string;
+  /**
+   * Returns a code as a string for evaluation that checks if the condition is truthy.
+   * @param condition - The JS condition to check as a string
+   * @param options - Optional options object. `self` is the name of the tester argument, which should be used in the code. Default: `"t"`.
+   */
+  TRUE(condition: string, options: {self?: string}): string;
+  /**
+   * Returns a code as a string for evaluation that checks if the condition is truthy.
+   * @param condition - The JS condition to check as a string
+   */
+  TRUE(condition: string): string;
+
+  /**
+   * Returns a code as a string for evaluation that checks if the condition is truthy.
+   * @param condition - The JS condition to check as a string
+   * @param message - Message to display if the assertion fails
+   * @param options - Optional options object. `self` is the name of the tester argument, which should be used in the code. Default: `"t"`.
+   */
+  ASSERT(condition: string, message: string, options?: {self?: string}): string;
+  /**
+   * Returns a code as a string for evaluation that checks if the condition is truthy.
+   * @param condition - The JS condition to check as a string
+   * @param options - Optional options object. `self` is the name of the tester argument, which should be used in the code. Default: `"t"`.
+   */
+  ASSERT(condition: string, options: {self?: string}): string;
+  /**
+   * Returns a code as a string for evaluation that checks if the condition is truthy.
+   * @param condition - The JS condition to check as a string
+   */
+  ASSERT(condition: string): string;
 }
 
 export declare interface Test {
@@ -711,4 +768,5 @@ export declare interface Test {
 
 declare const test: Test;
 
+export {test};
 export default test;

package/index.js

@@ -191,4 +191,5 @@ if (!getConfiguredFlag()) {
   registerNotifyCallback(testCallback);
 }
 
+export {test};
 export default test;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tape-six",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "description": "TAP the test harness for the modern JavaScript (ES6).",
   "type": "module",
   "main": "index.js",
@@ -61,7 +61,14 @@
   ],
   "tape6": {
     "tests": [
-      "/tests/test-*.*js"
+      "/tests/test-*.js",
+      "/tests/test-*.mjs"
+    ],
+    "cli": [
+      "/tests/test-*.cjs"
+    ],
+    "browser": [
+      "/tests/web/test-*.html"
     ],
     "importmap": {
       "imports": {

package/src/OK.js

@@ -0,0 +1,47 @@
+import {Tester, setAliases} from './Tester.js';
+
+// code mostly borrowed from https://github.com/heya/ice/blob/master/assert.js under BSD-3
+
+const listVariables = (code, self) => {
+  const vars =
+    code
+      .replace(
+        /(?:\b[A-Z]|\.[a-zA-Z_$])[a-zA-Z_$\d]*\b|\b[a-zA-Z_$][a-zA-Z_$\d]*:|\b(?:function|return|if|else|switch|case|while|for|do|break|continue|var|try|catch|finally|throw|with|debugger|default|this|true|false|null|undefined|typeof|instanceof|in|delete|new|void|arguments|decodeURI|decodeURIComponent|encodeURI|encodeURIComponent|escape|eval|isFinite|isNaN|parseFloat|parseInt|unescape|window|document)\b|'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"/g,
+        ''
+      )
+      .match(/(\b[a-z_$][a-z_$\d]*\b)/gi) || [];
+  const result = [],
+    resultSet = {};
+  for (const name of vars) {
+    const key = '-' + name;
+    if (name != self && !resultSet[key]) {
+      result.push("'" + name + "':" + name);
+      resultSet[key] = 1;
+    }
+  }
+  return '{' + result.join(',') + '}';
+};
+
+Tester.prototype.OK = function OK(condition, msg, options) {
+  if (typeof condition != 'string') {
+    throw new TypeError('Condition must be a string');
+  }
+  if (typeof msg == 'object') {
+    options = msg;
+    msg = undefined;
+  }
+  const {self = 't'} = options || {};
+  return `(${self}.state.emit({
+  name: ${JSON.stringify(msg || condition)},
+  test: ${self}.testNumber,
+  marker: new Error(),
+  time: ${self}.state.timer.now(),
+  operator: 'ok',
+  fail: !(${condition}),
+  data: {
+    actual: ${listVariables(condition, self)}
+  }
+}))`;
+};
+
+setAliases('OK', 'TRUE, ASSERT');

package/src/Tester.js

@@ -9,7 +9,7 @@ const throwHelper = fn => {
   return null;
 };
 
-class Tester {
+export class Tester {
   constructor(state, testNumber) {
     this.state = state;
     this.testNumber = testNumber;
@@ -400,7 +400,7 @@ class Tester {
 }
 Tester.prototype.any = Tester.prototype._ = any;
 
-const setAliases = (source, aliases) =>
+export const setAliases = (source, aliases) =>
   aliases.split(', ').forEach(alias => (Tester.prototype[alias] = Tester.prototype[source]));
 
 setAliases('ok', 'true, assert');

package/src/test.js

@@ -1,11 +1,13 @@
 import {selectTimer} from './utils/timer.js';
 import State, {StopTest} from './State.js';
-import Tester from './Tester.js';
 import getDeferred from './utils/getDeferred.js';
 import timeout from './utils/timeout.js';
 import {formatTime} from './utils/formatters.js';
 import defer from './utils/defer.js';
 
+import Tester from './Tester.js';
+import './OK.js';
+
 let tests = [],
   reporter = null,
   testCounter = 0,

package/src/utils/config.js

@@ -37,7 +37,7 @@ export const getConfig = async (rootFolder, traceFn) => {
   }
 
   // check well-known files
-  if (!cfg) cfg = {tests: ['/tests/test-*.*js']};
+  if (!cfg) cfg = {tests: ['/tests/test-*.js', '/tests/test-*.mjs'], cli: ['/tests/test-*.cjs']};
 
   return cfg;
 };
@@ -55,6 +55,14 @@ export const resolveTests = async (rootFolder, type, traceFn) => {
     }
   }
 
+  if (type !== 'browser') {
+    if (Array.isArray(cfg.cli)) {
+      patterns = patterns.concat(cfg.cli);
+    } else if (typeof cfg.cli == 'string') {
+      patterns.push(cfg.cli);
+    }
+  }
+
   if (Array.isArray(cfg.tests)) {
     patterns = patterns.concat(cfg.tests);
   } else if (typeof cfg.tests == 'string') {