@lumjs/tests 1.6.0 → 1.7.0

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

@@ -1,10 +1,10 @@
 // A functional interface to the test library.
-const Test = require('./test');
+const Test = require('./index');
 
 /**
  * A new test instance and a set of functions wrapping it.
  * 
- * @typedef {object} module:@lumjs/tests/functional.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
@@ -45,9 +45,9 @@ const Test = require('./test');
  *   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}
+ * @returns {module:@lumjs/tests/test/functional.Functional}
  * 
- * @exports module:@lumjs/tests/functional
+ * @exports module:@lumjs/tests/test/functional
  */
 function functional(opts={}, testClass=Test)
 {

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

@@ -1,8 +1,7 @@
 const core = require('@lumjs/core');
 const {types,obj} = core;
-const {F,S,N,isObj,isArray,needs,def} = types;
-
-// We use a separate class to represent test logs.
+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.
@@ -41,16 +40,10 @@ function $call (testfunc, args)
  * Raku's Test libraries.
  *
  * @exports module:@lumjs/tests/test
+ * @extends module:@lumjs/tests/test~Base
  * 
- * @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
+class Test extends Stats
 {
   /**
    * Build a new Test instance.
@@ -73,68 +66,11 @@ class Test
    *
    */
   constructor (opts={})
-  {
-    if (typeof opts === N)
-    {
-      opts = {plan: opts};
-    }
-    else if (typeof opts === S)
-    {
-      opts = {id: opts};
-    }
-
-    const hasModule = isObj(opts.module);
+  { // First call the Base constructor.
+    super(opts);
 
-    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;
-
-    // Methods that can be ran via run().
+    // Now register methods that can be ran via run().
     this.$testMethods = TEST_METHODS.slice();
-
-    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;
-      }
-    }
-
   }
 
   /**
@@ -160,84 +96,6 @@ class Test
     return require('./functional')(opts, this);
   }
 
-  // A wrapper around types.stringify()
-  stringify(what)
-  {
-    return types.stringify(what, this.stringifyDepth);
-  }
-
-  /**
-   * Indicate how many tests are planned to be run in this set.
-   * 
-   * @param {number} num - The number of tests that should run. 
-   */
-  plan (num)
-  {
-    if (typeof num === N)
-    {
-      this.planned = num;
-    }
-    else if (num === false)
-    {
-      this.planned = 0;
-    }
-    else
-    {
-      throw new Error("Invalid value passed to plan()");
-    }
-  }
-
-  /**
-   * 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.
-   * 
-   * @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.
-   */
-  ok (test, desc, directive, details)
-  {
-    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;
-  }
-
   /**
    * Run a function and pass its return value to `ok()`.
    *
@@ -256,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.
    * 
@@ -712,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.
    *
@@ -814,109 +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 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 ()
-  {
-    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);
 
@@ -980,8 +686,3 @@ 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/lib/{log.js → test/log.js}

@@ -9,27 +9,31 @@ const {S,O,isArray,stringify,def} = types;
  * 
  * @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 {module:@lumjs/tests/test} test - The parent `Test` instance.
+   * @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 = {};
@@ -66,7 +70,9 @@ 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";
 
@@ -101,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`;
       }
     }