iDoc.dev

Português

English
简体中文
Español
Français
Deutsch
Italiano
日本語
한국어
Русский
العربية

Português

English
简体中文
Español
Français
Deutsch
Italiano
日本語
한국어
Русский
العربية

Tema

Assert ​

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 2 - Estável

Código Fonte: lib/assert.js

O módulo node:assert fornece um conjunto de funções de asserção para verificar invariantes.

Modo de asserção estrita ​

[Histórico]

VersãoMudanças
v15.0.0Exposto como require('node:assert/strict').
v13.9.0, v12.16.2Alterado "modo estrito" para "modo de asserção estrita" e "modo legado" para "modo de asserção legado" para evitar confusão com o significado mais usual de "modo estrito".
v9.9.0Adicionadas diferenças de erro ao modo de asserção estrita.
v9.9.0Adicionado modo de asserção estrita ao módulo assert.
v9.9.0Adicionado em: v9.9.0

No modo de asserção estrita, os métodos não estritos se comportam como seus métodos estritos correspondentes. Por exemplo, assert.deepEqual() se comportará como assert.deepStrictEqual().

No modo de asserção estrita, as mensagens de erro para objetos exibem uma diferença. No modo de asserção legado, as mensagens de erro para objetos exibem os objetos, muitas vezes truncados.

Para usar o modo de asserção estrita:

js
import { strict as assert } from 'node:assert'
js
const assert = require('node:assert').strict
js
import assert from 'node:assert/strict'
js
const assert = require('node:assert/strict')

Exemplo de diferença de erro:

js
import { strict as assert } from 'node:assert'

assert.deepEqual([[[1, 2, 3]], 4, 5], [[[1, 2, '3']], 4, 5])
// AssertionError: Espera-se que as entradas sejam estritamente iguais em profundidade:
// + atual - esperado ... Linhas ignoradas
//
//   [
//     [
// ...
//       2,
// +     3
// -     '3'
//     ],
// ...
//     5
//   ]
js
const assert = require('node:assert/strict')

assert.deepEqual([[[1, 2, 3]], 4, 5], [[[1, 2, '3']], 4, 5])
// AssertionError: Espera-se que as entradas sejam estritamente iguais em profundidade:
// + atual - esperado ... Linhas ignoradas
//
//   [
//     [
// ...
//       2,
// +     3
// -     '3'
//     ],
// ...
//     5
//   ]

Para desativar as cores, use as variáveis de ambiente NO_COLOR ou NODE_DISABLE_COLORS. Isso também desativará as cores no REPL. Para mais informações sobre suporte a cores em ambientes de terminal, leia a documentação tty getColorDepth().

Modo de asserção legado ​

O modo de asserção legado usa o operador == em:

Para usar o modo de asserção legado:

js
import assert from 'node:assert'
js
const assert = require('node:assert')

O modo de asserção legado pode ter resultados surpreendentes, especialmente ao usar assert.deepEqual():

js
// AVISO: Isso não lança um AssertionError no modo de asserção legado!
assert.deepEqual(/a/gi, new Date())

Classe: assert.AssertionError ​

Indica a falha de uma asserção. Todos os erros lançados pelo módulo node:assert serão instâncias da classe AssertionError.

new assert.AssertionError(options) ​

Adicionado em: v0.1.21

  • options <Object>
    • message <string> Se fornecido, a mensagem de erro é definida para este valor.
    • actual <any> A propriedade actual na instância do erro.
    • expected <any> A propriedade expected na instância do erro.
    • operator <string> A propriedade operator na instância do erro.
    • stackStartFn <Function> Se fornecido, o stack trace gerado omite os frames anteriores a esta função.

Uma subclasse de Error que indica a falha de uma asserção.

Todas as instâncias contêm as propriedades Error internas (message e name) e:

  • actual <any> Definido como o argumento actual para métodos como assert.strictEqual().
  • expected <any> Definido como o valor expected para métodos como assert.strictEqual().
  • generatedMessage <boolean> Indica se a mensagem foi gerada automaticamente (true) ou não.
  • code <string> O valor é sempre ERR_ASSERTION para mostrar que o erro é um erro de asserção.
  • operator <string> Definido como o valor do operador passado.
js
import assert from 'node:assert'

// Gere um AssertionError para comparar a mensagem de erro mais tarde:
const { message } = new assert.AssertionError({
  actual: 1,
  expected: 2,
  operator: 'strictEqual',
})

// Verifique a saída de erro:
try {
  assert.strictEqual(1, 2)
} catch (err) {
  assert(err instanceof assert.AssertionError)
  assert.strictEqual(err.message, message)
  assert.strictEqual(err.name, 'AssertionError')
  assert.strictEqual(err.actual, 1)
  assert.strictEqual(err.expected, 2)
  assert.strictEqual(err.code, 'ERR_ASSERTION')
  assert.strictEqual(err.operator, 'strictEqual')
  assert.strictEqual(err.generatedMessage, true)
}
js
const assert = require('node:assert')

// Gere um AssertionError para comparar a mensagem de erro mais tarde:
const { message } = new assert.AssertionError({
  actual: 1,
  expected: 2,
  operator: 'strictEqual',
})

// Verifique a saída de erro:
try {
  assert.strictEqual(1, 2)
} catch (err) {
  assert(err instanceof assert.AssertionError)
  assert.strictEqual(err.message, message)
  assert.strictEqual(err.name, 'AssertionError')
  assert.strictEqual(err.actual, 1)
  assert.strictEqual(err.expected, 2)
  assert.strictEqual(err.code, 'ERR_ASSERTION')
  assert.strictEqual(err.operator, 'strictEqual')
  assert.strictEqual(err.generatedMessage, true)
}

Classe: assert.CallTracker ​

[Histórico]

VersãoMudanças
v20.1.0A classe assert.CallTracker foi descontinuada e será removida em uma versão futura.
v14.2.0, v12.19.0Adicionado em: v14.2.0, v12.19.0

[Estável: 0 - Descontinuado]

Estável: 0 Estabilidade: 0 - Descontinuado

Este recurso foi descontinuado e será removido em uma versão futura. Considere usar alternativas como a função auxiliar mock.

new assert.CallTracker() ​

Adicionado em: v14.2.0, v12.19.0

Cria um novo objeto CallTracker que pode ser usado para rastrear se as funções foram chamadas um número específico de vezes. O tracker.verify() deve ser chamado para que a verificação ocorra. O padrão usual seria chamá-lo em um manipulador process.on('exit').

js
import assert from 'node:assert'
import process from 'node:process'

const tracker = new assert.CallTracker()

function func() {}

// callsfunc() deve ser chamada exatamente 1 vez antes de tracker.verify().
const callsfunc = tracker.calls(func, 1)

callsfunc()

// Chama tracker.verify() e verifica se todas as funções tracker.calls() foram
// chamadas o número exato de vezes.
process.on('exit', () => {
  tracker.verify()
})
js
const assert = require('node:assert')
const process = require('node:process')

const tracker = new assert.CallTracker()

function func() {}

// callsfunc() deve ser chamada exatamente 1 vez antes de tracker.verify().
const callsfunc = tracker.calls(func, 1)

callsfunc()

// Chama tracker.verify() e verifica se todas as funções tracker.calls() foram
// chamadas o número exato de vezes.
process.on('exit', () => {
  tracker.verify()
})

tracker.calls([fn][, exact]) ​

Adicionado em: v14.2.0, v12.19.0

Espera-se que a função de wrapper seja chamada exatamente exact vezes. Se a função não tiver sido chamada exatamente exact vezes quando tracker.verify() for chamado, então tracker.verify() lançará um erro.

js
import assert from 'node:assert'

// Cria o rastreador de chamadas.
const tracker = new assert.CallTracker()

function func() {}

// Retorna uma função que envolve func() que deve ser chamada o número exato de vezes
// antes de tracker.verify().
const callsfunc = tracker.calls(func)
js
const assert = require('node:assert')

// Cria o rastreador de chamadas.
const tracker = new assert.CallTracker()

function func() {}

// Retorna uma função que envolve func() que deve ser chamada o número exato de vezes
// antes de tracker.verify().
const callsfunc = tracker.calls(func)

tracker.getCalls(fn) ​

Adicionado em: v18.8.0, v16.18.0

js
import assert from 'node:assert'

const tracker = new assert.CallTracker()

function func() {}
const callsfunc = tracker.calls(func)
callsfunc(1, 2, 3)

assert.deepStrictEqual(tracker.getCalls(callsfunc), [{ thisArg: undefined, arguments: [1, 2, 3] }])
js
const assert = require('node:assert')

// Cria um rastreador de chamadas.
const tracker = new assert.CallTracker()

function func() {}
const callsfunc = tracker.calls(func)
callsfunc(1, 2, 3)

assert.deepStrictEqual(tracker.getCalls(callsfunc), [{ thisArg: undefined, arguments: [1, 2, 3] }])

tracker.report() ​

Adicionado em: v14.2.0, v12.19.0

  • Retorna: <Array> Um array de objetos contendo informações sobre as funções wrapper retornadas por tracker.calls().
  • Objeto <Object>
    • message <string>
    • actual <number> O número real de vezes que a função foi chamada.
    • expected <number> O número de vezes que a função deveria ser chamada.
    • operator <string> O nome da função que está sendo envolvida.
    • stack <Object> Um rastreamento de pilha da função.

O array contém informações sobre o número esperado e real de chamadas das funções que não foram chamadas o número esperado de vezes.

js
import assert from 'node:assert'

// Cria um rastreador de chamadas.
const tracker = new assert.CallTracker()

function func() {}

// Retorna uma função que envolve func() que deve ser chamada o número exato de vezes
// antes de tracker.verify().
const callsfunc = tracker.calls(func, 2)

// Retorna um array contendo informações sobre callsfunc()
console.log(tracker.report())
// [
//  {
//    message: 'Esperava-se que a função func fosse executada 2 vez(es), mas foi
//    executada 0 vez(es).',
//    actual: 0,
//    expected: 2,
//    operator: 'func',
//    stack: rastreamento de pilha
//  }
// ]
js
const assert = require('node:assert')

// Cria um rastreador de chamadas.
const tracker = new assert.CallTracker()

function func() {}

// Retorna uma função que envolve func() que deve ser chamada o número exato de vezes
// antes de tracker.verify().
const callsfunc = tracker.calls(func, 2)

// Retorna um array contendo informações sobre callsfunc()
console.log(tracker.report())
// [
//  {
//    message: 'Esperava-se que a função func fosse executada 2 vez(es), mas foi
//    executada 0 vez(es).',
//    actual: 0,
//    expected: 2,
//    operator: 'func',
//    stack: rastreamento de pilha
//  }
// ]

tracker.reset([fn]) ​

Adicionado em: v18.8.0, v16.18.0

  • fn <Function> uma função rastreada para redefinir.

Redefine as chamadas do rastreador de chamadas. Se uma função rastreada for passada como argumento, as chamadas serão redefinidas para ela. Se nenhum argumento for passado, todas as funções rastreadas serão redefinidas.

js
import assert from 'node:assert'

const tracker = new assert.CallTracker()

function func() {}
const callsfunc = tracker.calls(func)

callsfunc()
// O rastreador foi chamado uma vez
assert.strictEqual(tracker.getCalls(callsfunc).length, 1)

tracker.reset(callsfunc)
assert.strictEqual(tracker.getCalls(callsfunc).length, 0)
js
const assert = require('node:assert')

const tracker = new assert.CallTracker()

function func() {}
const callsfunc = tracker.calls(func)

callsfunc()
// O rastreador foi chamado uma vez
assert.strictEqual(tracker.getCalls(callsfunc).length, 1)

tracker.reset(callsfunc)
assert.strictEqual(tracker.getCalls(callsfunc).length, 0)

tracker.verify() ​

Adicionado em: v14.2.0, v12.19.0

Itera pela lista de funções passadas para tracker.calls() e lançará um erro para funções que não foram chamadas o número esperado de vezes.

js
import assert from 'node:assert'

// Cria o rastreador de chamadas.
const tracker = new assert.CallTracker()

function func() {}

// Retorna uma função que envolve func() que deve ser chamada exatamente vezes
// antes de tracker.verify().
const callsfunc = tracker.calls(func, 2)

callsfunc()

// Lançará um erro, pois callsfunc() foi chamada apenas uma vez.
tracker.verify()
js
const assert = require('node:assert')

// Cria o rastreador de chamadas.
const tracker = new assert.CallTracker()

function func() {}

// Retorna uma função que envolve func() que deve ser chamada exatamente vezes
// antes de tracker.verify().
const callsfunc = tracker.calls(func, 2)

callsfunc()

// Lançará um erro, pois callsfunc() foi chamada apenas uma vez.
tracker.verify()

assert(value[, message]) ​

Adicionado em: v0.5.9

Um alias de assert.ok().

assert.deepEqual(actual, expected[, message]) ​

[Histórico]

VersãoMudanças
v22.2.0, v20.15.0A causa do erro e as propriedades de erros agora também são comparadas.
v18.0.0A propriedade lastIndex de expressões regulares agora também é comparada.
v16.0.0, v14.18.0No modo de asserção Legado, o status foi alterado de Descontinuado para Legado.
v14.0.0NaN agora é tratado como idêntico se ambos os lados forem NaN.
v12.0.0As tags de tipo agora são comparadas corretamente e há alguns pequenos ajustes de comparação para tornar a verificação menos surpreendente.
v9.0.0Os nomes e mensagens de Error agora são comparados corretamente.
v8.0.0O conteúdo de Set e Map também é comparado.
v6.4.0, v4.7.1Fatias de matrizes tipadas agora são tratadas corretamente.
v6.1.0, v4.5.0Objetos com referências circulares podem ser usados como entradas agora.
v5.10.1, v4.4.3Trata corretamente matrizes tipadas não-Uint8Array.
v0.1.21Adicionado em: v0.1.21

Modo de asserção estrita

Um alias de assert.deepStrictEqual().

Modo de asserção legado

[Estável: 3 - Legado]

Estável: 3 Estabilidade: 3 - Legado: Use assert.deepStrictEqual() em vez disso.

Testa a igualdade profunda entre os parâmetros actual e expected. Considere usar assert.deepStrictEqual() em vez disso. assert.deepEqual() pode ter resultados surpreendentes.

Igualdade profunda significa que as propriedades "próprias" enumeráveis de objetos filhos também são avaliadas recursivamente pelas seguintes regras.

Detalhes da Comparação ​

  • Valores primitivos são comparados com o operador ==, com a exceção de NaN. Ele é tratado como idêntico caso ambos os lados sejam NaN.
  • Tags de tipo de objetos devem ser as mesmas.
  • Apenas propriedades enumeráveis "próprias" são consideradas.
  • Nomes de Error, mensagens, causas e erros são sempre comparados, mesmo que não sejam propriedades enumeráveis.
  • Wrappers de objetos são comparados tanto como objetos quanto como valores desembrulhados.
  • Propriedades de Object são comparadas sem ordem.
  • Chaves de Map e itens de Set são comparados sem ordem.
  • A recursão para quando ambos os lados diferem ou ambos os lados encontram uma referência circular.
  • A implementação não testa o [[Prototype]] de objetos.
  • Propriedades de Symbol não são comparadas.
  • A comparação de WeakMap e WeakSet não depende de seus valores, mas apenas de suas instâncias.
  • RegExp RegExp lastIndex, flags e source são sempre comparados, mesmo que não sejam propriedades enumeráveis.

O exemplo a seguir não lança um AssertionError porque os primitivos são comparados usando o operador ==.

js
import assert from 'node:assert'
// AVISO: Isso não lança um AssertionError!

assert.deepEqual('+00000000', false)
js
const assert = require('node:assert')
// AVISO: Isso não lança um AssertionError!

assert.deepEqual('+00000000', false)

Igualdade "profunda" significa que as propriedades "próprias" enumeráveis de objetos filhos também são avaliadas:

js
import assert from 'node:assert'

const obj1 = {
  a: {
    b: 1,
  },
}
const obj2 = {
  a: {
    b: 2,
  },
}
const obj3 = {
  a: {
    b: 1,
  },
}
const obj4 = { __proto__: obj1 }

assert.deepEqual(obj1, obj1)
// OK

// Valores de b são diferentes:
assert.deepEqual(obj1, obj2)
// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }

assert.deepEqual(obj1, obj3)
// OK

// Protótipos são ignorados:
assert.deepEqual(obj1, obj4)
// AssertionError: { a: { b: 1 } } deepEqual {}
js
const assert = require('node:assert')

const obj1 = {
  a: {
    b: 1,
  },
}
const obj2 = {
  a: {
    b: 2,
  },
}
const obj3 = {
  a: {
    b: 1,
  },
}
const obj4 = { __proto__: obj1 }

assert.deepEqual(obj1, obj1)
// OK

// Valores de b são diferentes:
assert.deepEqual(obj1, obj2)
// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }

assert.deepEqual(obj1, obj3)
// OK

// Protótipos são ignorados:
assert.deepEqual(obj1, obj4)
// AssertionError: { a: { b: 1 } } deepEqual {}

Se os valores não forem iguais, um AssertionError é lançado com uma propriedade message definida como igual ao valor do parâmetro message. Se o parâmetro message for indefinido, uma mensagem de erro padrão é atribuída. Se o parâmetro message for uma instância de um Error, então ele será lançado em vez do AssertionError.

assert.deepStrictEqual(actual, expected[, message]) ​

[Histórico]

VersãoMudanças
v22.2.0, v20.15.0A causa do erro e as propriedades de erros agora também são comparadas.
v18.0.0A propriedade lastIndex das expressões regulares agora também é comparada.
v9.0.0As propriedades de símbolo enumeráveis agora são comparadas.
v9.0.0O NaN agora é comparado usando a comparação SameValueZero.
v8.5.0Os nomes e mensagens do Error agora são comparados corretamente.
v8.0.0O conteúdo do Set e Map também é comparado.
v6.1.0Objetos com referências circulares agora podem ser usados como entradas.
v6.4.0, v4.7.1Fatias de array tipadas agora são tratadas corretamente.
v5.10.1, v4.4.3Manipula arrays tipadas não-Uint8Array corretamente.
v1.2.0Adicionado em: v1.2.0

Testa a igualdade profunda entre os parâmetros actual e expected. Igualdade "profunda" significa que as propriedades "próprias" enumeráveis de objetos filhos são avaliadas recursivamente também pelas seguintes regras.

Detalhes da comparação ​

  • Valores primitivos são comparados usando Object.is().
  • Tags de tipo de objetos devem ser as mesmas.
  • [[Prototype]] de objetos são comparados usando o operador ===.
  • Apenas propriedades "próprias" enumeráveis são consideradas.
  • Nomes, mensagens, causas e erros do Error são sempre comparados, mesmo que não sejam propriedades enumeráveis. errors também é comparado.
  • Propriedades próprias enumeráveis Symbol também são comparadas.
  • Wrappers de objeto são comparados tanto como objetos quanto como valores desembrulhados.
  • As propriedades de Object são comparadas sem ordem.
  • Chaves de Map e itens de Set são comparados sem ordem.
  • A recursão para quando ambos os lados diferem ou ambos os lados encontram uma referência circular.
  • A comparação de WeakMap e WeakSet não depende de seus valores. Veja abaixo para mais detalhes.
  • RegExp lastIndex, flags e source são sempre comparados, mesmo que não sejam propriedades enumeráveis.
js
import assert from 'node:assert/strict'

// Isso falha porque 1 !== '1'.
assert.deepStrictEqual({ a: 1 }, { a: '1' })
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
//   {
// +   a: 1
// -   a: '1'
//   }

// Os seguintes objetos não possuem propriedades próprias
const date = new Date()
const object = {}
const fakeDate = {}
Object.setPrototypeOf(fakeDate, Date.prototype)

// [[Prototype]] diferentes:
assert.deepStrictEqual(object, fakeDate)
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + {}
// - Date {}

// Tags de tipo diferentes:
assert.deepStrictEqual(date, fakeDate)
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + 2018-04-26T00:49:08.604Z
// - Date {}

assert.deepStrictEqual(NaN, NaN)
// OK porque Object.is(NaN, NaN) é verdadeiro.

// Números desembrulhados diferentes:
assert.deepStrictEqual(new Number(1), new Number(2))
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + [Number: 1]
// - [Number: 2]

assert.deepStrictEqual(new String('foo'), Object('foo'))
// OK porque o objeto e a string são idênticos quando desembrulhados.

assert.deepStrictEqual(-0, -0)
// OK

// Zeros diferentes:
assert.deepStrictEqual(0, -0)
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + 0
// - -0

const symbol1 = Symbol()
const symbol2 = Symbol()
assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol1]: 1 })
// OK, porque é o mesmo símbolo em ambos os objetos.

assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 })
// AssertionError [ERR_ASSERTION]: Inputs identical but not reference equal:
//
// {
//   [Symbol()]: 1
// }

const weakMap1 = new WeakMap()
const weakMap2 = new WeakMap([[{}, {}]])
const weakMap3 = new WeakMap()
weakMap3.unequal = true

assert.deepStrictEqual(weakMap1, weakMap2)
// OK, porque é impossível comparar as entradas

// Falha porque weakMap3 tem uma propriedade que weakMap1 não contém:
assert.deepStrictEqual(weakMap1, weakMap3)
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
//   WeakMap {
// +   [items unknown]
// -   [items unknown],
// -   unequal: true
//   }
js
const assert = require('node:assert/strict')

// Isso falha porque 1 !== '1'.
assert.deepStrictEqual({ a: 1 }, { a: '1' })
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
//   {
// +   a: 1
// -   a: '1'
//   }

// Os seguintes objetos não possuem propriedades próprias
const date = new Date()
const object = {}
const fakeDate = {}
Object.setPrototypeOf(fakeDate, Date.prototype)

// [[Prototype]] diferentes:
assert.deepStrictEqual(object, fakeDate)
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + {}
// - Date {}

// Tags de tipo diferentes:
assert.deepStrictEqual(date, fakeDate)
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + 2018-04-26T00:49:08.604Z
// - Date {}

assert.deepStrictEqual(NaN, NaN)
// OK porque Object.is(NaN, NaN) é verdadeiro.

// Números desembrulhados diferentes:
assert.deepStrictEqual(new Number(1), new Number(2))
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + [Number: 1]
// - [Number: 2]

assert.deepStrictEqual(new String('foo'), Object('foo'))
// OK porque o objeto e a string são idênticos quando desembrulhados.

assert.deepStrictEqual(-0, -0)
// OK

// Zeros diferentes:
assert.deepStrictEqual(0, -0)
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + 0
// - -0

const symbol1 = Symbol()
const symbol2 = Symbol()
assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol1]: 1 })
// OK, porque é o mesmo símbolo em ambos os objetos.

assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 })
// AssertionError [ERR_ASSERTION]: Inputs identical but not reference equal:
//
// {
//   [Symbol()]: 1
// }

const weakMap1 = new WeakMap()
const weakMap2 = new WeakMap([[{}, {}]])
const weakMap3 = new WeakMap()
weakMap3.unequal = true

assert.deepStrictEqual(weakMap1, weakMap2)
// OK, porque é impossível comparar as entradas

// Falha porque weakMap3 tem uma propriedade que weakMap1 não contém:
assert.deepStrictEqual(weakMap1, weakMap3)
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
//   WeakMap {
// +   [items unknown]
// -   [items unknown],
// -   unequal: true
//   }

Se os valores não forem iguais, um AssertionError é lançado com uma propriedade message definida como igual ao valor do parâmetro message. Se o parâmetro message não estiver definido, uma mensagem de erro padrão é atribuída. Se o parâmetro message for uma instância de um Error, então ele será lançado em vez do AssertionError.

assert.doesNotMatch(string, regexp[, message]) ​

[Histórico]

VersãoMudanças
v16.0.0Esta API não é mais experimental.
v13.6.0, v12.16.0Adicionado em: v13.6.0, v12.16.0

Espera que a entrada string não corresponda à expressão regular.

js
import assert from 'node:assert/strict'

assert.doesNotMatch('Eu vou falhar', /falhar/)
// AssertionError [ERR_ASSERTION]: Esperava-se que a entrada não correspondesse a ...

assert.doesNotMatch(123, /passar/)
// AssertionError [ERR_ASSERTION]: O argumento "string" deve ser do tipo string.

assert.doesNotMatch('Eu vou passar', /diferente/)
// OK
js
const assert = require('node:assert/strict')

assert.doesNotMatch('Eu vou falhar', /falhar/)
// AssertionError [ERR_ASSERTION]: Esperava-se que a entrada não correspondesse a ...

assert.doesNotMatch(123, /passar/)
// AssertionError [ERR_ASSERTION]: O argumento "string" deve ser do tipo string.

assert.doesNotMatch('Eu vou passar', /diferente/)
// OK

Se os valores corresponderem ou se o argumento string for de um tipo diferente de string, um AssertionError será lançado com uma propriedade message definida como igual ao valor do parâmetro message. Se o parâmetro message não estiver definido, uma mensagem de erro padrão será atribuída. Se o parâmetro message for uma instância de um Error, então ele será lançado em vez do AssertionError.

assert.doesNotReject(asyncFn[, error][, message]) ​

Adicionado em: v10.0.0

Aguarda a promessa asyncFn ou, se asyncFn for uma função, chama imediatamente a função e aguarda a conclusão da promessa retornada. Em seguida, ele verificará se a promessa não é rejeitada.

Se asyncFn for uma função e lançar um erro de forma síncrona, assert.doesNotReject() retornará uma Promise rejeitada com esse erro. Se a função não retornar uma promessa, assert.doesNotReject() retornará uma Promise rejeitada com um erro ERR_INVALID_RETURN_VALUE. Em ambos os casos, o manipulador de erros é ignorado.

Usar assert.doesNotReject() não é realmente útil porque há pouco benefício em capturar uma rejeição e depois rejeitá-la novamente. Em vez disso, considere adicionar um comentário ao lado do caminho de código específico que não deve rejeitar e manter as mensagens de erro o mais expressivas possível.

Se especificado, error pode ser uma Class, RegExp ou uma função de validação. Consulte assert.throws() para mais detalhes.

Além da natureza assíncrona para aguardar a conclusão, ele se comporta de forma idêntica a assert.doesNotThrow().

js
import assert from 'node:assert/strict'

await assert.doesNotReject(async () => {
  throw new TypeError('Valor incorreto')
}, SyntaxError)
js
const assert = require('node:assert/strict')

;(async () => {
  await assert.doesNotReject(async () => {
    throw new TypeError('Valor incorreto')
  }, SyntaxError)
})()
js
import assert from 'node:assert/strict'

assert.doesNotReject(Promise.reject(new TypeError('Valor incorreto'))).then(() => {
  // ...
})
js
const assert = require('node:assert/strict')

assert.doesNotReject(Promise.reject(new TypeError('Valor incorreto'))).then(() => {
  // ...
})

assert.doesNotThrow(fn[, error][, message]) ​

[Histórico]

VersãoMudanças
v5.11.0, v4.4.5O parâmetro message é respeitado agora.
v4.2.0O parâmetro error agora pode ser uma função de seta.
v0.1.21Adicionado em: v0.1.21

Afirma que a função fn não lança um erro.

Usar assert.doesNotThrow() na verdade não é útil porque não há benefício em capturar um erro e depois relançá-lo. Em vez disso, considere adicionar um comentário próximo ao caminho de código específico que não deve lançar um erro e mantenha as mensagens de erro o mais expressivas possível.

Quando assert.doesNotThrow() é chamado, ele chamará imediatamente a função fn.

Se um erro for lançado e for do mesmo tipo especificado pelo parâmetro error, então um AssertionError será lançado. Se o erro for de um tipo diferente, ou se o parâmetro error for indefinido, o erro é propagado de volta para o chamador.

Se especificado, error pode ser uma Class, RegExp ou uma função de validação. Consulte assert.throws() para obter mais detalhes.

O seguinte, por exemplo, lançará o TypeError porque não há um tipo de erro correspondente na asserção:

js
import assert from 'node:assert/strict'

assert.doesNotThrow(() => {
  throw new TypeError('Valor incorreto')
}, SyntaxError)
js
const assert = require('node:assert/strict')

assert.doesNotThrow(() => {
  throw new TypeError('Valor incorreto')
}, SyntaxError)

No entanto, o seguinte resultará em um AssertionError com a mensagem 'Obteve exceção indesejada...':

js
import assert from 'node:assert/strict'

assert.doesNotThrow(() => {
  throw new TypeError('Valor incorreto')
}, TypeError)
js
const assert = require('node:assert/strict')

assert.doesNotThrow(() => {
  throw new TypeError('Valor incorreto')
}, TypeError)

Se um AssertionError for lançado e um valor for fornecido para o parâmetro message, o valor de message será anexado à mensagem AssertionError:

js
import assert from 'node:assert/strict'

assert.doesNotThrow(
  () => {
    throw new TypeError('Valor incorreto')
  },
  /Valor incorreto/,
  'Opa'
)
// Lança: AssertionError: Obteve exceção indesejada: Opa
js
const assert = require('node:assert/strict')

assert.doesNotThrow(
  () => {
    throw new TypeError('Valor incorreto')
  },
  /Valor incorreto/,
  'Opa'
)
// Lança: AssertionError: Obteve exceção indesejada: Opa

assert.equal(actual, expected[, message]) ​

[Histórico]

VersãoMudanças
v16.0.0, v14.18.0No modo de asserção Legado, alterou o status de Obsoleto para Legado.
v14.0.0NaN agora é tratado como idêntico se ambos os lados forem NaN.
v0.1.21Adicionado em: v0.1.21

Modo de asserção estrita

Um alias de assert.strictEqual().

Modo de asserção legado

[Estável: 3 - Legado]

Estável: 3 Estabilidade: 3 - Legado: Use assert.strictEqual() em vez disso.

Testa a igualdade rasa e coerciva entre os parâmetros actual e expected usando o operador ==. NaN é tratado especialmente e considerado idêntico se ambos os lados forem NaN.

js
import assert from 'node:assert'

assert.equal(1, 1)
// OK, 1 == 1
assert.equal(1, '1')
// OK, 1 == '1'
assert.equal(NaN, NaN)
// OK

assert.equal(1, 2)
// AssertionError: 1 == 2
assert.equal({ a: { b: 1 } }, { a: { b: 1 } })
// AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
js
const assert = require('node:assert')

assert.equal(1, 1)
// OK, 1 == 1
assert.equal(1, '1')
// OK, 1 == '1'
assert.equal(NaN, NaN)
// OK

assert.equal(1, 2)
// AssertionError: 1 == 2
assert.equal({ a: { b: 1 } }, { a: { b: 1 } })
// AssertionError: { a: { b: 1 } } == { a: { b: 1 } }

Se os valores não forem iguais, um AssertionError é lançado com uma propriedade message definida como igual ao valor do parâmetro message. Se o parâmetro message for indefinido, uma mensagem de erro padrão será atribuída. Se o parâmetro message for uma instância de um Error, ele será lançado em vez do AssertionError.

assert.fail([message]) ​

Adicionado em: v0.1.21

Lança um AssertionError com a mensagem de erro fornecida ou uma mensagem de erro padrão. Se o parâmetro message for uma instância de Error, ele será lançado em vez do AssertionError.

js
import assert from 'node:assert/strict'

assert.fail()
// AssertionError [ERR_ASSERTION]: Falhou

assert.fail('boom')
// AssertionError [ERR_ASSERTION]: boom

assert.fail(new TypeError('precisa de array'))
// TypeError: precisa de array
js
const assert = require('node:assert/strict')

assert.fail()
// AssertionError [ERR_ASSERTION]: Falhou

assert.fail('boom')
// AssertionError [ERR_ASSERTION]: boom

assert.fail(new TypeError('precisa de array'))
// TypeError: precisa de array

Usar assert.fail() com mais de dois argumentos é possível, mas está obsoleto. Veja abaixo para mais detalhes.

assert.fail(actual, expected[, message[, operator[, stackStartFn]]]) ​

[Histórico]

VersãoMudanças
v10.0.0Chamar assert.fail() com mais de um argumento está obsoleto e emite um aviso.
v0.1.21Adicionado em: v0.1.21

[Estável: 0 - Obsoleto]

Estável: 0 Estabilidade: 0 - Obsoleto: Use assert.fail([message]) ou outras funções assert.

Se message for falso, a mensagem de erro é definida como os valores de actual e expected separados pelo operator fornecido. Se apenas os dois argumentos actual e expected forem fornecidos, operator terá como padrão '!='. Se message for fornecido como terceiro argumento, ele será usado como a mensagem de erro e os outros argumentos serão armazenados como propriedades no objeto lançado. Se stackStartFn for fornecido, todos os frames de pilha acima dessa função serão removidos do stacktrace (veja Error.captureStackTrace). Se nenhum argumento for fornecido, a mensagem padrão Falhou será usada.

js
import assert from 'node:assert/strict'

assert.fail('a', 'b')
// AssertionError [ERR_ASSERTION]: 'a' != 'b'

assert.fail(1, 2, undefined, '>')
// AssertionError [ERR_ASSERTION]: 1 > 2

assert.fail(1, 2, 'falhou')
// AssertionError [ERR_ASSERTION]: falhou

assert.fail(1, 2, 'opa', '>')
// AssertionError [ERR_ASSERTION]: opa

assert.fail(1, 2, new TypeError('precisa de array'))
// TypeError: precisa de array
js
const assert = require('node:assert/strict')

assert.fail('a', 'b')
// AssertionError [ERR_ASSERTION]: 'a' != 'b'

assert.fail(1, 2, undefined, '>')
// AssertionError [ERR_ASSERTION]: 1 > 2

assert.fail(1, 2, 'falhou')
// AssertionError [ERR_ASSERTION]: falhou

assert.fail(1, 2, 'opa', '>')
// AssertionError [ERR_ASSERTION]: opa

assert.fail(1, 2, new TypeError('precisa de array'))
// TypeError: precisa de array

Nos três últimos casos, actual, expected e operator não têm influência na mensagem de erro.

Exemplo de uso de stackStartFn para truncar o stacktrace da exceção:

js
import assert from 'node:assert/strict'

function suppressFrame() {
  assert.fail('a', 'b', undefined, '!==', suppressFrame)
}
suppressFrame()
// AssertionError [ERR_ASSERTION]: 'a' !== 'b'
//     em repl:1:1
//     em ContextifyScript.Script.runInThisContext (vm.js:44:33)
//     ...
js
const assert = require('node:assert/strict')

function suppressFrame() {
  assert.fail('a', 'b', undefined, '!==', suppressFrame)
}
suppressFrame()
// AssertionError [ERR_ASSERTION]: 'a' !== 'b'
//     em repl:1:1
//     em ContextifyScript.Script.runInThisContext (vm.js:44:33)
//     ...

assert.ifError(value) ​

[Histórico]

VersãoMudanças
v10.0.0Em vez de lançar o erro original, ele agora é encapsulado em um [AssertionError][] que contém o rastreamento de pilha completo.
v10.0.0O valor agora pode ser apenas undefined ou null. Antes, todos os valores falsy eram tratados da mesma forma que null e não lançavam.
v0.1.97Adicionado em: v0.1.97

Lança value se value não for undefined ou null. Isso é útil ao testar o argumento error em retornos de chamada. O rastreamento de pilha contém todos os quadros do erro passado para ifError() incluindo os possíveis novos quadros para ifError() em si.

js
import assert from 'node:assert/strict'

assert.ifError(null)
// OK
assert.ifError(0)
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0
assert.ifError('error')
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error'
assert.ifError(new Error())
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error

// Cria alguns quadros de erro aleatórios.
let err
;(function errorFrame() {
  err = new Error('test error')
})()

;(function ifErrorFrame() {
  assert.ifError(err)
})()
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error
//     at ifErrorFrame
//     at errorFrame
js
const assert = require('node:assert/strict')

assert.ifError(null)
// OK
assert.ifError(0)
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0
assert.ifError('error')
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error'
assert.ifError(new Error())
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error

// Cria alguns quadros de erro aleatórios.
let err
;(function errorFrame() {
  err = new Error('test error')
})()

;(function ifErrorFrame() {
  assert.ifError(err)
})()
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error
//     at ifErrorFrame
//     at errorFrame

assert.match(string, regexp[, message]) ​

[Histórico]

VersãoMudanças
v16.0.0Esta API não é mais experimental.
v13.6.0, v12.16.0Adicionado em: v13.6.0, v12.16.0

Espera que a entrada string corresponda à expressão regular.

js
import assert from 'node:assert/strict'

assert.match('Eu vou falhar', /pass/)
// AssertionError [ERR_ASSERTION]: A entrada não correspondeu à expressão regular ...

assert.match(123, /pass/)
// AssertionError [ERR_ASSERTION]: O argumento "string" deve ser do tipo string.

assert.match('Eu vou passar', /pass/)
// OK
js
const assert = require('node:assert/strict')

assert.match('Eu vou falhar', /pass/)
// AssertionError [ERR_ASSERTION]: A entrada não correspondeu à expressão regular ...

assert.match(123, /pass/)
// AssertionError [ERR_ASSERTION]: O argumento "string" deve ser do tipo string.

assert.match('Eu vou passar', /pass/)
// OK

Se os valores não corresponderem, ou se o argumento string for de um tipo diferente de string, um AssertionError é lançado com uma propriedade message definida igual ao valor do parâmetro message. Se o parâmetro message for indefinido, uma mensagem de erro padrão é atribuída. Se o parâmetro message for uma instância de um Error, então ele será lançado em vez do AssertionError.

assert.notDeepEqual(actual, expected[, message]) ​

[Histórico]

VersãoMudanças
v16.0.0, v14.18.0No modo de asserção Legado, o status mudou de Obsoleto para Legado.
v14.0.0NaN agora é tratado como idêntico se ambos os lados forem NaN.
v9.0.0Os nomes e mensagens de Error agora são comparados corretamente.
v8.0.0O conteúdo de Set e Map também é comparado.
v6.4.0, v4.7.1Fatias de array tipados agora são tratadas corretamente.
v6.1.0, v4.5.0Objetos com referências circulares agora podem ser usados como entradas.
v5.10.1, v4.4.3Lidar corretamente com arrays tipados não Uint8Array.
v0.1.21Adicionado em: v0.1.21

Modo de asserção estrita

Um alias de assert.notDeepStrictEqual().

Modo de asserção Legado

[Estável: 3 - Legado]

Estável: 3 Estabilidade: 3 - Legado: Use assert.notDeepStrictEqual() em vez disso.

Testa qualquer desigualdade profunda. Oposto de assert.deepEqual().

js
import assert from 'node:assert'

const obj1 = {
  a: {
    b: 1,
  },
}
const obj2 = {
  a: {
    b: 2,
  },
}
const obj3 = {
  a: {
    b: 1,
  },
}
const obj4 = { __proto__: obj1 }

assert.notDeepEqual(obj1, obj1)
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }

assert.notDeepEqual(obj1, obj2)
// OK

assert.notDeepEqual(obj1, obj3)
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }

assert.notDeepEqual(obj1, obj4)
// OK
js
const assert = require('node:assert')

const obj1 = {
  a: {
    b: 1,
  },
}
const obj2 = {
  a: {
    b: 2,
  },
}
const obj3 = {
  a: {
    b: 1,
  },
}
const obj4 = { __proto__: obj1 }

assert.notDeepEqual(obj1, obj1)
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }

assert.notDeepEqual(obj1, obj2)
// OK

assert.notDeepEqual(obj1, obj3)
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }

assert.notDeepEqual(obj1, obj4)
// OK

Se os valores forem profundamente iguais, um AssertionError será lançado com uma propriedade message definida igual ao valor do parâmetro message. Se o parâmetro message for indefinido, uma mensagem de erro padrão é atribuída. Se o parâmetro message for uma instância de um Error, então ele será lançado em vez do AssertionError.

assert.notDeepStrictEqual(actual, expected[, message]) ​

[Histórico]

VersãoMudanças
v9.0.0-0 e +0 não são mais considerados iguais.
v9.0.0NaN agora é comparado usando a comparação SameValueZero.
v9.0.0Os nomes e mensagens de Error agora são comparados corretamente.
v8.0.0O conteúdo de Set e Map também é comparado.
v6.1.0Objetos com referências circulares podem ser usados como entradas agora.
v6.4.0, v4.7.1Fatias de array tipadas são tratadas corretamente agora.
v5.10.1, v4.4.3Lida com arrays tipados não-Uint8Array corretamente.
v1.2.0Adicionado em: v1.2.0

Testa a desigualdade estrita profunda. Oposto de assert.deepStrictEqual().

js
import assert from 'node:assert/strict'

assert.notDeepStrictEqual({ a: 1 }, { a: '1' })
// OK
js
const assert = require('node:assert/strict')

assert.notDeepStrictEqual({ a: 1 }, { a: '1' })
// OK

Se os valores forem profundamente e estritamente iguais, um AssertionError será lançado com uma propriedade message definida como o valor do parâmetro message. Se o parâmetro message for indefinido, uma mensagem de erro padrão será atribuída. Se o parâmetro message for uma instância de um Error, ele será lançado em vez do AssertionError.

assert.notEqual(actual, expected[, message]) ​

[Histórico]

VersãoMudanças
v16.0.0, v14.18.0No modo de asserção Legado, o status foi alterado de Obsoleto para Legado.
v14.0.0NaN agora é tratado como idêntico se ambos os lados forem NaN.
v0.1.21Adicionado em: v0.1.21

Modo de asserção estrita

Um alias de assert.notStrictEqual().

Modo de asserção legado

[Estável: 3 - Legado]

Estável: 3 Estabilidade: 3 - Legado: Use assert.notStrictEqual() em vez disso.

Testa a desigualdade superficial e coerciva com o != operador. NaN é tratado especialmente e considerado idêntico se ambos os lados forem NaN.

js
import assert from 'node:assert'

assert.notEqual(1, 2)
// OK

assert.notEqual(1, 1)
// AssertionError: 1 != 1

assert.notEqual(1, '1')
// AssertionError: 1 != '1'
js
const assert = require('node:assert')

assert.notEqual(1, 2)
// OK

assert.notEqual(1, 1)
// AssertionError: 1 != 1

assert.notEqual(1, '1')
// AssertionError: 1 != '1'

Se os valores forem iguais, um AssertionError será lançado com uma propriedade message definida como o valor do parâmetro message. Se o parâmetro message for indefinido, uma mensagem de erro padrão será atribuída. Se o parâmetro message for uma instância de um Error, ele será lançado em vez do AssertionError.

assert.notStrictEqual(actual, expected[, message]) ​

[Histórico]

VersãoMudanças
v10.0.0A comparação usada mudou de Igualdade Estrita para Object.is().
v0.1.21Adicionado em: v0.1.21

Testa a desigualdade estrita entre os parâmetros actual e expected conforme determinado por Object.is().

js
import assert from 'node:assert/strict'

assert.notStrictEqual(1, 2)
// OK

assert.notStrictEqual(1, 1)
// AssertionError [ERR_ASSERTION]: Esperado que "actual" seja estritamente diferente de:
//
// 1

assert.notStrictEqual(1, '1')
// OK
js
const assert = require('node:assert/strict')

assert.notStrictEqual(1, 2)
// OK

assert.notStrictEqual(1, 1)
// AssertionError [ERR_ASSERTION]: Esperado que "actual" seja estritamente diferente de:
//
// 1

assert.notStrictEqual(1, '1')
// OK

Se os valores forem estritamente iguais, um AssertionError é lançado com uma propriedade message definida igual ao valor do parâmetro message. Se o parâmetro message for indefinido, uma mensagem de erro padrão é atribuída. Se o parâmetro message for uma instância de um Error, então ele será lançado em vez de AssertionError.

assert.ok(value[, message]) ​

[Histórico]

VersãoMudanças
v10.0.0O assert.ok() (sem argumentos) agora usará uma mensagem de erro predefinida.
v0.1.21Adicionado em: v0.1.21

Testa se value é verdadeiro. É equivalente a assert.equal(!!value, true, message).

Se value não for verdadeiro, um AssertionError será lançado com uma propriedade message definida igual ao valor do parâmetro message. Se o parâmetro message for undefined, uma mensagem de erro padrão será atribuída. Se o parâmetro message for uma instância de um Error, então ele será lançado em vez do AssertionError. Se nenhum argumento for passado, message será definido como a string: 'Nenhum argumento de valor passado para assert.ok()'.

Esteja ciente de que no repl a mensagem de erro será diferente daquela lançada em um arquivo! Veja abaixo para mais detalhes.

js
import assert from 'node:assert/strict'

assert.ok(true)
// OK
assert.ok(1)
// OK

assert.ok()
// AssertionError: Nenhum argumento de valor passado para `assert.ok()`

assert.ok(false, 'é falso')
// AssertionError: é falso

// No repl:
assert.ok(typeof 123 === 'string')
// AssertionError: false == true

// Em um arquivo (por exemplo, test.js):
assert.ok(typeof 123 === 'string')
// AssertionError: A expressão avaliou para um valor falso:
//
//   assert.ok(typeof 123 === 'string')

assert.ok(false)
// AssertionError: A expressão avaliou para um valor falso:
//
//   assert.ok(false)

assert.ok(0)
// AssertionError: A expressão avaliou para um valor falso:
//
//   assert.ok(0)
js
const assert = require('node:assert/strict')

assert.ok(true)
// OK
assert.ok(1)
// OK

assert.ok()
// AssertionError: Nenhum argumento de valor passado para `assert.ok()`

assert.ok(false, 'é falso')
// AssertionError: é falso

// No repl:
assert.ok(typeof 123 === 'string')
// AssertionError: false == true

// Em um arquivo (por exemplo, test.js):
assert.ok(typeof 123 === 'string')
// AssertionError: A expressão avaliou para um valor falso:
//
//   assert.ok(typeof 123 === 'string')

assert.ok(false)
// AssertionError: A expressão avaliou para um valor falso:
//
//   assert.ok(false)

assert.ok(0)
// AssertionError: A expressão avaliou para um valor falso:
//
//   assert.ok(0)
js
import assert from 'node:assert/strict'

// Usar `assert()` funciona da mesma forma:
assert(0)
// AssertionError: A expressão avaliou para um valor falso:
//
//   assert(0)
js
const assert = require('node:assert')

// Usar `assert()` funciona da mesma forma:
assert(0)
// AssertionError: A expressão avaliou para um valor falso:
//
//   assert(0)

assert.rejects(asyncFn[, error][, message]) ​

Adicionado em: v10.0.0

Aguarda a promessa asyncFn ou, se asyncFn for uma função, chama imediatamente a função e aguarda a conclusão da promessa retornada. Em seguida, verifica se a promessa é rejeitada.

Se asyncFn for uma função e lançar um erro de forma síncrona, assert.rejects() retornará uma Promise rejeitada com esse erro. Se a função não retornar uma promessa, assert.rejects() retornará uma Promise rejeitada com um erro ERR_INVALID_RETURN_VALUE. Em ambos os casos, o manipulador de erros é ignorado.

Além da natureza assíncrona para aguardar a conclusão, o comportamento é idêntico a assert.throws().

Se especificado, error pode ser uma Class, RegExp, uma função de validação, um objeto onde cada propriedade será testada ou uma instância de erro onde cada propriedade será testada, incluindo as propriedades não enumeráveis message e name.

Se especificado, message será a mensagem fornecida pelo AssertionError se asyncFn não conseguir rejeitar.

js
import assert from 'node:assert/strict'

await assert.rejects(
  async () => {
    throw new TypeError('Valor errado')
  },
  {
    name: 'TypeError',
    message: 'Valor errado',
  }
)
js
const assert = require('node:assert/strict')

;(async () => {
  await assert.rejects(
    async () => {
      throw new TypeError('Valor errado')
    },
    {
      name: 'TypeError',
      message: 'Valor errado',
    }
  )
})()
js
import assert from 'node:assert/strict'

await assert.rejects(
  async () => {
    throw new TypeError('Valor errado')
  },
  err => {
    assert.strictEqual(err.name, 'TypeError')
    assert.strictEqual(err.message, 'Valor errado')
    return true
  }
)
js
const assert = require('node:assert/strict')

;(async () => {
  await assert.rejects(
    async () => {
      throw new TypeError('Valor errado')
    },
    err => {
      assert.strictEqual(err.name, 'TypeError')
      assert.strictEqual(err.message, 'Valor errado')
      return true
    }
  )
})()
js
import assert from 'node:assert/strict'

assert.rejects(Promise.reject(new Error('Valor errado')), Error).then(() => {
  // ...
})
js
const assert = require('node:assert/strict')

assert.rejects(Promise.reject(new Error('Valor errado')), Error).then(() => {
  // ...
})

error não pode ser uma string. Se uma string for fornecida como segundo argumento, então assume-se que error foi omitido e a string será usada para message em vez disso. Isso pode levar a erros fáceis de perder. Leia o exemplo em assert.throws() cuidadosamente se o uso de uma string como segundo argumento for considerado.

assert.strictEqual(actual, expected[, message]) ​

[Histórico]

VersãoMudanças
v10.0.0A comparação usada mudou de Igualdade Estrita para Object.is().
v0.1.21Adicionado em: v0.1.21

Testa a igualdade estrita entre os parâmetros actual e expected, conforme determinado por Object.is().

js
import assert from 'node:assert/strict'

assert.strictEqual(1, 2)
// AssertionError [ERR_ASSERTION]: Esperava-se que as entradas fossem estritamente iguais:
//
// 1 !== 2

assert.strictEqual(1, 1)
// OK

assert.strictEqual('Hello foobar', 'Hello World!')
// AssertionError [ERR_ASSERTION]: Esperava-se que as entradas fossem estritamente iguais:
// + actual - esperado
//
// + 'Hello foobar'
// - 'Hello World!'
//          ^

const apples = 1
const oranges = 2
assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`)
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2

assert.strictEqual(1, '1', new TypeError('As entradas não são idênticas'))
// TypeError: As entradas não são idênticas
js
const assert = require('node:assert/strict')

assert.strictEqual(1, 2)
// AssertionError [ERR_ASSERTION]: Esperava-se que as entradas fossem estritamente iguais:
//
// 1 !== 2

assert.strictEqual(1, 1)
// OK

assert.strictEqual('Hello foobar', 'Hello World!')
// AssertionError [ERR_ASSERTION]: Esperava-se que as entradas fossem estritamente iguais:
// + actual - esperado
//
// + 'Hello foobar'
// - 'Hello World!'
//          ^

const apples = 1
const oranges = 2
assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`)
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2

assert.strictEqual(1, '1', new TypeError('As entradas não são idênticas'))
// TypeError: As entradas não são idênticas

Se os valores não forem estritamente iguais, um AssertionError é lançado com uma propriedade message definida como igual ao valor do parâmetro message. Se o parâmetro message for indefinido, uma mensagem de erro padrão será atribuída. Se o parâmetro message for uma instância de um Error, ele será lançado em vez do AssertionError.

assert.throws(fn[, error][, message]) ​

[Histórico]

VersãoMudanças
v10.2.0O parâmetro error agora pode ser um objeto contendo expressões regulares.
v9.9.0O parâmetro error agora também pode ser um objeto.
v4.2.0O parâmetro error agora pode ser uma função de seta.
v0.1.21Adicionado em: v0.1.21

Espera que a função fn lance um erro.

Se especificado, error pode ser uma Class, RegExp, uma função de validação, um objeto de validação onde cada propriedade será testada para igualdade profunda estrita, ou uma instância de erro onde cada propriedade será testada para igualdade profunda estrita, incluindo as propriedades não enumeráveis message e name. Ao usar um objeto, também é possível usar uma expressão regular ao validar uma propriedade de string. Consulte os exemplos abaixo.

Se especificado, message será anexado à mensagem fornecida por AssertionError caso a chamada fn falhe ao lançar ou caso a validação de erro falhe.

Objeto/instância de erro de validação personalizada:

js
import assert from 'node:assert/strict'

const err = new TypeError('Valor incorreto')
err.code = 404
err.foo = 'bar'
err.info = {
  nested: true,
  baz: 'text',
}
err.reg = /abc/i

assert.throws(
  () => {
    throw err
  },
  {
    name: 'TypeError',
    message: 'Valor incorreto',
    info: {
      nested: true,
      baz: 'text',
    },
    // Apenas as propriedades no objeto de validação serão testadas.
    // Usar objetos aninhados requer que todas as propriedades estejam presentes. Caso contrário,
    // a validação vai falhar.
  }
)

// Usar expressões regulares para validar propriedades de erro:
assert.throws(
  () => {
    throw err
  },
  {
    // As propriedades `name` e `message` são strings e usar expressões regulares nelas corresponderá à string. Se elas falharem, um
    // erro é lançado.
    name: /^TypeError$/,
    message: /Incorreto/,
    foo: 'bar',
    info: {
      nested: true,
      // Não é possível usar expressões regulares para propriedades aninhadas!
      baz: 'text',
    },
    // A propriedade `reg` contém uma expressão regular e somente se o
    // objeto de validação contiver uma expressão regular idêntica, ela vai
    // passar.
    reg: /abc/i,
  }
)

// Falha devido às diferentes propriedades `message` e `name`:
assert.throws(
  () => {
    const otherErr = new Error('Não encontrado')
    // Copiar todas as propriedades enumeráveis de `err` para `otherErr`.
    for (const [key, value] of Object.entries(err)) {
      otherErr[key] = value
    }
    throw otherErr
  },
  // As propriedades `message` e `name` do erro também serão verificadas ao usar
  // um erro como objeto de validação.
  err
)
js
const assert = require('node:assert/strict')

const err = new TypeError('Valor incorreto')
err.code = 404
err.foo = 'bar'
err.info = {
  nested: true,
  baz: 'text',
}
err.reg = /abc/i

assert.throws(
  () => {
    throw err
  },
  {
    name: 'TypeError',
    message: 'Valor incorreto',
    info: {
      nested: true,
      baz: 'text',
    },
    // Apenas as propriedades no objeto de validação serão testadas.
    // Usar objetos aninhados requer que todas as propriedades estejam presentes. Caso contrário,
    // a validação vai falhar.
  }
)

// Usar expressões regulares para validar propriedades de erro:
assert.throws(
  () => {
    throw err
  },
  {
    // As propriedades `name` e `message` são strings e usar expressões regulares nelas corresponderá à string. Se elas falharem, um
    // erro é lançado.
    name: /^TypeError$/,
    message: /Incorreto/,
    foo: 'bar',
    info: {
      nested: true,
      // Não é possível usar expressões regulares para propriedades aninhadas!
      baz: 'text',
    },
    // A propriedade `reg` contém uma expressão regular e somente se o
    // objeto de validação contiver uma expressão regular idêntica, ela vai
    // passar.
    reg: /abc/i,
  }
)

// Falha devido às diferentes propriedades `message` e `name`:
assert.throws(
  () => {
    const otherErr = new Error('Não encontrado')
    // Copiar todas as propriedades enumeráveis de `err` para `otherErr`.
    for (const [key, value] of Object.entries(err)) {
      otherErr[key] = value
    }
    throw otherErr
  },
  // As propriedades `message` e `name` do erro também serão verificadas ao usar
  // um erro como objeto de validação.
  err
)

Validar instanceof usando o construtor:

js
import assert from 'node:assert/strict'

assert.throws(() => {
  throw new Error('Valor incorreto')
}, Error)
js
const assert = require('node:assert/strict')

assert.throws(() => {
  throw new Error('Valor incorreto')
}, Error)

Validar a mensagem de erro usando RegExp:

Usar uma expressão regular executa .toString no objeto de erro e, portanto, também incluirá o nome do erro.

js
import assert from 'node:assert/strict'

assert.throws(() => {
  throw new Error('Valor incorreto')
}, /^Error: Valor incorreto$/)
js
const assert = require('node:assert/strict')

assert.throws(() => {
  throw new Error('Valor incorreto')
}, /^Error: Valor incorreto$/)

Validação de erro personalizada:

A função deve retornar true para indicar que todas as validações internas foram aprovadas. Caso contrário, ela falhará com um AssertionError.

js
import assert from 'node:assert/strict'

assert.throws(
  () => {
    throw new Error('Valor incorreto')
  },
  err => {
    assert(err instanceof Error)
    assert(/valor/.test(err))
    // Evite retornar qualquer coisa de funções de validação além de `true`.
    // Caso contrário, não está claro qual parte da validação falhou. Em vez disso,
    // lance um erro sobre a validação específica que falhou (como feito neste
    // exemplo) e adicione o máximo de informações úteis de depuração a esse erro, tanto quanto
    // possível.
    return true
  },
  'erro inesperado'
)
js
const assert = require('node:assert/strict')

assert.throws(
  () => {
    throw new Error('Valor incorreto')
  },
  err => {
    assert(err instanceof Error)
    assert(/valor/.test(err))
    // Evite retornar qualquer coisa de funções de validação além de `true`.
    // Caso contrário, não está claro qual parte da validação falhou. Em vez disso,
    // lance um erro sobre a validação específica que falhou (como feito neste
    // exemplo) e adicione o máximo de informações úteis de depuração a esse erro, tanto quanto
    // possível.
    return true
  },
  'erro inesperado'
)

error não pode ser uma string. Se uma string for fornecida como segundo argumento, então assume-se que error foi omitido e a string será usada para message. Isso pode levar a erros fáceis de passar despercebidos. Usar a mesma mensagem da mensagem de erro lançada resultará em um erro ERR_AMBIGUOUS_ARGUMENT. Leia o exemplo abaixo com atenção se o uso de uma string como segundo argumento for considerado:

js
import assert from 'node:assert/strict'

function throwingFirst() {
  throw new Error('Primeiro')
}

function throwingSecond() {
  throw new Error('Segundo')
}

function notThrowing() {}

// O segundo argumento é uma string e a função de entrada lançou um Erro.
// O primeiro caso não lançará, pois não corresponde à mensagem de erro
// lançada pela função de entrada!
assert.throws(throwingFirst, 'Segundo')
// No próximo exemplo, a mensagem não tem benefício sobre a mensagem do
// erro e como não está claro se o usuário pretendia realmente fazer uma correspondência
// com a mensagem de erro, o Node.js lança um erro `ERR_AMBIGUOUS_ARGUMENT`.
assert.throws(throwingSecond, 'Segundo')
// TypeError [ERR_AMBIGUOUS_ARGUMENT]

// A string só é usada (como mensagem) caso a função não lance:
assert.throws(notThrowing, 'Segundo')
// AssertionError [ERR_ASSERTION]: Exceção esperada ausente: Segundo

// Se a intenção era corresponder à mensagem de erro, faça isso em vez disso:
// Ela não lança porque as mensagens de erro correspondem.
assert.throws(throwingSecond, /Segundo$/)

// Se a mensagem de erro não corresponder, um AssertionError é lançado.
assert.throws(throwingFirst, /Segundo$/)
// AssertionError [ERR_ASSERTION]
js
const assert = require('node:assert/strict')

function throwingFirst() {
  throw new Error('Primeiro')
}

function throwingSecond() {
  throw new Error('Segundo')
}

function notThrowing() {}

// O segundo argumento é uma string e a função de entrada lançou um Erro.
// O primeiro caso não lançará, pois não corresponde à mensagem de erro
// lançada pela função de entrada!
assert.throws(throwingFirst, 'Segundo')
// No próximo exemplo, a mensagem não tem benefício sobre a mensagem do
// erro e como não está claro se o usuário pretendia realmente fazer uma correspondência
// com a mensagem de erro, o Node.js lança um erro `ERR_AMBIGUOUS_ARGUMENT`.
assert.throws(throwingSecond, 'Segundo')
// TypeError [ERR_AMBIGUOUS_ARGUMENT]

// A string só é usada (como mensagem) caso a função não lance:
assert.throws(notThrowing, 'Segundo')
// AssertionError [ERR_ASSERTION]: Exceção esperada ausente: Segundo

// Se a intenção era corresponder à mensagem de erro, faça isso em vez disso:
// Ela não lança porque as mensagens de erro correspondem.
assert.throws(throwingSecond, /Segundo$/)

// Se a mensagem de erro não corresponder, um AssertionError é lançado.
assert.throws(throwingFirst, /Segundo$/)
// AssertionError [ERR_ASSERTION]

Devido à notação confusa e propensa a erros, evite usar uma string como segundo argumento.

assert.partialDeepStrictEqual(actual, expected[, message]) ​

Adicionado em: v23.4.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1.0 - Desenvolvimento inicial

assert.partialDeepStrictEqual() Assere a equivalência entre os parâmetros actual e expected através de uma comparação profunda, garantindo que todas as propriedades no parâmetro expected estejam presentes no parâmetro actual com valores equivalentes, não permitindo coerção de tipo. A principal diferença com assert.deepStrictEqual() é que assert.partialDeepStrictEqual() não requer que todas as propriedades no parâmetro actual estejam presentes no parâmetro expected. Este método deve sempre passar nos mesmos casos de teste que assert.deepStrictEqual(), comportando-se como um superconjunto dele.

js
import assert from 'node:assert'

assert.partialDeepStrictEqual({ a: 1, b: 2 }, { a: 1, b: 2 })
// OK

assert.partialDeepStrictEqual({ a: { b: { c: 1 } } }, { a: { b: { c: 1 } } })
// OK

assert.partialDeepStrictEqual({ a: 1, b: 2, c: 3 }, { a: 1, b: 2 })
// OK

assert.partialDeepStrictEqual(new Set(['value1', 'value2']), new Set(['value1', 'value2']))
// OK

assert.partialDeepStrictEqual(new Map([['key1', 'value1']]), new Map([['key1', 'value1']]))
// OK

assert.partialDeepStrictEqual(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3]))
// OK

assert.partialDeepStrictEqual(/abc/, /abc/)
// OK

assert.partialDeepStrictEqual([{ a: 5 }, { b: 5 }], [{ a: 5 }])
// OK

assert.partialDeepStrictEqual(new Set([{ a: 1 }, { b: 1 }]), new Set([{ a: 1 }]))
// OK

assert.partialDeepStrictEqual(new Date(0), new Date(0))
// OK

assert.partialDeepStrictEqual({ a: 1 }, { a: 1, b: 2 })
// AssertionError

assert.partialDeepStrictEqual({ a: 1, b: '2' }, { a: 1, b: 2 })
// AssertionError

assert.partialDeepStrictEqual({ a: { b: 2 } }, { a: { b: '2' } })
// AssertionError
js
const assert = require('node:assert')

assert.partialDeepStrictEqual({ a: 1, b: 2 }, { a: 1, b: 2 })
// OK

assert.partialDeepStrictEqual({ a: { b: { c: 1 } } }, { a: { b: { c: 1 } } })
// OK

assert.partialDeepStrictEqual({ a: 1, b: 2, c: 3 }, { a: 1, b: 2 })
// OK

assert.partialDeepStrictEqual([{ a: 5 }, { b: 5 }], [{ a: 5 }])
// OK

assert.partialDeepStrictEqual(new Set([{ a: 1 }, { b: 1 }]), new Set([{ a: 1 }]))
// OK

assert.partialDeepStrictEqual({ a: 1 }, { a: 1, b: 2 })
// AssertionError

assert.partialDeepStrictEqual({ a: 1, b: '2' }, { a: 1, b: 2 })
// AssertionError

assert.partialDeepStrictEqual({ a: { b: 2 } }, { a: { b: '2' } })
// AssertionError