@lumjs/tests 1.1.1 → 1.5.0

package/lib/test.js

@@ -1,15 +1,57 @@
+/**
+ * Module defining the Test class.
+ * @module @lumjs/tests/test
+ */
+
 const core = require('@lumjs/core');
-const {F,S,N,isType,isObj,isInstance,def} = core.types;
+const types = core.types;
+const {F,S,N,isObj,isArray,needs,def} = types;
 
 // We use a separate class to represent test logs.
 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',
+];
+
+// A list of other methods to export that are not standard tests.
+const META_METHODS = 
+[
+  'plan', 'diag', 'run', 'tap', 'output', 'done',
+];
+
+// The function that powers `Test.call()` and friends.
+function $call (testfunc, args)
+{
+  const ret = {};
+  try
+  {
+    ret.val = testfunc(...args);
+  }
+  catch (e)
+  {
+    ret.err = e;
+  }
+  return ret;
+}
+
 /**
  * A simple testing library with TAP support.
  * 
  * 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
 {
@@ -29,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={})
   {
@@ -56,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);
   }
 
   /**
@@ -106,15 +177,14 @@ class Test
    *   If the value evaluates as `true` (aka a truthy value), the test passes.
    *   If it evaluates as `false` (a falsey value), the test fails.
    * 
-   * @param {string} desc - A short description of the test.
-   * 
+   * @param {string} [desc] A short description of the test.
    * @param {(string|Error)} [directive] Further information for the log.
-   *    
+   * @param {object} [details] Extra details to add to the log.
    * @returns {Log} The test log with the results.
    */
-  ok (test, desc, directive)
+  ok (test, desc, directive, details)
   {
-    const log = new Log();
+    const log = new Log(this);
 
     if (test)
     {
@@ -135,11 +205,34 @@ class Test
       log.directive = directive;
     }
 
+    if (isObj(details))
+    {
+      log.details = details;
+    }
+
     this.log.push(log);
 
     return log;
   }
 
+  /**
+   * Run a function and pass its return value to `ok()`.
+   *
+   * @param {function} testfunc - The function to run.
+   *   If the function returns, the return value will be passed to `ok()`.
+   *   If it throws an Error, the test will be marked as failed, and the
+   *   Error will be passed as the `directive` to the `ok()` method.
+   *
+   * @param {string} [desc] A description for `ok()`.
+   * @param {...any} [args] Arguments to pass to the test function.
+   * @returns {Log}
+   */
+  call (testfunc, desc, ...args)
+  {
+    const ret = $call(testfunc, args);
+    return this.ok(ret.val, desc, ret.err);
+  }
+
   /**
    * Mark a test as failed.
    * 
@@ -174,20 +267,91 @@ class Test
    * call. If no error is caught the test will be considered to have failed.
    * 
    * @param {function} testfunc 
-   * @param {string} desc 
+   * @param {string} [desc] 
+   * @param {...any} [args]
    * @returns {Log}
    */
-  dies (testfunc, desc)
+  dies (testfunc, desc, ...args)
   {
-    let ok = false;
-    let err;
-    try { testfunc(); } 
-    catch (e)
+    const ret = $call(testfunc, args);
+    return this.ok(('err' in ret), desc, ret.err);
+  }
+
+  /**
+   * See if a function throws an Error, and if the Error passes a second test.
+   * 
+   * All the notes that apply to `dies()` apply here as well.
+   *
+   * @param {function} testfunc - Same as `dies()` and `call()`
+   *   We don't care about the return value of this function.
+   *   We only care that it *should* throw an Error.
+   *
+   * @param {(function|string)} testerr - A test to validate the Error.
+   *
+   * If this is a `function` it will be passed the thrown `Error` as the first
+   * parameter, and an `Array` of `args` as the second parameter. The return
+   * value from this will be passed to `ok()`.
+   *
+   * If this is a `string` then the test will pass only if the either the
+   * `Error.name` or `Error.message` is exactly equal to this value.
+   *
+   * @param {string} [desc] 
+   * @param {...any} [args]
+   * @returns {Log}
+   */
+  diesWith (testfunc, testerr, desc, ...args)
+  {
+    let ok = false, details = {}, err = null;
+
+    const r1 = $call(testfunc, args);
+
+    if ('err' in r1)
     {
-      ok = true;
-      err = e;
-    }
-    return this.ok(ok, desc, err);
+      err = r1.err;
+
+      if (typeof testerr === F)
+      { // A secondary function to test the error with.
+        const r2 = $call(testerr, [err, args]);
+        if ('err' in r2)
+        { // Second function threw an error, add it as diagnostic info.
+          details.info = r2.err;
+        }
+        else
+        { // No error, use the function output as the test value.
+          ok = r2.val;
+        }
+      }
+      else if (typeof testerr === S)
+      { // A simple name/message test.
+        if (err.name === testerr || err.message === testerr)
+        { // Either the name or the message matched the string.
+          ok = true;
+        }
+      }
+      
+    } // if r1.err
+
+    return this.ok(ok, desc, err, details);
+  }
+
+  /**
+   * See if a function runs without throwing an Error.
+   * 
+   * The function will be called in a `try { } catch (err) { }` block.
+   * 
+   * If an error is caught, the test will be considered to have failed,
+   * and the `Error` object will be used as the `directive` in the `ok()`
+   * call. If no error is caught the test will be considered to have passed.
+   * 
+   * @param {function} testfunc 
+   * @param {string} [desc] 
+   * @param {...any} [args]
+   * @returns {Log}
+   */
+  lives (testfunc, desc, ...args)
+  {
+    const ret = $call(testfunc, args);
+    return this.ok(!('err' in ret), desc, ret.err);
   }
 
   /**
@@ -198,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}
    */
@@ -221,6 +392,7 @@ class Test
         break;
       case 'isnt':
       case '!==':
+      case 'not':
         test = (got !== want);
         break;
       case 'eq':
@@ -249,19 +421,66 @@ 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; 
     }
 
-    const log = this.ok(test, desc);
+    let details = null;
     if (!test)
-    {
-      log.details.got = got;
-      log.details.wanted = want;
-      log.details.stringify = stringify;
-      log.details.comparitor = comp;
+    { // The test failed, add the deets.
+      details = 
+      {
+        got, 
+        wanted: want,
+        stringify,
+        comparitor: comp,
+      };
     }
-    return log;
+
+    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);
   }
 
   /**
@@ -271,7 +490,7 @@ class Test
    * 
    * @param {*} got 
    * @param {*} want 
-   * @param {string} desc 
+   * @param {string} [desc] 
    * @param {boolean} [stringify=true]
    * @returns {Log}
    */
@@ -287,8 +506,8 @@ class Test
    * 
    * @param {*} got - The result value from the test function.
    * @param {*} want - The value we expected from the test function.
-   * @param {string} desc 
-   * @param {boolean} [stringify=true] Use JSON details in TAP output?
+   * @param {string} [desc] 
+   * @param {boolean} [stringify=true]
    * @returns {Log}
    */
   isnt (got, want, desc, stringify=true)
@@ -300,57 +519,176 @@ class Test
    * See if a value is of a certain type.
    * 
    * @param {*} got 
-   * @param {(string|function)} want - A type name, or a constructor function.
+   * @param {Array} wants - Type names or constructor functions.
    * 
-   * This uses two type checking functions from `@lumsj/core`.
-   * If this is a string, we use the `isType()` function.
-   * If this is a constructor function, we use the `isInstance()` function.
+   * Uses `@lumjs/core/types.isa()` to perform the test.
    *  
-   * @param {string} desc 
+   * @param {string} [desc]
    * @param {boolean} [stringify=true]
    * @returns {Log}
    */
-  isa (got, want, desc, stringify=true)
+  isa (got, wants, desc, stringify=true, not=false)
   {
-    let test;
-    if (typeof want === S)
-    { // A string, we're going to use the isType function.
-      test = isType(want, got);
-    }
-    else if (typeof want === F)
-    { // Assuming it's a constructor.
-      test = isInstance(got, want);
+    if (!isArray(wants))
+    {
+      wants = [wants];
     }
-    else 
-    { // That's not supported.
-      throw new TypeError("'want' must be a string or a constructor");
+    let res = types.isa(got, ...wants);
+    if (not)
+    { // Inverse the result.
+      res = !res;
     }
 
-    const log = this.ok(test, desc);
-    if (!test)
-    {
-      log.details.got = got;
-      log.details.wanted = want;
-      log.details.stringify = stringify;
+    let details = null;
+    if (!res)
+    { // The test failed, add the deets.
+      details = 
+      {
+        got, 
+        wanted: wants,
+        stringify,
+        comparitor: not ? 'nota()' : 'isa()',
+      };
     }
-    return log;
+
+    return this.ok(res, desc, null, details);
+  }
+
+  /**
+   * See if a value is NOT of a certain type.
+   *
+   * Just inverses the results of `isa()`.
+   *
+   * @param {*} got
+   * @param {Array} wants - Type names of constructor functions.
+   * @param {string} [desc]
+   * @param {boolean} [stringify=true]
+   * @returns {Log}
+   */
+  nota (got, wants, desc, stringify=true)
+  {
+    return this.isa(got, wants, desc, stringify, true);
   }
 
   /**
    * An `is()` test, but encode both values as JSON first.
    * 
+   * Actually uses `core.types.stringify()` so it supports more
+   * data types than standard JSON, and can stringify functions,
+   * symbols, and several extended object types.
+   * 
    * @param {*} got 
    * @param {*} want 
-   * @param {string} desc 
-   * @returns 
+   * @param {string} [desc] 
+   * @returns {Log}
    */
   isJSON (got, want, desc)
   {
-    got = JSON.stringify(got);
-    want = JSON.stringify(want);
+    got = this.stringify(got);
+    want = this.stringify(want);
     return this.is(got, want, desc, false);
   }
 
+  /**
+   * An `isnt()` test, but encode both values as JSON first.
+   * 
+   * Like `isJSON()` this uses `core.types.stringify()`.
+   * 
+   * @param {*} got 
+   * @param {*} want 
+   * @param {string} [desc] 
+   * @returns {Log}
+   */
+  isntJSON (got, want, desc)
+  {
+    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.
    * 
@@ -360,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;
@@ -381,6 +719,78 @@ class Test
     this.log.push(msg);
   }
 
+  /**
+   * Run an assortment of tests using a map.
+   *
+   * The *current* test method defaults to `ok`.
+   *
+   * @param {...any} tests - The tests we're running.
+   *
+   * If this is a `string`, and is the name of one of the standard testing
+   * 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.
+   * 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 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)
+  {
+    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 === 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[funcall](current, ...test);
+        }
+        else
+        { // A standard test is in use.
+          log = this[current](...test);
+        }
+        logs.push(log);
+      }
+    }
+
+    return logs;
+  }
+
   /**
    * Return TAP formatted output for all the tests.
    * 
@@ -388,22 +798,21 @@ 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++);
       }
       else
       { // A comment.
-        out += '# ' + (typeof log === S ? log : JSON.stringify(log)) + "\n";
+        out += '# ' + (typeof log === S ? log : types.stringify(log)) + "\n";
       }
     }
     if (this.skipped)
@@ -417,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";
@@ -425,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 ()
   {
@@ -434,10 +863,58 @@ 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...
 def(Test, 'Log', Log);
 
+// Probably don't need this either, but...
+def(Test, '$call', $call);
+
+// Methods we're exporting for the 'functional' API.
+def(Test, '$METHODS',
+{
+  test: TEST_METHODS,
+  meta: META_METHODS,
+  get all()
+  {
+    const list = [];
+    for (const name in this)
+    {
+      if (name === 'all') continue;
+      const prop = this[name];
+      if (isArray(prop))
+      {
+        list.push(...prop);
+      }
+    }
+    return list;
+  },
+});
+
 // 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');
+