Todo framework de teste que você já usou, seja Jest, Mocha ou node:test, baseia-se em uma ideia simples: declare o que você espera e, em seguida, lance um erro se a realidade não concordar. O Node.js entrega essa ideia como um módulo integrado chamado assert. Sem instalação, sem dependência, basta usar require e começar a verificar suposições.
O módulo assert vale a pena ser conhecido por si só. Ele capacita verificações rápidas de sanidade em scripts, sustenta muitos executores de teste e ensina o que é uma asserção antes que qualquer framework a embeleze. Este guia cobre os métodos importantes, a distinção entre modo estrito e legado que confunde as pessoas, como fazer asserções sobre erros e código assíncrono, e como o mesmo módulo ajuda a validar respostas de API.
O que o módulo assert faz
Uma asserção é uma declaração que deve ser verdadeira para que seu programa seja considerado correto. Quando você escreve assert.strictEqual(total, 100), você está declarando que total deve ser igual a 100. Se for, nada acontece e a execução continua. Se não for, assert lança um AssertionError que interrompe a execução e informa o que deu errado.
Importe o módulo. A forma moderna e recomendada é a versão estrita:
const assert = require('node:assert/strict');
// ou com módulos ES:
// import assert from 'node:assert/strict';
A asserção mais simples verifica se um valor é verdadeiro (truthy):
const user = getUser(42);
assert(user, 'getUser deve retornar um objeto de usuário');
O primeiro argumento é o valor sendo testado. O segundo, opcional, é uma mensagem exibida quando a asserção falha. Sempre escreva essa mensagem. Uma falha que diz “getUser deve retornar um objeto de usuário” é muito mais útil do que um AssertionError simples. Entender asserções também ajuda quando você passa para asserções de API dedicadas em uma ferramenta de teste.
Modo estrito versus modo legado
Esta é a única coisa mais importante a fazer corretamente. O módulo assert tem dois modos.
O modo legado, que você obtém de require('node:assert'), usa igualdade flexível (==) para assert.equal e assert.deepEqual. Isso significa que assert.equal(1, '1') passa, porque 1 == '1' é verdadeiro em JavaScript. A igualdade flexível é uma fonte conhecida de bugs.
O modo estrito, que você obtém de require('node:assert/strict'), usa igualdade estrita (===) para tudo. assert.equal(1, '1') falha, como deveria, porque os tipos são diferentes.
const looseAssert = require('node:assert');
looseAssert.equal(1, '1'); // passa, surpreendente e perigoso
const strict = require('node:assert/strict');
strict.equal(1, '1'); // lança AssertionError, correto
Use o modo estrito. Não há uma boa razão para aceitar igualdade flexível em testes. O restante deste guia assume node:assert/strict, onde assert.equal se comporta de forma idêntica a assert.strictEqual.
Comparando valores: equal e strictEqual
assert.strictEqual(actual, expected) verifica se dois valores são idênticos usando ===. É o carro-chefe para primitivos como números, strings e booleanos.
const assert = require('node:assert/strict');
function priceWithTax(price, rate) {
return price + price * rate;
}
assert.strictEqual(priceWithTax(100, 0.08), 108, 'o cálculo do imposto deve adicionar 8 por cento');
assert.strictEqual(typeof priceWithTax(100, 0.08), 'number', 'o resultado deve ser um número');
Existe também assert.notStrictEqual, que passa quando os dois valores não são idênticos. Use-o para confirmar que um valor mudou:
const before = getCacheKey();
refreshCache();
const after = getCacheKey();
assert.notStrictEqual(before, after, 'a chave do cache deve mudar após a atualização');
Para objetos e arrays, strictEqual não ajudará. Dois literais de objeto com o mesmo conteúdo são referências diferentes, então === retorna falso. Para isso existe a igualdade profunda.
Comparando objetos: deepStrictEqual
assert.deepStrictEqual(actual, expected) compara estrutura e valores recursivamente. Dois objetos passam se cada chave contiver um valor estritamente igual, em todos os níveis.
const assert = require('node:assert/strict');
function buildOrder(id, items) {
return { id, items, status: 'pending' };
}
assert.deepStrictEqual(
buildOrder(7, ['keyboard', 'mouse']),
{ id: 7, items: ['keyboard', 'mouse'], status: 'pending' },
'o objeto do pedido deve corresponder à forma esperada'
);
Este é o método que você mais usará ao testar funções que retornam objetos, e especialmente ao testar respostas de API, já que os corpos JSON são objetos. Sua contraparte assert.notDeepStrictEqual passa quando as estruturas diferem.
Uma ressalva: deepStrictEqual também verifica os tipos. Uma propriedade que contém o número 7 não corresponderá a uma propriedade que contém a string '7'. Essa rigidez é um recurso; ela detecta desvios de tipo em seus dados. Se você está testando funções com muitas combinações de entrada, nosso guia sobre testes orientados por dados com CSV e JSON mostra como escalar asserções em conjuntos de dados.
Quando deepStrictEqual falha, o Node imprime uma diferença que destaca exatamente quais propriedades discordam. Essa diferença é uma das coisas mais úteis sobre o módulo. Em vez de olhar para dois objetos grandes tentando encontrar a diferença, você lê algumas linhas destacadas. Para dados aninhados, isso por si só justifica o uso de deepStrictEqual em vez de verificar manualmente cada campo com strictEqual.
Correspondência parcial com assert.match e assert.ok
Nem toda verificação precisa de igualdade total. Às vezes, você só se importa que um valor pareça aproximadamente correto. assert.ok(value) passa sempre que o valor é verdadeiro (truthy), o que é a ferramenta certa para verificações de "isso deve existir": uma string não vazia, um objeto definido, uma contagem diferente de zero.
assert.match(string, regexp) verifica se uma string corresponde a uma expressão regular, e assert.doesNotMatch verifica o oposto. Estes são úteis para valores cujo conteúdo exato varia, mas cuja forma é fixa.
const assert = require('node:assert/strict');
function generateOrderId() {
return 'ORD-' + Date.now();
}
const id = generateOrderId();
// o carimbo de data/hora exato muda, então afirme o formato, não o valor
assert.match(id, /^ORD-\d+$/, 'o ID do pedido deve ser ORD- seguido por dígitos');
assert.ok(id.length > 4, 'o ID do pedido não deve estar vazio');
Este padrão é importante especialmente para testes de API, onde as respostas contêm carimbos de data/hora, IDs gerados e tokens que você não pode prever. Você afirma o formato com match e a existência com ok, e reserva strictEqual para os valores que você realmente controla.
Afirmando que o código lança um erro
Às vezes, o comportamento correto significa lançar um erro. assert.throws(fn, expectedError) executa uma função e passa apenas se ela lançar um erro.
const assert = require('node:assert/strict');
function parsePort(value) {
const port = Number(value);
if (!Number.isInteger(port) || port < 1 || port > 65535) {
throw new RangeError('a porta deve ser um número inteiro entre 1 e 65535');
}
return port;
}
// passa: entrada inválida deve lançar um RangeError
assert.throws(
() => parsePort('70000'),
RangeError,
'porta fora do intervalo deve lançar RangeError'
);
// você também pode corresponder à mensagem de erro com uma regex
assert.throws(
() => parsePort('abc'),
/deve ser um número inteiro/,
'porta não numérica deve lançar um erro descritivo'
);
// passa: entrada válida não deve lançar erro
assert.doesNotThrow(
() => parsePort('8080'),
'uma porta válida não deve lançar erro'
);
Note que você passa uma função, não uma chamada. assert.throws(parsePort('70000')) executaria parsePort antes que assert a visse, e o erro escaparia sem ser capturado. Sempre a envolva: () => parsePort('70000').
Afirmando sobre código assíncrono: rejects
O código Node.js moderno está cheio de promessas, e uma promessa rejeitada é o equivalente assíncrono de um erro lançado. assert.rejects e assert.doesNotReject lidam com esse caso. Ambos retornam promessas, então você as await.
const assert = require('node:assert/strict');
async function fetchUser(id) {
if (typeof id !== 'number') {
throw new TypeError('o ID deve ser um número');
}
// ... a busca real aconteceria aqui
return { id, name: 'Dana Lee' };
}
async function runTests() {
// passa: entrada inválida rejeita com um TypeError
await assert.rejects(
fetchUser('not-a-number'),
TypeError,
'ID de string deve rejeitar'
);
// passa: entrada válida resolve sem rejeitar
await assert.doesNotReject(
fetchUser(101),
'ID válido deve resolver corretamente'
);
}
runTests();
Esquecer de usar await em uma chamada assert.rejects é um erro comum. Sem await, a função de teste termina antes que a asserção seja resolvida, e uma falha se torna uma rejeição não tratada em vez de um erro de teste claro.
Usando assert para testar respostas de API
O módulo assert é realmente útil para verificar a saída de uma requisição HTTP. Depois de buscar um endpoint, você tem um código de status e um corpo JSON, e ambos são coisas sobre as quais você pode fazer asserções.
const assert = require('node:assert/strict');
async function testGetUser() {
const res = await fetch('https://api.example.com/users/101');
// verifica o código de status
assert.strictEqual(res.status, 200, 'GET /users/101 deve retornar 200');
const body = await res.json();
// verifica a forma e os tipos da resposta
assert.strictEqual(typeof body.id, 'number', 'o ID deve ser um número');
assert.strictEqual(body.id, 101, 'o ID deve corresponder ao usuário solicitado');
assert.ok(body.name, 'a resposta deve incluir um nome');
assert.ok(Array.isArray(body.roles), 'roles deve ser um array');
}
testGetUser().then(
() => console.log('Teste de API passou'),
(err) => { console.error('Teste de API falhou:', err.message); process.exitCode = 1; }
);
Este padrão funciona e ensina os fundamentos. Mas para um pacote de testes de API real, você desejará execuções estruturadas, retentativas, manipulação de ambiente e relatórios que o assert puro não oferece. Nossos guias sobre como escrever scripts de teste automatizados e o framework de automação de API pytest cobrem esse próximo passo.
Se você preferir não construir um sistema de teste manualmente, o Apidog permite definir requisições de API e anexar asserções visuais em códigos de status, cabeçalhos e campos JSON sem escrever nenhum código de asserção. Você pode encadear requisições em cenários de teste automatizados, executá-los em CI/CD e ainda recorrer a scripts personalizados quando precisar do controle que o assert oferece. É um caminho mais rápido de “Tenho um endpoint” para “Tenho um pacote de testes”, e você pode baixar o Apidog e usá-lo gratuitamente. Juntamente com o Apidog, o módulo assert do Node.js cobre tanto verificações rápidas quanto pacotes completos.
Perguntas frequentes
Preciso instalar o módulo assert?
Não. O assert é integrado ao Node.js. Importe-o com require('node:assert/strict') ou require('node:assert'). Não há pacote npm para instalar e nenhuma dependência para gerenciar. O prefixo node: torna explícito que você está carregando um módulo central.
Qual a diferença entre assert.equal e assert.strictEqual?
No modo legado, assert.equal usa igualdade flexível (==) e assert.strictEqual usa igualdade estrita (===). No modo estrito, carregado via node:assert/strict, assert.equal se comporta de forma idêntica a assert.strictEqual. Sempre use o modo estrito para que a coerção de tipo nunca passe um teste silenciosamente.
Quando devo usar deepStrictEqual em vez de strictEqual?
Use strictEqual para primitivos: números, strings, booleanos. Use deepStrictEqual para objetos e arrays, porque strictEqual compara referências e dois objetos separados nunca são referencialmente iguais. Sempre que você fizer uma asserção em um corpo JSON ou em um objeto retornado, use deepStrictEqual.
Devo usar o módulo assert ou um framework de teste como o Jest?
Para scripts rápidos e aprendizado, o assert puro é bom. Para um pacote de testes real, use um framework. O Node.js também vem com um executor de testes integrado, node:test, que combina naturalmente com o assert e oferece organização de testes, relatórios e paralelismo sem uma dependência externa.
Como faço para afirmar que uma função assíncrona rejeita?
Use assert.rejects e lembre-se de usar await. Passe a promessa ou uma chamada de função assíncrona, opcionalmente com um tipo de erro esperado ou regex de mensagem. assert.rejects(somePromise, TypeError) passa apenas se a promessa for rejeitada com um TypeError. Sem await, uma falha se torna uma rejeição não tratada em vez de um erro de asserção claro.