node:test & node:assert

O Node 24 lança um runner de testes nativo e um módulo de asserção para que testes unitários rodem sem Jest ou Vitest para lógica de backend pura.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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

Quando usar isso:

• Funções puras, parsers e lógica de domínio.
• Você quer zero dependências de runner de teste.
• Bibliotecas que não devem forçar Jest nos consumidores.

Exemplo de Trabalho

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

O que isso demonstra:

• Importações ESM com extensões .js para compatibilidade NodeNext.
• assert.throws valida caminhos de erro sem uma biblioteca de mock.
• --test-reporter spec fornece saída legível para CI.

Mergulho Profundo

Como Funciona

• node:test descobre arquivos *.test.ts (ou caminhos explícitos) e executa em paralelo por padrão.
• Hooks: before, after, beforeEach, afterEach no escopo do describe.
• node:assert/strict lança AssertionError em caso de incompatibilidade (deep equal usa regras === para primitivos).
• Subtestes via aninhamento de it ou test.context() para agrupamento granular.

Auxiliares de Asserção

Notas de TypeScript

node --import tsx --test

• O loader tsx compila TypeScript na hora para desenvolvimento e CI.
• A implantação de produção ainda usa a compilação tsc; os testes não são enviados.

Armadilhas

• Sem ergonomia de mock/spy embutida - Verboso sem node:test/mock (Node 22+). Correção: use mock.fn() de node:test ou adicione Vitest para mocks pesados.
• Testes paralelos compartilhando estado global - Falhas intermitentes. Correção: describe(..., { concurrency: 1 }) ou isolar o estado por teste.
• Falta de tsx na CI - node --test puro falha em .ts. Correção: dependência de desenvolvimento tsx e --import tsx.
• Caminho de importação .ts em testes - Quebra a resolução ESM. Correção: importar caminhos .js que correspondam ao layout de emissão.
• Teste de snapshot ausente - Sem snapshots do Jest. Correção: afirmar campos explícitos ou adotar Vitest para necessidades de snapshot.

Alternativas

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

Relacionados

• Noções Básicas de Teste - visão geral da pirâmide
• Vitest - quando você precisa de mocks e watch
• Supertest & Integração HTTP - testes de camada HTTP

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.