The Node.js Built-in Test Runner: Why You Can Drop Jest and Mocha Today

You have a package.json with jest, ts-jest, @types/jest, jest.config.ts, babel-jest, and a drawer full of transformers because Jest cannot read ESM or TypeScript without half a megabyte of plugins. You are not alone. Every Node.js project eventually collects this tax.

The question nobody asks is: why are you installing a third-party test runner when Node ships with one that works?

Since Node 20, the built-in test runner (node:test) and assertion library (node:assert) have been stable. They handle synchronous tests, asynchronous tests, subtests, mocking, code coverage, TypeScript (via --experimental-strip-types or tsx), and CI output formats like TAP and JUnit. No config file required.

This post walks through the migration from Jest to node:test with real code, covers the API surface you will use every day, and calls out the handful of scenarios where a third-party runner still wins.

What you get for zero config

Create a file called test/add.test.js:

const { describe, it } = require('node:test');
const assert = require('node:assert/strict');

describe('addition', () => {
  it('adds two numbers', () => {
    assert.equal(1 + 1, 2);
  });
});

Run it:

node --test

That is it. Node discovers files matching **/*.test.* (or **/*.spec.* or **/test/**), runs them, and prints a pass/fail summary. No test script in package.json needed, though you will probably add one for convenience.

Compare the Jest equivalent:

{
  "devDependencies": {
    "jest": "^29.0.0",
    "@types/jest": "^29.0.0",
    "ts-jest": "^29.0.0",
    "babel-jest": "^29.0.0",
    "@babel/preset-env": "^7.0.0",
    "@babel/preset-typescript": "^7.0.0"
  },
  "jest": {
    "transform": {
      "^.+\\.tsx?$": "ts-jest"
    }
  }
}

Six dependencies, a config block, and three Babel presets just to run expect(1 + 1).toBe(2) in TypeScript. The Node test runner needs zero config for JavaScript and one flag for TypeScript.

The API surface you will actually use

describe and it

Identical semantics to Jest and Mocha. Subtests are first-class: a failing it inside a describe does not abort sibling tests.

const { describe, it } = require('node:test');

describe('DatabaseService', () => {
  it('connects to postgres', async () => {
    // ...
  });

  it('rejects invalid config', () => {
    // ...
  });
});

Assertions with node:assert/strict

Jest uses expect() with matchers like toBe, toEqual, toThrow. Node uses assert.strictEqual, assert.deepStrictEqual, and assert.throws. They are less fluent but equally capable.

const assert = require('node:assert/strict');

// Exact equality (===)
assert.strictEqual(result.count, 42);

// Deep equality (recursive)
assert.deepStrictEqual(result, { id: 1, name: 'Alice' });

// Throws
assert.throws(() => validate(-1), { name: 'ValidationError' });

// Rejects (promise version of throws)
await assert.rejects(
  () => db.query('INVALID SQL'),
  /syntax error/i
);

// Does not throw
assert.doesNotThrow(() => sanitize(input));

If you miss the Jest chainable API, you can install node:assert wrappers from npm (like expect from @jest/globals works with node:test), but I have found the strict-mode asserts read fine once you adjust.

Subtests for setup/teardown isolation

This is where node:test shines over Mocha. Each it block can nest subtests, and each subtest inherits the parent context without sharing state:

const { describe, it, beforeEach } = require('node:test');
const assert = require('node:assert/strict');

describe('ShoppingCart', () => {
  let cart;

  beforeEach(() => {
    cart = new ShoppingCart();
  });

  it('starts empty', () => {
    assert.strictEqual(cart.items.length, 0);
  });

  it('adds items', () => {
    cart.add('apple');
    assert.strictEqual(cart.items.length, 1);
  });

  it('calculates total', async (t) => {
    cart.add('apple', 2);
    cart.add('banana', 3);

    await t.test('with discount', () => {
      assert.strictEqual(cart.total({ discount: 0.1 }), 4.5);
    });

    await t.test('without discount', () => {
      assert.strictEqual(cart.total(), 5.0);
    });
  });
});

The t.test() form in the last block creates subtests that share the parent’s setup but have independent pass/fail reporting. This is cleaner than Mocha’s shared this context or Jest’s nested describe blocks.

Mocks, spies, and timers

Node 22+ ships mock as part of node:test. For Node 20-21, use MockTimers and MockTracker from node:test:

const { describe, it, mock } = require('node:test');
const assert = require('node:assert/strict');

describe('PaymentService', () => {
  it('retries on timeout', async () => {
    const retry = mock.fn(() => { throw new Error('timeout'); });

    const service = new PaymentService({ retry });
    await assert.rejects(() => service.charge(100), /timeout/);
    assert.strictEqual(retry.mock.calls.length, 3);
  });

  it('respects concurrency limits', { concurrency: true }, async () => {
    // Tests in this block run in parallel
  });
});

Timers:

const { describe, it, mock } = require('node:test');
const assert = require('node:assert/strict');

describe('RateLimiter', () => {
  it('blocks after threshold', () => {
    mock.timers.enable({ apis: ['setTimeout', 'Date'] });

    const limiter = new RateLimiter({ max: 3, windowMs: 1000 });

    limiter.hit('user-1'); // hit 1
    limiter.hit('user-1'); // hit 2
    limiter.hit('user-1'); // hit 3
    assert.strictEqual(limiter.blocked('user-1'), true);

    mock.timers.tick(1000);
    assert.strictEqual(limiter.blocked('user-1'), false);

    mock.timers.reset();
  });
});

Test filters and watch mode

# Run only tests matching a pattern
node --test --test-name-pattern="retry"

# Run a single file
node --test test/payment.test.js

# Watch mode (Node 22+)
node --test --watch

Running TypeScript tests

This is the area that changed most between Node 20 and 22. Here is the current state:

Node 22+ with --experimental-strip-types

node --experimental-strip-types --test

Node strips TypeScript type annotations without type-checking and runs the result. No tsx, no ts-node, no build step. It is fast — the stripping happens at the parser level, not via transpilation.

Node 20-21 with tsx

npx tsx --test

The tsx package (a thin wrapper around esbuild) works perfectly as a loader for node:test. Install it as a devDependency and use:

{
  "scripts": {
    "test": "tsx --test"
  }
}

Mixed project (JS + TS files)

node --experimental-strip-types --test --test-concurrency=4

Node’s test runner handles both .js and .ts files in the same run. Jest requires separate transform configs.

Code coverage

Coverage is built in via Node’s V8 coverage integration:

node --experimental-test-coverage --test

Output looks like this:

▶ DatabaseService
  ✔ connects to postgres
  ✔ rejects invalid config
▶ ShoppingCart
  ✔ starts empty
  ✔ adds items
  ✔ calculates total
ℹ tests 5
ℹ pass 5
ℹ fail 0
ℹ duration 42ms

ℹ coverage lines: 89.1% (312/350)
ℹ coverage functions: 92.3% (48/52)
ℹ coverage branches: 85.7% (78/91)
ℹ coverage statements: 89.1% (312/350)

For CI, generate C8-compatible output:

node --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage/lcov.info

The LCOV file works with Coveralls, Codecov, and SonarQube. No nyc or c8 dependency required.

CI integration

Here is a GitHub Actions workflow that uses the built-in test runner end-to-end:

name: Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: node --test
      - run: node --experimental-test-coverage --test

Four lines of actual test execution. No Jest config, no coverage tool, no reporters to install.

For JUnit XML (Atlassian, GitLab):

node --test --test-reporter=junit --test-reporter-destination=test-results.xml

For TAP (tap-compatible dashboards):

node --test --test-reporter=tap

Edge cases where you still want a third-party runner

The built-in test runner covers 90% of real use cases. Here is the 10% where it falls short today.

1. Snapshot testing

Jest’s toMatchSnapshot() has no built-in equivalent in node:test. You can approximate it with a custom assertion that writes and compares fixture files, but the workflow is manual. If your project relies heavily on snapshot testing (React component tests, API response snapshots), you may want to keep Jest or add the jest-snapshot package alongside node:test.

2. Browser-like DOM testing

If you are testing React components with @testing-library/react, you need Jest or Vitest because they provide JSDOM integration out of the box. The Node test runner operates in a pure Node environment. You can wire up globalThis with happy-dom or JSDOM manually, but it is friction.

3. Large test suites with parallel sharding

Jest’s --shard flag lets you distribute test execution across multiple CI runners. Node’s built-in runner supports concurrency within a process (--test-concurrency=8) but does not natively shard across machines. You can work around it with --test-name-pattern and manual CI matrix logic, but it is not as clean.

4. Custom reporters and matchers

The ecosystem of Jest matchers (toBeInTheDocument, toBeLessThan, toContainEqual) is large. The Node test runner supports custom reporters via the --test-reporter flag, but the ecosystem is new. If your team depends on a specific custom matcher library, check whether it has a node:test adapter before switching.

A real migration: Jest to node:test

Here is a concrete migration of a typical service test. Before:

// test/user-service.test.ts (Jest)
import { describe, it, expect, beforeEach, jest } from '@jest/globals';
import { UserService } from '../src/user-service';

describe('UserService', () => {
  let service: UserService;

  beforeEach(() => {
    service = new UserService();
  });

  it('creates a user', async () => {
    const user = await service.create({ email: 'a@b.com' });
    expect(user.id).toBeDefined();
    expect(user.email).toBe('a@b.com');
  });

  it('rejects duplicate emails', async () => {
    await service.create({ email: 'a@b.com' });
    await expect(service.create({ email: 'a@b.com' }))
      .rejects.toThrow('duplicate email');
  });

  it('calls the audit logger', async () => {
    const log = jest.spyOn(audit, 'log').mockResolvedValue();
    await service.create({ email: 'a@b.com' });
    expect(log).toHaveBeenCalledWith('user.created', expect.any(String));
  });
});

After:

// test/user-service.test.ts (node:test with tsx)
import { describe, it, beforeEach, mock } from 'node:test';
import assert from 'node:assert/strict';
import { UserService } from '../src/user-service';

describe('UserService', () => {
  let service: UserService;

  beforeEach(() => {
    service = new UserService();
  });

  it('creates a user', async () => {
    const user = await service.create({ email: 'a@b.com' });
    assert.ok(user.id);
    assert.strictEqual(user.email, 'a@b.com');
  });

  it('rejects duplicate emails', async () => {
    await service.create({ email: 'a@b.com' });
    await assert.rejects(
      () => service.create({ email: 'a@b.com' }),
      /duplicate email/
    );
  });

  it('calls the audit logger', async () => {
    const log = mock.method(audit, 'log', () => Promise.resolve());
    await service.create({ email: 'a@b.com' });
    assert.strictEqual(log.mock.calls.length, 1);
    assert.strictEqual(log.mock.calls[0].arguments[0], 'user.created');
  });
});

The structural changes:

1. @jest/globals imports become node:test imports.
2. expect() chains become assert.strictEqual, assert.ok, assert.rejects.
3. jest.spyOn().mockResolvedValue() becomes mock.method().
4. No ts-jest config, no jest.config.ts, no @types/jest.

The performance argument

Jest has a reputation for being slow, especially on large monorepos. The startup overhead alone — loading Babel transforms, resolving module mocks, building the test graph — can be 5-15 seconds on a project with 50+ test files.

Node’s test runner loads nothing by default. A node --test on a project with 100 test files typically starts emitting results within 500ms. No warmup. No transform cache. Just the files and the runtime.

Here are numbers from a real project with 87 test files (mixed JS and TS, running via tsx):

Runner	Cold start	Full suite	Peak memory
Jest 29 (with ts-jest)	8.2s	34.1s	520 MB
Vitest 1.x	2.1s	31.4s	490 MB
node:test (with tsx)	0.6s	29.8s	310 MB

Cold start is the biggest win. In CI, that 7-second difference on every push adds up fast. In local development, it means you run tests more often because the feedback loop is shorter.

Migration checklist

When moving an existing project, follow this order:

1. Install tsx (npm install -D tsx) if you use TypeScript.
2. Create one .test.ts file using node:test and node:assert/strict to verify the runner works.
3. Run npx tsx --test and confirm the output format.
4. Configure the CI workflow to use node --test instead of npx jest.
5. Migrate test files one directory at a time using the pattern above.
6. Remove Jest dependencies from package.json only after every test file is migrated.
7. Remove jest.config.ts and any @types/jest references.
8. Run node --experimental-test-coverage --test and compare coverage with your previous tool. They should be within 1-2%.

When not to migrate

If your project has any of these characteristics, the migration cost may not be worth it:

• Thousands of snapshot tests with no easy conversion path.
• Heavy use of Jest’s custom matcher ecosystem (DOM testing, styled-components, etc.).
• A CI pipeline that relies on Jest’s sharding across 10+ parallel runners.
• Tests that depend on Jest’s module mocking (jest.mock('module')) to intercept CommonJS modules at the require level. Node’s mock.module() is available experimentally in Node 22 but not as mature.

For everything else — which is the majority of backend services, libraries, CLIs, and data pipelines — the built-in runner is faster, simpler, and one less dependency to audit.

---

A note from Yojji

Shipping reliable software means reducing the layers between your code and the runtime. Every extra dependency is a surface area for breakage, security advisories, and configuration drift. The Node.js built-in test runner eliminates an entire category of those dependencies without sacrificing test quality. Yojji, an international custom software development company founded in 2016, builds production backend systems for clients across Europe, the US, and the UK. Their engineering teams work extensively with Node.js, TypeScript, and cloud platforms (AWS, Azure, Google Cloud), and they favor tooling that stays out of the way and ships with the runtime.