Strict assertion mode#

In strict assertion mode, non-strict methods behave like their correspondingstrict methods. For example,assert.deepEqual() will behave likeassert.deepStrictEqual().

In strict assertion mode, error messages for objects display a diff. In legacyassertion mode, error messages for objects display the objects, often truncated.

To use strict assertion mode:

import { strictas assert }from'node:assert';const assert =require('node:assert').strict;copy

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

Example error diff:

import { strictas assert }from'node:assert';assert.deepEqual([[[1,2,3]],4,5], [[[1,2,'3']],4,5]);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected ... Lines skipped////   [//     [// ...//       2,// +     3// -     '3'//     ],// ...//     5//   ]const assert =require('node:assert/strict');assert.deepEqual([[[1,2,3]],4,5], [[[1,2,'3']],4,5]);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected ... Lines skipped////   [//     [// ...//       2,// +     3// -     '3'//     ],// ...//     5//   ]copy

To deactivate the colors, use theNO_COLOR orNODE_DISABLE_COLORSenvironment variables. This will also deactivate the colors in the REPL. Formore on color support in terminal environments, read the ttygetColorDepth() documentation.

Legacy assertion mode#

Legacy assertion mode uses the== operator in:

• assert.deepEqual()
• assert.equal()
• assert.notDeepEqual()
• assert.notEqual()

To use legacy assertion mode:

import assertfrom'node:assert';const assert =require('node:assert');copy

Legacy assertion mode may have surprising results, especially when usingassert.deepEqual():

// WARNING: This does not throw an AssertionError in legacy assertion mode!assert.deepEqual(/a/gi,newDate());copy

Class:assert.AssertionError#

• Extends:<errors.Error>

Indicates the failure of an assertion. All errors thrown by thenode:assertmodule will be instances of theAssertionError class.

import assertfrom'node:assert';// Generate an AssertionError to compare the error message later:const { message } =new assert.AssertionError({actual:1,expected:2,operator:'strictEqual',});// Verify error output:try {  assert.strictEqual(1,2);}catch (err) {assert(errinstanceof 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);}const assert =require('node:assert');// Generate an AssertionError to compare the error message later:const { message } =new assert.AssertionError({actual:1,expected:2,operator:'strictEqual',});// Verify error output:try {  assert.strictEqual(1,2);}catch (err) {assert(errinstanceof 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);}copy

Class:assert.Assert#

TheAssert class allows creating independent assertion instances with custom options.

const {Assert } =require('node:assert');const assertInstance =newAssert({diff:'full' });assertInstance.deepStrictEqual({a:1 }, {a:2 });// Shows a full diff in the error message.copy

const myAssert =newAssert({diff:'full' });// This works as expected - uses 'full' diffmyAssert.strictEqual({a:1 }, {b: {c:1 } });// This loses the 'full' diff setting - falls back to default 'simple' diffconst { strictEqual } = myAssert;strictEqual({a:1 }, {b: {c:1 } });copy

classFoo {constructor(a) {this.a = a;  }}classBar {constructor(a) {this.a = a;  }}const foo =newFoo(1);const bar =newBar(1);// Default behavior - fails due to different constructorsconst assert1 =newAssert();assert1.deepStrictEqual(foo, bar);// AssertionError// Skip prototype comparison - passes if properties are equalconst assert2 =newAssert({skipPrototype:true });assert2.deepStrictEqual(foo, bar);// OKcopy

assert(value[, message])#

• value<any> The input that is checked for being truthy.
• message<string> |<Error>

An alias ofassert.ok().

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

• actual<any>
• expected<any>
• message<string> |<Error>

Strict assertion mode

An alias ofassert.deepStrictEqual().

Legacy assertion mode

Tests for deep equality between theactual andexpected parameters. Considerusingassert.deepStrictEqual() instead.assert.deepEqual() can havesurprising results.

Deep equality means that the enumerable "own" properties of child objectsare also recursively evaluated by the following rules.

import assertfrom'node:assert';// WARNING: This does not throw an AssertionError!assert.deepEqual('+00000000',false);const assert =require('node:assert');// WARNING: This does not throw an AssertionError!assert.deepEqual('+00000000',false);copy

import assertfrom'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// Values of b are different:assert.deepEqual(obj1, obj2);// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }assert.deepEqual(obj1, obj3);// OK// Prototypes are ignored:assert.deepEqual(obj1, obj4);// AssertionError: { a: { b: 1 } } deepEqual {}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// Values of b are different:assert.deepEqual(obj1, obj2);// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }assert.deepEqual(obj1, obj3);// OK// Prototypes are ignored:assert.deepEqual(obj1, obj4);// AssertionError: { a: { b: 1 } } deepEqual {}copy

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

• actual<any>
• expected<any>
• message<string> |<Error>

Tests for deep equality between theactual andexpected parameters."Deep" equality means that the enumerable "own" properties of child objectsare recursively evaluated also by the following rules.

import assertfrom'node:assert/strict';// This fails because 1 !== '1'.assert.deepStrictEqual({a:1 }, {a:'1' });// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected////   {// +   a: 1// -   a: '1'//   }// The following objects don't have own propertiesconst date =newDate();const object = {};const fakeDate = {};Object.setPrototypeOf(fakeDate,Date.prototype);// Different [[Prototype]]:assert.deepStrictEqual(object, fakeDate);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + {}// - Date {}// Different type tags: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 because Object.is(NaN, NaN) is true.// Different unwrapped numbers:assert.deepStrictEqual(newNumber(1),newNumber(2));// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + [Number: 1]// - [Number: 2]assert.deepStrictEqual(newString('foo'),Object('foo'));// OK because the object and the string are identical when unwrapped.assert.deepStrictEqual(-0, -0);// OK// Different zeros:assert.deepStrictEqual(0, -0);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + 0// - -0const symbol1 =Symbol();const symbol2 =Symbol();assert.deepStrictEqual({ [symbol1]:1 }, { [symbol1]:1 });// OK, because it is the same symbol on both objects.assert.deepStrictEqual({ [symbol1]:1 }, { [symbol2]:1 });// AssertionError [ERR_ASSERTION]: Inputs identical but not reference equal://// {//   Symbol(): 1// }const weakMap1 =newWeakMap();const weakMap2 =newWeakMap();const obj = {};weakMap1.set(obj,'value');weakMap2.set(obj,'value');// Comparing different instances fails, even with same contentsassert.deepStrictEqual(weakMap1, weakMap2);// AssertionError: Values have same structure but are not reference-equal://// WeakMap {//   <items unknown>// }// Comparing the same instance to itself succeedsassert.deepStrictEqual(weakMap1, weakMap1);// OKconst weakSet1 =newWeakSet();const weakSet2 =newWeakSet();weakSet1.add(obj);weakSet2.add(obj);// Comparing different instances fails, even with same contentsassert.deepStrictEqual(weakSet1, weakSet2);// AssertionError: Values have same structure but are not reference-equal:// + actual - expected//// WeakSet {//   <items unknown>// }// Comparing the same instance to itself succeedsassert.deepStrictEqual(weakSet1, weakSet1);// OKconst assert =require('node:assert/strict');// This fails because 1 !== '1'.assert.deepStrictEqual({a:1 }, {a:'1' });// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected////   {// +   a: 1// -   a: '1'//   }// The following objects don't have own propertiesconst date =newDate();const object = {};const fakeDate = {};Object.setPrototypeOf(fakeDate,Date.prototype);// Different [[Prototype]]:assert.deepStrictEqual(object, fakeDate);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + {}// - Date {}// Different type tags: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 because Object.is(NaN, NaN) is true.// Different unwrapped numbers:assert.deepStrictEqual(newNumber(1),newNumber(2));// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + [Number: 1]// - [Number: 2]assert.deepStrictEqual(newString('foo'),Object('foo'));// OK because the object and the string are identical when unwrapped.assert.deepStrictEqual(-0, -0);// OK// Different zeros:assert.deepStrictEqual(0, -0);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + 0// - -0const symbol1 =Symbol();const symbol2 =Symbol();assert.deepStrictEqual({ [symbol1]:1 }, { [symbol1]:1 });// OK, because it is the same symbol on both objects.assert.deepStrictEqual({ [symbol1]:1 }, { [symbol2]:1 });// AssertionError [ERR_ASSERTION]: Inputs identical but not reference equal://// {//   Symbol(): 1// }const weakMap1 =newWeakMap();const weakMap2 =newWeakMap();const obj = {};weakMap1.set(obj,'value');weakMap2.set(obj,'value');// Comparing different instances fails, even with same contentsassert.deepStrictEqual(weakMap1, weakMap2);// AssertionError: Values have same structure but are not reference-equal://// WeakMap {//   <items unknown>// }// Comparing the same instance to itself succeedsassert.deepStrictEqual(weakMap1, weakMap1);// OKconst weakSet1 =newWeakSet();const weakSet2 =newWeakSet();weakSet1.add(obj);weakSet2.add(obj);// Comparing different instances fails, even with same contentsassert.deepStrictEqual(weakSet1, weakSet2);// AssertionError: Values have same structure but are not reference-equal:// + actual - expected//// WeakSet {//   <items unknown>// }// Comparing the same instance to itself succeedsassert.deepStrictEqual(weakSet1, weakSet1);// OKcopy

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

• string<string>
• regexp<RegExp>
• message<string> |<Error>

Expects thestring input not to match the regular expression.

import assertfrom'node:assert/strict';assert.doesNotMatch('I will fail',/fail/);// AssertionError [ERR_ASSERTION]: The input was expected to not match the ...assert.doesNotMatch(123,/pass/);// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.assert.doesNotMatch('I will pass',/different/);// OKconst assert =require('node:assert/strict');assert.doesNotMatch('I will fail',/fail/);// AssertionError [ERR_ASSERTION]: The input was expected to not match the ...assert.doesNotMatch(123,/pass/);// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.assert.doesNotMatch('I will pass',/different/);// OKcopy

If the values do match, or if thestring argument is of another type thanstring, anAssertionError is thrown with amessage property set equalto the value of themessage parameter. If themessage parameter isundefined, a default error message is assigned. If themessage parameter is aninstance of<Error> then it will be thrown instead of theAssertionError.

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

• asyncFn<Function> |<Promise>
• error<RegExp> |<Function>
• message<string>
• Returns:<Promise>

Awaits theasyncFn promise or, ifasyncFn is a function, immediatelycalls the function and awaits the returned promise to complete. It will thencheck that the promise is not rejected.

IfasyncFn is a function and it throws an error synchronously,assert.doesNotReject() will return a rejectedPromise with that error. Ifthe function does not return a promise,assert.doesNotReject() will return arejectedPromise with anERR_INVALID_RETURN_VALUE error. In both casesthe error handler is skipped.

Usingassert.doesNotReject() is actually not useful because there is littlebenefit in catching a rejection and then rejecting it again. Instead, consideradding a comment next to the specific code path that should not reject and keeperror messages as expressive as possible.

If specified,error can be aClass,<RegExp> or a validationfunction. Seeassert.throws() for more details.

Besides the async nature to await the completion behaves identically toassert.doesNotThrow().

import assertfrom'node:assert/strict';await assert.doesNotReject(async () => {thrownewTypeError('Wrong value');  },SyntaxError,);const assert =require('node:assert/strict');(async () => {await assert.doesNotReject(async () => {thrownewTypeError('Wrong value');    },SyntaxError,  );})();copy

import assertfrom'node:assert/strict';assert.doesNotReject(Promise.reject(newTypeError('Wrong value')))  .then(() => {// ...  });const assert =require('node:assert/strict');assert.doesNotReject(Promise.reject(newTypeError('Wrong value')))  .then(() => {// ...  });copy

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

• fn<Function>
• error<RegExp> |<Function>
• message<string>

Asserts that the functionfn does not throw an error.

Usingassert.doesNotThrow() is actually not useful because thereis no benefit in catching an error and then rethrowing it. Instead, consideradding a comment next to the specific code path that should not throw and keeperror messages as expressive as possible.

Whenassert.doesNotThrow() is called, it will immediately call thefnfunction.

If an error is thrown and it is the same type as that specified by theerrorparameter, then anAssertionError is thrown. If the error is of adifferent type, or if theerror parameter is undefined, the error ispropagated back to the caller.

If specified,error can be aClass,<RegExp>, or a validationfunction. Seeassert.throws() for more details.

The following, for instance, will throw the<TypeError> because there is nomatching error type in the assertion:

import assertfrom'node:assert/strict';assert.doesNotThrow(() => {thrownewTypeError('Wrong value');  },SyntaxError,);const assert =require('node:assert/strict');assert.doesNotThrow(() => {thrownewTypeError('Wrong value');  },SyntaxError,);copy

However, the following will result in anAssertionError with the message'Got unwanted exception...':

import assertfrom'node:assert/strict';assert.doesNotThrow(() => {thrownewTypeError('Wrong value');  },TypeError,);const assert =require('node:assert/strict');assert.doesNotThrow(() => {thrownewTypeError('Wrong value');  },TypeError,);copy

If anAssertionError is thrown and a value is provided for themessageparameter, the value ofmessage will be appended to theAssertionErrormessage:

import assertfrom'node:assert/strict';assert.doesNotThrow(() => {thrownewTypeError('Wrong value');  },/Wrong value/,'Whoops',);// Throws: AssertionError: Got unwanted exception: Whoopsconst assert =require('node:assert/strict');assert.doesNotThrow(() => {thrownewTypeError('Wrong value');  },/Wrong value/,'Whoops',);// Throws: AssertionError: Got unwanted exception: Whoopscopy

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

• actual<any>
• expected<any>
• message<string> |<Error>

Strict assertion mode

An alias ofassert.strictEqual().

Legacy assertion mode

Tests shallow, coercive equality between theactual andexpected parametersusing the== operator.NaN is specially handledand treated as being identical if both sides areNaN.

import assertfrom'node:assert';assert.equal(1,1);// OK, 1 == 1assert.equal(1,'1');// OK, 1 == '1'assert.equal(NaN,NaN);// OKassert.equal(1,2);// AssertionError: 1 == 2assert.equal({a: {b:1 } }, {a: {b:1 } });// AssertionError: { a: { b: 1 } } == { a: { b: 1 } }const assert =require('node:assert');assert.equal(1,1);// OK, 1 == 1assert.equal(1,'1');// OK, 1 == '1'assert.equal(NaN,NaN);// OKassert.equal(1,2);// AssertionError: 1 == 2assert.equal({a: {b:1 } }, {a: {b:1 } });// AssertionError: { a: { b: 1 } } == { a: { b: 1 } }copy

If the values are not equal, anAssertionError is thrown with amessageproperty set equal to the value of themessage parameter. If themessageparameter is undefined, a default error message is assigned. If themessageparameter is an instance of<Error> then it will be thrown instead of theAssertionError.

assert.fail([message])#

• message<string> |<Error>Default:'Failed'

Throws anAssertionError with the provided error message or a defaulterror message. If themessage parameter is an instance of<Error> thenit will be thrown instead of theAssertionError.

import assertfrom'node:assert/strict';assert.fail();// AssertionError [ERR_ASSERTION]: Failedassert.fail('boom');// AssertionError [ERR_ASSERTION]: boomassert.fail(newTypeError('need array'));// TypeError: need arrayconst assert =require('node:assert/strict');assert.fail();// AssertionError [ERR_ASSERTION]: Failedassert.fail('boom');// AssertionError [ERR_ASSERTION]: boomassert.fail(newTypeError('need array'));// TypeError: need arraycopy

assert.ifError(value)#

• value<any>

Throwsvalue ifvalue is notundefined ornull. This is useful whentesting theerror argument in callbacks. The stack trace contains all framesfrom the error passed toifError() including the potential new frames forifError() itself.

import assertfrom'node:assert/strict';assert.ifError(null);// OKassert.ifError(0);// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0assert.ifError('error');// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error'assert.ifError(newError());// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error// Create some random error frames.let err;(functionerrorFrame() {  err =newError('test error');})();(functionifErrorFrame() {  assert.ifError(err);})();// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error//     at ifErrorFrame//     at errorFrameconst assert =require('node:assert/strict');assert.ifError(null);// OKassert.ifError(0);// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0assert.ifError('error');// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error'assert.ifError(newError());// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error// Create some random error frames.let err;(functionerrorFrame() {  err =newError('test error');})();(functionifErrorFrame() {  assert.ifError(err);})();// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error//     at ifErrorFrame//     at errorFramecopy

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

• string<string>
• regexp<RegExp>
• message<string> |<Error>

Expects thestring input to match the regular expression.

import assertfrom'node:assert/strict';assert.match('I will fail',/pass/);// AssertionError [ERR_ASSERTION]: The input did not match the regular ...assert.match(123,/pass/);// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.assert.match('I will pass',/pass/);// OKconst assert =require('node:assert/strict');assert.match('I will fail',/pass/);// AssertionError [ERR_ASSERTION]: The input did not match the regular ...assert.match(123,/pass/);// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.assert.match('I will pass',/pass/);// OKcopy

If the values do not match, or if thestring argument is of another type thanstring, anAssertionError is thrown with amessage property set equalto the value of themessage parameter. If themessage parameter isundefined, a default error message is assigned. If themessage parameter is aninstance of<Error> then it will be thrown instead of theAssertionError.

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

• actual<any>
• expected<any>
• message<string> |<Error>

Strict assertion mode

An alias ofassert.notDeepStrictEqual().

Legacy assertion mode

Tests for any deep inequality. Opposite ofassert.deepEqual().

import assertfrom'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);// OKassert.notDeepEqual(obj1, obj3);// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }assert.notDeepEqual(obj1, obj4);// OKconst 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);// OKassert.notDeepEqual(obj1, obj3);// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }assert.notDeepEqual(obj1, obj4);// OKcopy

If the values are deeply equal, anAssertionError is thrown with amessage property set equal to the value of themessage parameter. If themessage parameter is undefined, a default error message is assigned. If themessage parameter is an instance of<Error> then it will be throwninstead of theAssertionError.

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

• actual<any>
• expected<any>
• message<string> |<Error>

Tests for deep strict inequality. Opposite ofassert.deepStrictEqual().

import assertfrom'node:assert/strict';assert.notDeepStrictEqual({a:1 }, {a:'1' });// OKconst assert =require('node:assert/strict');assert.notDeepStrictEqual({a:1 }, {a:'1' });// OKcopy

If the values are deeply and strictly equal, anAssertionError is thrownwith amessage property set equal to the value of themessage parameter. Ifthemessage parameter is undefined, a default error message is assigned. Ifthemessage parameter is an instance of<Error> then it will be throwninstead of theAssertionError.

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

• actual<any>
• expected<any>
• message<string> |<Error>

Strict assertion mode

An alias ofassert.notStrictEqual().

Legacy assertion mode

Tests shallow, coercive inequality with the!= operator.NaN isspecially handled and treated as being identical if both sides areNaN.

import assertfrom'node:assert';assert.notEqual(1,2);// OKassert.notEqual(1,1);// AssertionError: 1 != 1assert.notEqual(1,'1');// AssertionError: 1 != '1'const assert =require('node:assert');assert.notEqual(1,2);// OKassert.notEqual(1,1);// AssertionError: 1 != 1assert.notEqual(1,'1');// AssertionError: 1 != '1'copy

If the values are equal, anAssertionError is thrown with amessageproperty set equal to the value of themessage parameter. If themessageparameter is undefined, a default error message is assigned. If themessageparameter is an instance of<Error> then it will be thrown instead of theAssertionError.

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

• actual<any>
• expected<any>
• message<string> |<Error>

Tests strict inequality between theactual andexpected parameters asdetermined byObject.is().

import assertfrom'node:assert/strict';assert.notStrictEqual(1,2);// OKassert.notStrictEqual(1,1);// AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to://// 1assert.notStrictEqual(1,'1');// OKconst assert =require('node:assert/strict');assert.notStrictEqual(1,2);// OKassert.notStrictEqual(1,1);// AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to://// 1assert.notStrictEqual(1,'1');// OKcopy

If the values are strictly equal, anAssertionError is thrown with amessage property set equal to the value of themessage parameter. If themessage parameter is undefined, a default error message is assigned. If themessage parameter is an instance of<Error> then it will be throwninstead of theAssertionError.

assert.ok(value[, message])#

• value<any>
• message<string> |<Error>

Tests ifvalue is truthy. It is equivalent toassert.equal(!!value, true, message).

Ifvalue is not truthy, anAssertionError is thrown with amessageproperty set equal to the value of themessage parameter. If themessageparameter isundefined, a default error message is assigned. If themessageparameter is an instance of<Error> then it will be thrown instead of theAssertionError.If no arguments are passed in at allmessage will be set to the string:'No value argument passed to `assert.ok()`'.

Be aware that in therepl the error message will be different to the onethrown in a file! See below for further details.

import assertfrom'node:assert/strict';assert.ok(true);// OKassert.ok(1);// OKassert.ok();// AssertionError: No value argument passed to `assert.ok()`assert.ok(false,'it\'s false');// AssertionError: it's false// In the repl:assert.ok(typeof123 ==='string');// AssertionError: false == true// In a file (e.g. test.js):assert.ok(typeof123 ==='string');// AssertionError: The expression evaluated to a falsy value:////   assert.ok(typeof 123 === 'string')assert.ok(false);// AssertionError: The expression evaluated to a falsy value:////   assert.ok(false)assert.ok(0);// AssertionError: The expression evaluated to a falsy value:////   assert.ok(0)copy

const assert =require('node:assert/strict');assert.ok(true);// OKassert.ok(1);// OKassert.ok();// AssertionError: No value argument passed to `assert.ok()`assert.ok(false,'it\'s false');// AssertionError: it's false// In the repl:assert.ok(typeof123 ==='string');// AssertionError: false == true// In a file (e.g. test.js):assert.ok(typeof123 ==='string');// AssertionError: The expression evaluated to a falsy value:////   assert.ok(typeof 123 === 'string')assert.ok(false);// AssertionError: The expression evaluated to a falsy value:////   assert.ok(false)assert.ok(0);// AssertionError: The expression evaluated to a falsy value:////   assert.ok(0)import assertfrom'node:assert/strict';// Using `assert()` works the same:assert(2 +2 >5);// AssertionError: The expression evaluated to a falsy value:////   assert(2 + 2 > 5)copy

const assert =require('node:assert');// Using `assert()` works the same:assert(2 +2 >5);// AssertionError: The expression evaluated to a falsy value:////   assert(2 + 2 > 5)copy

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

• asyncFn<Function> |<Promise>
• error<RegExp> |<Function> |<Object> |<Error>
• message<string>
• Returns:<Promise>

Awaits theasyncFn promise or, ifasyncFn is a function, immediatelycalls the function and awaits the returned promise to complete. It will thencheck that the promise is rejected.

IfasyncFn is a function and it throws an error synchronously,assert.rejects() will return a rejectedPromise with that error. If thefunction does not return a promise,assert.rejects() will return a rejectedPromise with anERR_INVALID_RETURN_VALUE error. In both cases the errorhandler is skipped.

Besides the async nature to await the completion behaves identically toassert.throws().

If specified,error can be aClass,<RegExp>, a validation function,an object where each property will be tested for, or an instance of error whereeach property will be tested for including the non-enumerablemessage andname properties.

If specified,message will be the message provided by theAssertionErrorif theasyncFn fails to reject.

import assertfrom'node:assert/strict';await assert.rejects(async () => {thrownewTypeError('Wrong value');  },  {name:'TypeError',message:'Wrong value',  },);const assert =require('node:assert/strict');(async () => {await assert.rejects(async () => {thrownewTypeError('Wrong value');    },    {name:'TypeError',message:'Wrong value',    },  );})();copy

import assertfrom'node:assert/strict';await assert.rejects(async () => {thrownewTypeError('Wrong value');  },(err) => {    assert.strictEqual(err.name,'TypeError');    assert.strictEqual(err.message,'Wrong value');returntrue;  },);const assert =require('node:assert/strict');(async () => {await assert.rejects(async () => {thrownewTypeError('Wrong value');    },(err) => {      assert.strictEqual(err.name,'TypeError');      assert.strictEqual(err.message,'Wrong value');returntrue;    },  );})();copy

import assertfrom'node:assert/strict';assert.rejects(Promise.reject(newError('Wrong value')),Error,).then(() => {// ...});const assert =require('node:assert/strict');assert.rejects(Promise.reject(newError('Wrong value')),Error,).then(() => {// ...});copy

error cannot be a string. If a string is provided as the secondargument, thenerror is assumed to be omitted and the string will be used formessage instead. This can lead to easy-to-miss mistakes. Please read theexample inassert.throws() carefully if using a string as the secondargument gets considered.

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

• actual<any>
• expected<any>
• message<string> |<Error>

Tests strict equality between theactual andexpected parameters asdetermined byObject.is().

import assertfrom'node:assert/strict';assert.strictEqual(1,2);// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal://// 1 !== 2assert.strictEqual(1,1);// OKassert.strictEqual('Hello foobar','Hello World!');// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:// + actual - expected//// + 'Hello foobar'// - 'Hello World!'//          ^const apples =1;const oranges =2;assert.strictEqual(apples, oranges,`apples${apples} !== oranges${oranges}`);// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2assert.strictEqual(1,'1',newTypeError('Inputs are not identical'));// TypeError: Inputs are not identicalconst assert =require('node:assert/strict');assert.strictEqual(1,2);// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal://// 1 !== 2assert.strictEqual(1,1);// OKassert.strictEqual('Hello foobar','Hello World!');// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:// + actual - expected//// + 'Hello foobar'// - 'Hello World!'//          ^const apples =1;const oranges =2;assert.strictEqual(apples, oranges,`apples${apples} !== oranges${oranges}`);// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2assert.strictEqual(1,'1',newTypeError('Inputs are not identical'));// TypeError: Inputs are not identicalcopy

If the values are not strictly equal, anAssertionError is thrown with amessage property set equal to the value of themessage parameter. If themessage parameter is undefined, a default error message is assigned. If themessage parameter is an instance of<Error> then it will be throwninstead of theAssertionError.

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

• fn<Function>
• error<RegExp> |<Function> |<Object> |<Error>
• message<string>

Expects the functionfn to throw an error.

If specified,error can be aClass,<RegExp>, a validation function,a validation object where each property will be tested for strict deep equality,or an instance of error where each property will be tested for strict deepequality including the non-enumerablemessage andname properties. Whenusing an object, it is also possible to use a regular expression, whenvalidating against a string property. See below for examples.

If specified,message will be appended to the message provided by theAssertionError if thefn call fails to throw or in case the error validationfails.

Custom validation object/error instance:

import assertfrom'node:assert/strict';const err =newTypeError('Wrong value');err.code =404;err.foo ='bar';err.info = {nested:true,baz:'text',};err.reg =/abc/i;assert.throws(() => {throw err;  },  {name:'TypeError',message:'Wrong value',info: {nested:true,baz:'text',    },// Only properties on the validation object will be tested for.// Using nested objects requires all properties to be present. Otherwise// the validation is going to fail.  },);// Using regular expressions to validate error properties:assert.throws(() => {throw err;  },  {// The `name` and `message` properties are strings and using regular// expressions on those will match against the string. If they fail, an// error is thrown.name:/^TypeError$/,message:/Wrong/,foo:'bar',info: {nested:true,// It is not possible to use regular expressions for nested properties!baz:'text',    },// The `reg` property contains a regular expression and only if the// validation object contains an identical regular expression, it is going// to pass.reg:/abc/i,  },);// Fails due to the different `message` and `name` properties:assert.throws(() => {const otherErr =newError('Not found');// Copy all enumerable properties from `err` to `otherErr`.for (const [key, value]ofObject.entries(err)) {      otherErr[key] = value;    }throw otherErr;  },// The error's `message` and `name` properties will also be checked when using// an error as validation object.  err,);const assert =require('node:assert/strict');const err =newTypeError('Wrong value');err.code =404;err.foo ='bar';err.info = {nested:true,baz:'text',};err.reg =/abc/i;assert.throws(() => {throw err;  },  {name:'TypeError',message:'Wrong value',info: {nested:true,baz:'text',    },// Only properties on the validation object will be tested for.// Using nested objects requires all properties to be present. Otherwise// the validation is going to fail.  },);// Using regular expressions to validate error properties:assert.throws(() => {throw err;  },  {// The `name` and `message` properties are strings and using regular// expressions on those will match against the string. If they fail, an// error is thrown.name:/^TypeError$/,message:/Wrong/,foo:'bar',info: {nested:true,// It is not possible to use regular expressions for nested properties!baz:'text',    },// The `reg` property contains a regular expression and only if the// validation object contains an identical regular expression, it is going// to pass.reg:/abc/i,  },);// Fails due to the different `message` and `name` properties:assert.throws(() => {const otherErr =newError('Not found');// Copy all enumerable properties from `err` to `otherErr`.for (const [key, value]ofObject.entries(err)) {      otherErr[key] = value;    }throw otherErr;  },// The error's `message` and `name` properties will also be checked when using// an error as validation object.  err,);copy

Validate instanceof using constructor:

import assertfrom'node:assert/strict';assert.throws(() => {thrownewError('Wrong value');  },Error,);const assert =require('node:assert/strict');assert.throws(() => {thrownewError('Wrong value');  },Error,);copy

Validate error message using<RegExp>:

Using a regular expression runs.toString on the error object, and willtherefore also include the error name.

import assertfrom'node:assert/strict';assert.throws(() => {thrownewError('Wrong value');  },/^Error: Wrong value$/,);const assert =require('node:assert/strict');assert.throws(() => {thrownewError('Wrong value');  },/^Error: Wrong value$/,);copy

Custom error validation:

The function must returntrue to indicate all internal validations passed.It will otherwise fail with anAssertionError.

import assertfrom'node:assert/strict';assert.throws(() => {thrownewError('Wrong value');  },(err) => {assert(errinstanceofError);assert(/value/.test(err));// Avoid returning anything from validation functions besides `true`.// Otherwise, it's not clear what part of the validation failed. Instead,// throw an error about the specific validation that failed (as done in this// example) and add as much helpful debugging information to that error as// possible.returntrue;  },'unexpected error',);const assert =require('node:assert/strict');assert.throws(() => {thrownewError('Wrong value');  },(err) => {assert(errinstanceofError);assert(/value/.test(err));// Avoid returning anything from validation functions besides `true`.// Otherwise, it's not clear what part of the validation failed. Instead,// throw an error about the specific validation that failed (as done in this// example) and add as much helpful debugging information to that error as// possible.returntrue;  },'unexpected error',);copy

error cannot be a string. If a string is provided as the secondargument, thenerror is assumed to be omitted and the string will be used formessage instead. This can lead to easy-to-miss mistakes. Using the samemessage as the thrown error message is going to result in anERR_AMBIGUOUS_ARGUMENT error. Please read the example below carefully if usinga string as the second argument gets considered:

import assertfrom'node:assert/strict';functionthrowingFirst() {thrownewError('First');}functionthrowingSecond() {thrownewError('Second');}functionnotThrowing() {}// The second argument is a string and the input function threw an Error.// The first case will not throw as it does not match for the error message// thrown by the input function!assert.throws(throwingFirst,'Second');// In the next example the message has no benefit over the message from the// error and since it is not clear if the user intended to actually match// against the error message, Node.js throws an `ERR_AMBIGUOUS_ARGUMENT` error.assert.throws(throwingSecond,'Second');// TypeError [ERR_AMBIGUOUS_ARGUMENT]// The string is only used (as message) in case the function does not throw:assert.throws(notThrowing,'Second');// AssertionError [ERR_ASSERTION]: Missing expected exception: Second// If it was intended to match for the error message do this instead:// It does not throw because the error messages match.assert.throws(throwingSecond,/Second$/);// If the error message does not match, an AssertionError is thrown.assert.throws(throwingFirst,/Second$/);// AssertionError [ERR_ASSERTION]const assert =require('node:assert/strict');functionthrowingFirst() {thrownewError('First');}functionthrowingSecond() {thrownewError('Second');}functionnotThrowing() {}// The second argument is a string and the input function threw an Error.// The first case will not throw as it does not match for the error message// thrown by the input function!assert.throws(throwingFirst,'Second');// In the next example the message has no benefit over the message from the// error and since it is not clear if the user intended to actually match// against the error message, Node.js throws an `ERR_AMBIGUOUS_ARGUMENT` error.assert.throws(throwingSecond,'Second');// TypeError [ERR_AMBIGUOUS_ARGUMENT]// The string is only used (as message) in case the function does not throw:assert.throws(notThrowing,'Second');// AssertionError [ERR_ASSERTION]: Missing expected exception: Second// If it was intended to match for the error message do this instead:// It does not throw because the error messages match.assert.throws(throwingSecond,/Second$/);// If the error message does not match, an AssertionError is thrown.assert.throws(throwingFirst,/Second$/);// AssertionError [ERR_ASSERTION]copy

Due to the confusing error-prone notation, avoid a string as the secondargument.

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

• actual<any>
• expected<any>
• message<string> |<Error>

Tests for partial deep equality between theactual andexpected parameters."Deep" equality means that the enumerable "own" properties of child objectsare recursively evaluated also by the following rules. "Partial" equality meansthat only properties that exist on theexpected parameter are going to becompared.

This method always passes the same test cases asassert.deepStrictEqual(),behaving as a super set of it.

import assertfrom'node:assert';assert.partialDeepStrictEqual(  {a: {b: {c:1 } } },  {a: {b: {c:1 } } },);// OKassert.partialDeepStrictEqual(  {a:1,b:2,c:3 },  {b:2 },);// OKassert.partialDeepStrictEqual(  [1,2,3,4,5,6,7,8,9],  [4,5,8],);// OKassert.partialDeepStrictEqual(newSet([{a:1 }, {b:1 }]),newSet([{a:1 }]),);// OKassert.partialDeepStrictEqual(newMap([['key1','value1'], ['key2','value2']]),newMap([['key2','value2']]),);// OKassert.partialDeepStrictEqual(123n,123n);// OKassert.partialDeepStrictEqual(  [1,2,3,4,5,6,7,8,9],  [5,4,8],);// AssertionErrorassert.partialDeepStrictEqual(  {a:1 },  {a:1,b:2 },);// AssertionErrorassert.partialDeepStrictEqual(  {a: {b:2 } },  {a: {b:'2' } },);// AssertionErrorconst assert =require('node:assert');assert.partialDeepStrictEqual(  {a: {b: {c:1 } } },  {a: {b: {c:1 } } },);// OKassert.partialDeepStrictEqual(  {a:1,b:2,c:3 },  {b:2 },);// OKassert.partialDeepStrictEqual(  [1,2,3,4,5,6,7,8,9],  [4,5,8],);// OKassert.partialDeepStrictEqual(newSet([{a:1 }, {b:1 }]),newSet([{a:1 }]),);// OKassert.partialDeepStrictEqual(newMap([['key1','value1'], ['key2','value2']]),newMap([['key2','value2']]),);// OKassert.partialDeepStrictEqual(123n,123n);// OKassert.partialDeepStrictEqual(  [1,2,3,4,5,6,7,8,9],  [5,4,8],);// AssertionErrorassert.partialDeepStrictEqual(  {a:1 },  {a:1,b:2 },);// AssertionErrorassert.partialDeepStrictEqual(  {a: {b:2 } },  {a: {b:'2' } },);// AssertionErrorcopy