\n\nTests are scripts. Not a framework.\n\nWrite tests in TypeScript, run with `node test.ts`.\n\nNo runner, no overhead — just **16 kB**.\n\n```sh\n$ node ./tests/index.ts\n\n12:34:56 ✔ adds numbers\n12:34:56 ✔ async operation (52ms)\n12:34:56 ✔ Auth › login succeeds\n12:34:56 ✔ Auth › logout clears session\n12:34:56 ✖ broken test\n\n523ms\n4 passed\n1 failed\n```\n\n`✔` passed · `✖` failed · `○` skipped · `•` pending (process exited before test finished)\n\n## Install\n\n```sh\nnpm i -D manten\n```\n\n## Why manten?\n\n### No runner, just Node\n\nTest files are plain scripts — run them directly:\n\n```sh\nnode tests/index.ts\n```\n\nNo file discovery, no config files, no abstraction layers. Node.js startup time, nothing more.\n\n### You already know the API\n\nsequential = `await`\n\nconcurrent = Remove `await`\n\nThat's the entire concurrency model.\n\n```ts\nawait test('first', async () => { /* ... */ }) // waits\n\ntest('second', async () => { /* ... */ }) // runs immediately\n\ntest('third', async () => { /* ... */ }) // runs with second\n```\n\n> [!TIP]\n> Prefer concurrent by default. Only `await` to enforce ordering. Since Node.js won't exit while promises are settling, you don't actually need to `await` anything.\n\n### Standalone imports\n\nEvery API is a standalone import — no callback destructuring:\n\n```ts\nimport {\n test, describe, expect, skip, onTestFinish\n} from 'manten'\n```\n\nEach function automagically knows which test or group it belongs to.\n\n### Tiny\n\nOne dependency ([`expect`](https://www.npmjs.com/package/expect) for assertions — swap it for any assertion library).\n\n## Quick start\n\n```ts\n// tests/index.ts\nimport { test, expect } from 'manten'\n\ntest('adds numbers', () => {\n expect(1 + 1).toBe(2)\n})\n\ntest('async operation', async () => {\n const result = await fetchData()\n expect(result).toBeDefined()\n})\n```\n\n```sh\nnode tests/index.ts\n```\n\n> [!TIP]\n> Node.js 22.6+ runs TypeScript natively — no loaders needed.\n\n## Core concepts\n\n### Async flow control\n\nTests execute immediately when `test()` is called. Use `await` to control ordering:\n\n```ts\n// Sequential\nawait test('step 1', async () => { /* ... */ })\nawait test('step 2', async () => { /* ... */ }) // runs after step 1\n\n// Concurrent\ntest('independent A', async () => { /* ... */ })\ntest('independent B', async () => { /* ... */ }) // runs with A\n```\n\n### Grouping with describe\n\n```ts\nimport { describe, test } from 'manten'\n\nawait describe('Auth', () => {\n test('login', async () => { /* ... */ }) // Auth › login\n test('logout', async () => { /* ... */ }) // Auth › logout\n})\n\n// Runs after both Auth tests complete\ntest('next', () => { /* ... */ })\n```\n\nAwaiting a group waits for all children. Groups nest infinitely.\n\n### Splitting tests across files\n\nImport files inside `describe()` — their tests automatically nest under the parent group:\n\n```ts\n// tests/index.ts\nimport { describe } from 'manten'\n\ndescribe('my-app', async () => {\n import('./auth.ts')\n import('./api.ts')\n import('./utils.ts')\n\n // Or add `await` to run files sequentially\n})\n```\n\n```ts\n// tests/auth.ts\nimport { describe, test, expect } from 'manten'\n\ndescribe('Authentication', () => {\n test('login', () => { /* ... */ })\n test('logout', () => { /* ... */ })\n test('refresh token', () => { /* ... */ })\n})\n// Output: my-app › Authentication › login\n// my-app › Authentication › logout\n// my-app › Authentication › refresh token\n```\n\nEach file works standalone too — `node tests/auth.ts` runs just that file. The entry point is your test runner, written in plain JavaScript.\n\n### Parameterized test files\n\nTo pass data into a test file, export a function that wraps a `describe()`:\n\n```ts\n// tests/specs/builds.ts\nimport { describe, test, expect } from 'manten'\n\nexport const builds = (nodePath: string) => describe('builds', () => {\n test('compiles', async () => {\n const result = await run(nodePath)\n expect(result.exitCode).toBe(0)\n })\n})\n```\n\nSince the `describe()` doesn't run until the function is called, these can be statically imported:\n\n```ts\n// tests/index.ts\nimport { builds } from './specs/builds.ts'\nimport { errors } from './specs/errors.ts'\nimport { describe } from 'manten'\n\ndescribe('my-app', async () => {\n for (const nodeVersion of ['v20', 'v22', 'v24']) {\n const node = await getNode(nodeVersion)\n await describe(`Node ${node.version}`, () => {\n builds(node.path)\n errors(node.path)\n })\n }\n})\n```\n\n### Recommended project structure\n\n```\ntests/\n index.ts # entry point — run this\n specs/ # test files\n utils/ # shared test helpers\n fixtures/ # static test data\n```\n\nUse a single `index.ts` entry point that imports all test files. This gives you one command to run everything and enables `node --watch` across all files.\n\n### Watch mode\n\n```sh\nnode --watch tests/index.ts\n```\n\nBuilt into [Node.js](https://nodejs.org/api/cli.html#--watch) (stable since v22). Watches all imported files — change any test file and tests re-run automatically. This is why a single entry point matters: one command watches your entire test suite.\n\n## Features\n\n### Timeouts & abort signals\n\nPass a timeout (ms) as the third argument. The test receives an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) for cooperative cancellation:\n\n```ts\ntest('fetch with timeout', async ({ signal }) => {\n await fetch('https://api.example.com', { signal })\n}, 5000)\n```\n\nFor multi-step tests, use [`signal.throwIfAborted()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/throwIfAborted) between operations. Combine with your own signals using [`AbortSignal.any()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/any_static).\n\n### Retries\n\n```ts\ntest('flaky API', async () => {\n await unreliableAPI()\n}, {\n timeout: 5000,\n retry: 3\n})\n```\n\nOutput shows which attempt succeeded: `✔ flaky API (2/3)`.\n\n### Hooks\n\n```ts\nimport { test, onTestFail, onTestFinish } from 'manten'\n\ntest('with cleanup', async () => {\n const resource = await acquire()\n onTestFinish(() => resource.cleanup()) // runs after test (pass or fail)\n onTestFail(error => console.log('Debug:', error))\n})\n```\n\n`onFinish` runs after all tests in a `describe()`:\n\n```ts\nimport { describe, test, onFinish } from 'manten'\n\ndescribe('Database', async () => {\n const database = await connect()\n onFinish(() => database.close())\n\n test('query', () => { /* ... */ })\n})\n```\n\n### Skipping\n\n```ts\nimport { test, skip } from 'manten'\n\ntest('linux only', () => {\n if (process.platform !== 'linux') {\n skip('Only runs on Linux')\n }\n // ...\n})\n```\n\nSkip entire groups — `skip()` must be called before any `test()` or nested `describe()`:\n\n```ts\ndescribe('GPU tests', () => {\n if (!hasGPU) {\n skip('GPU not available')\n }\n test('render shader', () => { /* ... */ }) // all skipped\n})\n```\n\n### Snapshot testing\n\n```ts\nimport { test, expectSnapshot } from 'manten'\n\ntest('user state', () => {\n // Named (recommended) — order-independent\n expectSnapshot(getUser(), 'initial state')\n\n // Auto-numbered — keys become \"user state 1\", \"user state 2\", etc.\n expectSnapshot(getUser())\n expectSnapshot(getPermissions())\n})\n```\n\nSnapshots are stored in `.manten.snap`. Update with `MANTEN_UPDATE_SNAPSHOTS=1 node tests/index.ts`. Without named snapshots, reordering `expectSnapshot()` calls breaks comparisons.\n\n> [!WARNING]\n> Snapshots are serialized with [`util.inspect`](https://nodejs.org/api/util.html#utilinspectobject-options), which may produce different output across Node.js versions. If snapshots fail after upgrading Node, re-run with `MANTEN_UPDATE_SNAPSHOTS=1` to regenerate.\n\n### Concurrency limiting\n\n```ts\ndescribe('Database tests', () => {\n test('query 1', async () => { /* ... */ })\n test('query 2', async () => { /* ... */ })\n test('query 3', async () => { /* ... */ })\n}, { parallel: 2 }) // max 2 concurrent\n```\n\nOptions:\n- `false` (sequential)\n- `true` (unbounded)\n- `number` (limit)\n- `'auto'` (adapts to CPU load)\n\nTests that you explicitly `await` run immediately, bypassing the parallel queue — useful for setup/teardown steps within a parallel group.\n\n### Group timeouts\n\n```ts\ndescribe('API suite', () => {\n test('endpoint 1', async () => { /* ... */ })\n test('endpoint 2', async () => { /* ... */ })\n}, { timeout: 10_000 })\n```\n\nIndividual test timeouts still apply — whichever is stricter wins.\n\n### Process timeout\n\nPrevent stuck processes in CI:\n\n```ts\nimport { setProcessTimeout } from 'manten'\n\nsetProcessTimeout(10 * 60 * 1000) // kill after 10 minutes\n```\n\n### Filtering\n\nRun specific tests by substring match (case-sensitive). Matches against the full title including describe prefixes:\n\n```sh\nTESTONLY='login' node tests/index.ts\nTESTONLY='Auth' node tests/index.ts # matches \"Auth › login\", \"Auth › logout\", etc.\n```\n\n## API\n\n### test(name, fn, timeoutOrOptions?)\n\nCreate and run a test. `fn` always receives `{ signal }` — an `AbortSignal` that aborts on timeout or when the parent group is aborted.\n\n- `timeoutOrOptions`: `number | { timeout?: number, retry?: number }`\n- Returns: `Promise`\n\n### describe(name, fn, options?)\n\nCreate a test group. `fn` always receives `{ signal }` — an `AbortSignal` that aborts on timeout or when the parent group is aborted.\n\n- `options`: `{ parallel?: boolean | number | 'auto', timeout?: number }`\n- Returns: `Promise`\n\n### expect(value)\n\nJest's [`expect`](https://jestjs.io/docs/expect). Or use [Node.js Assert](https://nodejs.org/api/assert.html), [Chai](https://www.chaijs.com/), etc.\n\n### expectSnapshot(value, name?)\n\nCompare against a stored snapshot. Creates one if none exists. Test names must be unique across all files — duplicates throw an error.\n\n### onTestFail(callback) · onTestFinish(callback)\n\nHooks for the current test. Must be called within `test()`. Hook errors are logged but don't fail the test.\n\n### onFinish(callback)\n\nCleanup hook for the current `describe()` group. Errors are logged and set `process.exitCode = 1`.\n\n### skip(reason?)\n\nSkip the current test or describe group.\n\n### setProcessTimeout(ms)\n\nGlobal timeout for the entire process.\n\n### configure(options)\n\n`{ snapshotPath?: string }` — must be called before any `expectSnapshot()`. Also configurable via `MANTEN_SNAPSHOT_PATH` and `MANTEN_UPDATE_SNAPSHOTS` env vars.\n\n## TypeScript\n\nManten is written in TypeScript. All APIs are fully typed, and `Test`/`Describe` types are exported for advanced use cases.\n\n## FAQ\n\n### What does manten mean?\n\nManten (まんてん, 満点) means \"maximum points\" or 100% in Japanese.\n\n### Why no test runner?\n\nNo runner = zero overhead. No file discovery, no spawning processes, no config. Tests are scripts — run them however you want.\n\n### Why no beforeAll/beforeEach?\n\nManten runs tests concurrently by default. Shared setup hooks don't compose with concurrent execution. Inline setup in each test, or use `describe()` + `onFinish()` for shared resources.\n\n### How does manten report failures to CI?\n\nWhen a test fails, manten sets `process.exitCode = 1` but doesn't force-exit. All remaining tests run to completion, and the final report prints on the `exit` event. CI systems pick up the non-zero exit code automatically.\n\n## Related\n\n### [fs-fixture](https://github.com/privatenumber/fs-fixture)\n\nCreate disposable file system fixtures for testing. Pairs naturally with manten's hooks:\n\n```ts\nimport { createFixture } from 'fs-fixture'\nimport { test, expect } from 'manten'\n\ntest('reads config', async () => {\n await using fixture = await createFixture({\n 'package.json': JSON.stringify({ name: 'my-app' }),\n 'src/index.js': 'export default 42'\n })\n\n const result = await readPackageJson(fixture.path)\n expect(result.name).toBe('my-app')\n}) // fixture auto-cleaned up when test scope exits\n```\n\n## Sponsors\n\n
![](\".github/logo.png\"){kind=logo}
\n \n![](\"https://cdn.jsdelivr.net/gh/privatenumber/sponsors/sponsorkit/sponsors.svg\")
\n\t\n