# @exodus/test
[](https://npmjs.org/package/@exodus/test)
[](https://github.com/ExodusOSS/test/releases)
[](https://github.com/ExodusOSS/test/blob/HEAD/LICENSE)
[](https://github.com/ExodusOSS/test/actions/workflows/checks.yml?query=branch%3Amain)
[](https://github.com/ExodusOSS/test/stargazers)
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:
[](https://nodejs.org/api/test.html)
[](https://deno.com/)
[](https://bun.sh/)
[](http://electronjs.org/)
[](https://github.com/cloudflare/workerd)\
[](https://www.chromium.org/Home/)
[](http://webkit.org/)
[](https://github.com/mozilla-firefox)
[](https://github.com/brave)
[](https://github.com/microsoftedge)
[](https://servo.org/)\
[](https://hermesengine.dev)
[](https://v8.dev/docs/d8)
[](https://docs.webkit.org/Deep%20Dive/JSC/JavaScriptCore.html)
[](https://spidermonkey.dev/)\
[](https://github.com/quickjs-ng/quickjs)
[](https://github.com/Moddable-OpenSource/moddable)
[](https://github.com/oracle/graaljs)
[](https://github.com/boa-dev/boa)
[](https://github.com/trynova/nova)
[](https://github.com/Samsung/escargot)
[](https://github.com/engine262/engine262)
Compatible with tests written in:
[](#using-with-nodetest-tests)
[](#migrating-from-jest)
[](#migrating-from-tape)
See [documentation](https://exodusoss.github.io/test/).
## Features
- Zero learning curve: runs your existing tests
- Runs anywhere (including Hermes, the [React Native](https://reactnative.dev/) JavaScript engine)
- Native ESM, including in Jest tests
- Esbuild on the fly for old faux-ESM interop (enable via `--esbuild`)
- TypeScript support
- Use snapshots to cross-compare between runtimes, browsers and barebones (including Hermes)
- 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 on Bun. \
Without this, Bun leaks globals / side effects between test files ([ref](https://github.com/oven-sh/bun/issues/6024)),
and has incompatible `test()` lifecycle / order
## Getting started
First install with `npm install --save-dev @exodus/test` (or with your favorite package manager)
Then, add this to `package.json` scripts (or see [engines example](https://github.com/ExodusOSS/bytes/blob/v1.11.0/package.json#L25-L42)):
```json
"test": "exodus-test"
```
That's it. It works zero-config.
See [Options](#options) to change defaults, e.g. to enable Jest globals with `--jest`.
To use [Engines](#engines) on CI, see e.g. GitHub CI config of [@exodus/bytes](https://github.com/ExodusOSS/bytes/blob/main/.github/workflows/test.yml).
### Using with node:test tests
You don't need to change the tests or any extra configuration on top of [Getting started](#getting-started).
It just works out of the box, and on Node.js native `node:test` is used under the hood.
Using this script is similar to `node --test`:
```json
"test": "exodus-test"
```
But, unlike bare `node --test` it supports [engines](#engines) and the [GitHub CI reporter](#github-actions).
### Migrating from Jest
Use this in `package.json` scripts:
```json
"test": "exodus-test --jest"
```
If that doesn't work (e.g. some deps are faux-ESM), add `--esbuild` to transpile those:
```json
"test": "exodus-test --jest --esbuild"
```
To adjust module mocks for native ESM support, see [Module mocking in ESM](#module-mocking-in-esm).
Some complex setups with React Native don't work yet.
### Migrating from tape
Use this in `package.json` scripts:
```json
"test": "exodus-test"
```
Great! Now your tape tests run on top of `node:test`, and are also runnable in browsers / barebone [engines](#engines).
> [!TIP]
> You can optionally replace `tape` imports with `@exodus/test/tape`
> to be able to be individually run them with just `node ./path-to-file.js`:
>
> ```js
> import test from '@exodus/test/tape' // ESM
> const test = require('@exodus/test/tape') // CJS
> ```
## 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.
- `workerd:bundle` — [Cloudflare Workers runtime (workerd)](https://github.com/cloudflare/workerd), expects `workerd` package to be installed
- 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
- Bundle
- `servo:bundle` — Servo (expects it to be installed in the system)
- Barebone engines (system-provided or installed with `npx jsvu` / `npx esvu`):
- `v8: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` — [Moddable XS](https://github.com/Moddable-OpenSource/moddable)
- `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)
- `nova:bundle` — [Nova](https://github.com/trynova/nova) (note that Nova itself is a Work In Progress)
- `engine262:bundle` - [engine262](https://github.com/engine262/engine262), the per-spec implementation of ECMA-262
(install with [esvu](https://npmjs.com/package/esvu))
## Options
- `--jest` — register jest test helpers as global variables, also load `jest.config.*` configuration options
- `--esbuild` — use esbuild loader, also enables Typescript support on old Node.js
- `--typescript` — enable Typescript type stripping (only needed on older Node.js versions which don't have it natively)
- `--babel` — use babel loader (slower than `--esbuild`, makes sense if you have a special config)
- `--coverage` — enable coverage, prints coverage output (varies by coverage engine)
- `--coverage-engine c8` — use c8 coverage engine (default), also generates `./coverage/` dirs
- `--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
- `--engine` — specify one of [Engines](#engines) to run on
## Reporter samples
### CLI
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)
```
### GitHub Actions
Collapses test results per-file, like this:
✅ tests/jest/lifecycle.test.js
✔ 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)
✅ tests/jest/timers.async.test.js
✔ 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)
See live output in [CI](https://github.com/ExodusOSS/test/actions/workflows/checks.yaml)
## Module mocking in ESM
Module mocks in ESM is a common source of confusion, as Jest in most old setups does not run real ESM,
and instead uses Babel to transform ESM into CJS, and then hoists mocks on top of `require()` calls.
That hoisting is not possible in ESM world, as static import statements are always resolved before
any other code.
Also see [Jest documentation](https://jestjs.io/docs/ecmascript-modules#module-mocking-in-esm) on that.
To port code from CJS or Babel, e.g. the following approach with dynamic imports can be used:
```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)
})
```
Note that all modules that transitively import `hogwarts.js` will have to be imported after the mock is defined.
## License
[MIT](./LICENSE)