@lumjs/tests 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -6,6 +6,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2022-09-12
+#### The *sub-classes* update
+### Added
+- `Test.new()` works like the `@lumjs/tests.new()`, but uses `this` so it's sub-classable.
+- `Test.static()`, calls `@lumjs/tests.functional()`, and passes `this` as the `testClass`.
+- `Test#TAP`, read-only accessor alias to `Test#tap()`.
+- `Test.$METHODS.$meta`, a list of properties to skip in `$METHODS.all` output.
+- `Test.$METHODS.extend()`, allow `Test` *sub-classes* to build upon the `$METHODS`
+  without changing the list in the original `Test` class.
+### Changed
+- Reworked a bunch of the DocBlocks to make the docs better.
+- Modified the `functional()` method to accept a `testClass` parameter.
+  This allows *sub-classes* to make their own functional APIs.
+- Changed `Log.tap()` to make the `details` structure more flexible.
+  The `wanted` property is now optional.
+- The `Test` class saves the test method list for `call()` into `this.$testMethods`
+  instead of using the `.$METHODS.test` directly.
+### Fixed
+- Added some missing functions to the registered list of test methods.
+
 ## [1.5.0] - 2022-08-30
 ### Added
 - Sample `data` used in some of the old tests.
@@ -85,7 +105,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.5.0...HEAD
+[Unreleased]: https://github.com/supernovus/lum.tests.js/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/supernovus/lum.tests.js/compare/v1.5.0...v1.6.0
 [1.5.0]: https://github.com/supernovus/lum.tests.js/compare/v1.4.0...v1.5.0
 [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

package/lib/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
- */
-
 /**
  * A new test instance and a set of functions wrapping it.
- * @typedef {object} Functional
+ * 
+ * @typedef {object} module:@lumjs/tests/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/functional.Functional}
  * 
+ * @exports module:@lumjs/tests/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/log.js

@@ -5,6 +5,8 @@ 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?
@@ -19,6 +21,10 @@ const {S,O,isArray,stringify,def} = types;
  */
 class Log 
 {
+  /**
+   * (Internal Constructor) 
+   * @param {module:@lumjs/tests/test} test - The parent `Test` instance.
+   */
   constructor (test)
   {
     this.ok = false;
@@ -64,17 +70,21 @@ class Log
 
     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`;

package/lib/test.js

@@ -1,10 +1,5 @@
-/**
- * Module defining the Test class.
- * @module @lumjs/tests/test
- */
-
 const core = require('@lumjs/core');
-const types = core.types;
+const {types,obj} = core;
 const {F,S,N,isObj,isArray,needs,def} = types;
 
 // We use a separate class to represent test logs.
@@ -13,8 +8,8 @@ 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,6 +40,8 @@ function $call (testfunc, args)
  * Which itself was based on Perl 5's Test::More, and
  * Raku's Test libraries.
  *
+ * @exports module:@lumjs/tests/test
+ * 
  * @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.
@@ -112,6 +109,9 @@ class Test
     this.isTop   = false;
     this.harness = null;
 
+    // Methods that can be ran via run().
+    this.$testMethods = TEST_METHODS.slice();
+
     if (typeof opts.plan === N)
     {
       this.plan(opts.plan);
@@ -137,6 +137,29 @@ class Test
 
   }
 
+  /**
+   * A static shortcut for creating a new instance.
+   * 
+   * @param {object} [opts] Options to pass to constructor.
+   * @returns {module:@lumjs/tests/test}
+   */
+  static new(opts={})
+  {
+    return new this(opts);
+  }
+
+  /**
+   * A static shortcut for creating a `Functional` API object.
+   * 
+   * @param {object} [opts] Options to pass to constructor.
+   * @returns {module:@lumjs/tests/functional.Functional}
+   */
+  static functional(opts={})
+  {
+    //console.debug('functional this', this);
+    return require('./functional')(opts, this);
+  }
+
   // A wrapper around types.stringify()
   stringify(what)
   {
@@ -758,7 +781,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;
       }
@@ -834,6 +857,16 @@ class Test
     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}
@@ -895,12 +928,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,7 +947,36 @@ def(Test, '$METHODS',
     }
     return list;
   },
-});
+  extend(newClass, opts={})
+  {
+    const mode  = obj.CLONE.DEEP;
+    const clone = obj.clone(this, {mode});
+
+    //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);
+    }
+
+    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/tests",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "main": "lib/index.js",
   "exports":
   {
@@ -18,7 +18,7 @@
     "url": "https://github.com/supernovus/lum.tests.js.git"
   },
   "dependencies": {
-    "@lumjs/core": "^1.1.0"
+    "@lumjs/core": "^1.3.0"
   },
   "scripts":
   {