Org Skills

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

Supporting material for nodejs-testing. Agents load it on demand; it ships inside the skill folder.

RawSource

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

// 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.

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

3. Jest

// 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

node --test                                   # runs **/*.test.ts, types stripped
node --test --experimental-test-coverage
node --test --test-concurrency=4
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

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.