@lumjs/tests 1.5.0 → 1.7.0

package/lib/{functional.js → test/functional.js}

@@ -1,22 +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;
-
-/**
- * Module defining the functional API.
- * @module @lumjs/tests/functional
- */
+const Test = require('./index');
 
 /**
  * A new test instance and a set of functions wrapping it.
- * @typedef {object} Functional
+ * 
+ * @typedef {object} module:@lumjs/tests/test/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.
  */
 
 /**
@@ -42,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/test/functional.Functional}
  * 
+ * @exports module:@lumjs/tests/test/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/{test.js → test/index.js}

@@ -1,20 +1,14 @@
-/**
- * Module defining the Test class.
- * @module @lumjs/tests/test
- */
-
 const core = require('@lumjs/core');
-const types = core.types;
-const {F,S,N,isObj,isArray,needs,def} = types;
-
-// We use a separate class to represent test logs.
+const {types,obj} = core;
+const {F,S,isObj,isArray,needs,def} = types;
+const Stats = require('./stats');
 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.
@@ -45,15 +39,11 @@ function $call (testfunc, args)
  * 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.
+ * @exports module:@lumjs/tests/test
+ * @extends module:@lumjs/tests/test~Base
+ * 
  */
-class Test
+class Test extends Stats
 {
   /**
    * Build a new Test instance.
@@ -76,143 +66,34 @@ class Test
    *
    */
   constructor (opts={})
-  {
-    if (typeof opts === N)
-    {
-      opts = {plan: opts};
-    }
-    else if (typeof opts === S)
-    {
-      opts = {id: opts};
-    }
-
-    const hasModule = isObj(opts.module);
-
-    if (typeof opts.id === S)
-    { // A specific id was specified.
-      this.id = opts.id;
-    }
-    else if (hasModule)
-    { // We're going to generate a simple name.
-      this.id = core.modules.name(opts.module, opts.moduleName);
-    }
-    else 
-    { // An anonymous 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)
-    { // 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;
-      }
-    }
+  { // First call the Base constructor.
+    super(opts);
 
-  }
-
-  // A wrapper around types.stringify()
-  stringify(what)
-  {
-    return types.stringify(what, this.stringifyDepth);
+    // Now register methods that can be ran via run().
+    this.$testMethods = TEST_METHODS.slice();
   }
 
   /**
-   * Indicate how many tests are planned to be run in this set.
+   * A static shortcut for creating a new instance.
    * 
-   * @param {number} num - The number of tests that should run. 
+   * @param {object} [opts] Options to pass to constructor.
+   * @returns {module:@lumjs/tests/test}
    */
-  plan (num)
+  static new(opts={})
   {
-    if (typeof num === N)
-    {
-      this.planned = num;
-    }
-    else if (num === false)
-    {
-      this.planned = 0;
-    }
-    else
-    {
-      throw new Error("Invalid value passed to plan()");
-    }
+    return new this(opts);
   }
 
   /**
-   * Check if a value is truthy, and add a log indicating the result.
-   * 
-   * This is the absolute most basic method that every other testing method
-   * uses to log the results.
-   * 
-   * I won't document the `desc` and `directive` parameters on any of the
-   * other methods as they are exactly the same as here.
+   * A static shortcut for creating a `Functional` API object.
    * 
-   * @param {*} test - Any value, usually the output of a test function.
-   *   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|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.
+   * @param {object} [opts] Options to pass to constructor.
+   * @returns {module:@lumjs/tests/functional.Functional}
    */
-  ok (test, desc, directive, details)
+  static functional(opts={})
   {
-    const log = new Log(this);
-
-    if (test)
-    {
-      log.ok = true;
-    }
-    else
-    {
-      this.failed++;
-    }
-
-    if (typeof desc === S)
-    {
-      log.desc = desc;
-    }
-
-    if (directive)
-    {
-      log.directive = directive;
-    }
-
-    if (isObj(details))
-    {
-      log.details = details;
-    }
-
-    this.log.push(log);
-
-    return log;
+    //console.debug('functional this', this);
+    return require('./functional')(opts, this);
   }
 
   /**
@@ -233,30 +114,6 @@ class Test
     return this.ok(ret.val, desc, ret.err);
   }
 
-  /**
-   * Mark a test as failed.
-   * 
-   * @param {string} desc 
-   * @param {*} [directive] 
-   * @returns {Log}
-   */
-  fail (desc, directive)
-  {
-    return this.ok(false, desc, directive);
-  }
-
-  /**
-   * Mark a test as passed.
-   * 
-   * @param {string} desc 
-   * @param {*} [directive] 
-   * @returns {Log}
-   */
-  pass (desc, directive)
-  {
-    return this.ok(true, desc, directive);
-  }
-
   /**
    * See if a function throws an Error.
    * 
@@ -689,36 +546,6 @@ class Test
     }
   }
 
-  /**
-   * Skip a test.
-   * 
-   * @param {?string} reason - Why the test was skipped.
-   * @param {string} desc 
-   * @returns {Log}
-   */
-  skip (reason, desc)
-  {
-    const log = this.ok(true, desc);
-    log.skipped = true;
-    if (typeof reason === S)
-      log.skippedReason = reason;
-    this.skipped++;
-    return log;
-  }
-
-  /**
-   * Add diagnostics info directly to our test logs.
-   * 
-   * @param {*} msg - The info to add. 
-   *   If this is a `string` it will be displayed as a comment as is.
-   *   If it is anything else, it will be encoded as JSON first.
-   * 
-   */
-  diag (msg)
-  {
-    this.log.push(msg);
-  }
-
   /**
    * Run an assortment of tests using a map.
    *
@@ -758,7 +585,7 @@ class Test
     for (const test of tests)
     {
       const tt = typeof test;
-      if (tt === S && TEST_METHODS.includes(test))
+      if (tt === S && this.$testMethods.includes(test))
       { // Set the current test to a built-in.
         current = test;
       }
@@ -791,99 +618,11 @@ class Test
     return logs;
   }
 
-  /**
-   * Return TAP formatted output for all the tests.
-   * 
-   * @returns {string} The test logs, in TAP format.
-   */
-  tap ()
-  {
-    let out = '';
-    if (this.planned > 0)
-    {
-      out += '1..'+this.planned+"\n";
-    }
-    let t = 1;
-    for (const log of this.log)
-    {
-      if (log instanceof Log)
-      {
-        out += log.tap(t++);
-      }
-      else
-      { // A comment.
-        out += '# ' + (typeof log === S ? log : types.stringify(log)) + "\n";
-      }
-    }
-    if (this.skipped)
-    {
-      out += '# Skipped '+this.skipped+" tests\n";
-    }
-    if (this.failed)
-    {
-      out += '# Failed '+this.failed+(this.failed>1?' tests':' test');
-      if (this.planned)
-        out += ' out of '+this.planned;
-      out += "\n";
-    }
-    const ran = t-1;
-    if (this.planned > 0 && this.planned != ran)
-    {
-      out += '# Looks like you planned '+this.planned+' but ran '+ran+" tests\n";
-    }
-    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 ()
-  {
-    console.log(this.tap());
-    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
 
+// May want this for sub-classes.
+def(Test, 'Stats', Stats);
+
 // Should never need this, but...
 def(Test, 'Log', Log);
 
@@ -895,12 +634,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))
       {
@@ -909,12 +653,36 @@ def(Test, '$METHODS',
     }
     return list;
   },
-});
+  extend(newClass, opts={})
+  {
+    const mode  = obj.CLONE.DEEP;
+    const clone = obj.clone(this, {mode});
 
-// Export the class
-module.exports = Test;
+    //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);
+    }
 
-// 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');
+    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;

package/lib/{log.js → test/log.js}

@@ -5,25 +5,35 @@ 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?
+ * @property {boolean} todo - Was the test marked TODO?
+ * @property {string} reason - If the test was skipped or TODO, why?
  * @property {?string} desc - A short description of the test.
  * @property {*} directive - Special directives describing the test.
  * @property {object} details - Extra information about the test.
  * 
- * @property {*} [details.got] The value that was received in an `is` test.
- * @property {*} [details.wanted] The value that was expectged in an `is` test.
- * @property {*} [details.stringify] If `true` then output the details as JSON.
+ * @property {*} [details.got] The value that was received in a test.
+ * @property {*} [details.wanted] The value that was expectged in a test.
+ * @property {string} [details.comparitor] The comparitor used in a test.
+ * @property {boolean} [details.stringify] If `true` then output the details as JSON.
+ * @property {object} [details.info] An optional array of extra information.
  * 
  */
 class Log 
 {
+  /**
+   * (Internal Constructor) 
+   * @param {object} test - The parent `Test` or `Stats` instance.
+   */
   constructor (test)
   {
     this.ok = false;
     this.skipped = false;
-    this.skippedReason = '';
+    this.todo = false;
+    this.reason = '';
     this.desc = null;
     this.directive = null;
     this.details = {};
@@ -60,21 +70,27 @@ class Log
     else if (typeof this.directive == O && this.directive instanceof Error)
       out += ` # ${this.directive.name}: ${this.directive.message}`;
     else if (this.skipped)
-      out += ' # SKIP ' + this.skippedReason;
+      out += ' # SKIP ' + this.reason;
+    else if (this.todo)
+      out += ' # TODO ' + this.reason;
 
     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, SD);
-        want = stringify(want, SD);
+        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`;
@@ -91,7 +107,7 @@ class Log
       for (const i in info)
       {
         const line = (typeof info[i] === S) ? info[i] : stringify(info[i], SD);
-        out += `## ${line}\n`;
+        out += `# - ${line}\n`;
       }
     }