@lumjs/tests 1.9.0 → 2.0.0

package/CHANGELOG.md

@@ -11,6 +11,42 @@ and a reference to a property of a module will be in `@tests.propName` format.
 
 ## [Unreleased]
 
+## [2.0.0] - 2024-08-14
+### Added
+- The `Stats` class (and `Test` which extends it) now has async support.
+  - A new `.waiting` integer property indicates if async calls are in use.
+  - New `opts.async` nested options added to constructor options.
+  - The `async()` method takes an async function that returns a Promise,
+    increments the `.waiting` property, and then decrements it once the
+    returned Promise is either resolved or rejected.
+  - A `wait()` method is used by the `done()` method, and the Harness
+    to wait for all async calls to finish.
+- A new `registerGlobal` option for the `Harness` constructor that if `true`
+  will make it assign the instance to a special global variable.
+### Changed
+- The `Harness` constructor now requires a `Plugin` as a mandatory
+  parameter. No more auto-detection or other crufty magic.
+- The `bin/lumtest.js` script was updated with the API changes.
+- The `Plugin` constructor no longer takes the Harness instance as
+  a paramter. The `harness` property will be assigned directly by 
+  the harness instance instead.
+- `Plugin` class no longer extends the deprecated `core.AbstractClass`.
+- `Harness` has support for the new async functionality.
+  - The `run()` method is now explicitly `async`, as are its sub-methods.
+- Moved Harness Plugins into a `harness/plugin` sub-folder.
+- `Stats` can find the harness via the `registerGlobal` feature.
+  It still supports the CommonJS `require.main` method, but no
+  longer depends on it.
+- The `functional` module now supports using a different name
+  for the exported function than the underlying method. Useful
+  as the `async()` method is a reserved word and cannot be used
+  as a variable/function name (so it's renamed to `callAsync()`).
+- A bunch of extra modules are exported directly now.
+- Renamed some constructors for easier debugging.
+### Removed
+- The `harness/browser` plugin that I never implemented.
+  That's better done in a separate package.
+
 ## [1.9.0] - 2024-07-27
 ### Changed
 - Renamed `Harness` constructor name to `LumTestsHarness` to be more unique.
@@ -149,7 +185,8 @@ and a reference to a property of a module will be in `@tests.propName` format.
 - 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.9.0...HEAD
+[Unreleased]: https://github.com/supernovus/lum.tests.js/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/supernovus/lum.tests.js/compare/v1.9.0...v2.0.0
 [1.9.0]: https://github.com/supernovus/lum.tests.js/compare/v1.8.0...v1.9.0
 [1.8.0]: https://github.com/supernovus/lum.tests.js/compare/v1.7.1...v1.8.0
 [1.7.1]: https://github.com/supernovus/lum.tests.js/compare/v1.7.0...v1.7.1

package/README.md

@@ -6,15 +6,6 @@ This is nowhere near as advanced as many of the other options out there,
 but does what I need it to do, and works with the TAP testing protocol that
 the Perl and Raku programming languages popularized.
 
-## Exports
-
-| Name                 | Description                                          |
-| -------------------- | ---------------------------------------------------- |
-| `Test`               | The core class for testing.                          | 
-| `Harness`            | A class for running a bunch of tests together.       |
-| `functional()`       | A function for using functional-style testing.       |
-| `new()`              | A function for getting a new `Test` instance.        |
-
 ## Official URLs
 
 This library can be found in two places:

package/TODO.md

@@ -1,12 +1,11 @@
 # TODO
 
-- Update to properly support `async` tests; the `harness` will need some work.
 - Write tests for:
   - `call()`
   - `diesWith()`
   - `callIs()`
   - `matches()`
   - `run()`
+  - `async()` (currently used in `@lumjs/encode:v2.0.0` package).
 - Test the `harness/parser` and associated `grammar/tap` libraries.
 - Test the *external* test mode in `Harness`.
-

package/bin/lumtest.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 const process = require('node:process');
 const Harness = require('../lib/harness');
+const NodePlugin = require('../lib/harness/plugin/node');
 const core = require('@lumjs/core');
 const {S} = core.types;
 
@@ -59,7 +60,8 @@ for (const arg of args)
   }
 }
 
-const harness = new Harness(hOpts); // Create our Harness instance.
-module.exports = harness;           // Export it as the 'main' module.
-harness.addDir(aDir, aOpts);        // Add all the files in the test dir.
-harness.run(rPlan);                 // Run all the tests.
+// Create our Harness instance.
+const harness = new Harness(NodePlugin, hOpts); 
+module.exports = harness;     // Export it as the 'main' module.
+harness.addDir(aDir, aOpts);  // Add all the files in the test dir.
+harness.run(rPlan);           // Run all the tests.

package/lib/harness/index.js

@@ -1,5 +1,5 @@
 const core = require('@lumjs/core');
-const {def,lazy,context:ctx} = core;
+const {def,lazy} = core;
 const {B,F} = core.types;
 const QueuedTest = require('./queuedtest');
 const Plugin = require('./plugin');
@@ -12,16 +12,13 @@ const Plugin = require('./plugin');
  * 
  * @prop {object} opts - Options passed to constructor
  * 
- * @prop {object} testSuite - A `Stats` (or `Test`) instance
+ * @prop {module:@lumjs/tests/test/stats} testSuite
  * 
  * This meta-test will keep track of the success or failure of
  * all the other tests. So its `plan` will be equal to the number of
  * tests we're running, and so forth.
  * 
- * @prop {object} plugin - A platform-specific `Plugin`
- * 
- * This may be provided as a parameter to the constructor,
- * or auto-selected based on our Javascript environment.
+ * @prop {module:@lumjs/tests/harness/plugin} plugin - JS platform plugin
  * 
  * @prop {Array} queue - An array of `QueuedTest` instances
  * representing tests that we want to run.
@@ -38,15 +35,12 @@ class LumTestsHarness
   /**
    * Build a new Harness
    * 
-   * @param {object} [opts] Options
-   * @param {object} [opts.testSuite] A `Test` or `Stats` instance
-   * 
-   * This is probably not needed. We'll generate a new `Stats` instance.
+   * @param {module:@lumjs/tests/harness/plugin} plugin 
+   * The plugin for the current JS environment.
    * 
-   * @param {object} [opts.plugin] A `Plugin` instance.
+   * You can pass an instance `object`, or a class constructor `function`.
    * 
-   * This is probably not needed. We'll automatically determine a default
-   * plugin to use based on the JS environment.
+   * @param {object} [opts] Advanced Options
    * 
    * @param {boolean} [opts.plannedFailure=true] Is a broken plan a failure?
    * 
@@ -63,9 +57,35 @@ class LumTestsHarness
    * 
    * If this is `false` then no warning will be shown.
    * 
+   * @param {boolean} [opts.registerGlobal=false] Add a global variable?
+   * 
+   * If this is `true`, a global variable called `__lum_tests_harness__`
+   * will be registered as a pointer to this instance.
+   * 
+   * @param {module:@lumjs/tests/test/stats} [opts.testSuite] Meta-test
+   * 
+   * This option is generally for internal (mostly debugging) use only.
+   * Don't use it, just let the constructor build a new `Stats` instance.
+   * 
    */
-  constructor(opts={})
+  constructor(plugin, opts={})
   {
+    if (typeof plugin === F && Plugin.isPrototypeOf(plugin))
+    { // Class constructor was passed, build an instance.
+      plugin = new plugin();
+    }
+
+    if (plugin instanceof Plugin)
+    { // An explicit plugin was specified.
+      this.plugin = plugin;
+      plugin.harness = this;
+    }
+    else
+    { // That's not valid...
+      console.error({plugin, opts, harness: this});
+      throw new TypeError('Invalid Plugin specified');
+    }
+
     // Save a reference to the options.
     this.opts = opts;
 
@@ -78,23 +98,6 @@ class LumTestsHarness
       this.testSuite = new Stats(opts.testSuite);
     }
 
-    if (opts.plugin instanceof Plugin)
-    {
-      this.plugin = opts.plugin;
-    }
-    else if (ctx.isBrowser)
-    {
-      this.plugin = require('./browser').new(this);
-    }
-    else if (ctx.isNode)
-    {
-      this.plugin = require('./node').new(this);
-    }
-    else
-    {
-      throw new Error('Could not determine plugin');
-    }
-
     //console.debug("# ~ plugin", this.plugin, this);
 
     this.queue = []; // Tests to be ran.
@@ -105,6 +108,11 @@ class LumTestsHarness
     this.plannedFailure = opts.plannedFailure ?? true;
     this.plannedWarning = opts.plannedWarning ?? true;
 
+    if (opts.registerGlobal)
+    { // Add a global variable.
+      globalThis[Stats.HARNESS_GLOBAL] = this;
+    }
+
   } // constructor()
 
   /**
@@ -177,9 +185,9 @@ class LumTestsHarness
    * Run all the queued tests
    * 
    * @param {boolean} [plan=true] Set a test plan for the entire suite 
-   * @returns {object} `this`
+   * @returns {Promise<object>} Resolves to `this`
    */
-  run(plan=true)
+  async run(plan=true)
   {
     if (plan)
     {
@@ -188,15 +196,15 @@ class LumTestsHarness
 
     for (const queued of this.queue)
     {
-      this.runTest(queued);
+      await this.runTest(queued);
     }
 
     this.testSuite.done();
 
-    return this;
+    return this
   }
 
-  runTest(queued)
+  async runTest(queued)
   {
     const name = queued.filename;
     let test;
@@ -218,22 +226,42 @@ class LumTestsHarness
     }
     else
     { // Evaluate if the test is successful or not.
-      const ok = this.plugin.ok(test);
-      if (typeof ok === B)
-      { // A simple boolean response
-        this.testSuite.ok(ok, name);
-      }
-      else if (ok instanceof Error)
-      { // An error was returned
-        this.testSuite.fail(name, ok);
+      if (test.waiting)
+      { // async tests running
+        try
+        {
+          await test.wait();
+          this.testTest(test, name);
+        }
+        catch (err)
+        {
+          this.testSuite.fail(name, err);
+        }
       }
-      else 
-      { // This should never happen...
-        throw new Error("Invalid result from plugin.ok() !!");
+      else
+      {
+        this.testTest(test, name);
       }
     }
 
-    return this;
+    return test;
+  }
+
+  testTest(test, name)
+  {
+    const ok = this.plugin.ok(test);
+    if (typeof ok === B)
+    { // A simple boolean response
+      this.testSuite.ok(ok, name);
+    }
+    else if (ok instanceof Error)
+    { // An error was returned
+      this.testSuite.fail(name, ok);
+    }
+    else 
+    { // This should never happen...
+      throw new Error("Invalid result from plugin.ok() !!");
+    }
   }
 
   tap()

package/lib/harness/parser.js

@@ -1,4 +1,4 @@
-const {S,N,needType,isArray,isObj} = require('@lumjs/core/types');
+const {S,N,needType,isArray} = require('@lumjs/core/types');
 const Stats = require('../test/stats');
 const Tap = require('../grammar/tap');
 
@@ -21,7 +21,7 @@ const T = 'test',
  * 
  * @exports module:@lumjs/tests/harness/parser
  */
-class Parser
+class LumTestParser
 {
   /**
    * Build a TAP Parser.
@@ -145,9 +145,9 @@ class Parser
 
   static new(opts)
   {
-    return new Parser(opts);
+    return new LumTestParser(opts);
   }
 }
 
 // Export the class as the parser.
-module.exports = Parser;
+module.exports = LumTestParser;

package/lib/harness/{plugin.js → plugin/index.js}

@@ -1,34 +1,28 @@
 const core = require('@lumjs/core');
-const {AbstractClass} = core;
-const {TestFailure,PlanFailure} = require('./errors');
+const {AbstractError} = core;
+const {TestFailure,PlanFailure} = require('../errors');
 
 /**
  * An abstract base class for Harness plugins
  * 
- * @exports module:@lumjs/tests/harness~Plugin
+ * @prop {module:@lumjs/tests/harness} harness 
+ * The harness instance will assign itself to this property.
+ * 
+ * @exports module:@lumjs/tests/harness/plugin
  */
-class Plugin extends AbstractClass
+class Plugin
 {
-  /**
-   * (Internal class constructor)
-   * @param {module:@lumjs/tests/harness} harness - Parent `Harness` instance
-   */
-  constructor(harness)
-  {
-    super();
-    this.harness = harness;
-    this.$needs('run');
-  }
-
   /**
    * (ABSTRACT METHOD) Run a test
    * 
    * This method must be implemented by every plugin.
    * 
-   * @name module:@lumjs/tests/harness~Plugin#run
-   * @function
    * @param {object} queued - A queued test object
    */
+  run(queued)
+  {
+    throw new AbstractError("run() method not implemented");
+  }
 
   /**
    * See if a test had failures
@@ -67,11 +61,6 @@ class Plugin extends AbstractClass
     return true;
   }
 
-  static new(harness)
-  {
-    return new this(harness);
-  }
-
 }
 
 module.exports = Plugin;

package/lib/harness/{node.js → plugin/node.js}

@@ -1,7 +1,7 @@
 // Node.js harness plugin
 const core = require('@lumjs/core');
 const {N} = core.types;
-const Plugin = require('./plugin');
+const Plugin = require('./index');
 const cp = require('node:child_process');
 const getCwd = require('node:process').cwd;
 const fs = require('node:fs');
@@ -10,8 +10,8 @@ const path = require('node:path');
 /**
  * Node.js Harness plugin
  * 
- * @exports module:@lumjs/tests/harness~NodePlugin
- * @extends module:@lumjs/tetss/harness~Plugin
+ * @exports module:@lumjs/tests/harness/plugin/node
+ * @extends module:@lumjs/tetss/harness/plugin
  */
 class NodePlugin extends Plugin
 {

package/lib/test/functional.js

@@ -56,11 +56,22 @@ function functional(opts={}, testClass=Test)
   const proxyMethods = testClass.$METHODS.all;
   const test = new testClass(opts);
   const functions = { test };
-  for (const meth of proxyMethods)
+  for (const mdef of proxyMethods)
   {
-    functions[meth] = function ()
+    let sname, tname;
+    if (Array.isArray(mdef))
+    { // separate source and target names
+      sname = mdef[0];
+      tname = mdef[1];
+    }
+    else
+    { // same names for both
+      sname = tname = mdef;
+    }
+
+    functions[tname] = function ()
     {
-      return test[meth](...arguments);
+      return test[sname](...arguments);
     }
   }
   return functions;

package/lib/test/index.js

@@ -9,12 +9,13 @@ const TEST_METHODS =
 [
   'ok', 'call', 'callIs', 'fail', 'pass', 'dies', 'diesWith', 'lives', 'cmp',
   'is', 'isnt', 'isa', 'nota', 'isJSON', 'isntJSON', 'matches', 'skip',
+  ['async', 'callAsync'],
 ];
 
 // A list of other methods to export that are not standard tests.
 const META_METHODS = 
 [
-  'plan', 'diag', 'run', 'tap', 'output', 'done',
+  'plan', 'diag', 'run', 'tap', 'output', 'done', 'wait',
 ];
 
 // The function that powers `Test.call()` and friends.
@@ -40,10 +41,10 @@ function $call (testfunc, args)
  * Raku's Test libraries.
  *
  * @exports module:@lumjs/tests/test
- * @extends module:@lumjs/tests/test~Base
+ * @extends module:@lumjs/tests/test/stats
  * 
  */
-class Test extends Stats
+class LumTest extends Stats
 {
   /**
    * Build a new Test instance.
@@ -621,16 +622,16 @@ class Test extends Stats
 } // class Test
 
 // May want this for sub-classes.
-def(Test, 'Stats', Stats);
+def(LumTest, 'Stats', Stats);
 
 // Should never need this, but...
-def(Test, 'Log', Log);
+def(LumTest, 'Log', Log);
 
 // Probably don't need this either, but...
-def(Test, '$call', $call);
+def(LumTest, '$call', $call);
 
 // Methods we're exporting for the 'functional' API.
-def(Test, '$METHODS',
+def(LumTest, '$METHODS',
 {
   test: TEST_METHODS,
   meta: META_METHODS,
@@ -685,4 +686,4 @@ def(Test, '$METHODS',
 }); // Test.$METHODS
 
 // Export the class
-module.exports = Test;
+module.exports = LumTest;

package/lib/test/log.js

@@ -22,7 +22,7 @@ const {S,O,isArray,stringify,def} = types;
  * @property {object} [details.info] An optional array of extra information.
  * 
  */
-class Log 
+class LumTestLog 
 {
   /**
    * (Internal Constructor) 
@@ -117,4 +117,4 @@ class Log
 } // class Log
 
 // Export the class itself.
-module.exports = Log;
+module.exports = LumTestLog;

package/lib/test/stats.js

@@ -1,8 +1,15 @@
 const core = require('@lumjs/core');
 const mods = require('@lumjs/core/modules');
 const {types} = core;
-const {S,N,isObj,def} = types;
+const {S,N,F,isObj,def} = types;
 const Log = require('./log');
+const HARNESS_GLOBAL = '__lum_tests_harness__';
+
+const DEFAULT_ASYNC_OPTS =
+{
+  timeout:  30000,
+  interval: 5,
+}
 
 /**
  * Minimalistic base class for the `Test` library.
@@ -11,7 +18,7 @@ const Log = require('./log');
  * It's extremely minimal and does not provide the core testing methods.
  * See the [Test]{@link module:@lumjs/tests/test} class for that.
  *
- * @alias module:@lumjs/tests/test~Stats
+ * @alias module:@lumjs/tests/test/stats
  * 
  * @property {number}  planned - Number of tests planned, `0` if unplanned.
  * @property {number}  failed  - Number of tests that failed.
@@ -21,7 +28,7 @@ const Log = require('./log');
  * @property {boolean} isTop   - Test module was loaded from the command line.
  * @property {?object} harness - The top-level `Harness` if one was found.
  */
-class Stats
+class LumTestStats
 {
   /**
    * Build a new instance.
@@ -42,6 +49,10 @@ class Stats
    * @param {number} [opts.stringify=1] The depth `stringify()` should recurse
    *   objects and Arrays before switching to plain JSON stringification.
    *
+   * @param {object} [opts.async] Options for async tests
+   * @param {number} [opts.async.timeout=30000] Max time to wait (in ms)
+   * @param {number} [opts.async.interval=5] Status check every (in ms)
+   * 
    */
   constructor (opts={})
   {
@@ -74,6 +85,9 @@ class Stats
     this.failed  = 0;
     this.skipped = 0;
     this.planned = 0;
+    this.waiting = 0;
+
+    this.asyncOpts = Object.assign({}, DEFAULT_ASYNC_OPTS, opts.async);
 
     // The test logs for each unit.
     this.log = [];
@@ -106,10 +120,12 @@ class Stats
       { // We found the Harness instance.
         this.harness = require.main.exports;
       }
+      else if (isObj(globalThis[HARNESS_GLOBAL]))
+      {
+        this.harness = globalThis[HARNESS_GLOBAL];
+      }
     }
-
-    // Finally, mark the test stats as not generated yet.
-    def(this, '$done', false);
+    
   }
 
   // Internal method.
@@ -277,6 +293,83 @@ class Stats
     this.log.push(msg);
   }
 
+  /**
+   * Run async test code
+   * 
+   * If a test needs to wait for the results of an async operation,
+   * then this is the way to do it. This method does not actually
+   * call any testing methods, that needs to be done inside the `call`.
+   * 
+   * This increments `this.waiting`, which will be decremented when
+   * the `Promise` returned by the `call` is resolved or rejected.
+   * 
+   * @param {(function|Promise)} call - Async code to wait for
+   * 
+   * The `function` must be `async` or return a `Promise`.
+   * The function will have this Stats instance applied as `this`.
+   * 
+   * @param  {...any} args - Arguments for `call` function.
+   * 
+   * @returns {Promise}
+   */
+  async async(call, ...args)
+  {    
+    let testPromise;
+    this.waiting++;
+
+    if (typeof call === F)
+    { // It MUST be an async function, OR return a Promise.
+      testPromise = call.apply(this, args);
+    }
+    else
+    { // Assume the promise was passed directly.
+      testPromise = call;
+    }
+
+    if (testPromise instanceof Promise)
+    {
+      testPromise.finally(() => this.waiting--);
+    }
+    else
+    {
+      throw new TypeError("async() call must return a Promise");
+    }
+
+    return testPromise;
+  }
+
+  /**
+   * Called if `this.waiting` is greater than `0`
+   * 
+   * @returns {Promise<object>}
+   * 
+   * Will resolve to `this` when `this.waiting` becomes `0`.
+   * Will be rejected if the maximum wait timeout is reached.
+   */
+  wait()
+  {
+    const ao = this.asyncOpts;
+    return new Promise((resolve, reject) =>
+    {
+      const timeout = setTimeout(() =>
+      {
+        clearInterval(test);
+        clearTimeout(timeout);
+        reject(new Error("Timed out waiting for async encoding"));
+      }, ao.timeout);
+
+      const test = setInterval(() =>
+      {
+        if (this.waiting === 0)
+        {
+          clearInterval(test);
+          clearTimeout(timeout);
+          resolve(this);
+        }
+      }, ao.interval);
+    });
+  }
+
   /**
    * Return TAP formatted output for all the tests.
    * 
@@ -360,24 +453,33 @@ class Stats
   }
 
   /**
-   * 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.
+   * Run this when you're done testing.
    *
-   * If no `Harness` is in use, this will also run `this.output()`.
+   * It doesn't do much at all if a `Harness` is in use.
+   * 
+   * If no `Harness` is in use, this will call `this.output()`.
+   * If there are any async calls we're waiting on this will wait
+   * until they are complete before calling `this.output()`.
    */
   done ()
   {
-    if (this.$done)
+    if (this.harness)
+    { // The harness will handle the rest.
+      return this;
+    }
+    else if (this.waiting)
     {
-      throw new RangeError('Test set is already done');
+      this.wait().finally(() => this.done());
+    }
+    else
+    {
+      this.output();
     }
-    def(this, '$done', true);
-    return (this.harness ? this : this.output());
   }
 
-} // class Test
+} // class Stats
+
+def(LumTestStats, 'HARNESS_GLOBAL', HARNESS_GLOBAL);
 
 // Export the class
-module.exports = Stats;
+module.exports = LumTestStats;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/tests",
-  "version": "1.9.0",
+  "version": "2.0.0",
   "main": "lib/index.js",
   "bin":
   {
@@ -11,8 +11,11 @@
     ".": "./lib/index.js",
     "./test": "./lib/test/index.js",
     "./test/functional": "./lib/test/functional.js",
+    "./test/stats": "./lib/test/stats.js",
     "./harness": "./lib/harness/index.js",
     "./harness/parser": "./lib/harness/parser.js",
+    "./harness/plugin": "./lib/harness/plugin/index.js",
+    "./harness/plugin/node": "./lib/harness/plugin/node.js",
     "./package.json": "./package.json",
     "./data/*": "./test/data/*.js"
   },
@@ -24,7 +27,7 @@
   },
   "dependencies": 
   {
-    "@lumjs/core": "^1.8.0"
+    "@lumjs/core": "^1.26.0"
   },
   "scripts": {
     "test": "./bin/lumtest.js",

package/lib/harness/browser.js

@@ -1,18 +0,0 @@
-// Browser harness plugin
-const Plugin = require('./plugin');
-
-/**
- * Browser Harness plugin
- * 
- * @exports module:@lumjs/tests/harness~BrowserPlugin
- * @extends module:@lumjs/tetss/harness~Plugin
- */
-class BrowserPlugin extends Plugin
-{
-  run(queued)
-  {
-    throw new Error("Browser tests not supported yet");
-  }
-} // Node plugin class
-
-module.exports = BrowserPlugin;