@lumjs/tests 1.1.0 → 1.4.0

package/CHANGELOG.md

@@ -6,6 +6,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2022-07-29
+## Added
+- Explicit `exports` section in `package.json` file.
+- Added `test.done()` method to be used instead of `test.output()`.
+- Added ability to configure the stringify depth.
+- Added ability to detect if the script was ran directly.
+- Added ability to check for a top-level `Harness` instance.
+- Added four new *binary flag* comparitor tests to `cmp()` method.
+- Added `not` alias for `!==` comparitor.
+- Added `matches` method for using a regular expression to match a string.
+- Added `callIs()` method that is like `call()` but takes a desired value and passes the function return value to `cmp()`, `isa()`, or other test methods.
+- A new `test.ran` computed property.
+
+## Changed
+- Enhanced a lot of docblocks.
+- Updated anything using `types.stringify()` to support the depth setting.
+- Updated `run()` so it can use either `call()` or `callIs()` as the underlying test method when using a custom `function` test.
+
+### Added
+- Configuration for JSDoc.
+- A few module-level *docblocks*.
+### Changed
+- Updated `@lumjs/core` dependency to `^1.0.0` (no more *beta* tags!)
+- Updated various *docblocks* for documentation.
+
+## [1.3.0] - 2022-07-27
+### Added
+- `$call()` function; powers `call()`, `lives()`, `dies()`, and `diesWith()`. 
+- `call()` method; test the result of a function call.
+- `diesWith()` method; like `dies()` but also tests the thrown `Error`.
+- `run()` method; for running a bunch of similar tests with a compact syntax.
+### Changed
+- How `functional` gets its list of test methods to proxy.
+- Cleaned up a bunch of stuff in the `Log` class.
+- Added a `details.info` structure to the `Log` class.
+- Refactored `lives()` and `dies()` to use the new `$call()` function.
+- Updated `ok()` to support passing `details` to it directly.
+- Some further cleanups in the `Test` class.
+
+## [1.2.0] - 2022-07-26
+### Added
+- `lives()` method; the inverse of `dies()`.
+- `nota()` method; the inverse of `isa()`.
+- `isntJSON()` method; the inverse of `isJSON()`.
+- Tests for `isa()`, `isJSON()`, and all the new methods.
+### Changed
+- `isa()` uses `core.types.isa()` method now.
+- `isa()` supports multiple `wants` values, just use an Array.
+- Anything that used `JSON.stringify()` now uses `core.types.stringify()`.
+
+## [1.1.1] - 2022-07-15
+### Fixed
+- Dependency issue in `package.json` with pre-release parent.
+### Added
+- A temporary `npm test` script using the `prove` utility from Perl 5.
+
 ## [1.1.0] - 2022-07-08
 ### Fixed
 - Changelog had wrong URLs.
@@ -26,7 +82,11 @@ 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.1.0...HEAD
+[Unreleased]: https://github.com/supernovus/lum.tests.js/compare/v1.4.0...HEAD
+[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
+[1.2.0]: https://github.com/supernovus/lum.tests.js/compare/v1.1.1...v1.2.0
+[1.1.1]: https://github.com/supernovus/lum.tests.js/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/supernovus/lum.tests.js/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/supernovus/lum.tests.js/releases/tag/v1.0.0
 

package/TODO.md

@@ -1,7 +1,12 @@
 # TODO
 
-- Add tests for `isa()` method.
+- Write tests for:
+  - `call()`
+  - `diesWith()`
+  - `callIs()`
+  - `matches()`
+  - `run()`
 - Write the `Harness` class, based of the Lum.php version.
 - Add tests for `Harness`.
-- Create 'lumtest' binary for running the harness without `prove` utility.
+- Create `lumtest` binary for running the harness without `prove` utility.
 

package/jsdoc.json

@@ -0,0 +1,33 @@
+{
+  "tags": 
+  {
+    "allowUnknownTags": true
+  },
+  "source":
+  {
+    "include": ["./lib"]
+  },
+  "opts": 
+  {
+    "destination": "./docs/api",
+    "recurse": true
+  },
+  "plugins": 
+  [
+    "plugins/markdown"
+  ],
+  "templates": 
+  {
+    "cleverLinks": false,
+    "monospaceLinks": false,
+    "default": 
+    {
+      "outputSourceFiles": true
+    },
+    "path": "ink-docstrap",
+    "theme": "cerulean",
+    "navType": "vertical",
+    "linenums": true,
+    "dateFormat": "YYYY-MM-DD, hh:mm:ss"
+  }
+}

package/lib/functional.js

@@ -2,11 +2,12 @@
 const Test = require('./test');
 
 // A list of methods we can proxy directly.
-const PROXY_METHODS = 
-[
-  'plan', 'ok', 'fail', 'pass', 'dies', 'cmp', 'isa', 'is', 'isnt', 
-  'isJSON', 'skip', 'diag', 'tap', 'output',
-];
+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.
@@ -16,20 +17,6 @@ const PROXY_METHODS =
  * 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.
- * 
- * @property {function} plan 
- * @property {function} ok
- * @property {function} fail 
- * @property {function} pass 
- * @property {function} dies 
- * @property {function} cmp 
- * @property {function} isa 
- * @property {function} is 
- * @property {function} isnt 
- * @property {function} isJSON 
- * @property {function} skip 
- * @property {function} diag 
- * @property {function} tap  
  */
 
 /**
@@ -39,11 +26,12 @@ const PROXY_METHODS =
  * Usage is like:
  * 
  * ```js
- * const {plan,ok,isa} = require('@lumjs/tests').functional({module});
+ * const {plan,ok,isa,done} = require('@lumjs/tests').functional({module});
  * 
  * plan(2);
  * ok(true, 'ok() works');
  * isa(isa, 'function', 'isa is a function');
+ * done();
  * 
  * ```
  * 

package/lib/harness.js

@@ -2,6 +2,11 @@
 const Test = require('./test');
 const Log  = require('./log');
 
+/**
+ * Module defining the Harness class.
+ * @module @lumjs/tests/harness
+ */
+
 /**
  * A class that acts as a test harness for running other tests.
  * 
@@ -14,3 +19,7 @@ class Harness
     throw new Error("Not yet implemented");
   }
 }
+
+// Export it.
+module.exports = Harness;
+

package/lib/index.js

@@ -1,13 +1,28 @@
 /**
  * Several test related classes.
+ * @module @lumjs/tests
  */
 
+/**
+ * Test class.
+ * @alias module:@lumjs/tests.Test
+ * @see module:@lumjs/tests/test
+ */
 const Test = require('./test');
-
 module.exports.Test = Test;
+
+/**
+ * Test Harness class.
+ * @alias module:@lumjs/tests.Harness
+ * @see module:@lumjs/tests/harness
+ */
 module.exports.Harness = require('./harness');
 
-// This one is not a class, but a special function.
+/**
+ * Functional API registration.
+ * @alias module:@lumjs/tests.functional
+ * @see module:@lumjs/tests/functional
+ */
 module.exports.functional = require('./functional');
 
 /**

package/lib/log.js

@@ -1,5 +1,6 @@
 
-const {F,S,O} = require('@lumjs/core').types;
+const types = require('@lumjs/core').types;
+const {S,O,isArray,stringify,def} = types;
 
 /**
  * A log representing the results of a test.
@@ -18,7 +19,7 @@ const {F,S,O} = require('@lumjs/core').types;
  */
 class Log 
 {
-  constructor ()
+  constructor (test)
   {
     this.ok = false;
     this.skipped = false;
@@ -26,6 +27,8 @@ class Log
     this.desc = null;
     this.directive = null;
     this.details = {};
+    this.stringifyDepth = test.stringifyDepth;
+    def(this, '$test$', test);
   }
 
   /**
@@ -34,11 +37,13 @@ class Log
    * Generally this is never needed to be used by outside code.
    * The `Test.tap()` method uses it when generating a full log.
    * 
-   * @param {*} num - The test #
+   * @param {*} num - The test number.
    * @returns {string} The TAP log.
    */
   tap (num)
   {
+    const SD = this.stringifyDepth;
+
     var out;
     if (this.ok)
       out = 'ok ';
@@ -53,7 +58,7 @@ class Log
     if (typeof this.directive === S)
       out += ' # ' + this.directive;
     else if (typeof this.directive == O && this.directive instanceof Error)
-      out += ' # ' + this.directive.name + ': ' + this.directive.message;
+      out += ` # ${this.directive.name}: ${this.directive.message}`;
     else if (this.skipped)
       out += ' # SKIP ' + this.skippedReason;
 
@@ -65,14 +70,28 @@ class Log
       var want = this.details.wanted;
       if (this.details.stringify)
       {
-        got = (typeof got === F) ? got.toString() : JSON.stringify(got);
-        want = (typeof want === F) ? want.toString() : JSON.stringify(want);
+        got = stringify(got, SD);
+        want = stringify(want, SD);
       }
-      out += '#       got: ' + got + "\n";
-      out += '#  expected: ' + want + "\n";
+      out += `#       got: ${got}\n`;
+      out += `#  expected: ${want}\n`;
       if (typeof this.details.comparitor === S)
       {
-        out += '#        op: ' + this.details.comparitor + "\n";
+        out += `#        op: ${this.details.comparitor}\n`;
+      }
+    }
+
+    if ('info' in this.details)
+    { // Extended information. Usually an array, but can be whatever.
+      const info 
+        = isArray(this.details.info) 
+        ? this.details.info
+        : [this.details.info];
+
+      for (const i in info)
+      {
+        const line = (typeof info[i] === S) ? info[i] : stringify(info[i], SD);
+        out += `## ${line}\n`;
       }
     }