@exodus/test 1.0.0-rc.4 → 1.0.0-rc.40

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Exodus Movement, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,18 +1,84 @@
 # @exodus/test
 
+A runner for `node:test`, `jest`, and `tape` test suites on top of `node:test` (and any runtime)
+
 Most likely it will just work on your simple jest tests as as drop-in replacement
 
+Comes with typescript support, optional esm/cjs interop, and also loading babel transforms!
+
+Use `--coverage` to generate coverage output
+
+Default `NODE_ENV` value is "test", use `NODE_ENV=` to override (e.g. to empty)
+
+## Why?
+
+- Can run your tests on Node.js, Bun, Deno, JavaScriptCore and Hermes without extra churn
+
+- Unlike `jest`, it is fast
+
+- Unlike `node:test`, it is a drop-in replacement for `jest`
+
+  - With `expect`, support for snapshots, mocks and matchers
+
+  - `jest-when` and `jest-extended` are fully compatible and can just be used
+
+  - Snapshots are compatible with Jest and can just be used both ways
+
+  - Also compatible to `node:test`
+
+- Unlike `bun:test`, it runs all test files in isolated contexts
+
+  Bun leaks globals / side effects between test files and has incompatible `test()` lifecycle / order
+
+- Can use Jest config
+
+- Native coverage support (enable via `--coverage`)
+
+- Can record / replay `fetch` and `WebSocket` sessions. And run them on all runtimes (including Hermes)
+
+- Automatic polyfills for JavaScriptCore / Hermes, including crypto
+
+- Hanging tests error by default (unlike `jest`)
+
+- Native ESM out of the box
+
+- Esbuild on the fly for babelified ESM interop (enable via `--esbuild`)
+
+- TypeScript support in both transform (enable via `--esbuild`) and typestrip (via `--typescript`) modes
+
+- Babel support, picks up your Babel config (enable via `--babel`)
+
+- `--drop-network` support for guaranteed offline testing
+
 ## Library
 
+### Using with `node:test` natively
+
+You can just use pure [`node:test`](https://nodejs.org/api/test.html) in your tests,
+this runner is fully compatible with that (and will set version-specific options for you)!
+
 ### Moving from jest
 
-`import { describe, it, assert, jest, expect } from '@exodus/test'`
+```js
+import {
+  jest,
+  expect,
+  describe,
+  it,
+  beforeEach,
+  afterEach,
+  beforeAll,
+  afterAll,
+} from '@exodus/test/jest'
+```
+
+Or, run with [`--jest` option](#options) to register jest globals
 
 ### Moving from tap/tape
 
-`import { tap as test } from '@exodus/test'`
-
-Not all features might be supported
+```js
+import test from '@exodus/test/tape'
+```
 
 ### Running tests asynchronously
 
@@ -20,38 +86,19 @@ Add `{ concurrency: true }`, like this: `describe('my testsuite', { concurrency:
 
 ### List of exports
 
-Adapters:
-
-- `jest` -- jest mock adapter
-- `tap` -- tap/tape adapter
-- `mock`
-
-Assertions:
+- `@exodus/test/jest` -- `jest` mock
 
-- `assert` -- alias for `node:assert/strict`
-- `expect` -- expect with additional features for function mocks
-
-Suite:
-
-- `describe`
-- `test`
-- `it` -- alias for `test`
-- `beforeEach`
-- `afterEach`
-- `before` -- alias for `beforeAll`
-- `after` -- alias for `afterAll`
+- `@exodus/test/tape` -- `tape` mock (can also be helpful when moving from `tap`)
 
 ## Binary
 
-Just use `"test: "exodus-test"`
+Just use `"test": "exodus-test"`
 
 ### Options
 
-- `--global` -- register all test helpers as global variables
-
-- `--typescript` -- use typescript loader (which also compiles esm to cjs where needed)
+- `--jest` -- register jest test helpers as global variables, also load `jest.config.*` configuration options
 
-- `--esbuild` -- use esbuild loader (currently an alias for `--typescript`)
+- `--esbuild` -- use esbuild loader, also enables Typescript support
 
 - `--babel` -- use babel loader (slower than `--esbuild`, makes sense if you have a special config)
 
@@ -61,4 +108,16 @@ 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
+
+- `--only` -- only run the tests marked with `test.only`
+
 - `--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)
+
+## License
+
+[MIT](./LICENSE)

package/bin/babel-worker.cjs

@@ -0,0 +1,62 @@
+const { Worker, MessageChannel, isMainThread, parentPort } = require('node:worker_threads')
+const { once } = require('node:events')
+const { availableParallelism } = require('node:os')
+
+if (isMainThread) {
+  const maxWorkers = availableParallelism() >= 4 ? 2 : 1
+  const workers = []
+
+  const getWorker = () => {
+    const idle = workers.find((info) => info.busy === 0)
+    if (idle) return idle
+
+    if (workers.length < maxWorkers) {
+      const worker = new Worker(__filename)
+      worker.unref()
+      // unhandled top-level errors will crash automatically, which is desired behavior, no need to listen to error
+      workers.unshift({ worker, busy: 0 })
+    } else if (workers.length > 1) {
+      workers.sort((a, b) => a.busy - b.busy)
+    }
+
+    return workers[0]
+  }
+
+  const transformAsync = async (code, options) => {
+    const info = getWorker()
+    info.busy++
+    const channel = new MessageChannel()
+    info.worker.postMessage({ port: channel.port1, code, options }, [channel.port1])
+    const [{ result, error }] = await once(channel.port2, 'message')
+    info.busy--
+    if (error) throw error
+    return result
+  }
+
+  module.exports = { transformAsync }
+} else {
+  const babel = require('@babel/core')
+  const tryLoadPlugin = (name) => {
+    // Try unwrapping plugin names, as otherwise Babel tries to require them from the wrong dir,
+    // which breaks strict directory structure under pnpm in some setups
+    try {
+      if (typeof name === 'string' && name.startsWith('@babel/plugin-')) return require(name)
+    } catch {}
+
+    return name
+  }
+
+  parentPort.on('message', ({ port, code: input, options }) => {
+    try {
+      // eslint-disable-next-line @exodus/mutable/no-param-reassign-prop-only
+      if (options.plugins) options.plugins = options.plugins.map((name) => tryLoadPlugin(name))
+      const { code, sourcetype, map } = babel.transformSync(input, options) // async here is useless and slower
+      // additional properties are deleted as we don't want to transfer e.g. Plugin instances
+      port.postMessage({ result: { code, sourcetype, map } })
+    } catch (error) {
+      port.postMessage({ error })
+    }
+
+    port.close()
+  })
+}

package/bin/bundle.js

@@ -0,0 +1,305 @@
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { basename, dirname, extname, resolve, join } from 'node:path'
+import { createRequire } from 'node:module'
+import { randomUUID as uuid, randomBytes } from 'node:crypto'
+import * as esbuild from 'esbuild'
+import glob from 'fast-glob'
+
+const require = createRequire(import.meta.url)
+const resolveRequire = (query) => require.resolve(query)
+const resolveImport = import.meta.resolve && ((query) => fileURLToPath(import.meta.resolve(query)))
+
+const readSnapshots = async (files, resolvers) => {
+  const snapshots = []
+  for (const file of files) {
+    for (const resolver of resolvers) {
+      const snapshotFile = join(...resolver(dirname(file), basename(file)))
+      try {
+        snapshots.push([snapshotFile, await readFile(snapshotFile, 'utf8')])
+      } catch (e) {
+        if (e.code !== 'ENOENT') throw e
+      }
+    }
+  }
+
+  return snapshots
+}
+
+// These packages throw on import
+const blockedDeps = ['@pollyjs/adapter-node-http', '@pollyjs/node-server']
+const loadPipeline = [
+  function (source, filepath) {
+    return source
+      .replace(/\bimport\.meta\.url\b/g, JSON.stringify(pathToFileURL(filepath)))
+      .replace(/\b(__dirname|import\.meta\.dirname)\b/g, JSON.stringify(dirname(filepath)))
+      .replace(/\b(__filename|import\.meta\.filename)\b/g, JSON.stringify(filepath))
+  },
+  function (source, filepath) {
+    // Just a convenience wrapper to show pretty errors instead of generic bundle-apis/empty/module-throw.cjs
+    for (const pkg of blockedDeps) {
+      const str = `require(${JSON.stringify(pkg)})`
+      assert(!str.includes("'"))
+      const err = `module unsupported in bundled form: ${pkg}\n       loaded from ${filepath}`
+      const rep = `((() => { throw new Error(${JSON.stringify(err)}) })())`
+      for (const sub of [str, str.replaceAll('"', "'")]) source = source.replace(sub, rep)
+    }
+
+    return source
+  },
+]
+
+const options = {}
+
+export const init = async ({ platform, jest, flow, target, jestConfig, outdir }) => {
+  Object.assign(options, { platform, jest, flow, target, jestConfig, outdir })
+
+  if (options.flow) {
+    const { default: flowRemoveTypes } = await import('flow-remove-types')
+    loadPipeline.unshift((source) => flowRemoveTypes(source, { pretty: true }).toString())
+  }
+
+  if (options.platform === 'hermes') {
+    const babel = await import('./babel-worker.cjs')
+    loadPipeline.push(async (source) => {
+      const result = await babel.transformAsync(source, {
+        compact: false,
+        babelrc: false,
+        configFile: false,
+        plugins: [
+          '@babel/plugin-syntax-typescript',
+          '@babel/plugin-transform-block-scoping',
+          '@babel/plugin-transform-class-properties',
+          '@babel/plugin-transform-classes',
+          '@babel/plugin-transform-private-methods',
+        ],
+      })
+      return result.code
+    })
+  }
+}
+
+const hermesSupported = {
+  arrow: false,
+  class: false, // we get a safeguard check this way that it's not used
+  'async-generator': false,
+  'const-and-let': false, // have to explicitly set for esbuild to not emit that in helpers, also to get a safeguard check
+  'for-await': false,
+}
+
+const getPackageFiles = async (dir) => {
+  // Returns an empty list on errors
+  let patterns
+  try {
+    patterns = JSON.parse(await readFile(resolve(dir, 'package.json'), 'utf8')).files
+  } catch {}
+
+  if (!patterns) {
+    const parent = dirname(dir)
+    if (parent !== dir) return getPackageFiles(parent)
+    return []
+  }
+
+  // Hack for now, TODO: fix this
+  const expanded = patterns.flatMap((x) => (x.includes('.') ? [x] : [x, `${x}/**/*`]))
+  return glob(expanded, { ignore: ['**/node_modules'], cwd: dir, absolute: true })
+}
+
+const loadCache = new Map()
+const loadSourceFile = async (filepath) => {
+  if (!loadCache.has(filepath)) {
+    const load = async () => {
+      let contents = await readFile(filepath, 'utf8')
+      for (const transform of loadPipeline) contents = await transform(contents, filepath)
+      return contents
+    }
+
+    loadCache.set(filepath, load())
+  }
+
+  return loadCache.get(filepath)
+}
+
+export const build = async (...files) => {
+  const input = []
+  const importSource = async (file) => input.push(await loadSourceFile(resolveRequire(file)))
+  const importFile = (...args) => input.push(`await import(${JSON.stringify(resolve(...args))});`)
+  const stringify = (x) => ([undefined, null].includes(x) ? `${x}` : JSON.stringify(x))
+
+  if (!['node'].includes(options.platform)) {
+    if (['jsc', 'hermes', 'd8'].includes(options.platform)) {
+      const entropy = randomBytes(5 * 1024).toString('base64')
+      input.push(`globalThis.EXODUS_TEST_CRYPTO_ENTROPY = ${stringify(entropy)};`)
+    }
+
+    await importSource('../src/bundle-apis/globals.cjs')
+  }
+
+  if (options.jest) {
+    const { jestConfig } = options
+    const preload = [...(jestConfig.setupFiles || []), ...(jestConfig.setupFilesAfterEnv || [])]
+    if (jestConfig.testEnvironment && jestConfig.testEnvironment !== 'node') {
+      const { specialEnvironments } = await import('../src/jest.environment.js')
+      assert(Object.hasOwn(specialEnvironments, jestConfig.testEnvironment))
+      preload.push(...(specialEnvironments[jestConfig.testEnvironment].dependencies || []))
+    }
+
+    if (preload.length === 0) {
+      input.push(`globalThis.EXODUS_TEST_PRELOADED = []`)
+    } else {
+      assert(jestConfig.rootDir)
+      const local = createRequire(resolve(jestConfig.rootDir, 'package.json'))
+      const w = (f) => `[${stringify(f)}, () => require(${stringify(local.resolve(f))})]`
+      input.push(`globalThis.EXODUS_TEST_PRELOADED = [${preload.map((f) => w(f)).join(', ')}]`)
+    }
+
+    await importSource('./jest.js')
+  }
+
+  for (const file of files) importFile(file)
+
+  const filename = files.length === 1 ? `${files[0]}-${uuid().slice(0, 8)}` : `bundle-${uuid()}`
+  const outfile = `${join(options.outdir, filename)}.js`
+  const EXODUS_TEST_SNAPSHOTS = await readSnapshots(files, [
+    (dir, name) => [dir, `${name}.snapshot`], // node:test
+    (dir, name) => [dir, '__snapshots__', `${name}.snap`], // jest
+  ])
+  const EXODUS_TEST_RECORDINGS = await readSnapshots(files, [
+    (dir, name) => [dir, '__recordings__', 'fetch', `${name}.json`],
+    (dir, name) => [dir, '__recordings__', 'websocket', `${name}.json`],
+  ])
+  const buildWrap = async (opts) => esbuild.build(opts).catch((err) => err)
+  let main = input.join(';\n')
+  if (['jsc', 'hermes', 'd8'].includes(options.platform)) {
+    const exit = `EXODUS_TEST_PROCESS.exitCode = 1; EXODUS_TEST_PROCESS._maybeProcessExitCode();`
+    main = `try {\n${main}\n} catch (err) { print(err); ${exit} }`
+  }
+
+  const fsfiles = await getPackageFiles(filename ? dirname(resolve(filename)) : process.cwd())
+
+  const hasBuffer = ['node', 'bun'].includes(options.platform)
+  const api = (f) => resolveRequire(join('../src/bundle-apis', f))
+  const res = await buildWrap({
+    logLevel: 'silent',
+    stdin: {
+      contents: `(async function () {\n${main}\n})()`,
+      resolveDir: dirname(fileURLToPath(import.meta.url)),
+    },
+    bundle: true,
+    outdir: options.outdir,
+    entryNames: filename,
+    platform: 'neutral',
+    mainFields: ['browser', 'module', 'main'],
+    define: {
+      'process.env.FORCE_COLOR': stringify('0'),
+      'process.env.NO_COLOR': stringify('1'),
+      'process.env.NODE_ENV': stringify(process.env.NODE_ENV),
+      'process.env.EXODUS_TEST_CONTEXT': stringify('pure'),
+      'process.env.EXODUS_TEST_ENVIRONMENT': stringify('bundle'), // always 'bundle'
+      'process.env.EXODUS_TEST_PLATFORM': stringify(process.env.EXODUS_TEST_PLATFORM), // e.g. 'hermes', 'node'
+      'process.env.EXODUS_TEST_ENGINE': stringify(process.env.EXODUS_TEST_ENGINE), // e.g. 'hermes:bundle', 'node:bundle'
+      'process.env.EXODUS_TEST_JEST_CONFIG': stringify(JSON.stringify(options.jestConfig)),
+      'process.env.EXODUS_TEST_EXECARGV': stringify(process.env.EXODUS_TEST_EXECARGV),
+      'process.env.EXODUS_TEST_ONLY': stringify(process.env.EXODUS_TEST_ONLY),
+      'process.env.NODE_DEBUG': stringify(),
+      'process.env.DEBUG': stringify(),
+      'process.env.READABLE_STREAM': stringify(),
+      'process.env.CI': stringify(process.env.CI),
+      'process.env.CI_ENABLE_VERBOSE_LOGS': stringify(process.env.CI_ENABLE_VERBOSE_LOGS),
+      'process.browser': stringify(true),
+      'process.emitWarning': 'undefined',
+      'process.stderr': 'undefined',
+      'process.stdout': 'undefined',
+      'process.type': 'undefined',
+      'process.version': stringify('v22.5.1'), // shouldn't depend on currently used Node.js version
+      'process.versions.node': stringify('22.5.1'), // see line above
+      EXODUS_TEST_FILES: stringify(files.map((f) => [dirname(f), basename(f)])),
+      EXODUS_TEST_SNAPSHOTS: stringify(EXODUS_TEST_SNAPSHOTS),
+      EXODUS_TEST_RECORDINGS: stringify(EXODUS_TEST_RECORDINGS),
+      EXODUS_TEST_FSFILES: stringify(fsfiles), // TODO: can we safely use relative paths?
+    },
+    alias: {
+      // Jest and tape
+      '@jest/globals': resolveImport('../src/jest.js'),
+      tape: resolveImport('../src/tape.cjs'),
+      'tape-promise/tape': resolveImport('../src/tape.cjs'),
+      // Node browserify
+      'node:assert': dirname(dirname(resolveRequire('assert/'))),
+      'node:assert/strict': api('assert-strict.cjs'),
+      'node:fs': api('fs.cjs'),
+      'node:fs/promises': api('fs-promises.cjs'),
+      fs: api('fs.cjs'),
+      'fs/promises': api('fs-promises.cjs'),
+      assert: dirname(dirname(resolveRequire('assert/'))),
+      buffer: hasBuffer ? api('node-buffer.cjs') : dirname(resolveRequire('buffer/')),
+      child_process: api('child_process.cjs'),
+      constants: resolveRequire('constants-browserify'),
+      crypto: api('crypto.cjs'),
+      events: dirname(resolveRequire('events/')),
+      http: api('http.cjs'),
+      https: api('https.cjs'),
+      os: resolveRequire('os-browserify'),
+      path: resolveRequire('path-browserify'),
+      querystring: resolveRequire('querystring-es3'),
+      stream: resolveRequire('stream-browserify'),
+      timers: resolveRequire('timers-browserify'),
+      url: dirname(resolveRequire('url/')),
+      util: dirname(resolveRequire('util/')),
+      zlib: resolveRequire('browserify-zlib'),
+      // expect-related deps
+      'ansi-styles': api('ansi-styles.cjs'),
+      'jest-util': api('jest-util.js'),
+      'jest-message-util': api('jest-message-util.js'),
+      // unwanted deps
+      bindings: api('empty/function-throw.cjs'),
+      'node-gyp-build': api('empty/function-throw.cjs'),
+      ws: api('ws.cjs'),
+      // unsupported deps
+      ...Object.fromEntries(blockedDeps.map((n) => [n, api('empty/module-throw.cjs')])),
+    },
+    sourcemap: ['hermes', 'jsc', 'd8'].includes(options.platform) ? 'inline' : 'linked', // FIXME?
+    sourcesContent: false,
+    keepNames: true,
+    format: 'iife',
+    target: options.target || `node${process.versions.node}`,
+    supported: {
+      bigint: true,
+      ...(options.platform === 'hermes' ? hermesSupported : {}),
+    },
+    plugins: [
+      {
+        name: 'exodus-test.bundle',
+        setup({ onLoad }) {
+          onLoad({ filter: /\.[cm]?[jt]sx?$/, namespace: 'file' }, async (args) => {
+            let filepath = args.path
+            // Resolve .native versions
+            // TODO: move flag to engine options
+            // TODO: maybe follow package.json for this
+            if (['jsc', 'hermes'].includes(options.platform)) {
+              const maybeNative = filepath.replace(/(\.[cm]?[jt]sx?)$/u, '.native$1')
+              if (existsSync(maybeNative)) filepath = maybeNative
+            }
+
+            const loader = extname(filepath).replace(/^\.[cm]?/, '') // TODO: a flag to force jsx/tsx perhaps
+            assert(['js', 'ts', 'jsx', 'tx'].includes(loader))
+
+            return { contents: await loadSourceFile(filepath), loader }
+          })
+        },
+      },
+    ],
+  })
+  assert.equal(res instanceof Error, res.errors.length > 0)
+
+  // if (res.errors.length === 0) require('fs').copyFileSync(outfile, 'tempout.cjs') // DEBUG
+
+  // We treat warnings as errors, so just merge all them
+  const errors = []
+  const formatOpts = { color: process.stdout.hasColors?.(), terminalWidth: process.stdout.columns }
+  const formatMessages = (list, kind) => esbuild.formatMessages(list, { kind, ...formatOpts })
+  if (res.warnings.length > 0) errors.push(...(await formatMessages(res.warnings, 'warning')))
+  if (res.errors.length > 0) errors.push(...(await formatMessages(res.errors, 'error')))
+  return { file: outfile, errors }
+}