node:test & node:assert

Node 24 ships a native test runner and assertion module so unit tests run without Jest or Vitest for pure backend logic.

Recipe

Quick-reference recipe card - copy-paste ready.

import assert from "node:assert/strict";
import { describe, it } from "node:test";
 
describe("math", () => {
  it("adds", () => {
    assert.equal(1 + 1, 2);
  });
});

node --import tsx --test

When to reach for this:

• Pure functions, parsers, and domain logic.
• You want zero test-runner dependencies.
• Libraries that must not force Jest on consumers.

Working Example

// src/pricing/discount.ts
export function applyDiscount(cents: number, percent: number): number {
  if (percent < 0 || percent > 100) throw new Error("invalid percent");
  return Math.round(cents * (1 - percent / 100));
}

// test/pricing/discount.test.ts
import assert from "node:assert/strict";
import { describe, it } from "node:test";
 
import { applyDiscount } from "../../src/pricing/discount.js";
 
describe("applyDiscount", () => {
  it("reduces price by percentage", () => {
    assert.equal(applyDiscount(1000, 10), 900);
  });
 
  it("throws on invalid percent", () => {
    assert.throws(() => applyDiscount(1000, -1), /invalid percent/);
  });
});

{
  "scripts": {
    "test": "node --import tsx --test --test-reporter spec"
  }
}

What this demonstrates:

• ESM imports with .js extensions for NodeNext compatibility.
• assert.throws validates error paths without a mocking library.
• --test-reporter spec gives readable CI output.

Deep Dive

How It Works

• node:test discovers *.test.ts files (or explicit paths) and runs in parallel by default.
• Hooks: before, after, beforeEach, afterEach at describe scope.
• node:assert/strict throws AssertionError on mismatch (deep equal uses === rules for primitives).
• Subtests via it nesting or test.context() for fine-grained grouping.

Assertion Helpers

TypeScript Notes

node --import tsx --test

• tsx loader compiles TypeScript on the fly for dev and CI.
• Production deploy still uses tsc build; tests are not shipped.

Gotchas

• No built-in mock/spy ergonomics - Verbose without node:test/mock (Node 22+). Fix: use mock.fn() from node:test or add Vitest for heavy mocking.
• Parallel tests sharing global state - Flaky failures. Fix: describe(..., { concurrency: 1 }) or isolate state per test.
• Missing tsx in CI - Raw node --test fails on .ts. Fix: devDependency tsx and --import tsx.
• Import path .ts in tests - Breaks ESM resolution. Fix: import .js paths matching emit layout.
• Snapshot testing absent - No Jest snapshots. Fix: assert explicit fields or adopt Vitest for snapshot needs.

Alternatives

FAQs

node --import tsx --test test/pricing/discount.test.ts

import { mock } from "node:test";
const fn = mock.fn(() => 42);

node --import tsx --experimental-test-coverage --test

Related

• Testing Basics - pyramid overview
• Vitest - when you need mocks and watch
• Supertest & HTTP Integration - HTTP layer tests

External Related Links

• Node.js API Documentation - Complete reference for core modules and APIs.
• Node.js GitHub Repository - Source code, issues, contribution guides.
• Node.js Best Practices (GitHub) - Curated production best practices.
• Node.js Design Patterns, 4th Edition - Production-grade application patterns.
• Node.js Cookbook, 5th Edition - Practical server-side recipes.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.