@exodus/test 1.0.0-rc.5 → 1.0.0-rc.7

package/README.md

@@ -8,6 +8,8 @@ Comes with typescript support, optional esm/cjs interop, and also loading babel
 
 Use `--coverage` to generate coverage output
 
+Default `NODE_ENV` value is "test", use `NODE_ENV=` to override (e.g. to empty)
+
 ## Library
 
 ### Using with `node:test` natively
@@ -68,6 +70,10 @@ Just use `"test": "exodus-test"`
 
 - `--coverage-engine node` -- use Node.js builtint coverage engine
 
+- `--watch` -- operate in watch mode and re-run tests on file changes
+
 - `--passWithNoTests` -- do not error when no test files were found
 
 - `--write-snapshots` -- write snapshots instead of verifying them (has `--test-update-snapshots` alias)
+
+- `--test-force-exit` -- force exit after tests are done (useful in integration tests where it could be unfeasible to resolve all open handles)

package/bin/index.js

@@ -26,9 +26,10 @@ function parseOptions() {
     esbuild: false,
     babel: false,
     coverage: false,
+    coverageEngine: 'c8', // c8 or node
+    watch: false,
     passWithNoTests: false,
     writeSnapshots: false,
-    coverageEngine: 'c8', // c8 or node
   }
 
   const args = [...process.argv]
@@ -63,6 +64,9 @@ function parseOptions() {
       case '--coverage':
         options.coverage = true
         break
+      case '--watch':
+        options.watch = true
+        break
       case '--passWithNoTests':
         options.passWithNoTests = true
         break
@@ -70,6 +74,10 @@ function parseOptions() {
       case '--write-snapshots':
         options.writeSnapshots = true
         break
+      case '--test-force-exit':
+      case '--forceExit':
+        options.forceExit = true
+        break
       default:
         throw new Error(`Unknown option: ${option}`)
     }
@@ -111,6 +119,16 @@ if (options.writeSnapshots) {
   args.push('--test-update-snapshots')
 }
 
+if (options.forceExit) {
+  assert((major === 20 && minor > 13) || major >= 22, 'For forceExit, use Node.js >= 20.14.0')
+  args.push('--test-force-exit')
+}
+
+if (options.watch) {
+  assert((major === 18 && minor > 13) || major >= 20, 'For watch mode, use Node.js >= 18.13.0')
+  args.push('--watch')
+}
+
 if (options.coverage) {
   if (options.coverageEngine === 'node') {
     args.push('--experimental-test-coverage')
@@ -172,6 +190,8 @@ if (tsTests.length > 0 && !options.typescript) {
 assert(files.length > 0) // otherwise we can run recursively
 args.push(...files)
 
+if (!Object.hasOwn(process.env, 'NODE_ENV')) process.env.NODE_ENV = 'test'
+
 assert(program && ['node', c8].includes(program))
 const node = spawn(program, args, { stdio: 'inherit' })
 

package/bin/jest.js

@@ -1,8 +1,10 @@
 import * as globals from '../src/jest.js'
+import { resolveModule } from '../src/jest.mock.js'
 import { mock } from 'node:test'
 
 Object.assign(globalThis, globals)
 
 try {
-  if (mock.module) mock.module('@jest/globals', { defaultExport: globals, namedExports: globals })
+  const resolved = resolveModule('@jest/globals')
+  if (mock.module) mock.module(resolved, { defaultExport: globals, namedExports: globals })
 } catch {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/test",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.7",
   "author": "Exodus Movement, Inc.",
   "description": "A test suite runner",
   "homepage": "https://github.com/ExodusMovement/test",
@@ -44,6 +44,7 @@
   ],
   "scripts": {
     "test": "./bin/index.js --jest --typescript",
+    "test:tape": "./bin/index.js --esbuild '__test__/tape/test/*.js' __test__/tape.test.js",
     "coverage": "./bin/index.js --jest --typescript --coverage",
     "lint": "prettier --list-different . && eslint .",
     "lint:fix": "prettier --write . && eslint --fix ."
@@ -59,6 +60,7 @@
   "devDependencies": {
     "@exodus/eslint-config": "^5.24.0",
     "@exodus/prettier": "^1.0.0",
+    "@jest/globals": "^29.7.0",
     "@types/jest-when": "^3.5.2",
     "@typescript-eslint/eslint-plugin": "^7.15.0",
     "eslint": "^8.44.0",

package/src/jest.fn.js

@@ -3,15 +3,17 @@ import assert from 'node:assert/strict'
 
 const registry = new Set()
 
-function applyAll(method) {
-  assert(['mockClear', 'mockReset', 'mockRestore'].includes(method))
-  for (const obj of registry) obj[method]()
-}
+const applyAllWrap = (method) =>
+  function () {
+    assert(['mockClear', 'mockReset', 'mockRestore'].includes(method))
+    for (const obj of registry) obj[method]()
+    return this
+  }
 
 export const allMocks = {
-  mockClear: () => applyAll('mockClear'),
-  mockReset: () => applyAll('mockReset'),
-  mockRestore: () => applyAll('mockRestore'),
+  clearAllMocks: applyAllWrap('mockClear'),
+  resetAllMocks: applyAllWrap('mockReset'),
+  restoreAllMocks: applyAllWrap('mockRestore'),
 }
 
 // We need parent and property for jest.spyOn and mockfn.mockRestore()
@@ -33,6 +35,7 @@ export const jestfn = (baseimpl, parent, property) => {
     queuedMockClear()
     onceStack.length = 0
     mockimpl = noop
+    mockname = undefined
     reportedmockimpl = undefined
     fnmock.mockImplementation(mockimpl)
   }
@@ -66,18 +69,20 @@ export const jestfn = (baseimpl, parent, property) => {
 
   const queuedMockOnce = (impl) => {
     onceStack.push(impl)
-    fnmock.mockImplementation(function (...args) {
-      try {
-        const impl = onceStack.shift() || mockimpl
-        return impl.call(this, ...args)
-      } finally {
-        // load fast path if we are done with the queue
-        if (onceStack.length === 0) {
-          assert(mockimpl)
-          fnmock.mockImplementation(mockimpl)
-        }
+    fnmock.mockImplementation(queueImplementation)
+  }
+
+  const queueImplementation = function (...args) {
+    try {
+      const impl = onceStack.shift() || mockimpl
+      return impl.call(this, ...args)
+    } finally {
+      // load fast path if we are done with the queue
+      if (onceStack.length === 0) {
+        assert(mockimpl)
+        fnmock.mockImplementation(mockimpl)
       }
-    })
+    }
   }
 
   const jestfnmock = {
@@ -123,7 +128,7 @@ export const jestfn = (baseimpl, parent, property) => {
       case '_isMockFunction':
         return true
       case 'getMockName':
-        return () => mockname
+        return () => mockname ?? 'jest.fn()'
       case 'mockName':
         return wrap((name) => {
           mockname = name

package/src/jest.js

@@ -1,10 +1,11 @@
 import assert from 'node:assert/strict'
-import { describe, test, it } from 'node:test'
-import { format } from 'node:util'
+import { describe as nodeDescribe, test as nodeTest, afterEach } from 'node:test'
+import { format, types } from 'node:util'
 import { jestfn, allMocks } from './jest.fn.js'
-import { jestmock, requireActual, requireMock } from './jest.mock.js'
+import { jestmock, requireActual, requireMock, resetModules } from './jest.mock.js'
 import * as jestTimers from './jest.timers.js'
 import './jest.snapshot.js'
+import { expect } from 'expect'
 
 const makeEach = (impl) => (list) => (template, fn) => {
   for (const args of list) {
@@ -26,16 +27,38 @@ const makeEach = (impl) => (list) => (template, fn) => {
   }
 }
 
+const forceExit = process.execArgv.map((x) => x.replaceAll('_', '-')).includes('--test-force-exit')
+
+const describe = (...args) => nodeDescribe(...args)
+const test = (name, fn) => {
+  if (fn.length > 0) return nodeTest(name, (t, c) => fn(c))
+  if (!forceExit) return nodeTest(name, fn)
+  return nodeTest(name, async (t) => {
+    const res = fn()
+    assert(
+      types.isPromise(res),
+      `Test "${t.fullName}" did not return a Promise or supply a callback, which is required in force-exit mode.
+For tests to not end abruptly, use either async functions (recommended), Promises, or specify callbacks to test() / it().
+Also, using expect.assertions() to ensure the planned number of assertions is being called is advised for async code.`
+    )
+    return res
+  })
+}
+
 describe.each = makeEach(describe)
 test.each = makeEach(test)
-it.each = makeEach(it)
+describe.skip = (...args) => nodeDescribe.skip(...args)
+test.skip = (...args) => nodeTest.skip(...args)
+
+afterEach(() => {
+  for (const { error } of expect.extractExpectedAssertionsErrors()) throw error
+})
 
 const jest = {
   fn: (impl) => jestfn(impl), // hide extra arguments
-  clearAllMocks: () => allMocks.mockClear(),
-  resetAllMocks: () => allMocks.mockReset(),
-  restoreAllMocks: () => allMocks.mockRestore(),
-  spyOn: (obj, name) => {
+  ...allMocks,
+  spyOn: (obj, name, accessType) => {
+    assert(!accessType, `accessType "${accessType}" is not supported`)
     assert(obj && name && name in obj && !(name in {}) && !(name in Object.prototype))
     const fn = jestfn(obj[name], obj, name)
     // eslint-disable-next-line @exodus/mutable/no-param-reassign-prop-only
@@ -45,17 +68,10 @@ const jest = {
   mock: jestmock,
   requireMock,
   requireActual,
+  resetModules,
   ...jestTimers,
 }
 
-export { jest }
+export { jest, describe, test, test as it }
 export { expect } from 'expect'
-export {
-  beforeEach,
-  afterEach,
-  before as beforeAll,
-  after as afterAll,
-  describe,
-  test,
-  it,
-} from 'node:test'
+export { beforeEach, afterEach, before as beforeAll, after as afterAll } from 'node:test'

package/src/jest.mock.js

@@ -1,14 +1,18 @@
 import assert from 'node:assert/strict'
-import { createRequire, builtinModules } from 'node:module'
+import { createRequire, builtinModules, syncBuiltinESMExports } from 'node:module'
+import { existsSync } from 'node:fs'
+import { normalize } from 'node:path'
 import { mock } from 'node:test'
 import { jestfn } from './jest.fn.js'
 
-const require = createRequire(import.meta.url)
+const files = process.argv.slice(1)
+const baseUrl = files.length === 1 && existsSync(files[0]) ? normalize(files[0]) : undefined
+const require = createRequire(baseUrl || import.meta.url)
 const mapMocks = new Map()
 const mapActual = new Map()
 
-function resolveModule(name) {
-  assert(/^[@a-zA-Z]/u.test(name), 'Mocking relative paths is not supported')
+export function resolveModule(name) {
+  assert(baseUrl || /^[@a-zA-Z]/u.test(name), 'Mocking relative paths is not possible')
   return require.resolve(name)
 }
 
@@ -25,6 +29,11 @@ export function requireMock(name) {
   return mapMocks.get(resolved)
 }
 
+export function resetModules() {
+  // Caveat: only resets CJS modules, not ESM
+  for (const key of Object.keys(require.cache)) delete require.cache[key]
+}
+
 const isObject = (obj) => [Object.prototype, null].includes(Object.getPrototypeOf(obj))
 
 function override(resolved, lax = false) {
@@ -41,7 +50,9 @@ function override(resolved, lax = false) {
 
   // We want to skip overriding frozen properties that already match, e.g. fs.constants
   const filtered = Object.entries(value).filter(([k, v]) => !(k in {}) && current[k] !== v)
-  Object.assign(current, Object.fromEntries(filtered))
+  const access = { configurable: true, enumerable: true, writable: true }
+  const definitions = Object.fromEntries(filtered.map(([k, value]) => [k, { value, ...access }]))
+  Object.defineProperties(current, definitions)
   if (!lax) assert.deepEqual({ ...current }, value)
 }
 
@@ -86,7 +97,7 @@ export function jestmock(name, mocker) {
 
   // Loaded ESM: isn't mocked
   // Loaded CJS: mocked via object overriding
-  // Loaded built-ins: not mocked for now (!!!)
+  // Loaded built-ins: mocked via object overriding where possible
   // New CJS: mocked via mock.module + require.cache
   // New ESM: mocked via mock.module
   // New built-ins: mocked via mock.module
@@ -108,15 +119,15 @@ export function jestmock(name, mocker) {
   // fall through when e.g. this module doesn't exist or is ESM
   if (Object.hasOwn(require.cache, resolved)) {
     assert.equal(mapActual.get(resolved), require.cache[resolved].exports)
-    // If we did't have this prior but have now, it means we just loaded it and there are not leaked instances
+    // If we did't have this prior but have now, it means we just loaded it and there are no leaked instances
     if (havePrior) override(resolved)
     require.cache[resolved].exports = value
   } else if (builtinModules.includes(resolved.replace(/^node:/, ''))) {
     override(resolved, true) // Override builtin modules
+    syncBuiltinESMExports()
   }
 
-  mock.module(name, {
-    defaultExport: value.default,
-    namedExports: value,
-  })
+  mock.module(name, { defaultExport: value.default, namedExports: value })
+
+  return this
 }

package/src/jest.snapshot.js

@@ -58,39 +58,36 @@ function wrapContextName(fn) {
   }
 }
 
-function expectError(fn) {
-  let err
-  expect(() => {
-    try {
-      fn()
-    } catch (e) {
-      err = e
-      throw e
-    }
-  }).toThrow()
-  return expect(err.message) // jest just checks error message, not error obj
+const throws = (fn, check) =>
+  context.assert.throws(fn, (e) => {
+    check(e.message) // jest stores only messages for errors
+    return true
+  })
+
+const snapInline = (obj, inline) => {
+  assert(inline !== undefined, 'Inline Snapshots generation is not supported')
+  assert(typeof inline === 'string')
+  context.assert.equal(serialize(obj).trim(), inline.trim())
 }
 
-expect.extend({
-  toMatchInlineSnapshot: (obj, inline) => {
-    assert(inline !== undefined, 'Inline Snapshots generation is not supported')
-    assert(typeof inline === 'string')
-    return wrap(() => expect(serialize(obj).trim()).toEqual(inline.trim()))
-  },
-  toMatchSnapshot: (obj) => {
+const snapOnDisk = (obj) =>
+  wrapContextName(() => {
     const str = serialize(obj)
     if (!str.includes('\n')) {
       // Node.js always wraps with newlines, while jest wraps only those that are already multiline
       // Hopefully, for simple objects there is no need to use snapshots and those can be just compared directly
-      const msg = `Snapshotting primitives or empty objects/arrays is not supported yet: ${str}`
-      return { pass: false, message: () => msg }
+      throw new Error(`Snapshots of primitives or empty objects/arrays is not supported: ${str}`)
     }
 
     maybeSetupJestSnapshots()
-    return wrap(() => wrapContextName(() => context.assert.snapshot(obj)))
-  },
-  toThrowErrorMatchingInlineSnapshot: (f, i) => wrap(() => expectError(f).toMatchInlineSnapshot(i)),
-  toThrowErrorMatchingSnapshot: (f) => wrap(() => expectError(f).toMatchSnapshot()),
+    return context.assert.snapshot(obj)
+  })
+
+expect.extend({
+  toMatchInlineSnapshot: (obj, i) => wrap(() => snapInline(obj, i)),
+  toMatchSnapshot: (obj) => wrap(() => snapOnDisk(obj)),
+  toThrowErrorMatchingInlineSnapshot: (f, i) => wrap(() => throws(f, (msg) => snapInline(msg, i))),
+  toThrowErrorMatchingSnapshot: (f) => wrap(() => throws(f, (msg) => snapOnDisk(msg))),
 })
 
 expect.addSnapshotSerializer = (plugin) => plugins.push(plugin)

package/src/jest.timers.js

@@ -14,12 +14,12 @@ const warnOldTimers = () => {
   if (!ok) console.warn('Warning: timer mocks are known to be glitchy before Node.js >=20.11.0')
 }
 
-export const useRealTimers = () => {
+export function useRealTimers() {
   mock.timers.reset()
-  return jest
+  return this
 }
 
-export const useFakeTimers = ({ doNotFake = [], ...rest } = {}) => {
+export function useFakeTimers({ doNotFake = [], ...rest } = {}) {
   assertHaveTimers()
   warnOldTimers()
   assert.deepEqual(rest, {}, 'Unsupported options')
@@ -33,33 +33,35 @@ export const useFakeTimers = ({ doNotFake = [], ...rest } = {}) => {
     if (e.code !== 'ERR_INVALID_STATE') throw e
   }
 
-  return jest
+  return this
 }
 
-export const runAllTimers = () => {
+export function runAllTimers() {
   assertHaveTimers()
   warnOldTimers()
   mock.timers.tick(100_000_000_000) // > 3 years
-  return jest
+  return this
 }
 
-export const runOnlyPendingTimers = () => {
+export function runOnlyPendingTimers() {
   const noInfiniteLoopBug = major >= 22 || (major === 20 && minor >= 11)
   assert(noInfiniteLoopBug, 'runOnlyPendingTimers requires Node.js >=20.11.0')
   mock.timers.runAll()
-  return jest
+  return this
 }
 
-export const advanceTimersByTime = (time) => {
+export function advanceTimersByTime(time) {
   assertHaveTimers()
   warnOldTimers()
   mock.timers.tick(time)
-  return jest
+  return this
 }
 
-export const advanceTimersByTimeAsync = async (time) => jest.advanceTimersByTime(time)
+export async function advanceTimersByTimeAsync(time) {
+  return this.advanceTimersByTime(time)
+}
 
-export const setSystemTime = (time) => {
+export function setSystemTime(time) {
   mock.timers.setTime(+time)
-  return jest
+  return this
 }

package/src/tape.js

@@ -1,7 +1,8 @@
 import assert from 'node:assert/strict'
+import assertLoose from 'node:assert'
 import { test } from 'node:test'
 
-const knownOptions = new Set(['skip', 'todo', 'concurrency'])
+const knownOptions = new Set(['skip', 'todo', 'concurrency', 'timeout'])
 
 function verifyOptions(options) {
   for (const key of Object.keys(options)) {
@@ -52,7 +53,7 @@ const aliases = {
   rejects: ['rejects'],
   doesNotReject: ['resolves'],
 
-  // specially handled ones as do not exist in t.assert
+  // specially handled ones as do not exist in t.assert / assert
   notOk: ['notOk', 'false', 'notok'],
   pass: ['pass'],
   error: ['error', 'ifError', 'ifErr', 'iferror'], // tape
@@ -61,44 +62,73 @@ const aliases = {
   // match/notMatch are confusing as operate on strings in some impls and objs in others. we skip them
 }
 
-function tapeWrapAssert(t) {
-  // Note: we must use t.assert instead of assert everywhere as we have t.plan
+function tapeWrapAssert(t, callback) {
+  // Auto-call api.end() on planned test count reaching zero
+  let plan = null
+  let count = 0
+  const track = (...calls) => {
+    count += calls.length
+    if (plan === count) api.end()
+    if (plan !== null) assert(plan >= count, `plan (${plan}) < count (${count})`)
+  }
+
+  const plannedAssert = () => (plan !== null && t.assert) || assertLoose // t.assert is cached and affected by t.plan
 
+  // Note: we must use plannedAssert instead of assert everywhere on user calls as we have t.plan
   const api = {
     test: tapeWrap(t.test.bind(t)),
-    plan: (...r) => t.plan(...r),
+    plan: (total) => {
+      assert.equal(typeof total, 'number')
+      plan = total
+      assert(plan >= count, `plan (${plan}) < count (${count})`)
+      if (t.plan) t.plan(plan - count) // plan the remaining tests through node
+      track()
+    },
     skip: (...r) => t.skip(...r),
     todo: (...r) => t.todo(...r),
     comment: (...r) => t.diagnostic(...r),
-    end: () => {},
+    end: () => {
+      if (plan !== null) assert.equal(plan, count, `plan (${plan}) !== count (${count})`)
+      if (callback) callback()
+      api.end = () => {}
+    },
   }
 
-  // Copy implementations from here if they exist, preferring over t.assert
+  // Copy implementations from here if they exist, preferring over plannedAssert
   const base = {
-    pass: (...r) => t.assert.ok(true, ...r),
-    notOk: (x, ...r) => t.assert.ok(!x, ...r),
-    error: (err, msg) => t.assert.ok(!err, msg || err?.message),
-    assertion: (fn, ...args) => fn.apply(t.assert, args),
+    pass: (...r) => plannedAssert().ok(true, ...r),
+    notOk: (x, ...r) => plannedAssert().ok(!x, ...r),
+    error: (err, msg) => plannedAssert().ok(!err, msg || err?.message),
+    assertion: (fn, ...args) => fn.apply(plannedAssert(), args),
   }
 
   for (const [key, names] of Object.entries(aliases)) {
-    const impl = Object.hasOwn(base, key) ? base[key] : (...r) => t.assert[key](...r)
-    Object.assign(api, Object.fromEntries(names.map((name) => [name, impl])))
+    const impl = Object.hasOwn(base, key) ? base[key] : (...r) => plannedAssert()[key](...r)
+    Object.assign(api, Object.fromEntries(names.map((name) => [name, (...r) => track(impl(...r))])))
   }
 
   return api
 }
 
+const AsyncFunction = (async () => {}).constructor
+
 function tapeWrap(test) {
-  const tap = (name, ...args) => {
+  const tap = (...args) => {
     const fn = args.pop()
+    const name = args.shift() || 'test'
     assert(args.length <= 1)
     const [opts = {}] = args
     verifyOptions(opts)
-    test(name, opts, (t) => fn(tapeWrapAssert(t)))
+    assert(fn instanceof Function)
+    if (fn instanceof AsyncFunction) {
+      test(name, opts, (t) => fn(tapeWrapAssert(t)))
+    } else {
+      test(name, opts, (t, callback) => fn(tapeWrapAssert(t, callback)))
+    }
   }
 
   tap.skip = (...args) => test.skip(...args)
+  if (test.only) tap.only = tapeWrap(test.only)
   return tap
 }