tape-six 0.12.3 → 1.0.0

package/README.md

@@ -3,35 +3,239 @@
 [npm-img]:      https://img.shields.io/npm/v/tape-six.svg
 [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.
+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.
 
-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 unmemorable names. That's why all internal names, environment variables, and public names still use `tape6`.
+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
+unmemorable names. That's why all internal names, environment variables, and public names still use `tape6`.
 
 ## Rationale
 
-Why another library? Working on projects written in modern JS (with modules) I found several problems with existing unit test libraries:
+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`, browsers (with a trivial HTML file to load a test file) without a need for a special test runner utility, which wraps and massages my beautiful code.
+* In my opinion unit test files should be directly executable with `node`, `deno`, `bun`, 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.
 * The test harness should not obfuscate code nor include hundreds of other packages.
   * 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. 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? 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.
 * 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.
 
 ## 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).
 
-The documentation is mostly TBD but you can inspect `tests/` to see how it is used.
-If you are familiar with other TAP-based libraries you'll feel right at home.
+The whole API is based on two objects: `test` and `Tester`.
+
+### `test`
+
+`test` is the entry point to the test suite:
+
+```js
+import test from 'tape-six';
+```
+
+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.
+  * 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.
+  * 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
+  using the callback-style API to notify that the test suite is finished.
+  * The test function has a different signature: `testPromiseFn(tester, resolve, reject)`.
+
+The arguments mentioned above are:
+
+* `name` — the optional name of the test suite. If not provided, it will be set to the name of the test function or `'(anonymous)'`.
+* `options` — the optional options object. Available options:
+  * `skip` — if `true`, the test suite will be skipped.
+  * `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).
+
+Given all that `test` and its helpers can be called like this:
+
+```js
+test(name, options, testFn);
+test(name, testFn);
+test(testFn);
+test(name, options);
+test(options, testFn);
+test(options);
+
+// examples:
+test('foo', t => {
+  t.pass();
+});
+test('bar', async t => {
+  t.fail();
+});
+test(function baz(t) {
+  t.ok(1 < 2);
+});
+test({
+  name: 'qux',
+  todo: true,
+  testFn: t => {
+    t.ok(1 < 2);
+  }
+});
+```
+
+### `Tester`
+
+`Tester` helps to do asserts and provides an interface between a test suite and the test harness.
+The following methods are available (all `msg` arguments are optional):
+
+* Asserts:
+  * `pass(msg)` &mdash; asserts that the test passed.
+  * `fail(msg)` &mdash; asserts that the test failed.
+  * `ok(val, msg)` &mdash; asserts that `val` is truthy.
+    * `true()` &mdash; an alias of `ok()`.
+    * `assert()` &mdash; an alias of `ok()`.
+  * `notOk(val, msg)` &mdash; asserts that `val` is falsy.
+    * `false()` &mdash; an alias of `notOk()`.
+    * `notok()` &mdash; an alias of `notOk()`.
+  * `error(err, msg)` &mdash; asserts that `err` is falsy.
+    * `ifError()` &mdash; an alias of `error()`.
+    * `ifErr()` &mdash; an alias of `error()`.
+    * `iferror()` &mdash; an alias of `error()`.
+  * `strictEqual(a, b, msg)` &mdash; asserts that `a` and `b` are strictly equal.
+    * Strict equality is defined as `a === b`.
+    * `is()` &mdash; an alias of `strictEqual()`.
+    * `equal()` &mdash; an alias of `strictEqual()`.
+    * `isEqual()` &mdash; an alias of `strictEqual()`.
+    * `equals()` &mdash; an alias of `strictEqual()`.
+    * `strictEquals()` &mdash; an alias of `strictEqual()`.
+  * `notStrictEqual(a, b, msg)` &mdash; asserts that `a` and `b` are not strictly equal.
+    * `not()` &mdash; an alias of `notStrictEqual()`.
+    * `notEqual()` &mdash; an alias of `notStrictEqual()`.
+    * `notEquals()` &mdash; an alias of `notStrictEqual()`.
+    * `notStrictEquals()` &mdash; an alias of `notStrictEqual()`.
+    * `doesNotEqual()` &mdash; an alias of `notStrictEqual()`.
+    * `isUnequal()` &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()`.
+  * `notLooseEqual(a, b, msg)` &mdash; asserts that `a` and `b` are not loosely equal.
+    * `notLooseEquals()` &mdash; an alias of `notLooseEqual()`.
+  * `deepEqual(a, b, msg)` &mdash; asserts that `a` and `b` are deeply equal.
+    * Individual components of `a` and `b` are compared recursively using the strict equality.
+    * See [deep6's equal()](https://github.com/uhop/deep6/wiki/equal()) for details.
+    * `same()` &mdash; an alias of `deepEqual()`.
+    * `deepEquals()` &mdash; an alias of `deepEqual()`.
+    * `isEquivalent()` &mdash; an alias of `deepEqual()`.
+  * `notDeepEqual(a, b, msg)` &mdash; asserts that `a` and `b` are not deeply equal.
+    * `notSame()` &mdash; an alias of `notDeepEqual()`.
+    * `notDeepEquals()` &mdash; an alias of `notDeepEqual()`.
+    * `notEquivalent()` &mdash; an alias of `notDeepEqual()`.
+    * `notDeeply()` &mdash; an alias of `notDeepEqual()`.
+    * `isNotDeepEqual()` &mdash; an alias of `notDeepEqual()`.
+    * `isNotEquivalent()` &mdash; an alias of `notDeepEqual()`.
+  * `deepLooseEqual(a, b, msg)` &mdash; asserts that `a` and `b` are deeply loosely equal.
+    * Individual components of `a` and `b` are compared recursively using the loose equality.
+  * `notDeepLooseEqual(a, b, msg)` &mdash; asserts that `a` and `b` are not deeply loosely equal.
+  * `throws(fn, msg)` &mdash; asserts that `fn` throws.
+    * `fn` is called with no arguments in the global context.
+  * `doesNotThrow(fn, msg)` &mdash; asserts that `fn` does not throw.
+  * `matchString(string, regexp, msg)` &mdash; asserts that `string` matches `regexp`.
+  * `doesNotMatchString(string, regexp, msg)` &mdash; asserts that `string` does not match `regexp`.
+  * `match(a, b, msg)` &mdash; asserts that `a` matches `b`.
+    * See [deep6's match()](https://github.com/uhop/deep6/wiki/match()) for details.
+  * `doesNotMatch(a, b, msg)` &mdash; asserts that `a` does not match `b`.
+  * `rejects(promise, msg)` &mdash; asserts that `promise` rejects.
+    * This is an asynchronous method. It is likely to be waited for.
+    * `doesNotResolve()` &mdash; an alias of `rejects()`.
+  * `resolves(promise, msg)` &mdash; asserts that `promise` resolves.
+    * This is an asynchronous method. It is likely to be waited for.
+    * `doesNotReject()` &mdash; an alias of `resolves()`.
+* Embedded test suites (all of them are asynchronous and should be waited for):
+  * `test(name, options, testFn)` &mdash; runs a test suite asynchronously. See `test()` above.
+  * `skip(name, options, testFn)` &mdash; skips a test suite asynchronously. See `test.skip()` above.
+  * `todo(name, options, testFn)` &mdash; runs a provisional test suite asynchronously. See `test.todo()` above.
+  * `asPromise(name, options, testPromiseFn)` &mdash; runs a test suite asynchronously. See `test.asPromise()` above.
+* 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.
+  * `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.
+  * `bailOut(msg)` &mdash; stops the test suite and sends a message to the test harness.
+
+In all cases, the `msg` message is optional. If it is not provided, some suitable generic message will be used.
+
+Example:
+
+```js
+test('Sample test', async t => {
+  const result = await getFromDb({first: 'Bob', last: 'Smith'});
+  t.equal(result.position, 'chief bozo', 'the position is correct');
+  t.ok(result.manager, 'the manager exists');
+
+  const manager = await getFromDb(result.manager);
+  t.ok(manager, 'the manager is retrieved');
+  t.equal(manager.first, 'Jane', 'the manager is Jane');
+  t.deepEqual(manager.employees, ['Bob Smith'], 'Jane manages only Bob Smith');
+});
+```
+
+### Running tests
+
+It is super easy to run tests:
+
+1. Install the `tape-six` package: `npm i -D tape-six`
+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`
+   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.
+
+### Command-line utilities
+
+TBD
+
+### Setting up your project
+
+TBD
 
 ## Release notes
 
 The most recent releases:
 
+* 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.*

package/bin/tape6-bun.js

@@ -38,7 +38,7 @@ const config = () => {
     d: 'showData',
     o: 'failOnce',
     n: 'showAssertNumber',
-    c: 'hasColors'
+    m: 'monochrome'
   };
 
   let flagIsSet = false,
@@ -103,7 +103,7 @@ const init = async () => {
       reporter = ttyReporter.report.bind(ttyReporter);
     }
     if (!reporter) {
-      const tapReporter = new TapReporter({useJson: true});
+      const tapReporter = new TapReporter({useJson: true, hasColors: !options.monochrome});
       reporter = tapReporter.report.bind(tapReporter);
     }
     setReporter(reporter);

package/bin/tape6-deno.js

@@ -38,7 +38,7 @@ const config = () => {
     d: 'showData',
     o: 'failOnce',
     n: 'showAssertNumber',
-    c: 'hasColors'
+    m: 'monochrome'
   };
 
   let flagIsSet = false,
@@ -103,7 +103,7 @@ const init = async () => {
       reporter = ttyReporter.report.bind(ttyReporter);
     }
     if (!reporter) {
-      const tapReporter = new TapReporter({useJson: true});
+      const tapReporter = new TapReporter({useJson: true, hasColors: !options.monochrome});
       reporter = tapReporter.report.bind(tapReporter);
     }
     setReporter(reporter);

package/bin/tape6-node.js

@@ -39,7 +39,7 @@ const config = () => {
     d: 'showData',
     o: 'failOnce',
     n: 'showAssertNumber',
-    c: 'hasColors'
+    m: 'monochrome'
   };
 
   let flagIsSet = false,
@@ -104,7 +104,7 @@ const init = async () => {
       reporter = ttyReporter.report.bind(ttyReporter);
     }
     if (!reporter) {
-      const tapReporter = new TapReporter({useJson: true});
+      const tapReporter = new TapReporter({useJson: true, hasColors: !options.monochrome});
       reporter = tapReporter.report.bind(tapReporter);
     }
     setReporter(reporter);

package/index.js

@@ -19,7 +19,8 @@ const optionNames = {
   d: 'showData',
   o: 'failOnce',
   n: 'showAssertNumber',
-  c: 'hasColors'
+  m: 'monochrome',
+  j: 'useJsonL'
 };
 
 const init = async () => {
@@ -60,6 +61,10 @@ const init = async () => {
         reporter = event => window.__tape6_reporter(id, event);
       } else if (window.parent && typeof window.parent.__tape6_reporter == 'function') {
         reporter = event => window.parent.__tape6_reporter(id, event);
+      } else if (options.useJsonL) {
+        const JSONLReporter = (await import('./src/JSONLReporter.js')).default,
+          jsonlReporter = new JSONLReporter(options);
+        reporter = jsonlReporter.report.bind(jsonlReporter);
       }
     } else if (isDeno) {
       if (Deno.env.TAPE6_JSONL) {
@@ -93,7 +98,7 @@ const init = async () => {
       }
     }
     if (!reporter) {
-      const tapReporter = new TapReporter({useJson: true, hasColors: options.hasColors});
+      const tapReporter = new TapReporter({useJson: true, hasColors: !options.monochrome});
       reporter = tapReporter.report.bind(tapReporter);
     }
     setReporter(reporter);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tape-six",
-  "version": "0.12.3",
+  "version": "1.0.0",
   "description": "TAP the test harness for the modern JavaScript (ES6).",
   "type": "module",
   "main": "index.js",
@@ -64,6 +64,6 @@
     }
   },
   "devDependencies": {
-    "puppeteer": "^23.4.1"
+    "puppeteer": "^23.5.1"
   }
 }

package/src/JSONLReporter.js

@@ -1,5 +1,5 @@
 class JSONLReporter {
-  constructor({renumberAsserts = false}) {
+  constructor({renumberAsserts = false} = {}) {
     this.renumberAsserts = renumberAsserts;
     this.assertCounter = 0;
   }

package/src/Tester.js

@@ -398,11 +398,11 @@ setAliases('ok', 'true, assert');
 setAliases('notOk', 'false, notok');
 setAliases('error', 'ifError, ifErr, iferror');
 setAliases('strictEqual', 'is, equal, equals, isEqual, strictEquals');
-setAliases('notStrictEqual', 'not, notEqual, notEquals, isNotEqual, doesNotEqual, isInequal, notStrictEquals, isNot');
+setAliases('notStrictEqual', 'not, notEqual, notEquals, isNotEqual, doesNotEqual, isUnequal, notStrictEquals, isNot');
 setAliases('looseEqual', 'looseEquals');
 setAliases('notLooseEqual', 'notLooseEquals');
 setAliases('deepEqual', 'same, deepEquals, isEquivalent');
-setAliases('notDeepEqual', 'notSame, notDeepEquals, notEquivalent, notDeeply, isNotDeepEqual, isNotDeepEqual, isNotEquivalent, isInequivalent');
+setAliases('notDeepEqual', 'notSame, notDeepEquals, notEquivalent, notDeeply, isNotDeepEqual, isNotEquivalent');
 setAliases('rejects', 'doesNotResolve');
 setAliases('resolves', 'doesNotReject');
 

package/web-app/index.js

@@ -3,13 +3,25 @@ import {getReporter, setReporter, setConfiguredFlag} from '../src/test.js';
 import defer from '../src/utils/defer.js';
 import State, {StopTest} from '../src/State.js';
 import TapReporter from '../src/TapReporter.js';
+import JSONLReporter from '../src/JSONLReporter.js';
 import DomReporter from './DomReporter.js';
 import DashReporter from './DashReporter.js';
 import TestWorker from './TestWorker.js';
 
 setConfiguredFlag(true); // we are running the show
 
-const optionNames = {f: 'failureOnly', t: 'showTime', b: 'showBanner', d: 'showData', o: 'failOnce', s: 'showStack', l: 'showLog', n: 'showAssertNumber'},
+const optionNames = {
+    f: 'failureOnly',
+    t: 'showTime',
+    b: 'showBanner',
+    d: 'showData',
+    o: 'failOnce',
+    s: 'showStack',
+    l: 'showLog',
+    n: 'showAssertNumber',
+    m: 'monochrome',
+    j: 'useJsonL'
+  },
   options = {};
 
 let flags = '',
@@ -62,10 +74,23 @@ window.addEventListener('DOMContentLoaded', () => {
     };
   }
 
-  const tapReporter = new TapReporter({useJson: true}),
-    domReporter = new DomReporter({root: document.querySelector('.tape6 .report')}),
-    dashReporter = new DashReporter();
-  setReporter(event => (options.showLog && tapReporter.report(event), domReporter.report(event), dashReporter.report(event)));
+  const dashReporter = new DashReporter(),
+    domReporter = new DomReporter({root: document.querySelector('.tape6 .report')});
+
+  let textReporter = null;
+  if (options.showLog) {
+    textReporter = options.useJsonL
+      ? new JSONLReporter()
+      : new TapReporter({useJson: true, hasColors: !options.monochrome});
+  }
+
+  setReporter(
+    event => (
+      textReporter && textReporter.report(event),
+      domReporter.report(event),
+      dashReporter.report(event)
+    )
+  );
 
   const donut = document.querySelector('tape6-donut');
   donut.show([{value: 0, className: 'nothing'}], {
@@ -92,9 +117,9 @@ window.addEventListener('DOMContentLoaded', () => {
 
     if (window.location.search) {
       if (patterns && patterns.length) {
-        files = await fetch('/--patterns?' + patterns.map(pattern => 'q=' + encodeURIComponent(pattern)).join('&')).then(response =>
-          response.ok ? response.json() : null
-        );
+        files = await fetch(
+          '/--patterns?' + patterns.map(pattern => 'q=' + encodeURIComponent(pattern)).join('&')
+        ).then(response => (response.ok ? response.json() : null));
       }
     }
 
@@ -107,7 +132,9 @@ window.addEventListener('DOMContentLoaded', () => {
       return;
     }
 
-    const importmap = await fetch('/--importmap').then(response => (response.ok ? response.json() : null));
+    const importmap = await fetch('/--importmap').then(response =>
+      response.ok ? response.json() : null
+    );
     if (importmap) options.importmap = importmap;
 
     const rootState = new State(null, {callback: getReporter(), failOnce: options.failOnce}),