@exodus/test 1.0.0-rc.10 → 1.0.0-rc.101

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,79 +1,200 @@
 # @exodus/test
 
-A runner for `node:test`, `jest`, and `tape` test suites on top of `node:test`
-
-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
+A runner for `node:test`, `jest`, and `tape` test suites on top of `node:test` (and any runtime).
+
+It can run your existing tests on [all runtimes and also browsers](#engines), with snapshots and module mocks.
+
+## Features
+
+- Native ESM, including in Jest tests
+- Esbuild on the fly for babelified ESM interop (enable via `--esbuild`)
+- TypeScript support in both transform (through [tsx](https://tsx.is/), enable via `--esbuild`)
+  and typestrip (via `--typescript`) modes
+- Runs on Node.js [node:test](https://nodejs.org/api/test.html), Bun, Deno, Electron,
+  [v8 CLI](https://v8.dev/docs/d8), JSC, [Hermes](https://hermesengine.dev), [SpiderMonkey](https://spidermonkey.dev/),
+  Chrome, Firefox, WebKit, Brave, Microsoft Edge,
+  [QuickJS](https://github.com/quickjs-ng/quickjs), [XS](https://github.com/Moddable-OpenSource/moddable-xst),
+  [GraalJS](https://github.com/oracle/graaljs), [Escargot](https://github.com/Samsung/escargot),
+  [Boa](https://github.com/boa-dev/boa), and even [engine262](https://github.com/engine262/engine262).
+- Testsuite-agnostic — can run any file as long as it sets exit code based on test results
+- Built-in [Jest](https://jestjs.io) compatibility (with `--jest`), including `jest.*` global
+  - Up to ~10x faster depending on the original setup
+  - Actual `expect` module, also `jest-extended` and `jest-when` just work on top
+  - Snapshots, including snapshot matchers
+  - Function and timer mocks
+  - [test.concurrent](https://jestjs.io/docs/api#testconcurrentname-fn-timeout)
+  - Module mocks, including for ESM modules (already loaded ESM modules can be mocked only on `node:test`)
+  - Loads Jest configuration
+- Built-in network record/replay for offline tests, mocking `fetch` and `WebSocket` sessions
+- `--drop-network` support for guaranteed offline testing
+- Native code coverage via v8 (Node.js or [c8](https://github.com/bcoe/c8)), with istanbul reporters
+- GitHub reporter (auto-enabled by default)
+- JSDOM env support
+- Hanging tests error by default (unlike `jest`)
+- Babel support, picks up your Babel config (enable via `--babel`)
+- Unlike `bun:test`, it runs test files in isolated contexts \
+  Bun leaks globals / side effects between test files ([ref](https://github.com/oven-sh/bun/issues/6024)),
+  and has incompatible `test()` lifecycle / order
+- Also features a tape API for drop-in replacement
+
+## Engines
+
+Use `--engine` (or `EXODUS_TEST_ENGINE=`) to specify one of:
+
+- `node:test` — the default one, runs on top of modern Node.js [test runner API](https://nodejs.org/api/test.html)
+- `node:pure` — implementation in pure JS, runs on Node.js
+- `node:bundle` — same as `node:pure`, but bundles everything into a single file before launching
+- Other runtimes:
+  - `deno:pure` — Deno (requires Deno v2.4.0 or later, expects `deno` to be available)
+  - `deno:bundle` — Deno (v1 or v2, whichever `deno` is)
+  - `deno:test` — incomplete, lacks `--jest` support due to missing `afterEach` / `beforeEach` in Deno
+  - `bun:pure` / `bun:bundle` — Bun, expects `bun` to be available
+  - `electron-as-node:test` / `electron-as-node:pure` / `electron-as-node:bundle`\
+    Same as `node:*`, but uses `electron` binary.\
+    The usecase is mostly to test on BoringSSL instead of OpenSSL.
+  - `electron:bundle` — run tests in Electron [BrowserWindow](https://www.electronjs.org/docs/latest/api/browser-window)
+    without Node.js integration.
+- Browsers:
+  - Playwright builds (install Playwright-built engines with `exodus-test --playwright install`)
+    - `chromium:playwright` — Playwright-built Chromium
+    - `firefox:playwright` — Playwright-built Firefox
+    - `webkit:playwright` — Playwright-built WebKit, close to Safari
+    - `chrome:playwright` — Chrome (system-installed)
+    - `msedge:playwright` — Microsoft Edge (system-installed)
+  - Puppeteer (system-provided or upstream builds)
+    - `chrome:puppeteer` — Chrome
+    - `firefox:puppeteer` — Firefox
+    - `brave:puppeteer` — Brave
+    - `msedge:puppeteer` — Microsoft Edge
+- Barebone engines (system-provided or installed with `npx jsvu` / `npx esvu`):
+  - `d8:bundle` — [v8 CLI](https://v8.dev/docs/d8) (Chrome/Blink/Node.js JavaScript engine)
+  - `jsc:bundle` — [JavaScriptCore](https://docs.webkit.org/Deep%20Dive/JSC/JavaScriptCore.html) (Safari/WebKit JavaScript engine)
+  - `hermes:bundle` — [Hermes](https://hermesengine.dev) (React Native JavaScript engine)
+  - `spidermonkey:bundle` — [SpiderMonkey](https://spidermonkey.dev/) (Firefox/Gecko JavaScript engine)
+  - `quickjs:bundle` — [QuickJS](https://github.com/quickjs-ng/quickjs)
+  - `xs:bundle` — [XS](https://github.com/Moddable-OpenSource/moddable-xst)
+  - `graaljs:bundle` — [GraalJS](https://github.com/oracle/graaljs)
+  - `escargot:bundle` — [Escargot](https://github.com/Samsung/escargot)
+  - `boa:bundle` — [Boa](https://github.com/boa-dev/boa)
+  - `engine262:bundle` - [engine262](https://github.com/engine262/engine262), the per-spec implementation of ECMA-262
+    (install with [esvu](https://npmjs.com/package/esvu))
+
+## Reporter samples
+
+#### CLI (but uses colors when output supports them, e.g. in terminal):
+
+```console
+# tests/jest/expect.mock.test.js
+✔ PASS drinkAll > drinks something lemon-flavoured (1.300417ms)
+✔ PASS drinkAll > does not drink something octopus-flavoured (0.191791ms)
+✔ PASS drinkAll (1.842959ms)
+✔ PASS drinkEach > drinkEach drinks each drink (0.360625ms)
+✔ PASS drinkEach (0.463416ms)
+✔ PASS toHaveBeenCalledWith > registration applies correctly to orange La Croix (0.53325ms)
+✔ PASS toHaveBeenCalledWith (0.564166ms)
+✔ PASS toHaveBeenLastCalledWith > applying to all flavors does mango last (0.380375ms)
+✔ PASS toHaveBeenLastCalledWith (0.473417ms)
+# tests/jest/fn.invocationCallOrder.test.js
+✔ PASS mock.invocationCallOrder (4.221042ms)
+```
 
-Default `NODE_ENV` value is "test", use `NODE_ENV=` to override (e.g. to empty)
+#### GitHub Actions collapses test results per-file, like this:
+
+<details>
+ <summary>✅ <strong>tests/jest/lifecycle.test.js</strong></summary>
+ <pre>
+  ✔ PASS A > B > C (3.26166ms)
+  ✔ PASS A > B > D (1.699463ms)
+  ✔ PASS A > B (6.72719ms)
+  ✔ PASS A > E > F (1.117997ms)
+  ✔ PASS A > E > G > H (1.330904ms)
+  ✔ PASS A > E > G (1.94971ms)
+  ✔ PASS A > E (3.821825ms)
+  ✔ PASS A > I (0.533096ms)
+  ✔ PASS A (13.887889ms)
+  ✔ PASS J (0.373187ms)
+  ✔ PASS K > L (0.659852ms)
+  ✔ PASS K (1.143195ms)
+ </pre>
+</details><details>
+ <summary>✅ <strong>tests/jest/timers.async.test.js</strong></summary>
+ <pre>
+  ✔ PASS advanceTimersByTime() does not let microtasks to pass (5.326604ms)
+  ✔ PASS advanceTimersByTime() does not let microtasks to pass even with await (1.336064ms)
+  ✔ PASS advanceTimersByTimeAsync() lets microtasks to pass (6.99526ms)
+  ✔ PASS advanceTimersByTimeAsync() lets microtasks to pass, chained (10.131664ms)
+  ✔ PASS advanceTimersByTimeAsync() lets microtasks to pass, longer chained (8.635472ms)
+  ✔ PASS advanceTimersByTimeAsync() lets microtasks to pass, async chain (56.937983ms)
+ </pre>
+</details>
+
+See live output in [CI](https://github.com/ExodusMovement/test/actions/workflows/checks.yaml)
 
 ## 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)!
+### List of exports
 
-### Moving from jest
+- `@exodus/test/node` — `node:test` API, working under non-Node.js platforms
 
-```js
-import {
-  jest,
-  expect,
-  describe,
-  it,
-  beforeEach,
-  afterEach,
-  beforeAll,
-  afterAll,
-} from '@exodus/test/jest'
-```
+- `@exodus/test/jest` — `jest` implementation
 
-Or, run with [`--jest` option](#options) to register jest globals
+- `@exodus/test/tape` — `tape` mock (can also be helpful when moving from `tap`)
 
-### Moving from tap/tape
-
-```js
-import test from '@exodus/test/tap'
-```
+## Binary
 
-### Running tests asynchronously
+Just use `"test": "exodus-test"`
 
-Add `{ concurrency: true }`, like this: `describe('my testsuite', { concurrency: true }, () => {`
+### Options
 
-### List of exports
+- `--jest` — register jest test helpers as global variables, also load `jest.config.*` configuration options
 
-- `@exodus/test/jest` -- `jest` mock
+- `--esbuild` — use esbuild loader, also enables Typescript support
 
-- `@exodus/test/tape` -- `tape` mock (can also be helpful when moving from `tap`)
+- `--babel` — use babel loader (slower than `--esbuild`, makes sense if you have a special config)
 
-## Binary
+- `--coverage` — enable coverage, prints coverage output (varies by coverage engine)
 
-Just use `"test": "exodus-test"`
+- `--coverage-engine c8` — use c8 coverage engine (default), also generates `./coverage/` dirs
 
-### Options
+- `--coverage-engine node` — use Node.js builtint coverage engine
 
-- `--jest` -- register jest test helpers as global variables
+- `--watch` — operate in watch mode and re-run tests on file changes
 
-- `--typescript` -- use typescript loader (which also compiles esm to cjs where needed)
+- `--only` — only run the tests marked with `test.only`
 
-- `--esbuild` -- use esbuild loader (currently an alias for `--typescript`)
+- `--passWithNoTests` — do not error when no test files were found
 
-- `--babel` -- use babel loader (slower than `--esbuild`, makes sense if you have a special config)
+- `--write-snapshots` — write snapshots instead of verifying them (has `--test-update-snapshots` alias)
 
-- `--coverage` -- enable coverage, prints coverage output (varies by coverage engine)
+- `--test-force-exit` — force exit after tests are done
 
-- `--coverage-engine c8` -- use c8 coverage engine (default), also generates `./coverage/` dirs
+## Jest compatibility
 
-- `--coverage-engine node` -- use Node.js builtint coverage engine
+The `--jest` mode is mostly compatible with Jest. There are some noteworthy differences though.
+This tool does not hoist mocks, so it is important that a mock is defined before the module that uses it is imported.
+In ESM, this can be achieved with dynamic imports:
 
-- `--watch` -- operate in watch mode and re-run tests on file changes
+```js
+jest.doMock('./hogwarts.js', () => ({
+  __esModule: true,
+  default: jest.fn(),
+}))
+
+const { default: getEntryQualification } = await import('./hogwarts.js')
+const { qualifiesForHogwarts } = await import('./wizard.js') // module importing ./hogwarts.js
+
+test('qualifies for Hogwarts', () => {
+  // doSomething is a mock function
+  getEntryQualification.mockReturnValue(['lumos'])
+
+  expect(qualifiesForHogwarts('potter')).toBe(false)
+  getEntryQualification.mockReturnValue([])
+  expect(qualifiesForHogwarts('potter')).toBe(true)
+})
+```
 
-- `--passWithNoTests` -- do not error when no test files were found
+Note that all modules that transitively import `hogwarts.js` will have to be imported after the mock is defined.
 
-- `--write-snapshots` -- write snapshots instead of verifying them (has `--test-update-snapshots` alias)
+## License
 
-- `--test-force-exit` -- force exit after tests are done (useful in integration tests where it could be unfeasible to resolve all open handles)
+[MIT](./LICENSE)

package/bin/browsers.js

@@ -0,0 +1,137 @@
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { readFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { findBinary } from './find-binary.js'
+
+// See https://playwright.dev/docs/browsers
+// > Playwright doesn't work with the branded version of Firefox since it relies on patches.
+// > Playwright doesn't work with the branded version of Safari since it relies on patches.
+
+let puppeteer
+let playwright
+
+const puppeteerBrowsers = { brave: 'chrome', msedge: 'chrome' }
+const playwrightBrowsers = { chrome: 'chromium', msedge: 'chromium' }
+
+const launched = Object.create(null)
+const launchers = {
+  async puppeteer({ binary, devtools }) {
+    if (!puppeteer) puppeteer = await import('puppeteer-core')
+    const browser = Object.hasOwn(puppeteerBrowsers, binary) ? puppeteerBrowsers[binary] : binary
+    assert(['chrome', 'firefox'].includes(browser))
+    return puppeteer.launch({ executablePath: findBinary(binary), browser, devtools })
+  },
+  async playwright({ binary: channel, devtools }) {
+    if (!playwright) playwright = await import('playwright-core')
+    const type = Object.hasOwn(playwrightBrowsers, channel) ? playwrightBrowsers[channel] : channel
+    assert(['chromium', 'firefox', 'webkit'].includes(type) && Object.hasOwn(playwright, type))
+    return playwright[type].launch({ devtools, channel })
+  },
+}
+
+export const close = () => Promise.all(Object.values(launched).map((p) => p.then((b) => b.close())))
+
+async function newPage(runner, browser, { binary, dropNetwork }) {
+  const context = await (browser.newContext ? browser.newContext() : browser.createBrowserContext())
+  if (dropNetwork && context.setOffline && binary !== 'webkit') await context.setOffline(true) // WebKit crashes if this is done prior to navigation to /dev/null
+  let page
+  try {
+    page = await context.newPage()
+  } catch (err) {
+    // Puppeteer has a bug with Firefox, we expect that and just retry
+    if (runner !== 'puppeteer' || binary !== 'firefox' || err.name !== 'ProtocolError') throw err
+    await context.close()
+    return newPage(runner, browser, { binary, dropNetwork })
+  }
+
+  // Need to load a secure origin for e.g. crypto.subtle to be available
+  if (runner === 'playwright' && binary === 'webkit') {
+    // Can attempt to download /dev/null, so we apply a work-around
+    await page.route('https://www.secure-context-top-level-domain-for-tests/*', (route) =>
+      route.fulfill({
+        status: 200,
+        contentType: 'text/html; charset=utf-8',
+        body: '<!doctype html><html><body></body></html>',
+      })
+    )
+    await page.goto('https://www.secure-context-top-level-domain-for-tests/')
+  } else {
+    await page.goto('file:///dev/null')
+  }
+
+  if (dropNetwork && context.setOffline) await context.setOffline(true)
+  if (dropNetwork && page.setOfflineMode) await page.setOfflineMode(true)
+  assert(!dropNetwork || context.setOffline || page.setOfflineMode)
+  return { context, page }
+}
+
+export async function run(runner, args, { binary, devtools, dropNetwork, timeout, throttle }) {
+  assert(args.length === 1, 'Unexpected args to browser runner')
+
+  const bundle = await readFile(args[0], 'utf8')
+  let code = 0
+  const [stdout, stderr] = [[], []]
+
+  assert(Object.hasOwn(launchers, runner), 'Unexpected runner')
+  if (!launched[runner]) launched[runner] = launchers[runner]({ binary, devtools: !!devtools })
+  const { page, context } = await newPage(runner, await launched[runner], { binary, dropNetwork })
+
+  if (throttle) {
+    try {
+      const cdp = await (page.createCDPSession
+        ? page.createCDPSession()
+        : context.newCDPSession(page))
+      await cdp.send('Emulation.setCPUThrottlingRate', { rate: throttle })
+    } catch (cause) {
+      throw new Error(`${binary}:${runner} engine does not support --throttle-cpu`, { cause })
+    }
+  }
+
+  page.on('console', (message) => {
+    const type = message.type()
+    const target = type === 'error' ? stderr : stdout
+    target.push(message.text())
+  })
+  page.on('pageerror', (error) => {
+    if (!code) code = 1
+    stderr.push(`${error}`)
+  })
+
+  let timer
+  const promise = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      stderr.push('timeout reached')
+      resolve(1) // Error code
+    }, timeout)
+  })
+
+  const wait = async () => {
+    await page.evaluate(bundle)
+    return page.evaluate('globalThis.EXODUS_TEST_PROMISE')
+  }
+
+  try {
+    // exitCode might be undefined if we failed before EXODUS_TEST_PROMISE was set, but we will have code then
+    const exitCode = await Promise.race([wait(), promise])
+    code = code || exitCode
+    if (!Number.isInteger(code)) {
+      stderr.push('Browser test did not indicate completion. Terminating with a failure...')
+      code = 1
+    }
+
+    return { code, stdout: stdout.join('\n'), stderr: stderr.join('\n') }
+  } catch (error) {
+    return { code: 1, stdout: '', stderr: `${error}` }
+  } finally {
+    clearTimeout(timer)
+    await context.close()
+  }
+}
+
+export function runPlaywrightCommand(args) {
+  const playwright = dirname(fileURLToPath(import.meta.resolve('playwright-core/package.json')))
+  const cli = resolve(playwright, 'cli.js')
+  return spawnSync(cli, args, { stdio: 'inherit' })
+}

package/bin/color.js

@@ -0,0 +1,14 @@
+import { inspect } from 'node:util'
+
+const colors = new Map(Object.entries(inspect.colors))
+const { CI, FORCE_COLOR } = process.env
+const CI_COLORS = CI && !FORCE_COLOR /// when not overriden via FORCE_COLOR, assume CI has colors even though not a tty
+export const haveColors = CI_COLORS || process.stdout.hasColors?.() || FORCE_COLOR === '1' // 0 is already handled by hasColors()
+export const dim = CI ? 'gray' : 'dim'
+
+export const color = (text, color) => {
+  if (!haveColors || text === '') return text
+  if (!colors.has(color)) throw new Error(`Unknown color: ${color}`)
+  const [start, end] = colors.get(color)
+  return `\x1B[${start}m${text}\x1B[${end}m`
+}

package/bin/electron.js

@@ -0,0 +1,71 @@
+import { app, ipcMain, protocol, session, BrowserWindow } from 'electron'
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+
+const abort = (message) => {
+  if (message) console.error(message)
+  app.exit(1)
+}
+
+if (process.argv[1] !== import.meta.filename) abort('Unexpected launcher script')
+const files = process.argv.slice(2).map((f) => readFile(f, 'utf8'))
+
+// synchronous to ensure we don't miss anything
+ipcMain.on('print', (event, args) => {
+  console.log(...args)
+  event.returnValue = undefined // eslint-disable-line @exodus/mutable/no-param-reassign-prop-only
+})
+
+process.env.ELECTRON_DISABLE_SECURITY_WARNINGS = true // we don't want Electron CSP warnings
+process.on('unhandledRejection', (e) => abort(e))
+app.on('window-all-closed', () => abort('Window got closed'))
+
+protocol.registerSchemesAsPrivileged([
+  {
+    scheme: 'exodustest',
+    privileges: { standard: true, secure: true, supportFetchAPI: true }, // has to be standard + secure for crypto
+  },
+])
+
+const enableIntegration = process.env.EXODUS_TEST_ENGINE === 'electron:pure'
+const devtools = process.env.EXODUS_TEST_DEVTOOLS === '1'
+const preload = fileURLToPath(import.meta.resolve('./electron.preload.cjs'))
+const partition = 'tmp' // not persistent
+const securityPreferences = enableIntegration
+  ? { sandbox: false, contextIsolation: false, nodeIntegration: true }
+  : { sandbox: true, contextIsolation: true, preload }
+const webPreferences = { ...securityPreferences, partition, spellcheck: false }
+const html = '<!doctype html><html><body></body></html>'
+const headers = { 'content-type': 'text/html' }
+
+// eslint-disable-next-line unicorn/prefer-top-level-await
+app.whenReady().then(async () => {
+  const ses = session.fromPartition(partition)
+  ses.protocol.handle('exodustest', () => new Response(html, { headers }))
+  const win = new BrowserWindow({ show: devtools, webPreferences })
+  if (devtools) win.openDevTools()
+
+  await win.loadURL('exodustest://bundle/')
+  await win.webContents.executeJavaScript(`
+    const consoleKeys = ['log', 'error', 'warn', 'info', 'debug', 'trace']
+    for (const k of consoleKeys) {
+      if (!Object.hasOwn(console, k)) continue
+      const orig = console[k].bind(console)
+      const value = (...args) => { __test_print(...args); orig(...args) }
+      Object.defineProperty(console, k, { value })
+    }
+    ;0
+  `)
+
+  try {
+    for (const file of files) {
+      await win.webContents.executeJavaScript(`${await file};0`)
+      const code = await win.webContents.executeJavaScript('globalThis.EXODUS_TEST_PROMISE')
+      if (code !== 0) app.exit(typeof code === 'number' ? code : 1)
+    }
+  } catch (err) {
+    abort(err)
+  }
+
+  app.quit()
+})

package/bin/electron.preload.cjs

@@ -0,0 +1,2 @@
+const { contextBridge, ipcRenderer } = require('electron')
+contextBridge.exposeInMainWorld('__test_print', (...args) => ipcRenderer.sendSync('print', args))

package/bin/find-binary.js

@@ -0,0 +1,102 @@
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+const nvm = process.env.NVM_BIN ? (x) => join(process.env.NVM_BIN, '../lib/node_modules', x) : null
+const jsvu = (x) => join(homedir(), '.jsvu/bin', x)
+const esvu = (x) => join(homedir(), '.esvu/bin', x)
+
+// Can modify PATH to add the binary to it!
+function findBinaryOnce(name) {
+  // For browsers where full path is needed
+  const paths = []
+  const addPaths = (platform, ...args) => process.platform === platform && paths.push(...args)
+
+  // For js engines where we can fall back to the command name
+  const findFile = (methods, allowGlobal = true) => {
+    for (const x of methods) {
+      try {
+        const file = x(process.platform === 'win32' ? `${name}.exe` : name)
+        if (file && existsSync(file)) return file
+      } catch {}
+    }
+
+    if (!allowGlobal) {
+      console.error(`Local ${name} not installed, refusing to run`)
+      process.exit(1)
+    }
+
+    console.warn(`Local ${name} not installed, attempting to load global ${name}...`)
+    return name
+  }
+
+  switch (name) {
+    case 'hermes': {
+      const flavors = { darwin: 'osx-bin', linux: 'linux64-bin', win32: 'win64-bin' }
+      const flavor = Object.hasOwn(flavors, process.platform) ? flavors[process.platform] : null
+      return findFile([
+        (bin) => flavor && require.resolve(`react-native/sdks/hermesc/${flavor}/${bin}`), // 1. Locally installed react-native dep (works only for osx)
+        (bin) => flavor && require.resolve(`hermes-engine-cli/${flavor}/${bin}`), // 2. Locally installed hermes-engine-cli
+        (bin) => jsvu(bin), // 3. jsvu
+        (bin) => nvm(`hermes-engine-cli/${flavor}/${bin}`), // 4. hermes-engine-cli installed in .nvm dir with npm i -g
+      ]) // 5. hermes installed in the system
+    }
+
+    case 'jsc':
+      return findFile([
+        (bin) => jsvu(bin), // prefer jsvu
+        (bin) => esvu(bin),
+        (bin) => `/System/Library/Frameworks/JavaScriptCore.framework/Versions/A/Helpers/${bin}`,
+        (bin) => `/System/Library/Frameworks/JavaScriptCore.framework/Versions/A/Resources/${bin}`,
+      ])
+    case 'd8':
+      return findFile([() => jsvu('v8'), () => esvu('v8')]) // jsvu/esvu name it v8
+    case 'spidermonkey':
+    case 'quickjs':
+    case 'graaljs':
+    case 'escargot':
+    case 'boa': // not present in jsvu, esvu lacks aarch64-apple-darwin platform (as it's only in nightly)
+    case 'ladybird-js': // naming by esvu
+    case 'engine262':
+      return findFile([jsvu, esvu])
+    case 'xs':
+      return findFile([jsvu, esvu], false)
+    case 'electron':
+      return require('electron')
+    case 'c8':
+      return require.resolve('c8/bin/c8.js')
+    case 'chrome':
+      addPaths('darwin', '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome')
+      addPaths('linux', '/usr/bin/chromium', '/snap/bin/chromium', '/usr/bin/google-chrome')
+      break
+    case 'firefox':
+      addPaths('darwin', '/Applications/Firefox.app/Contents/MacOS/firefox')
+      addPaths('linux', '/usr/bin/firefox')
+      break
+    case 'brave':
+      addPaths('darwin', '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser')
+      addPaths('linux', '/usr/bin/brave', '/snap/bin/brave', '/opt/brave-bin/brave')
+      break
+    case 'msedge':
+      addPaths('darwin', '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge')
+      addPaths('linux', '/usr/bin/msedge', '/snap/bin/msedge', '/opt/microsoft/msedge/msedge')
+      break
+    case 'safari':
+      addPaths('darwin', '/Applications/Safari.app/Contents/MacOS/Safari')
+      break
+    default:
+      throw new Error('Trying to find an unexpected executable name')
+  }
+
+  for (const path of paths) if (existsSync(path)) return path
+  throw new Error(`Failed to find ${name} executable`)
+}
+
+const binaries = new Map()
+
+export function findBinary(name) {
+  if (!binaries.has(name)) binaries.set(name, findBinaryOnce(name))
+  return binaries.get(name)
+}

package/bin/inband.js

@@ -0,0 +1,14 @@
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { describe, after } from '../src/engine.js'
+
+const files = JSON.parse(process.env.EXODUS_TEST_INBAND)
+if (!Array.isArray(files)) throw new Error('Unexpected')
+
+for (const file of files.sort()) {
+  await describe(`EXODUS_TEST_INBAND:${file}`, async () => {
+    await import(pathToFileURL(resolve(file)))
+  })
+}
+
+if (globalThis.EXODUS_TEST_AFTER_INBAND) after(globalThis.EXODUS_TEST_AFTER_INBAND)