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

package/README.md

@@ -71,3 +71,5 @@ Just use `"test": "exodus-test"`
 - `--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

@@ -70,6 +70,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 +115,11 @@ 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.coverage) {
   if (options.coverageEngine === 'node') {
     args.push('--experimental-test-coverage')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/test",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.6",
   "author": "Exodus Movement, Inc.",
   "description": "A test suite runner",
   "homepage": "https://github.com/ExodusMovement/test",

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()

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 * 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,15 +27,36 @@ 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(),
+  ...allMocks,
   spyOn: (obj, name) => {
     assert(obj && name && name in obj && !(name in {}) && !(name in Object.prototype))
     const fn = jestfn(obj[name], obj, name)
@@ -48,14 +70,6 @@ const jest = {
   ...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

@@ -86,7 +86,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 +108,14 @@ 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
   }
 
-  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

@@ -52,7 +52,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,41 +61,68 @@ 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) || assert // 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 fn = args.pop()
     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)