@lumjs/tests 1.6.0 → 1.7.1

package/lib/test/stats.js

@@ -0,0 +1,385 @@
+const core = require('@lumjs/core');
+const {types} = core;
+const {S,N,isObj,def} = types;
+const Log = require('./log');
+
+/**
+ * Minimalistic base class for the `Test` library.
+ * 
+ * This provides the properties and methods related to the test statistics.
+ * 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
+ * 
+ * @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 Stats
+{
+  /**
+   * Build a new instance.
+   * 
+   * @param {object} [opts] Named options.
+   * @param {string} [opts.id] A unique test id, used by Harness.
+   * @param {number} [opts.plan] Passed to `plan()` method.
+   * @param {object} [opts.moduleName] Options for `core.modules.name()`.
+   * @param {object} [opts.module] The node module to export this test to.
+   *
+   *   If you use this option, `opts.module.exports` will be assigned
+   *   to the test instance, overriding anything that may have been 
+   *   assigned to it previously.
+   *
+   *   Also, if this is passed, and `opts.id` was not specified, and id
+   *   will be auto-generated based on the filename of the module.
+   *
+   * @param {number} [opts.stringify=1] The depth `stringify()` should recurse
+   *   objects and Arrays before switching to plain JSON stringification.
+   *
+   */
+  constructor (opts={})
+  {
+    if (typeof opts === N)
+    {
+      opts = {plan: opts};
+    }
+    else if (typeof opts === S)
+    {
+      opts = {id: opts};
+    }
+
+    const hasModule = isObj(opts.module);
+
+    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;
+
+    // The test logs for each unit.
+    this.log = [];
+
+    // These will be updated below if possible.
+    this.isTop   = false;
+    this.harness = null;
+
+    if (typeof opts.plan === N)
+    {
+      this.plan(opts.plan);
+    }
+
+    //console.debug('checking for module');
+    if (hasModule)
+    { // If a module was passed, its going to export this test.
+      opts.module.exports = this;
+      //console.debug('module found');
+      // 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;
+      }
+    }
+
+    // Finally, mark the test stats as not generated yet.
+    def(this, '$done', false);
+  }
+
+  // Internal method.
+  $log()
+  {
+    return new Log(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 = this.$log();
+
+    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;
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * Skip a test.
+   * 
+   * In some circumstances, there may be a situation where a
+   * test is not applicable (maybe it's an optional feature
+   * that only applies to a certain platform), and shouldn't be run. 
+   * In order to maintain the correct number of tests ran, we can 
+   * mark those tests as *skipped* using this method.
+   * 
+   * @param {string} [reason] - Why the test was skipped.
+   * @param {string} [desc] - A description of the test.
+   * @returns {Log}
+   */
+  skip (reason, desc, _todo=false)
+  {
+    const log = this.ok(true, desc);
+    if (_todo)
+      log.todo = true;
+    else
+      log.skipped = true;
+    if (typeof reason === S)
+      log.reason = reason;
+    this.skipped++;
+    return log;
+  }
+ 
+  /**
+   * Mark a test as not yet implemented.
+   * 
+   * This is quite different from the version in PHP.
+   * In that one `TODO` items are considered a *failure*.
+   * In this implementation, TODO items are considered
+   * to be *skipped*. They simply have a different marker
+   * in the TAP output than tests marked with `skip()`.
+   * 
+   * @param {string} [reason] - What needs to be done to implement this test.
+   * @param {string} [desc] - A description of the test.
+   * @returns {Log}
+   */
+  todo(reason, desc)
+  {
+    return this.skip(reason, desc, true);
+  }
+
+  /**
+   * 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 ()
+  {
+    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 : this.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');
+    }
+    def(this, '$done', true);
+    return (this.harness ? this : this.output());
+  }
+
+} // class Test
+
+// Export the class
+module.exports = Stats;
+
+// 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/package.json

@@ -1,29 +1,38 @@
 {
   "name": "@lumjs/tests",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "main": "lib/index.js",
-  "exports":
+  "bin":
+  {
+    "lumtest": "bin/lumtest.js"
+  },
+  "exports": 
   {
     ".": "./lib/index.js",
-    "./test": "./lib/test.js",
-    "./functional": "./lib/functional.js",
-    "./harness": "./lib/harness.js",
+    "./test": "./lib/test/index.js",
+    "./test/functional": "./lib/test/functional.js",
+    "./harness": "./lib/harness/index.js",
+    "./harness/parser": "./lib/harness/parser.js",
     "./package.json": "./package.json",
     "./data/*": "./test/data/*.js"
   },
   "license": "MIT",
-  "repository":
+  "repository": 
   {
     "type": "git",
     "url": "https://github.com/supernovus/lum.tests.js.git"
   },
-  "dependencies": {
-    "@lumjs/core": "^1.3.0"
-  },
-  "scripts":
+  "dependencies": 
   {
-    "-TODO-1": "When Harness and bin/lumtest are done, use that for 'test'",
-    "test": "prove -e node --ext js ./test",
-    "build-docs": "jsdoc -c ./jsdoc.json"
+    "@lumjs/core": "^1.7.1"
+  },
+  "scripts": {
+    "test": "node ./bin/lumtest.js",
+    "build-docs": "jsdoc -c ./jsdoc.json",
+    "build": "npm run build:grammar",
+    "build:grammar": "./bin/build-grammar.sh tap"
+  },
+  "devDependencies": {
+    "peggy": "^2.0.1"
   }
 }

package/lib/harness.js

@@ -1,25 +0,0 @@
-
-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.
- * 
- * Based off of the Lum.php Test\Harness class.
- */
-class Harness
-{
-  construct()
-  {
-    throw new Error("Not yet implemented");
-  }
-}
-
-// Export it.
-module.exports = Harness;
-

package/test/basics.js

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

package/test/data/people.js

@@ -1,58 +0,0 @@
-module.exports = function (opts={})
-{
-  let people = 
-  [
-    {
-      name: 'Bob',
-      age: 40,
-    },
-    {
-      name: 'Lisa',
-      age: 25,
-    },
-    {
-      name: 'Kevin',
-      age: 18,
-    },
-    {
-      name: 'Sarah',
-      age: 13,
-    },
-  ];
-
-  if (opts.withRecursion)
-  {
-    people[0].kids = [people[2],people[3]];
-    people[1].kids = [people[3]];
-    people[2].kids = [];
-    people[3].kids = [];
-    people[0].parents = [];
-    people[1].parents = [];
-    people[2].parents = [people[0]];
-    people[3].parents = [people[0],people[1]];
-  }
-  else if (opts.withReferences)
-  {
-    people[0].kids = [2,3];
-    people[1].kids = [3];
-    people[2].kids = [];
-    people[3].kids = [];
-    people[0].parents = [];
-    people[1].parents = [];
-    people[2].parents = [0];
-    people[3].parents = [0,1];
-  }
-  else if (opts.withNames)
-  {
-    people[0].kids = [people[2].name,people[3].name];
-    people[1].kids = [people[3].name];
-    people[2].kids = [];
-    people[3].kids = [];
-    people[0].parents = [];
-    people[1].parents = [];
-    people[2].parents = [people[0].name];
-    people[3].parents = [people[0].name,people[1].name];
-  }
-
-  return people;
-}

package/test/dies.js

@@ -1,17 +0,0 @@
-const def = require('./inc/dies.js');
-// Using the 'new()' function.
-const test = require('../lib').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

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

package/test/functional_dies.js

@@ -1,17 +0,0 @@
-const def = require('./inc/dies.js');
-
-const {dies,output} = require('../lib').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/functional_isa.js

@@ -1,23 +0,0 @@
-const {test,plan,tap,isa,nota} = require('../lib').functional();
-const def = require('./inc/isa.js');
-const getLabel = def.label;
-
-plan(def.plan);
-
-for (const isaTest of def.isaTests)
-{
-  const label = getLabel('isa',isaTest);
-  isa(isaTest[0], isaTest[1], label);
-}
-
-for (const notaTest of def.notaTests)
-{
-  const label = getLabel('nota',notaTest);
-  nota(notaTest[0], notaTest[1], label);
-}
-
-// We're done, output the log.
-console.log(tap());
-
-// And re-export the test.
-module.exports = test;