# Runner setup: Vitest, Jest and `node:test`

Verified 2026-09 against <https://vitest.dev/config/>, <https://jestjs.io/docs/configuration>,
<https://nodejs.org/api/test.html> and <https://docs.nestjs.com/migration-guide>.

## 1. Choosing

| | Vitest 5 | Jest 30 | `node:test` |
|---|---|---|---|
| ESM and TypeScript | Native, no transform config | Needs `ts-jest` or `@swc/jest`; ESM still needs care | Runs `*.test.ts` directly via type stripping (recent Node) |
| Speed | Fast watch, parallel by default | Slower start-up | Fastest to start, no dependencies |
| Ecosystem | Jest-compatible API, large | Largest | Small |
| Coverage | Built in (v8 or istanbul) | Built in | `--experimental-test-coverage` — still experimental |
| Snapshots | Yes | Yes | Stable since Node 23.4 |
| Pick for | New ESM services, NestJS 12 ESM projects | Existing CommonJS suites | Libraries and small services that want zero test dependencies |

Do not migrate a healthy Jest suite for speed alone — the migration cost lands on the whole team and
the payoff is seconds per run. Do pick Vitest for anything new.

## 2. Vitest

```ts
// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: false,                       // explicit imports read better in a service
    environment: 'node',
    globalSetup: ['./tests/global-setup.ts'],
    setupFiles: ['./tests/setup.ts'],     // per-worker: MSW server, matchers
    restoreMocks: true,
    coverage: { provider: 'v8', reporter: ['text', 'lcov'], include: ['src/**'] },
  },
});
```

`pool` defaults to `'forks'` and has since Vitest 2 — you do not need to opt in for native
dependencies. Switch to `'threads'` only to chase speed in a suite with no native addons, and
measure it.

`globalSetup` runs once per run (containers, migrations); `setupFiles` runs once per worker (MSW,
matchers). Putting container start-up in `setupFiles` starts one container per worker, which is the
usual cause of "the test suite eats my laptop".

Monorepo: one config per package, listed centrally, so the whole repository runs with one command.

```ts
// vitest.config.ts at the root
export default defineConfig({
  test: { projects: ['apps/*', 'packages/*'] },
});
```

## 3. Jest

```ts
// jest.config.ts
import type { Config } from 'jest';

const config: Config = {
  testEnvironment: 'node',
  transform: { '^.+\\.tsx?$': ['@swc/jest', {}] },
  globalSetup: '<rootDir>/tests/global-setup.ts',
  setupFilesAfterEnv: ['<rootDir>/tests/setup.ts'],
  restoreMocks: true,
  collectCoverageFrom: ['src/**/*.ts'],
};

export default config;
```

`@swc/jest` is much faster than `ts-jest` and does not type-check — which is correct, because
`tsc --noEmit` already does that in its own CI step. Running the type checker twice slows every test
run to buy nothing.

For ESM under Jest, `extensionsToTreatAsEsm` plus `NODE_OPTIONS=--experimental-vm-modules` is the
supported path, and it remains fiddly. If a project needs ESM and is on Jest, that is the moment to
consider Vitest rather than to fight the configuration.

## 4. `node:test`

```bash
node --test                                   # runs **/*.test.ts, types stripped
node --test --experimental-test-coverage
node --test --test-concurrency=4
```

```ts
import assert from 'node:assert/strict';
import { after, before, describe, it } from 'node:test';

describe('order totals', () => {
  it('adds line items', () => {
    assert.equal(total([{ price: 10, qty: 2 }]), 20);
  });
});
```

Snapshot testing is stable since Node 23.4 (`t.assert.snapshot(value)`), which removes one of the
main reasons teams reached for Jest. Coverage is still marked experimental, so treat the numbers as
indicative rather than as a gate.

Because type stripping only erases, TypeScript syntax that emits code — `enum`, parameter properties,
namespaces — will not run. Set `"erasableSyntaxOnly": true` in `tsconfig.json`
(`nodejs-development` §2) so that is a compile error rather than a runtime surprise in CI.

## 5. NestJS 12 under ESM

```ts
import { Test } from '@nestjs/testing';
import { beforeEach, expect, it } from 'vitest';

let app: INestApplication;

beforeEach(async () => {
  const moduleRef = await Test.createTestingModule({ imports: [OrdersModule] })
    .overrideProvider(PaymentGateway)
    .useValue({ charge: async () => ({ id: 'ch_1', status: 'authorised' as const }) })
    .compile();

  app = moduleRef.createNestApplication();
  await app.init();
});
```

Two ESM details to get right: relative imports carry the `.js` extension, and `reflect-metadata` must
be imported once in the setup file before any decorated class loads. `.overrideProvider` is the right
seam for a fake — reaching for `vi.mock` on a Nest provider fights the container instead of using it.

## 6. Finding open handles

Each runner has its own flag, and the wrong one silently does nothing:

| Runner | Flag | What it tells you |
|---|---|---|
| Jest | `--detectOpenHandles` | A stack trace for each handle keeping the process alive |
| Vitest | `--reporter=hanging-process` | What is still open when the run should have ended |
| `node:test` | `--test-force-exit` | Exits anyway — a workaround, not a diagnosis |

The cause is almost always the same short list: an HTTP server not closed (`await app.close()`), a
database pool or Redis client not closed in `afterAll`, or an `setInterval` without `.unref()`. Fix
the leak rather than forcing the exit; a handle held in tests is usually a handle held in production.
