@lumjs/tests 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -6,6 +6,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2022-07-29
+## Added
+- 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
+- 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.
+
+### Added
+- Configuration for JSDoc.
+- A few module-level *docblocks*.
+### Changed
+- Updated `@lumjs/core` dependency to `^1.0.0` (no more *beta* tags!)
+- Updated various *docblocks* for documentation.
+
 ## [1.3.0] - 2022-07-27
 ### Added
 - `$call()` function; powers `call()`, `lives()`, `dies()`, and `diesWith()`. 
@@ -57,7 +82,8 @@ 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.4.0...HEAD
+[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

@@ -4,6 +4,11 @@ const Test = require('./test');
 // A list of methods we can proxy directly.
 const PROXY_METHODS = Test.$METHODS.all;
 
+/**
+ * Module defining the functional API.
+ * @module @lumjs/tests/functional
+ */
+
 /**
  * A new test instance and a set of functions wrapping it.
  * @typedef {object} Functional
@@ -21,11 +26,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();
  * 
  * ```
  * 

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,6 +1,6 @@
 
 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.
@@ -19,7 +19,7 @@ const {F,S,O,isArray,stringify} = types;
  */
 class Log 
 {
-  constructor ()
+  constructor (test)
   {
     this.ok = false;
     this.skipped = false;
@@ -27,6 +27,8 @@ class Log
     this.desc = null;
     this.directive = null;
     this.details = {};
+    this.stringifyDepth = test.stringifyDepth;
+    def(this, '$test$', test);
   }
 
   /**
@@ -40,6 +42,8 @@ class Log
    */
   tap (num)
   {
+    const SD = this.stringifyDepth;
+
     var out;
     if (this.ok)
       out = 'ok ';
@@ -66,8 +70,8 @@ class Log
       var want = this.details.wanted;
       if (this.details.stringify)
       {
-        got = stringify(got);
-        want = stringify(want);
+        got = stringify(got, SD);
+        want = stringify(want, SD);
       }
       out += `#       got: ${got}\n`;
       out += `#  expected: ${want}\n`;
@@ -86,7 +90,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,11 @@
+/**
+ * Module defining the Test class.
+ * @module @lumjs/tests/test
+ */
+
 const core = require('@lumjs/core');
 const types = core.types;
-const {F,S,N,isObj,isArray,def} = types;
+const {F,S,N,isObj,isArray,needs,def} = types;
 
 // We use a separate class to represent test logs.
 const Log = require('./log');
@@ -15,7 +20,7 @@ const TEST_METHODS =
 // 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 +44,14 @@ 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.
+ *
+ * @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 +71,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 +101,46 @@ 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;
+
     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 wrapper around types.stringify()
+  stringify(what)
+  {
+    return types.stringify(what, this.stringifyDepth);
   }
 
   /**
@@ -142,7 +184,7 @@ class Test
    */
   ok (test, desc, directive, details)
   {
-    const log = new Log();
+    const log = new Log(this);
 
     if (test)
     {
@@ -185,7 +227,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 +299,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 +362,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 +392,7 @@ class Test
         break;
       case 'isnt':
       case '!==':
+      case 'not':
         test = (got !== want);
         break;
       case 'eq':
@@ -371,6 +421,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 +450,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 +579,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 +596,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 +698,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 +730,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 && TEST_METHODS.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 +798,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 +826,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 +834,28 @@ class Test
     return out;
   }
 
+  /**
+   * 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 +863,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...
@@ -679,3 +913,8 @@ def(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,15 @@
 {
   "name": "@lumjs/tests",
-  "version": "1.3.0",
+  "version": "1.4.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"
+  },
   "license": "MIT",
   "repository":
   {
@@ -9,11 +17,12 @@
     "url": "https://github.com/supernovus/lum.tests.js.git"
   },
   "dependencies": {
-    "@lumjs/core": "^1.0.0-beta.4"
+    "@lumjs/core": "^1.1.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"
   }
 }