@lumjs/tests 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2022-06-22
+### Added
+- Ported from Lum.js v4 library set.
+- Added a few more features from the PHP version.
+
+[Unreleased]: https://github.com/supernovus/simpledom/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/supernovus/simpledom/releases/tag/v1.0.0
+

package/README.md

@@ -0,0 +1,32 @@
+# lum.tests.js
+
+An extremely simple and minimal testing framework.
+
+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:
+
+ * [Github](https://github.com/supernovus/lum.tests.js)
+ * [NPM](https://www.npmjs.com/package/@lumjs/tests)
+
+## Author
+
+Timothy Totten <2010@totten.ca>
+
+## License
+
+[MIT](https://spdx.org/licenses/MIT.html)
+

package/TODO.md

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

package/index.js

@@ -0,0 +1,23 @@
+/**
+ * Several test related classes.
+ */
+
+const Test = require('./src/test');
+
+module.exports.Test = Test;
+module.exports.Harness = require('./src/harness');
+
+// This one is not a class, but a special function.
+module.exports.functional = require('./src/functional');
+
+// This one is a quick shortcut function.
+module.exports.new = function({plan,module}={})
+{
+  const test = new Test(plan);
+  if (module)
+  {
+    module.exports = test;
+  }
+  return test;
+}
+

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@lumjs/tests",
+  "version": "1.0.0",
+  "main": "index.js",
+  "license": "MIT",
+  "repository":
+  {
+    "type": "git",
+    "url": "https://github.com/supernovus/lum.tests.js.git"
+  },
+  "dependencies": {
+    "@lumjs/core": "^1.0.0"
+  }
+}

package/src/functional.js

@@ -0,0 +1,77 @@
+// A functional interface to the test library.
+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',
+];
+
+/**
+ * A new test instance and a set of functions wrapping it.
+ * @typedef {object} 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.
+ * 
+ * @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  
+ */
+
+/**
+ * Create a function that will export a bunch of wrapper
+ * functions that can be imported via object destructuring.
+ * 
+ * Usage is like:
+ * 
+ * ```js
+ * const {plan,ok,isa} = require('@lumjs/tests').functional({module});
+ * 
+ * plan(2);
+ * ok(true, 'ok() works');
+ * isa(isa, 'function', 'isa is a function');
+ * 
+ * ```
+ * 
+ * Because each time this function is run it creates a new test instance,
+ * and a new set of wrapper functions for the test instance, you could
+ * create multiple sets of functional tests in their own private scopes.
+ * Not sure why you'd want to do that, but in case you do, there ya go.
+ * 
+ * @returns {Functional}
+ * 
+ */
+function functional({plan,module}={})
+{
+  const test = new Test(plan);
+  if (module)
+  {
+    module.exports = test;
+  }
+  const functions = { test };
+  for (const meth of PROXY_METHODS)
+  {
+    functions[meth] = function ()
+    {
+      return test[meth](...arguments);
+    }
+  }
+  return functions;
+}
+
+// Export the function itself.
+module.exports = functional;

package/src/harness.js

@@ -0,0 +1,16 @@
+
+const Test = require('./test');
+const Log  = require('./log');
+
+/**
+ * A class that acts as a test harness for running other tests.
+ * 
+ * Based off of the Lum.php Test\Harness class.
+ */
+class Harness
+{
+  construct()
+  {
+    throw new Error("Not yet implemented");
+  }
+}

package/src/log.js

@@ -0,0 +1,85 @@
+
+const {F,S,O} = require('@lumjs/core').types;
+
+/**
+ * A log representing the results of a test.
+ * 
+ * @property {boolean} ok - Did the test pass.
+ * @property {boolean} skipped - Was the test skipped?
+ * @property {string} skippedReason - If the test was skipped, 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.
+ * 
+ */
+class Log 
+{
+  constructor ()
+  {
+    this.ok = false;
+    this.skipped = false;
+    this.skippedReason = '';
+    this.desc = null;
+    this.directive = null;
+    this.details = {};
+  }
+
+  /**
+   * Output this Log object in the TAP format.
+   * 
+   * 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 #
+   * @returns {string} The TAP log.
+   */
+  tap (num)
+  {
+    var out;
+    if (this.ok)
+      out = 'ok ';
+    else
+      out = 'not ok ';
+
+    out += num;
+
+    if (typeof this.desc === S)
+      out += ' - ' + this.desc;
+
+    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;
+    else if (this.skipped)
+      out += ' # SKIP ' + this.skippedReason;
+
+    out += "\n";
+
+    if ('got' in this.details && 'wanted' in this.details)
+    {
+      var got = this.details.got;
+      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);
+      }
+      out += '#       got: ' + got + "\n";
+      out += '#  expected: ' + want + "\n";
+      if (typeof this.details.comparitor === S)
+      {
+        out += '#        op: ' + this.details.comparitor + "\n";
+      }
+    }
+
+    return out;
+  } // Log.tap()
+
+} // class Log
+
+// Export the class itself.
+module.exports = Log;

package/src/test.js

@@ -0,0 +1,402 @@
+
+const {F,S,N,isType,isInstance,def} = require('@lumjs/core').types;
+
+// We use a separate class to represent test logs.
+const Log = require('./log');
+
+/**
+ * A simple testing library with TAP support.
+ * 
+ * Based on Lum.php's Test library.
+ * Which itself was based on Perl 5's Test::More, and
+ * Raku's Test libraries.
+ */
+class Test
+{
+  /**
+   * Build a new Test instance.
+   * 
+   * @param {number} [plan] If used, passed to `plan()` method.
+   *  
+   */
+  constructor (plan)
+  {
+    this.failed = 0;
+    this.skipped = 0;
+    this.planned = 0;
+    this.log = [];
+    if (plan)
+    {
+      this.plan(plan);
+    }
+  }
+
+  /**
+   * 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.
+   *    
+   * @returns {Log} The test log with the results.
+   */
+  ok (test, desc, directive)
+  {
+    const log = new Log();
+
+    if (test)
+    {
+      log.ok = true;
+    }
+    else
+    {
+      this.failed++;
+    }
+
+    if (typeof desc === S)
+    {
+      log.desc = desc;
+    }
+
+    if (directive)
+    {
+      log.directive = directive;
+    }
+
+    this.log.push(log);
+
+    return log;
+  }
+
+  /**
+   * 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.
+   * 
+   * The function will be called in a `try { } catch (err) { }` block.
+   * 
+   * If an error is caught, the test will be considered to have passed,
+   * and the `Error` object will be used as the `directive` in the `ok()`
+   * call. If no error is caught the test will be considered to have failed.
+   * 
+   * @param {function} testfunc 
+   * @param {string} desc 
+   * @returns {Log}
+   */
+  dies (testfunc, desc)
+  {
+    let ok = false;
+    let err;
+    try { testfunc(); } 
+    catch (e)
+    {
+      ok = true;
+      err = e;
+    }
+    return this.ok(ok, desc, err);
+  }
+
+  /**
+   * See if a value is what we expect it to be.
+   * 
+   * @param {*} got - The result value from the test function.
+   * @param {*} want - The value we expected from the test function.
+   * @param {string} comp - A comparitor to test with.
+   * 
+   * - `===`, `is`          (See also: `is()`)
+   * - `!==`, `isnt`        (See also: `isnt()`)
+   * - `==`,  `eq`
+   * - `!=`,  `ne`
+   * - `>`,   `gt`
+   * - `<`,   `lt`
+   * - `>=`,  `ge`, `gte`
+   * - `<=`,  `le`, `lte`
+   * 
+   * @param {string} desc 
+   * @param {boolean} [stringify=true] Stringify values in TAP output?
+   * @returns {Log}
+   */
+  cmp (got, want, comp, desc, stringify=true)
+  {
+    let test;
+    switch(comp)
+    {
+      case 'is':
+      case '===':
+        test = (got === want);
+        break;
+      case 'isnt':
+      case '!==':
+        test = (got !== want);
+        break;
+      case 'eq':
+      case '==':
+        test = (got == want);
+        break;
+      case 'ne':
+      case '!=':
+        test = (got != want);
+        break;
+      case 'lt':
+      case '<':
+        test = (got < want);
+        break;
+      case '>':
+      case 'gt':
+        test = (got > want);
+        break;
+      case 'le':
+      case 'lte':
+      case '<=':
+        test = (got <= want);
+        break;
+      case 'ge':
+      case 'gte':
+      case '>=':
+        test = (got >= want);
+        break;
+      default:
+        test = false; 
+    }
+
+    const log = this.ok(test, desc);
+    if (!test)
+    {
+      log.details.got = got;
+      log.details.wanted = want;
+      log.details.stringify = stringify;
+      log.details.comparitor = comp;
+    }
+    return log;
+  }
+
+  /**
+   * See if two values are equal.
+   * 
+   * The same as using `cmp()` with the `===` comparitor.
+   * 
+   * @param {*} got 
+   * @param {*} want 
+   * @param {string} desc 
+   * @param {boolean} [stringify=true]
+   * @returns {Log}
+   */
+  is (got, want, desc, stringify=true)
+  {
+    return this.cmp(got, want, '===', desc, stringify);
+  }
+
+  /**
+   * See if two values are NOT equal.
+   * 
+   * The same as using `cmp()` with the `!==` comparitor.
+   * 
+   * @param {*} got - The result value from the test function.
+   * @param {*} want - The value we expected from the test function.
+   * @param {string} desc 
+   * @param {boolean} [stringify=true] Use JSON details in TAP output?
+   * @returns {Log}
+   */
+  isnt (got, want, desc, stringify=true)
+  {
+    return this.cmp(got, want, '!==', desc, stringify);
+  }
+
+  /**
+   * See if a value is of a certain type.
+   * 
+   * @param {*} got 
+   * @param {(string|function)} want - A type name, or a constructor function.
+   * 
+   * This uses two type checking functions from `@lumsj/core`.
+   * If this is a string, we use the `isType()` function.
+   * If this is a constructor function, we use the `isInstance()` function.
+   *  
+   * @param {string} desc 
+   * @param {boolean} [stringify=true]
+   * @returns {Log}
+   */
+  isa (got, want, desc, stringify=true)
+  {
+    let test;
+    if (typeof want === S)
+    { // A string, we're going to use the isType function.
+      test = isType(want, got);
+    }
+    else if (typeof want === F)
+    { // Assuming it's a constructor.
+      test = isInstance(got, want);
+    }
+    else 
+    { // That's not supported.
+      throw new TypeError("'want' must be a string or a constructor");
+    }
+
+    const log = this.ok(test, desc);
+    if (!test)
+    {
+      log.details.got = got;
+      log.details.wanted = want;
+      log.details.stringify = stringify;
+    }
+    return log;
+  }
+
+  /**
+   * An `is()` test, but encode both values as JSON first.
+   * 
+   * @param {*} got 
+   * @param {*} want 
+   * @param {string} desc 
+   * @returns 
+   */
+  isJSON (got, want, desc)
+  {
+    got = JSON.stringify(got);
+    want = JSON.stringify(want);
+    return this.is(got, want, desc, false);
+  }
+
+  /**
+   * Skip a test.
+   * 
+   * @param {?string} reason - Why the test was skipped.
+   * @param {string} desc 
+   * @returns {Log}
+   */
+  skip (reason, desc)
+  {
+    var 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);
+  }
+
+  /**
+   * Return TAP formatted output for all the tests.
+   * 
+   * @returns {string} The test logs, in TAP format.
+   */
+  tap ()
+  {
+    var out = '';
+    if (this.planned > 0)
+    {
+      out += '1..'+this.planned+"\n";
+    }
+    var t = 1;
+    for (var i = 0; i < this.log.length; i++)
+    {
+      var log = this.log[i];
+      if (log instanceof Log)
+      {
+        out += log.tap(t++);
+      }
+      else
+      { // A comment.
+        out += '# ' + (typeof log === S ? log : JSON.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";
+    }
+    var ran = t-1;
+    if (this.planned > 0 && this.planned != ran)
+    {
+      out += '# Looks like you planned '+this.planned+' but ran '+ran+" tests\n";
+    }
+    return out;
+  }
+
+  /**
+   * Send the TAP output to the `console`.
+   */
+  output ()
+  {
+    console.log(this.tap());
+    return this;
+  }
+
+} // class Test
+
+// Should never need this, but...
+def(Test, 'Log', Log);
+
+// Export the class
+module.exports = Test;

package/test/basics.js

@@ -0,0 +1,32 @@
+const Test = require('../index').Test;
+const def = require('./inc/basics.js');
+
+const test = new Test();
+test.plan(def.plan);
+
+test.ok(def.okay, 'ok()');
+test.pass('pass()');
+
+for (const is of def.isTests)
+{
+  const t = JSON.stringify(is);
+  test.is(is, is, 'is('+t+','+t+')');
+}
+
+for (const [a,b] of def.isntTests)
+{
+  const msg = `isnt(${JSON.stringify(a)},${JSON.stringify(b)})`;
+  test.isnt(a, b, msg);
+}
+
+for (const args of def.cmpTests)
+{
+  const msg = 'cmp('+JSON.stringify(args)+')';
+  test.cmp(...args, msg);
+}
+
+// We're done, output the log.
+console.log(test.tap());
+
+// Re-expect the test.
+module.exports = test;

package/test/dies.js

@@ -0,0 +1,17 @@
+const def = require('./inc/dies.js');
+// Using the 'new()' function.
+const test = require('../index').new({module, plan: def.plan});
+
+for (const dt of def.diesErrors)
+{
+  test.dies(...dt);
+}
+
+for (const dt of def.diesSyntaxErrors)
+{
+  test.dies(...dt);
+}
+
+// We're done, output the log.
+test.output();
+

package/test/functional_basics.js

@@ -0,0 +1,33 @@
+// Testing the basic functions of the functional testing API.
+
+const {test,plan,ok,pass,is,isnt,cmp,tap} = require('../index').functional();
+const def = require('./inc/basics.js');
+
+plan(def.plan);
+
+ok(def.okay, 'ok()');
+pass('pass()');
+
+for (const it of def.isTests)
+{
+  const t = JSON.stringify(it);
+  is(it, it, 'is('+t+','+t+')');
+}
+
+for (const [a,b] of def.isntTests)
+{
+  const msg = `isnt(${JSON.stringify(a)},${JSON.stringify(b)})`;
+  isnt(a, b, msg);
+}
+
+for (const args of def.cmpTests)
+{
+  const msg = 'cmp('+JSON.stringify(args)+')';
+  cmp(...args, msg);
+}
+
+// We're done, output the log.
+console.log(tap());
+
+// And re-export the test.
+module.exports = test;

package/test/functional_dies.js

@@ -0,0 +1,17 @@
+const def = require('./inc/dies.js');
+
+const {dies,output} = require('../index').functional({module, plan: def.plan});
+
+for (const dt of def.diesErrors)
+{
+  dies(...dt);
+}
+
+for (const dt of def.diesSyntaxErrors)
+{
+  dies(...dt);
+}
+
+// We're done, output the log.
+output();
+

package/test/inc/basics.js

@@ -0,0 +1,42 @@
+// Common stuff for both regular and functional tests.
+
+const okay = (1==1);
+
+const isTests = [1, 1.1, 'a', true, false, [1,2,3], null];
+const isntTests =
+[ // Tests to compare strict non-equality.
+  [1,     '1'],
+  [1.1,   '1.1'],
+  [true,  1],
+  [false, 0],
+  [false, null],
+  ['',    null],
+  [[1,2], [2,1]],
+];
+
+const cmpTests =
+[ // Tests to use custom comparisons and aliases.
+  [1, 1,     '==='],
+  [1, 1,     'is'],
+  [0, 1,     '!=='],
+  [0, 1,     'isnt'],
+  [1, '1',   'eq'],
+  [0, false, 'eq'],
+  [1, true,  '=='],
+  [1, false, 'ne'],
+  [0, true,  '!='],
+  [1, 0,     '>'],
+  [1, 0,     'gt'],
+  [1, 0,     '>='],
+  [1, 0,     'ge'],
+  [1, 0,     'gte'],
+  // TODO: finish this set of tests.
+];
+
+const plan 
+  = 2
+  + isTests.length
+  + isntTests.length
+  + cmpTests.length;
+
+module.exports = {okay, isTests, isntTests, cmpTests, plan};

package/test/inc/dies.js

@@ -0,0 +1,78 @@
+// Common include for testing the .dies() method.
+
+// A custom error class.
+class Exception extends Error 
+{
+  constructor(msg)
+  {
+    super(msg);
+    this.name = "Exception";
+  }
+}
+
+exports.Exception = Exception;
+
+// A simplistic class for testing.
+class TestObject
+{
+  static throwError()
+  {
+    throw new Error("error thrown statically");
+  }
+  static throwSyntaxError()
+  {
+    return this.noSuchMethod();
+  }
+
+  throwError()
+  {
+    throw new Error("error thrown");
+  }
+  throwSyntaxError()
+  {
+    return this.noSuchMethod();
+  }
+}
+
+exports.TestObject = TestObject;
+
+function makeException()
+{
+  throw new Exception("exception made");
+}
+
+exports.makeException = makeException;
+
+function syntaxError()
+{
+  noSuchFunction();
+}
+
+exports.syntaxError = syntaxError;
+
+const testObject = new TestObject();
+
+const diesErrors =
+[
+  [function() { throw new Error("001"); }, 'dies(thrown_from_inline_function)'],
+  [() => { throw new Error("002") }, 'dies(thrown_from_arrow_function)'],
+  [() => { throw new Exception("003")}, 'dies(threw_custom_error)'],
+  [makeException, 'dies(thrown_from_named_function)'],
+  [() => TestObject.throwError(), 'dies(thrown_from_static_method'],
+  [() => testObject.throwError(), 'dies(thrown_from_instance_method'],
+];
+
+exports.diesErrors = diesErrors;
+
+const diesSyntaxErrors = 
+[
+  [function() { wrong(); }, 'dies(synax_error_from_inline_function)'],
+  [() => wrong(), 'dies(syntax_error_from_arrow_function)'],
+  [syntaxError, 'dies(syntax_error_from_named_function'],
+  [() => TestObject.throwSyntaxError(), 'dies(syntax_error_from_static_method)'],
+  [() => testObject.throwSyntaxError(), 'dies(syntax_error_from_instance_method)'],
+];
+
+exports.diesSyntaxErrors = diesSyntaxErrors;
+
+exports.plan = diesErrors.length + diesSyntaxErrors.length;