unexpectedly 0.0.7 → 2.0.0

package/README.md

@@ -4,41 +4,76 @@ Write a bunch of unit tests in a simple file.
 
 ## Install
 
-```
+```sh
 npm install -g unexpectedly
 ```
 
 ## Usage
 
 ```
-unexpectedly [file|directory] [jsPattern]
-  file: a file that contains tests
-  directory (default: "."): a directory containing ".tests" files
-  jsPattern (default: "../$1.js"): find the JS file relative to
-  the .tests file, replacing $1 with the basename of the test file
+Usage: unexpectedly [options] [...file]
+
+Arguments:
+  ...file                           Files or directories to test (default:
+                                    "./test/")
+
+Options:
+  -V, --version                     output the version number
+  -d,--defaultScript <replacement>  Find the script from the file name.
+                                    Replace `$<base>` with the basename of the
+                                    file. (default: "../$<base>.js")
+  -f,--function <functionName>      Use this function for testing in the
+                                    associated script (default: "test")
+  -h, --help                        display help for command
 ```
 
 ## Example
 
-foo.tests:
+This is the easiest case, when the function that you want to test is already
+exposed as the default export or exported as a function named `test`:
+
+tests/bar.tests:
 ```
-#! inline: (a, b) => a + b
-5 2 3
-8 7 1
+# "8" is the expected result, "4" and "2" are the inputs to the tested function
+8 4 2
 ```
 
-run:
+bar.js:
+```js
+// The default or `test` export from the associated .js file is the
+// tested function by default
+export default mult(a, b) {
+  return a * b;
+}
+
+export function baz(a) {
+  return a * 6;
+}
+```
+
+To test the `baz` function, we needed to write a little wrapper code:
+
+tests/baz.tests:
 ```
-unexpectedly foo.tests
+#! inline: `export {baz as test} from '../foo.js'`
+6 1 # Expect 6 to result from `baz("1")`
+12 2
+```
+
+run:
+```sh
+unexpectedly tests/
 ```
 
 ## API
 
 ```js
-const suite = require('unexpectedly')
+import {suite} from 'unexpectedly';
 
-// returns a Promise
-suite(directoryOrFile, jsPattern).catch(console.error)
+await suite(directoryOrFile, {
+  defaultScript: '../$<base>.js',
+  function: 'test',
+}).catch(console.error)
 ```
 
 ## Test language
@@ -57,11 +92,12 @@ test"
 ```
 
 Aggressive type coercion is used, including if the test JavaScript
-returns an non-string the result string is parsed as JSON before
+returns an non-string the result string is parsed as JavaScript before
 comparison.
 
 Set file-wide globals with lines that start with `#!`, separating
-the name and the value with a colon:
+the name and the value with a colon.  These globals will be made available
+to your test script as global variables:
 
 ```
 #! name: value
@@ -74,6 +110,11 @@ Special globals include:
    instead of the default
  - "timeout": If any test in the file takes longer than this (in ms),
    it fails.  Default: 2000
+ - "peggy": Treat the input as a compiled peggy grammar; look for a "parse"
+   function in the input script, provide better errors, and use the value
+   of the peggy global (if any) as the startRule.
+
+Environment variables can be set for the test code with `#!! name: value`.
 
 ## JavaScript to test
 
@@ -81,19 +122,24 @@ You can specify JavaScript to run for each test in one of three ways:
 
 - Use the mapping from test file name to a JavaScript file.  By default, this
   takes the basename of the .tests file and looks up one directory for a .js
-  file of the same basename.  So `tests/foo.tests` looks for `foo.js`.  If needed
-  you can replace the mapping with something else, that uses `%1` as a placeholder
-  for the basename.
+  file of the same basename.  So `tests/foo.tests` looks for `foo.js`.  If
+  needed you can replace the mapping with something else, that uses `$<base>`
+  as a placeholder for the basename.
 - Specify a global in your .tests file with the name `script`.  That is the name
   of the file, relative to the directory that contains the .tests file, to look
   for JavaScript.
 - Specify a global in your .tests file with the name `inline`.  That's just
   JavaScript to run per-line.
 
-For each of the above, make sure `module.exports` is a function, or that you
-export a function named `test`.  For inline code, if you don't export anything,
-`module.exports=` will be added to the beginning of your code, so that you
-can just put in a simple function.
+In es6 module projects, for each of the above, make sure `export default` is a
+function, or that you export a function named `test`.  For inline code, if you
+don't export anything, `export default` will be added to the beginning of your
+code, so that you can just put in a simple function.
+
+In commonjs projects, for each of the above, make sure `module.exports` is a
+function, or that you export a function named `test`.  For inline code, if you
+don't export anything, `module.exports=` will be added to the beginning of
+your code, so that you can just put in a simple function.
 
 Special globals available in all forms of the JavaScript above include:
 
@@ -101,3 +147,6 @@ Special globals available in all forms of the JavaScript above include:
 - `__expected` is the string form of the expected result
 - `__line` is the line number where the test starts
 - `__column` is the column where the test text starts
+
+[![Tests](https://github.com/hildjj/unexpectedly/actions/workflows/node.js.yml/badge.svg)](https://github.com/hildjj/unexpectedly/actions/workflows/node.js.yml)
+[![codecov](https://codecov.io/gh/hildjj/unexpectedly/graph/badge.svg?token=H8EXAJRBU1)](https://codecov.io/gh/hildjj/unexpectedly)

package/bin/unexpectedly.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env -S node --experimental-vm-modules --no-warnings
+/* eslint-disable no-console */
+
+import {Command, Option} from 'commander';
+import fs from 'node:fs/promises';
+import {suite} from '../index.js';
+
+let failures = 0;
+
+async function main() {
+  const pkg = JSON.parse(await fs.readFile(
+    new URL('../package.json', import.meta.url),
+    'utf-8'
+  ));
+
+  const program = new Command();
+  const opts = program
+    .version(pkg.version)
+    .argument('[...file]', 'Files or directories to test', './test/')
+    .option('-d,--defaultScript <replacement>', 'Find the script from the file name.  Replace `$<base>` with the basename of the file.', '../$<base>.js')
+    .option('-f,--function <functionName>', 'Use this function for testing in the associated script', 'test')
+    .addOption(new Option('-s,--silent18', 'Silently skip mjs tests on node 18.').hideHelp())
+    .parse()
+    .opts();
+
+  const {args} = program;
+  if (args.length === 0) {
+    args.push('./test/');
+  }
+
+  for (const arg of args) {
+    // eslint-disable-next-line require-atomic-updates
+    failures += await suite(arg, opts);
+  }
+}
+
+await main().catch(er => {
+  console.error(er);
+  process.exit(1);
+});
+
+if (failures) {
+  console.error(`Total of ${failures} failure${failures === 1 ? '' : 's'}`);
+  process.exit(2);
+}

package/index.js

@@ -1,115 +1,173 @@
-'use strict'
+import {Runner, SKIPPED} from './runner.js';
+import {hexlify, mapObj} from './utils.js';
+import Mocha from 'mocha';
+import assert from 'node:assert';
+import fs from 'node:fs/promises';
+import {parse} from './testFile.peg.js';
+import path from 'node:path';
 
-const assert = require('assert')
-const fs = require('fs')
-const util = require('util')
-const path = require('path')
-const Mocha = require('mocha') // TODO: just use one of the reporters
-const parser = require('./testFile.peg')
-const Runner = require('./runner')
-const { mapObj } = require('./utils')
+const EXCEPTION = Symbol('EXCEPTION');
 
-const EXCEPTION = Symbol('EXCEPTION')
-
-// TODO: once the warning goes away
-// const fsp = require('fs').promises
-const fsp = mapObj(['readdir', 'readFile', 'stat'],
-  s => util.promisify(fs[s]))
-
-function coerce (actual, expected) {
+async function coerce(actual, pt, runner) {
+  const {expected} = pt;
   if (typeof actual === 'string') {
-    return [actual, expected]
+    return [actual, expected];
+  }
+  if (actual === SKIPPED) {
+    return [SKIPPED, SKIPPED];
   }
   if (actual && (typeof actual === 'object') && actual.constructor) {
-    const name = actual.constructor.name
+    if (/^0x/.test(expected)) {
+      const {name} = actual.constructor;
 
-    switch (name) {
-      case 'Buffer':
-        return ['0x' + actual.toString('hex'), expected]
-      // note: other Typed Array's won't work for now because vm2 doens't
-      // support them
+      switch (name) {
+        case 'Buffer':
+          return [`0x${actual.toString('hex')}`, expected];
+        case 'Float32Array':
+        case 'Float64Array':
+        case 'Int16Array':
+        case 'Int32Array':
+        case 'Int8Array':
+        case 'Uint16Array':
+        case 'Uint32Array':
+        case 'Uint8Array':
+        case 'Uint8ClampedArray':
+          return [`0x${hexlify(actual)}`, expected];
+      }
     }
   }
-  return [actual, JSON.parse(expected)]
+
+  const exp = await runner.parse(expected, {
+    __line: pt.line,
+    __column: pt.column,
+  });
+  const def = Object.hasOwn(exp, 'default') ? exp.default : exp;
+  return [actual, def];
 }
 
 /**
- * Run a test suite from a file or directory
+ * @typedef {object} SuiteOptions
+ * @property {string} [defaultScript='../$<base>.js'] Find the script from the
+ *   file name.  Replace `$<base>` with the basename of the file.  For
+ *   example, "foo.test" will use "../foo.js" by default.
+ * @property {string} [function='test'] Use this function for testing in the
+ *   associated script.
+ */
+
+/**
+ * Run a test suite from a file or directory.
  *
- * @param {string} [target='.'] The file or directory to read.  If a diretory,
- *   reads all files ending in `.test`
- * @param {string} [defaultScript='../$1.js'] find the script from the file
- *   name.  Replace $1 with the basename of the file.  For example, "foo.test"
- *   will use "../foo.js" by default
- * @returns Promise fulfills on success
+ * @param {string} [target='.'] The file or directory to read.  If a
+ *   directory, reads all files ending in `.tests`.
+ * @param {SuiteOptions} [options={}] Options for processing the suite.
+ * @returns {Promise<number>} Promise fulfills on completion, with number of
+ *   test failures.
  */
-async function suite (target = '.', defaultScript = '../$1.js') {
-  let dir = path.resolve(target)
-  let files = [dir]
+export async function suite(target = '.', options = {}) {
+  options = {
+    defaultScript: '../$<base>.js',
+    function: 'test',
+    ...options,
+  };
+  let dir = path.resolve(target);
+  let files = [dir];
+  const mocha = new Mocha();
+  mocha.suite.title = dir;
 
-  const stats = await fsp.stat(target)
+  const stats = await fs.stat(dir);
   if (stats.isDirectory()) {
-    files = (await fsp.readdir(target))
-      .filter(f => f.endsWith('.tests'))
-      .map(f => path.join(dir, f))
+    files = (await fs.readdir(target))
+      .filter(f => /\.tests?$/.test(f))
+      .map(f => path.join(dir, f));
   } else if (stats.isFile()) {
-    const p = path.parse(target)
-    dir = p.dir
+    // eslint-disable-next-line require-atomic-updates
+    ({dir} = path.parse(target));
+  } else {
+    throw new Error(`Unknown file type: "${target}"`);
   }
-  const mocha = new Mocha()
 
   for (const f of files) {
-    const suite = Mocha.Suite.create(mocha.suite, f)
-    const contents = await fsp.readFile(f, 'utf8')
-    const parsed = parser.parse(contents, { EXCEPTION })
+    const msuite = Mocha.Suite.create(mocha.suite, f);
+    const contents = await fs.readFile(f, 'utf8');
 
-    const opts = {}
-    if (parsed.vars.inline) {
-      opts.filename = f
-      opts.text = parsed.vars.inline.value
-      if (opts.text.indexOf('exports') === -1) {
-        opts.text = 'module.exports= ' + opts.text // most common case
+    let parsed = null;
+    try {
+      parsed = parse(contents, {EXCEPTION, grammarSource: f});
+    } catch (er) {
+      if (typeof er.format === 'function') {
+        er.message = er.format([{
+          source: f,
+          text: contents,
+        }]);
+        delete er.expected;
+        delete er.location;
       }
-      opts.lineOffset = parsed.vars.inline.line
-      opts.columnOffset = parsed.vars.inline.column
-    } else {
-      opts.filename = parsed.vars.script
-        ? path.resolve(dir, parsed.vars.script.value)
-        : path.resolve(dir, f.replace(/([^./]*)\.tests?$/, defaultScript))
-    }
-    if (parsed.vars.timeout) {
-      suite.timeout(parseInt(parsed.vars.timeout.value))
+      throw er;
     }
-    opts.sandbox = mapObj(
-      Object.entries(parsed.vars),
-      ([key, value]) => [key, value.value])
 
-    let runner = new Runner(opts)
+    for (const pt of parsed) {
+      const opts = {
+        testFunction: options.function,
+      };
+      let text = '';
+      if (pt.vars.inline) {
+        opts.filename = f;
+        text = pt.vars.inline.value;
+        opts.lineOffset = pt.vars.inline.line - 1;
+        opts.columnOffset = pt.vars.inline.column;
+      } else {
+        opts.filename = pt.vars.script ?
+          path.resolve(dir, pt.vars.script.value) :
+          path.resolve(dir,
+            f.replace(/(?<base>[^\\/]*)\.tests?$/, options.defaultScript));
+        text = await fs.readFile(opts.filename, 'utf8');
+      }
+      if (pt.vars.timeout) {
+        msuite.timeout(parseInt(pt.vars.timeout.value, 10));
+      }
+      opts.context = mapObj(
+        Object.entries(pt.vars).filter(([k, v]) => !v.env),
+        ([key, value]) => [key, value.value]
+      );
+      opts.env = mapObj(
+        Object.entries(pt.vars).filter(([k, v]) => v.env),
+        ([key, value]) => [key, value.value]
+      );
+      opts.silent18 = Boolean(options.silent18);
+
+      const runner = new Runner(opts);
 
-    for (const pt of parsed.tests) {
-      const t = new Mocha.Test(`line ${pt.line}`, async () => {
-        let actual = null
+      const firstLine = (pt.expected === EXCEPTION) ? `! ${pt.inputs[0]}` : pt.expected.split(/\n/)[0];
+      const t = new Mocha.Test(`line ${pt.line}: ${firstLine || '""'}`, async() => {
+        let actual = null;
         try {
-          actual = await runner.run({
+          actual = await runner.run(text, {
             __expected: pt.expected,
             __line: pt.line,
-            __column: pt.column
-          }, ...pt.inputs)
+            __column: pt.column,
+            __offset: pt.offset,
+          }, ...pt.inputs);
+          if (actual === SKIPPED) {
+            t.skip('Node 20.8 required');
+            return;
+          }
         } catch (e) {
-          assert.strictEqual(pt.expected, EXCEPTION, e)
-          return
+          if (pt.expected !== EXCEPTION) {
+            throw e;
+          }
+          return;
         }
-        assert.notStrictEqual(pt.expected, EXCEPTION)
-        assert.deepStrictEqual.apply(null, coerce(actual, pt.expected))
-      })
-      suite.addTest(t)
+        assert.notStrictEqual(pt.expected, EXCEPTION);
+        assert.deepEqual.apply(null, await coerce(actual, pt, runner));
+      });
+
+      msuite.addTest(t);
     }
   }
 
   return new Promise((resolve, reject) => {
-    mocha.run(resolve)
-  })
+    mocha.run(resolve);
+  });
 }
 
-suite.EXCEPTION = EXCEPTION
-module.exports = suite
+suite.EXCEPTION = EXCEPTION;

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "unexpectedly",
-  "version": "0.0.7",
+  "version": "2.0.0",
   "description": "Keep a bunch of test cases in a file, with their expected results",
   "main": "index.js",
+  "type": "module",
   "scripts": {
-    "test": "bin/unexpectedly test",
-    "pretest": "npm run grammar",
-    "grammar": "peggy -o testFile.peg.js testFile.pegjs",
-    "lint": "eslint *.js test/*.js bin/*",
-    "release": "npm version patch && git push --follow-tags && npm publish"
+    "build": "peggy -o testFile.peg.js --format es testFile.peggy",
+    "pretest": "npm run build",
+    "test": "c8 npm run runtests",
+    "runtests": "mocha && bin/unexpectedly.js -s test test/pkg_mjs/test test/pkg_cjs/test",
+    "lint": "eslint --ext js,cjs,mjs . bin/*",
+    "ci": "npm run lint && npm run test",
+    "clean": "rimraf coverage testFile.peg.js"
   },
   "bin": {
-    "unexpectedly": "bin/unexpectedly"
+    "unexpectedly": "bin/unexpectedly.js"
   },
   "keywords": [
     "test",
@@ -23,25 +26,28 @@
     "harness"
   ],
   "author": "Joe Hildebrand <joe-github@cursive.net>",
+  "repository": {
+    "type": "git",
+    "url": "http://github.com/hildjj/unexpectedly.git"
+  },
   "license": "MPL-2.0",
+  "dependencies": {
+    "@peggyjs/from-mem": "1.3.0",
+    "commander": "12.0.0",
+    "mocha": "^10.3.0",
+    "semver": "7.6.0"
+  },
   "devDependencies": {
-    "eslint": "^7.24.0",
-    "eslint-config-standard": "^16.0.2",
-    "eslint-plugin-import": "^2.22.1",
-    "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-promise": "^5.1.0",
-    "eslint-plugin-standard": "^4.1.0",
-    "peggy": "^1.0.0"
+    "@cto.af/eslint-config": "3.1.0",
+    "c8": "9.1.0",
+    "eslint": "^8.57.0",
+    "eslint-plugin-jsdoc": "48.2.0",
+    "peggy": "^4.0.2",
+    "rimraf": "5.0.5",
+    "zx": "7.2.3"
   },
+  "packageManager": "pnpm@8.15.4",
   "engines": {
-    "node": ">=10"
-  },
-  "dependencies": {
-    "mocha": "^8.3.2",
-    "vm2": "^3.9.3"
-  },
-  "repository": {
-    "type": "git",
-    "url": "http://github.com/hildjj/unexpectedly.git"
+    "node": ">=18"
   }
 }