unexpectedly 0.0.7 → 1.0.0

package/README.md

@@ -4,38 +4,64 @@ Write a bunch of unit tests in a simple file.
 
 ## Install
 
-```
+```sh
 npm install -g unexpectedly
 ```
 
 ## Usage
 
 ```
-unexpectedly [file|directory] [jsPattern]
+unexpectedly [--defaultScript jsPattern] <...file|directory>
+  jsPattern (default: "../$<base>.js"): find the JS file relative to
+    the .tests file, replacing `$<base>` with the basename of the test file.
+    This may be specified multiple times, and modifies all files/directories
+    after.
   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
 ```
 
 ## 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)
@@ -57,11 +83,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
@@ -75,25 +102,32 @@ Special globals include:
  - "timeout": If any test in the file takes longer than this (in ms),
    it fails.  Default: 2000
 
+Environment variables can be set for the test code with `#!! name: value`.
+
 ## JavaScript to test
 
 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 +135,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,32 @@
+#!/usr/bin/env -S node --experimental-vm-modules --no-warnings
+/* eslint-disable no-console */
+
+import {suite} from '../index.js';
+
+let failures = 0;
+
+async function main() {
+  let defaultScript = undefined;
+  let nextDefault = false;
+  for (const arg of process.argv.slice(2)) {
+    if (nextDefault) {
+      defaultScript = arg;
+      nextDefault = false;
+    } else if (arg === '--defaultScript') {
+      nextDefault = true;
+    } else {
+      // eslint-disable-next-line require-atomic-updates
+      failures += await suite(arg, defaultScript);
+    }
+  }
+}
+
+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,147 @@
-'use strict'
+import {hexlify, mapObj} from './utils.js';
+import Mocha from 'mocha';
+import {Runner} from './runner.js';
+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 && (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
+ * 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 {string} [defaultScript='../$<base>.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<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 = '.', defaultScript = '../$<base>.js') {
+  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
+      throw er;
+    }
+
+    const opts = {};
+    let text = '';
+    if (parsed.vars.inline) {
+      opts.filename = f;
+      text = parsed.vars.inline.value;
+      opts.lineOffset = parsed.vars.inline.line - 1;
+      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))
+      opts.filename = parsed.vars.script ?
+        path.resolve(dir, parsed.vars.script.value) :
+        path.resolve(dir, f.replace(/(?<base>[^./]*)\.tests?$/, defaultScript));
+      text = await fs.readFile(opts.filename, 'utf8');
     }
     if (parsed.vars.timeout) {
-      suite.timeout(parseInt(parsed.vars.timeout.value))
+      msuite.timeout(parseInt(parsed.vars.timeout.value, 10));
     }
     opts.sandbox = mapObj(
-      Object.entries(parsed.vars),
-      ([key, value]) => [key, value.value])
-
-    let runner = new Runner(opts)
+      Object.entries(parsed.vars).filter(([k, v]) => !v.env),
+      ([key, value]) => [key, value.value]
+    );
+    opts.env = mapObj(
+      Object.entries(parsed.vars).filter(([k, v]) => v.env),
+      ([key, value]) => [key, value.value]
+    );
+    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.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,
+          }, ...pt.inputs);
         } 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/modtype.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export class ModType {
+  static #cache = new Map(); // Filename => 'commonjs', 'module', 'unknown'
+
+  static async #readPkg(dir) {
+    const pkg = path.join(dir, 'package.json');
+    try {
+      const {type = 'commonjs'} = JSON.parse(await fs.readFile(pkg, 'utf8'));
+      return type;
+    } catch {
+      return undefined;
+    }
+  }
+
+  static async find(name, dir = false, root = undefined) {
+    const prev = this.#cache.get(name);
+    if (prev) {
+      return prev;
+    }
+    let res = 'unknown';
+
+    if (!root) {
+      const p = path.parse(name);
+      switch (p.ext) {
+        case '.mjs':
+          res = 'module';
+          this.#cache.set(name, res);
+          return res;
+        case '.cjs':
+          res = 'commonjs';
+          this.#cache.set(name, res);
+          return res;
+      }
+      ({root} = p);
+      try {
+        // Avoid problems if an existing directory name is passed in originally.
+        dir = (await fs.stat(name)).isDirectory();
+      } catch {
+        // File doesn't exist.  Safe to assume it's file-ish, keep dir = false.
+      }
+    }
+
+    if (name !== root) { // Never go all the way to the root directory.
+      const t = dir ? await this.#readPkg(name) : undefined;
+      res = t ?? this.find(path.dirname(name), true, root);
+    }
+    this.#cache.set(name, res);
+    return res;
+  }
+
+  static clear() {
+    this.#cache.clear();
+  }
+
+  static get cacheSize() {
+    return this.#cache.size;
+  }
+}

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "unexpectedly",
-  "version": "0.0.7",
+  "version": "1.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.pegjs",
+    "pretest": "npm run build",
+    "test": "c8 npm run runtests",
+    "runtests": "mocha && bin/unexpectedly.js 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,30 @@
     "harness"
   ],
   "author": "Joe Hildebrand <joe-github@cursive.net>",
+  "repository": {
+    "type": "git",
+    "url": "http://github.com/hildjj/unexpectedly.git"
+  },
   "license": "MPL-2.0",
+  "dependencies": {
+    "mocha": "^10.2.0"
+  },
   "devDependencies": {
-    "eslint": "^7.24.0",
-    "eslint-config-standard": "^16.0.2",
-    "eslint-plugin-import": "^2.22.1",
+    "@cto.af/eslint-config": "3.0.2",
+    "c8": "8.0.1",
+    "eslint": "^8.54.0",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-import": "^2.29.0",
+    "eslint-plugin-jsdoc": "46.9.0",
+    "eslint-plugin-n": "16.3.1",
     "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-promise": "^5.1.0",
+    "eslint-plugin-promise": "^6.1.1",
     "eslint-plugin-standard": "^4.1.0",
-    "peggy": "^1.0.0"
+    "peggy": "^3.0.2",
+    "rimraf": "5.0.5",
+    "zx": "7.2.3"
   },
   "engines": {
-    "node": ">=10"
-  },
-  "dependencies": {
-    "mocha": "^8.3.2",
-    "vm2": "^3.9.3"
-  },
-  "repository": {
-    "type": "git",
-    "url": "http://github.com/hildjj/unexpectedly.git"
+    "node": ">=18"
   }
 }