@lumjs/tests 1.3.0 → 1.6.0

package/CHANGELOG.md

@@ -6,6 +6,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2022-09-12
+#### The *sub-classes* update
+### Added
+- `Test.new()` works like the `@lumjs/tests.new()`, but uses `this` so it's sub-classable.
+- `Test.static()`, calls `@lumjs/tests.functional()`, and passes `this` as the `testClass`.
+- `Test#TAP`, read-only accessor alias to `Test#tap()`.
+- `Test.$METHODS.$meta`, a list of properties to skip in `$METHODS.all` output.
+- `Test.$METHODS.extend()`, allow `Test` *sub-classes* to build upon the `$METHODS`
+  without changing the list in the original `Test` class.
+### Changed
+- Reworked a bunch of the DocBlocks to make the docs better.
+- Modified the `functional()` method to accept a `testClass` parameter.
+  This allows *sub-classes* to make their own functional APIs.
+- Changed `Log.tap()` to make the `details` structure more flexible.
+  The `wanted` property is now optional.
+- The `Test` class saves the test method list for `call()` into `this.$testMethods`
+  instead of using the `.$METHODS.test` directly.
+### Fixed
+- Added some missing functions to the registered list of test methods.
+
+## [1.5.0] - 2022-08-30
+### Added
+- Sample `data` used in some of the old tests.
+### Fixed
+- Mistakes in the changelog. 
+
+## [1.4.0] - 2022-07-29
+### Added
+- Configuration for JSDoc.
+- A few module-level *docblocks*.
+- Explicit `exports` section in `package.json` file.
+- Added `test.done()` method to be used instead of `test.output()`.
+- Added ability to configure the stringify depth.
+- Added ability to detect if the script was ran directly.
+- Added ability to check for a top-level `Harness` instance.
+- Added four new *binary flag* comparitor tests to `cmp()` method.
+- Added `not` alias for `!==` comparitor.
+- Added `matches` method for using a regular expression to match a string.
+- Added `callIs()` method that is like `call()` but takes a desired value and passes the function return value to `cmp()`, `isa()`, or other test methods.
+- A new `test.ran` computed property.
+
+### Changed
+- Updated `@lumjs/core` dependency to `^1.0.0` (no more *beta* tags!)
+- Updated various *docblocks* for documentation.
+- Enhanced a lot of docblocks.
+- Updated anything using `types.stringify()` to support the depth setting.
+- Updated `run()` so it can use either `call()` or `callIs()` as the underlying test method when using a custom `function` test.
+
 ## [1.3.0] - 2022-07-27
 ### Added
 - `$call()` function; powers `call()`, `lives()`, `dies()`, and `diesWith()`. 
@@ -57,7 +105,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ported from Lum.js v4 library set.
 - Added a few more features from the PHP version.
 
-[Unreleased]: https://github.com/supernovus/lum.tests.js/compare/v1.3.0...HEAD
+[Unreleased]: https://github.com/supernovus/lum.tests.js/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/supernovus/lum.tests.js/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/supernovus/lum.tests.js/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/supernovus/lum.tests.js/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/supernovus/lum.tests.js/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/supernovus/lum.tests.js/compare/v1.1.1...v1.2.0
 [1.1.1]: https://github.com/supernovus/lum.tests.js/compare/v1.1.0...v1.1.1

package/TODO.md

@@ -3,6 +3,8 @@
 - Write tests for:
   - `call()`
   - `diesWith()`
+  - `callIs()`
+  - `matches()`
   - `run()`
 - Write the `Harness` class, based of the Lum.php version.
 - Add tests for `Harness`.

package/jsdoc.json

@@ -0,0 +1,33 @@
+{
+  "tags": 
+  {
+    "allowUnknownTags": true
+  },
+  "source":
+  {
+    "include": ["./lib"]
+  },
+  "opts": 
+  {
+    "destination": "./docs/api",
+    "recurse": true
+  },
+  "plugins": 
+  [
+    "plugins/markdown"
+  ],
+  "templates": 
+  {
+    "cleverLinks": false,
+    "monospaceLinks": false,
+    "default": 
+    {
+      "outputSourceFiles": true
+    },
+    "path": "ink-docstrap",
+    "theme": "cerulean",
+    "navType": "vertical",
+    "linenums": true,
+    "dateFormat": "YYYY-MM-DD, hh:mm:ss"
+  }
+}

package/lib/functional.js

@@ -1,17 +1,18 @@
 // A functional interface to the test library.
 const Test = require('./test');
 
-// A list of methods we can proxy directly.
-const PROXY_METHODS = Test.$METHODS.all;
-
 /**
  * A new test instance and a set of functions wrapping it.
- * @typedef {object} Functional
+ * 
+ * @typedef {object} module:@lumjs/tests/functional.Functional
  * @property {Test} test - The new test instance.
  * 
  * All of the rest of the properties are functions that
  * can be imported into a JS scope using destructuring, and
  * which wrap the corresponding test instance method.
+ * 
+ * Basically anything that is a method of the `Test` instance
+ * will become a wrapped `function` available in this structure.
  */
 
 /**
@@ -21,11 +22,12 @@ const PROXY_METHODS = Test.$METHODS.all;
  * Usage is like:
  * 
  * ```js
- * const {plan,ok,isa} = require('@lumjs/tests').functional({module});
+ * const {plan,ok,isa,done} = require('@lumjs/tests').functional({module});
  * 
  * plan(2);
  * ok(true, 'ok() works');
  * isa(isa, 'function', 'isa is a function');
+ * done();
  * 
  * ```
  * 
@@ -36,14 +38,25 @@ const PROXY_METHODS = Test.$METHODS.all;
  *
  * @param {object} [opts] Options to pass to the `Test` constructor.
  * 
- * @returns {Functional}
+ * @param {function} [testClass=Test] The class we're creating an instance of.
+ * 
+ *   This defaults to `Test`, but can be changed to be a sub-class such as
+ *   `DOMTest` (defined in the `@lumjs/tests-dom` library.) This feature is
+ *   likely not useful for most end users, as knowledge of the internals is
+ *   required to make the functional API work.
+ * 
+ * @returns {module:@lumjs/tests/functional.Functional}
  * 
+ * @exports module:@lumjs/tests/functional
  */
-function functional(opts={})
+function functional(opts={}, testClass=Test)
 {
-  const test = new Test(opts);
+  //console.debug("functional()", testClass, testClass.$METHODS);
+  // A list of methods we can proxy directly.
+  const proxyMethods = testClass.$METHODS.all;
+  const test = new testClass(opts);
   const functions = { test };
-  for (const meth of PROXY_METHODS)
+  for (const meth of proxyMethods)
   {
     functions[meth] = function ()
     {

package/lib/harness.js

@@ -2,6 +2,11 @@
 const Test = require('./test');
 const Log  = require('./log');
 
+/**
+ * Module defining the Harness class.
+ * @module @lumjs/tests/harness
+ */
+
 /**
  * A class that acts as a test harness for running other tests.
  * 
@@ -14,3 +19,7 @@ class Harness
     throw new Error("Not yet implemented");
   }
 }
+
+// Export it.
+module.exports = Harness;
+

package/lib/index.js

@@ -1,13 +1,28 @@
 /**
  * Several test related classes.
+ * @module @lumjs/tests
  */
 
+/**
+ * Test class.
+ * @alias module:@lumjs/tests.Test
+ * @see module:@lumjs/tests/test
+ */
 const Test = require('./test');
-
 module.exports.Test = Test;
+
+/**
+ * Test Harness class.
+ * @alias module:@lumjs/tests.Harness
+ * @see module:@lumjs/tests/harness
+ */
 module.exports.Harness = require('./harness');
 
-// This one is not a class, but a special function.
+/**
+ * Functional API registration.
+ * @alias module:@lumjs/tests.functional
+ * @see module:@lumjs/tests/functional
+ */
 module.exports.functional = require('./functional');
 
 /**

package/lib/log.js

@@ -1,10 +1,12 @@
 
 const types = require('@lumjs/core').types;
-const {F,S,O,isArray,stringify} = types;
+const {S,O,isArray,stringify,def} = types;
 
 /**
  * A log representing the results of a test.
  * 
+ * @alias module:@lumjs/tests/test~Log
+ * 
  * @property {boolean} ok - Did the test pass.
  * @property {boolean} skipped - Was the test skipped?
  * @property {string} skippedReason - If the test was skipped, why?
@@ -19,7 +21,11 @@ const {F,S,O,isArray,stringify} = types;
  */
 class Log 
 {
-  constructor ()
+  /**
+   * (Internal Constructor) 
+   * @param {module:@lumjs/tests/test} test - The parent `Test` instance.
+   */
+  constructor (test)
   {
     this.ok = false;
     this.skipped = false;
@@ -27,6 +33,8 @@ class Log
     this.desc = null;
     this.directive = null;
     this.details = {};
+    this.stringifyDepth = test.stringifyDepth;
+    def(this, '$test$', test);
   }
 
   /**
@@ -40,6 +48,8 @@ class Log
    */
   tap (num)
   {
+    const SD = this.stringifyDepth;
+
     var out;
     if (this.ok)
       out = 'ok ';
@@ -60,17 +70,21 @@ class Log
 
     out += "\n";
 
-    if ('got' in this.details && 'wanted' in this.details)
+    if ('got' in this.details)
     {
-      var got = this.details.got;
-      var want = this.details.wanted;
-      if (this.details.stringify)
+      const stringy = this.details.stringify;
+      
+      let got = this.details.got;
+      if (stringy) got = stringify(got, SD);
+      out += `#       got: ${got}\n`;
+
+      if ('wanted' in this.details)
       {
-        got = stringify(got);
-        want = stringify(want);
+        let want = this.details.wanted;
+        if (stringy) want = stringify(want, SD);
+        out += `#  expected: ${want}\n`;
       }
-      out += `#       got: ${got}\n`;
-      out += `#  expected: ${want}\n`;
+
       if (typeof this.details.comparitor === S)
       {
         out += `#        op: ${this.details.comparitor}\n`;
@@ -86,7 +100,7 @@ class Log
 
       for (const i in info)
       {
-        const line = (typeof info[i] === S) ? info[i] : stringify(info[i]);
+        const line = (typeof info[i] === S) ? info[i] : stringify(info[i], SD);
         out += `## ${line}\n`;
       }
     }

package/lib/test.js

@@ -1,6 +1,6 @@
 const core = require('@lumjs/core');
-const types = core.types;
-const {F,S,N,isObj,isArray,def} = types;
+const {types,obj} = core;
+const {F,S,N,isObj,isArray,needs,def} = types;
 
 // We use a separate class to represent test logs.
 const Log = require('./log');
@@ -8,14 +8,14 @@ const Log = require('./log');
 // A list of Test methods that return Log objects.
 const TEST_METHODS =
 [
-  'ok', 'call', 'fail', 'pass', 'dies', 'diesWith', 'lives', 'cmp', 
-  'is', 'isnt', 'isa', 'nota', 'isJSON', 'isntJSON', 'skip',
+  'ok', 'call', 'callIs', 'fail', 'pass', 'dies', 'diesWith', 'lives', 'cmp',
+  'is', 'isnt', 'isa', 'nota', 'isJSON', 'isntJSON', 'matches', 'skip',
 ];
 
 // A list of other methods to export that are not standard tests.
 const META_METHODS = 
 [
-  'plan', 'diag', 'run', 'tap', 'output',
+  'plan', 'diag', 'run', 'tap', 'output', 'done',
 ];
 
 // The function that powers `Test.call()` and friends.
@@ -39,6 +39,16 @@ function $call (testfunc, args)
  * Based on Lum.php's Test library.
  * Which itself was based on Perl 5's Test::More, and
  * Raku's Test libraries.
+ *
+ * @exports module:@lumjs/tests/test
+ * 
+ * @property {number}  planned - Number of tests planned, `0` if unplanned.
+ * @property {number}  failed  - Number of tests that failed.
+ * @property {number}  skipped - Number of tests that were skipped.
+ * @property {number}  ran     - Number of tests ran (*calculated*). 
+ * @property {string}  id      - Unique test id used by `Harness` libary.
+ * @property {boolean} isTop   - Test module was loaded from the command line.
+ * @property {?object} harness - The top-level `Harness` if one was found.
  */
 class Test
 {
@@ -58,6 +68,9 @@ class Test
    *   Also, if this is passed, and `opts.id` was not specified, and id
    *   will be auto-generated based on the filename of the module.
    *
+   * @param {number} [opts.stringify=1] The depth `stringify()` should recurse
+   *   objects and Arrays before switching to plain JSON stringification.
+   *
    */
   constructor (opts={})
   {
@@ -85,20 +98,72 @@ class Test
       this.id = null;
     }
 
+    this.stringifyDepth = opts.stringify ?? 1;
+
     this.failed = 0;
     this.skipped = 0;
     this.planned = 0;
     this.log = [];
 
+    // These three will be updated below if possible.
+    this.isTop   = false;
+    this.harness = null;
+
+    // Methods that can be ran via run().
+    this.$testMethods = TEST_METHODS.slice();
+
     if (typeof opts.plan === N)
     {
       this.plan(opts.plan);
     }
 
     if (hasModule)
-    { // Finally, if a module was passed, its going to export this test.
+    { // If a module was passed, its going to export this test.
       opts.module.exports = this;
+      // We'll also use the module to determine if we're Harnessed or not.
+      if (require.main === opts.module)
+      { // Was called directly.
+        this.isTop = true;
+      }
+    }
+
+    if (!this.isTop)
+    { // Try to find a Harness instance.
+      if (isObj(require.main) && require.main.exports instanceof Harness)
+      { // We found the Harness instance.
+        this.harness = require.main.exports;
+      }
     }
+
+  }
+
+  /**
+   * A static shortcut for creating a new instance.
+   * 
+   * @param {object} [opts] Options to pass to constructor.
+   * @returns {module:@lumjs/tests/test}
+   */
+  static new(opts={})
+  {
+    return new this(opts);
+  }
+
+  /**
+   * A static shortcut for creating a `Functional` API object.
+   * 
+   * @param {object} [opts] Options to pass to constructor.
+   * @returns {module:@lumjs/tests/functional.Functional}
+   */
+  static functional(opts={})
+  {
+    //console.debug('functional this', this);
+    return require('./functional')(opts, this);
+  }
+
+  // A wrapper around types.stringify()
+  stringify(what)
+  {
+    return types.stringify(what, this.stringifyDepth);
   }
 
   /**
@@ -142,7 +207,7 @@ class Test
    */
   ok (test, desc, directive, details)
   {
-    const log = new Log();
+    const log = new Log(this);
 
     if (test)
     {
@@ -185,7 +250,7 @@ class Test
    * @param {...any} [args] Arguments to pass to the test function.
    * @returns {Log}
    */
-  call(testfunc, desc, ...args)
+  call (testfunc, desc, ...args)
   {
     const ret = $call(testfunc, args);
     return this.ok(ret.val, desc, ret.err);
@@ -257,7 +322,7 @@ class Test
    * @param {...any} [args]
    * @returns {Log}
    */
-  diesWith(testfunc, testerr, desc, ...args)
+  diesWith (testfunc, testerr, desc, ...args)
   {
     let ok = false, details = {}, err = null;
 
@@ -320,15 +385,22 @@ class Test
    * @param {string} comp - A comparitor to test with.
    * 
    * - `===`, `is`          (See also: `is()`)
-   * - `!==`, `isnt`        (See also: `isnt()`)
+   * - `!==`, `isnt`, `not` (See also: `isnt()`)
    * - `==`,  `eq`
    * - `!=`,  `ne`
    * - `>`,   `gt`
    * - `<`,   `lt`
    * - `>=`,  `ge`, `gte`
    * - `<=`,  `le`, `lte`
+   *
+   * A few special comparitors for *binary flag* testing:
+   *
+   * - `=&` → `((got & want) === want)`
+   * - `!&` → `((got & want) !== want)`
+   * - `+&` → `((got & want) !== 0)`
+   * - `-&` → `((got & want) === 0)`
    * 
-   * @param {string} desc 
+   * @param {string} [desc] 
    * @param {boolean} [stringify=true] Stringify values in TAP output?
    * @returns {Log}
    */
@@ -343,6 +415,7 @@ class Test
         break;
       case 'isnt':
       case '!==':
+      case 'not':
         test = (got !== want);
         break;
       case 'eq':
@@ -371,6 +444,16 @@ class Test
       case '>=':
         test = (got >= want);
         break;
+      case '=&':
+        test = ((got&want)===want);
+        break;
+      case '!&':
+        test = ((got&want)!==want)
+      case '+&':
+        test = ((got&want)!==0);
+        break;
+      case '-&':
+        test = ((got&want)===0);
       default:
         test = false; 
     }
@@ -390,6 +473,39 @@ class Test
     return this.ok(test, desc, null, details);
   }
 
+  /**
+   * See if a string matches a value.
+   * 
+   * @param {string} got
+   * @param {RegExp} want
+   * @param {string} [desc] 
+   * @param {boolean} [stringify=true]
+   * @returns {Log}
+   */
+  matches(got, want, desc, stringify=true)
+  {
+    const no = {error: "matches 'got' value must be a string"};
+    needs(got, no, S);
+    no.error = "matches 'want' value must be a RegExp";
+    needs(want, no, RegExp);
+
+    const test = want.test(got);
+
+    let details = null;
+    if (!test)
+    { // The test failed, add the deets.
+      details = 
+      {
+        got, 
+        wanted: want,
+        stringify,
+        comparitor: 'matches',
+      };
+    }
+
+    return this.ok(test, desc, null, details);
+  }
+
   /**
    * See if two values are equal.
    * 
@@ -486,13 +602,13 @@ class Test
    * 
    * @param {*} got 
    * @param {*} want 
-   * @param {string} desc 
-   * @returns 
+   * @param {string} [desc] 
+   * @returns {Log}
    */
   isJSON (got, want, desc)
   {
-    got = types.stringify(got);
-    want = types.stringify(want);
+    got = this.stringify(got);
+    want = this.stringify(want);
     return this.is(got, want, desc, false);
   }
 
@@ -503,16 +619,99 @@ class Test
    * 
    * @param {*} got 
    * @param {*} want 
-   * @param {string} desc 
-   * @returns 
+   * @param {string} [desc] 
+   * @returns {Log}
    */
   isntJSON (got, want, desc)
   {
-    got = types.stringify(got);
-    want = types.stringify(want);
+    got = this.stringify(got);
+    want = this.stringify(want);
     return this.isnt(got, want, desc, false);
   }
 
+  /**
+   * Run a function and see if it's return value is what we wanted.
+   *
+   * @param {function} testfunc - The function to run.
+   *   The return value will be passed to `cmp()` or another appropriate
+   *   testing method as determined by the options.
+   *   How this handles error handling is determined by options as well.
+   *
+   * @param {*} want - The value we want.
+   * @param {(object|string)} [opts] Named options for further behaviour.
+   *   If it is a string it's considered the `opts.desc` option.
+   * @param {string} [opts.desc] A description for `ok()`.
+   * @param {boolean} [opts.stringify=true]
+   * @param {Array} [opts.args] Arguments to pass to the test function.
+   * @param {string} [opts.comp="is"] - The comparitor to test with.
+   *   In addition to all of the comparitors from `cmp()`, there are a few
+   *   extra comparitors that will pass through to other methods:
+   *   - `isa` → Use `isa()` to test return value.
+   *   - `nota` → Use `nota()` to test return value.
+   *   - `=json`, `isJSON` → Use `isJSON()` to test return value.
+   *   - `!json`, `isntJSON` → Use `isntJSON()` to test return value.
+   *   - `matches` → Use `matches()` to test return value.
+   *
+   * @param {boolean} [opts.thrown=false] How to handle thrown errors.
+   *   
+   *   If this is `true`, then anything thrown will be passed as if it was
+   *   the return value from the function.
+   *
+   *   If this is `false`, then any errors thrown will result in an immediate
+   *   failure of the test without any further processing, and the error will
+   *   be passed as the `directive` to the `ok()` method.
+   *
+   * @returns {Log}
+   */
+  callIs (testfunc, want, opts={})
+  {
+    const args = opts.args ?? [];
+    const ret = $call(testfunc, args);
+    const desc = opts.desc;
+
+    let got;
+
+    if (ret.err)
+    { // How to handle errors.
+      if (opts.thrown)
+      { // We're going to test the error.
+        got = ret.err;
+      }
+      else
+      { // This is an automatic failure.
+        return this.ok(false, desc, ret.err);
+      }
+    }
+    else
+    { // No errors, good, testing against the return value.
+      got = ret.val;
+    }
+
+    const CFUN = 
+    {
+      'matches':  'matches',
+      'isa':      'isa',
+      'nota':     'nota',
+      'isJSON':   'isJSON',
+      '=json':    'isJSON',
+      'isntJSON': 'isntJSON',
+      '!json':    'isntJSON',
+     };
+
+    const comp = opts.comp ?? 'is';
+    const stringify = opts.stringify ?? true;
+
+    if (typeof CFUN[comp] === S)
+    { // A function with a custom return value.
+      const meth = CFUN[comp];
+      return this[meth](got, want, desc, stringify);
+    }
+    else
+    { // We're going to use the cmp() method.
+      return this.cmp(got, want, comp, desc, stringify);
+    }
+  }
+
   /**
    * Skip a test.
    * 
@@ -522,7 +721,7 @@ class Test
    */
   skip (reason, desc)
   {
-    var log = this.ok(true, desc);
+    const log = this.ok(true, desc);
     log.skipped = true;
     if (typeof reason === S)
       log.skippedReason = reason;
@@ -554,35 +753,55 @@ class Test
    * methods in this class, it will be set as the *current* test method.
    *
    * If this is a `function`, it will be set as the *current* test method.
-   * Function test methods are passed to `call()` with the test parameters.
+   * By default function test methods are passed to `call()` with the test 
+   * parameters. However, if the *previous* test method was `callIs` then
+   * the `callIs()` method will be used as long as the custom function is
+   * the *current* test method. Likewise to switch back to `call()` simply
+   * set the *current* test method to `call` before setting it to a new custom
+   * test `function`.
    *
    * If this is an `Array` then it's the parameters for the *current* test
-   * method. If a custom `function` is in use, remember that the *first*
-   * parameter is **always** the `desc`, and any subsequent parameters will be
-   * passed to the custom `function` call.
+   * method. If a custom `function` is in use, remember that it's the
+   * `call()` or `callIs()` methods that will be being called, with their
+   * first parameter always being the custom function.
    *
    * Any value other than one of those will throw a `TypeError`.
    *
    * @returns {Log[]} A `Log` item for each test that was ran.
    */
-  run(...tests)
+  run (...tests)
   {
+    const CF = 'call';
+    const CI = 'callIs';
+
     const logs = [];
+    let funcall = CF;
     let current = 'ok';
     
     for (const test of tests)
     {
       const tt = typeof test;
-      if (tt === F || (tt === S && TEST_METHODS.includes(test)))
-      { // Set the current test.
+      if (tt === S && this.$testMethods.includes(test))
+      { // Set the current test to a built-in.
         current = test;
       }
+      else if (tt === F)
+      { // A custom test function for further tests.
+        if (current === CI)
+        { // Last test was `callIs` using that for the custom function.
+          funcall = CI;
+        }
+        else if (current === CF)
+        { // Last test was `call`, using that for the custom function.
+          funcall = CF;
+        }
+      }
       else if (isArray(test))
       { // A set of test parameters.
         let log;
         if (typeof current === F)
         { // A custom test function is in use.
-          log = this.call(current, ...test);
+          log = this[funcall](current, ...test);
         }
         else
         { // A standard test is in use.
@@ -602,15 +821,14 @@ class Test
    */
   tap ()
   {
-    var out = '';
+    let out = '';
     if (this.planned > 0)
     {
       out += '1..'+this.planned+"\n";
     }
-    var t = 1;
-    for (var i = 0; i < this.log.length; i++)
+    let t = 1;
+    for (const log of this.log)
     {
-      var log = this.log[i];
       if (log instanceof Log)
       {
         out += log.tap(t++);
@@ -631,7 +849,7 @@ class Test
         out += ' out of '+this.planned;
       out += "\n";
     }
-    var ran = t-1;
+    const ran = t-1;
     if (this.planned > 0 && this.planned != ran)
     {
       out += '# Looks like you planned '+this.planned+' but ran '+ran+" tests\n";
@@ -639,8 +857,38 @@ class Test
     return out;
   }
 
+  /**
+   * A read-only *accessor* property alias for `tap()`.
+   * @returns {string}
+   * @see {@link module:@lumjs/tests/test#tap}
+   */
+  get TAP()
+  {
+    return this.tap();
+  }
+
+  /**
+   * A calculated property of the number of tests that were ran.
+   * @type {int}
+   */
+  get ran ()
+  {
+    let ran = 0;
+    for (const log of this.log)
+    {
+      if (log instanceof Log)
+      {
+        ran++;
+      }
+    }
+    return ran;
+  }
+
   /**
    * Send the TAP output to the `console`.
+   *
+   * This is a low-level method and is no longer recommended for use.
+   * Instead call the `done()` method, which will *do the right thing*.
    */
   output ()
   {
@@ -648,6 +896,25 @@ class Test
     return this;
   }
 
+  /**
+   * We're done testing.
+   *
+   * This will mark the test-set as finished, so attempting to run further
+   * tests after will result in a `RangeError` being thrown.
+   *
+   * If no `Harness` is in use, this will also run `this.output()`.
+   */
+  done ()
+  {
+    if (this.$done)
+    {
+      throw new RangeError('Test set is already done');
+    }
+    this.$done = true;
+
+    return (this.harness ? this : this.output());
+  }
+
 } // class Test
 
 // Should never need this, but...
@@ -661,12 +928,17 @@ def(Test, '$METHODS',
 {
   test: TEST_METHODS,
   meta: META_METHODS,
+  $meta: 
+  [ // A list of properties to skip in `all`.
+    '$meta', 'all', 'extend',
+  ],
   get all()
   {
     const list = [];
+    const skip = this.$meta;
     for (const name in this)
     {
-      if (name === 'all') continue;
+      if (skip.includes(name)) continue;
       const prop = this[name];
       if (isArray(prop))
       {
@@ -675,7 +947,41 @@ def(Test, '$METHODS',
     }
     return list;
   },
-});
+  extend(newClass, opts={})
+  {
+    const mode  = obj.CLONE.DEEP;
+    const clone = obj.clone(this, {mode});
+
+    //console.debug("extend:clone<pre>", clone);
+
+    if (isObj(opts.add))
+    { // Add in the extra properties.
+      //console.debug("opts.add", opts.add);
+      obj.copyProps(opts.add, clone, opts.addOpts);
+    }
+
+    if (isArray(opts.meta))
+    { // Added properties to skip in 'all'.
+      for (const val of opts.meta)
+      {
+        if (!clone.$meta.includes(val))
+        {
+          clone.$meta.push(val);
+        }
+      }
+    }
+
+    //console.debug("extend:clone<post>", clone);
+
+    // Add a new cloned and extended `$METHODS` property. 
+    def(newClass, '$METHODS', {value: clone});
+  }, // extend()
+}); // Test.$METHODS
 
 // Export the class
 module.exports = Test;
+
+// Finally at the bottom after `module.exports` has been set, we will load
+// the Harness class to avoid circular references failing.
+const Harness = require('./harness');
+

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@lumjs/tests",
-  "version": "1.3.0",
+  "version": "1.6.0",
   "main": "lib/index.js",
+  "exports":
+  {
+    ".": "./lib/index.js",
+    "./test": "./lib/test.js",
+    "./functional": "./lib/functional.js",
+    "./harness": "./lib/harness.js",
+    "./package.json": "./package.json",
+    "./data/*": "./test/data/*.js"
+  },
   "license": "MIT",
   "repository":
   {
@@ -9,11 +18,12 @@
     "url": "https://github.com/supernovus/lum.tests.js.git"
   },
   "dependencies": {
-    "@lumjs/core": "^1.0.0-beta.4"
+    "@lumjs/core": "^1.3.0"
   },
   "scripts":
   {
     "-TODO-1": "When Harness and bin/lumtest are done, use that for 'test'",
-    "test": "prove -e node --ext js ./test"
+    "test": "prove -e node --ext js ./test",
+    "build-docs": "jsdoc -c ./jsdoc.json"
   }
 }

package/test/data/people.js

@@ -0,0 +1,58 @@
+module.exports = function (opts={})
+{
+  let people = 
+  [
+    {
+      name: 'Bob',
+      age: 40,
+    },
+    {
+      name: 'Lisa',
+      age: 25,
+    },
+    {
+      name: 'Kevin',
+      age: 18,
+    },
+    {
+      name: 'Sarah',
+      age: 13,
+    },
+  ];
+
+  if (opts.withRecursion)
+  {
+    people[0].kids = [people[2],people[3]];
+    people[1].kids = [people[3]];
+    people[2].kids = [];
+    people[3].kids = [];
+    people[0].parents = [];
+    people[1].parents = [];
+    people[2].parents = [people[0]];
+    people[3].parents = [people[0],people[1]];
+  }
+  else if (opts.withReferences)
+  {
+    people[0].kids = [2,3];
+    people[1].kids = [3];
+    people[2].kids = [];
+    people[3].kids = [];
+    people[0].parents = [];
+    people[1].parents = [];
+    people[2].parents = [0];
+    people[3].parents = [0,1];
+  }
+  else if (opts.withNames)
+  {
+    people[0].kids = [people[2].name,people[3].name];
+    people[1].kids = [people[3].name];
+    people[2].kids = [];
+    people[3].kids = [];
+    people[0].parents = [];
+    people[1].parents = [];
+    people[2].parents = [people[0].name];
+    people[3].parents = [people[0].name,people[1].name];
+  }
+
+  return people;
+}