assert 断言 | Node.js v18 文档

断言#

node:assert 模块提供了一组用于验证不变量的断言函数。

英The node:assert module provides a set of assertion functions for verifying invariants.

严格断言模式#

版本历史

版本	变更
v15.0.0	暴露为 `require('node:assert/strict')`。
v13.9.0, v12.16.2	将 "严格模式" 更改为 "严格断言模式"，将 "旧版模式" 更改为 "旧版断言模式"，以避免与 "严格模式" 的更常见含义混淆。
v9.9.0	添加错误差异到严格断言模式。
v9.9.0	添加严格断言模式到断言模块。
v9.9.0	新增于: v9.9.0

在严格断言模式下，非严格方法的行为与其对应的严格方法相同。例如，assert.deepEqual() 的行为类似于 assert.deepStrictEqual()。

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

在严格断言模式下，对象的错误消息显示差异。在旧版断言模式下，对象的错误消息显示对象，通常被截断。

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

使用严格断言模式：

英To use strict assertion mode:

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

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

错误差异的示例：

英Example error diff:

import { strict as 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
//   ]

要停用颜色，则使用 NO_COLOR 或 NODE_DISABLE_COLORS 环境变量。这也将停用交互式解释器中的颜色。有关终端环境中颜色支持的更多信息，请阅读终端 getColorDepth() 文档。

英To deactivate the colors, use the NO_COLOR or NODE_DISABLE_COLORS environment variables. This will also deactivate the colors in the REPL. For more on color support in terminal environments, read the tty getColorDepth() documentation.

旧版断言模式#

旧版断言模式在以下情况下使用 == 操作符：

英Legacy assertion mode uses the == operator in:

要使用旧版断言模式：

英To use legacy assertion mode:

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

旧版断言模式可能会产生意外的结果，尤其是在使用 assert.deepEqual() 时：

英Legacy assertion mode may have surprising results, especially when using assert.deepEqual():

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

类：assert.AssertionError#

继承： <errors.Error>

表示断言的失败。 node:assert 模块抛出的所有错误都是 AssertionError 类的实例。

英Indicates the failure of an assertion. All errors thrown by the node:assert module will be instances of the AssertionError class.

`new assert.AssertionError(options)`#

新增于: v0.1.21

options <Object>
- message <string> 如果提供，则错误消息将设置为此值。
- actual <any> 错误实例上的 actual 属性。
- expected <any> 错误实例上的 expected 属性。
- operator <string> 错误实例上的 operator 属性。
- stackStartFn <Function> 如果提供，则生成的堆栈跟踪将省略此函数之前的帧。

Error 的子类，表示断言的失败。

英A subclass of Error that indicates the failure of an assertion.

所有实例都包含内置的 Error 属性（message 和 name），以及：

英All instances contain the built-in Error properties (message and name) and:

actual <any> 对于 assert.strictEqual() 等方法，设置为 actual 参数。
expected <any> 对于 assert.strictEqual() 等方法，设置为 expected 值。
generatedMessage <boolean> 指示消息是否是自动生成的 (true)。
code <string> 值始终为 ERR_ASSERTION，以表明该错误是断言错误。
operator <string> 设置为传入的运算符值。

import assert from '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(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);
}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(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);
}

类：`assert.CallTracker`#

新增于: v14.2.0, v12.19.0

稳定性: 1 - 实验

此功能目前处于实验阶段，行为可能仍会发生变化。

英This feature is currently experimental and behavior might still change.

`new assert.CallTracker()`#

新增于: v14.2.0, v12.19.0

创建新的 CallTracker 对象，其可用于跟踪函数是否被调用了特定次数。必须调用 tracker.verify() 才能进行验证。通常的模式是在 process.on('exit') 句柄中调用。

英Creates a new CallTracker object which can be used to track if functions were called a specific number of times. The tracker.verify() must be called for the verification to take place. The usual pattern would be to call it in a process.on('exit') handler.

import assert from 'node:assert';
import process from 'node:process';

const tracker = new assert.CallTracker();

function func() {}

// callsfunc() must be called exactly 1 time before tracker.verify().
const callsfunc = tracker.calls(func, 1);

callsfunc();

// Calls tracker.verify() and verifies if all tracker.calls() functions have
// been called exact times.
process.on('exit', () => {
  tracker.verify();
});const assert = require('node:assert');

const tracker = new assert.CallTracker();

function func() {}

// callsfunc() must be called exactly 1 time before tracker.verify().
const callsfunc = tracker.calls(func, 1);

callsfunc();

// Calls tracker.verify() and verifies if all tracker.calls() functions have
// been called exact times.
process.on('exit', () => {
  tracker.verify();
});

`tracker.calls([fn][, exact])`#

新增于: v14.2.0, v12.19.0

fn <Function> 默认值： 空操作函数。
exact <number> 默认值： 1。
返回： <Function> 封装 fn。

预计封装函数将被精确调用 exact 次。如果在调用 tracker.verify() 时函数没有被精确调用 exact 次，那么 tracker.verify() 将抛出错误。

英The wrapper function is expected to be called exactly exact times. If the function has not been called exactly exact times when tracker.verify() is called, then tracker.verify() will throw an error.

import assert from 'node:assert';

// Creates call tracker.
const tracker = new assert.CallTracker();

function func() {}

// Returns a function that wraps func() that must be called exact times
// before tracker.verify().
const callsfunc = tracker.calls(func);const assert = require('node:assert');

// Creates call tracker.
const tracker = new assert.CallTracker();

function func() {}

// Returns a function that wraps func() that must be called exact times
// before tracker.verify().
const callsfunc = tracker.calls(func);

`tracker.getCalls(fn)`#

新增于: v18.8.0

fn <Function>。
返回： <Array> 所有对跟踪函数的调用。
对象 <Object>
- thisArg <Object>
- arguments <Array> 传给被跟踪函数的参数

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] }]);const assert = require('node:assert');

// Creates call tracker.
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()`#

新增于: v14.2.0, v12.19.0

返回： <Array> 包含有关 tracker.calls() 返回的封装函数的信息的对象的数组。
对象 <Object>
- message <string>
- actual <number> 函数被调用的实际次数。
- expected <number> 函数预期被调用的次数。
- operator <string> 被封装的函数的名称。
- stack <Object> 函数的堆栈跟踪。

数组包含有关未调用预期次数的函数的预期和实际调用次数的信息。

英The arrays contains information about the expected and actual number of calls of the functions that have not been called the expected number of times.

import assert from 'node:assert';

// Creates call tracker.
const tracker = new assert.CallTracker();

function func() {}

// Returns a function that wraps func() that must be called exact times
// before tracker.verify().
const callsfunc = tracker.calls(func, 2);

// Returns an array containing information on callsfunc()
console.log(tracker.report());
// [
//  {
//    message: 'Expected the func function to be executed 2 time(s) but was
//    executed 0 time(s).',
//    actual: 0,
//    expected: 2,
//    operator: 'func',
//    stack: stack trace
//  }
// ]const assert = require('node:assert');

// Creates call tracker.
const tracker = new assert.CallTracker();

function func() {}

// Returns a function that wraps func() that must be called exact times
// before tracker.verify().
const callsfunc = tracker.calls(func, 2);

// Returns an array containing information on callsfunc()
console.log(tracker.report());
// [
//  {
//    message: 'Expected the func function to be executed 2 time(s) but was
//    executed 0 time(s).',
//    actual: 0,
//    expected: 2,
//    operator: 'func',
//    stack: stack trace
//  }
// ]

`tracker.reset([fn])`#

新增于: v18.8.0

fn <Function> 要重置的跟踪功能。

重置调用跟踪器的调用。如果被跟踪的函数作为参数传递，调用将被重置。如果没有传递参数，所有被跟踪的函数将被重置

英Reset calls of the call tracker. If a tracked function is passed as an argument, the calls will be reset for it. If no arguments are passed, all tracked functions will be reset

import assert from 'node:assert';

const tracker = new assert.CallTracker();

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

callsfunc();
// Tracker was called once
assert.strictEqual(tracker.getCalls(callsfunc).length, 1);

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

const tracker = new assert.CallTracker();

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

callsfunc();
// Tracker was called once
assert.strictEqual(tracker.getCalls(callsfunc).length, 1);

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

`tracker.verify()`#

新增于: v14.2.0, v12.19.0

遍历传给 tracker.calls() 的函数列表，对于未按预期调用次数的函数将抛出错误。

英Iterates through the list of functions passed to tracker.calls() and will throw an error for functions that have not been called the expected number of times.

import assert from 'node:assert';

// Creates call tracker.
const tracker = new assert.CallTracker();

function func() {}

// Returns a function that wraps func() that must be called exact times
// before tracker.verify().
const callsfunc = tracker.calls(func, 2);

callsfunc();

// Will throw an error since callsfunc() was only called once.
tracker.verify();const assert = require('node:assert');

// Creates call tracker.
const tracker = new assert.CallTracker();

function func() {}

// Returns a function that wraps func() that must be called exact times
// before tracker.verify().
const callsfunc = tracker.calls(func, 2);

callsfunc();

// Will throw an error since callsfunc() was only called once.
tracker.verify();

`assert(value[, message])`#

新增于: v0.5.9

value <any> 检查为真的输入。
message <string> | <Error>

assert.ok() 的别名。

英An alias of assert.ok().

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

版本历史

版本	变更
v18.0.0	现在也比较正则表达式的 lastIndex 属性。
v16.0.0, v14.18.0	在旧版断言模式下，状态从弃用更改为旧版。
v14.0.0	如果双方都是 NaN，则现在 NaN 被视为相同。
v12.0.0	现在可以正确地比较类型标签，并且有一些小的比较调整使检查更少意外。
v9.0.0	现在可以正确地比较 `Error` 名称和消息。
v8.0.0	也比较 `Set` 和 `Map` 的内容。
v6.4.0, v4.7.1	现在可以正确地处理类型化数组切片。
v6.1.0, v4.5.0	现在可以将具有循环引用的对象用作输入。
v5.10.1, v4.4.3	正确地处理非 `Uint8Array` 类型的数组。
v0.1.21	新增于: v0.1.21

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

严格断言模式

英Strict assertion mode

assert.deepStrictEqual() 的别名。

英An alias of assert.deepStrictEqual().

旧版断言模式

英Legacy assertion mode

稳定性: 3 - 旧版：改用 assert.deepStrictEqual()。

测试 actual 和 expected 参数之间的深度相等。考虑使用 assert.deepStrictEqual() 代替。 assert.deepEqual() 可能产生意外的结果。

英Tests for deep equality between the actual and expected parameters. Consider using assert.deepStrictEqual() instead. assert.deepEqual() can have surprising results.

深度相等意味着子对象的可枚举 "自有" 属性也按以下规则递归计算。

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

比较详情#

原始值与 == 操作符进行比较，但 NaN 除外。如果双方都是 NaN，则视为相同。
对象的 Type tags 应该是相同的。
仅考虑可枚举的 "自有" 属性。
Error 名称和消息总是被比较，即使它们不是可枚举的属性。
对象封装器作为对象和展开的值进行比较。
Object 属性是无序比较的。
Map 键和 Set 项是无序比较的。
当双方不同或双方遇到循环引用时，则递归停止。
实现不测试对象的 [[Prototype]]。
不比较 Symbol 属性。
WeakMap 和 WeakSet 的比较不依赖于它们的值。
RegExp 的 lastIndex、flags 和 source 总是被比较，即使它们不是可枚举的属性。

以下示例不会抛出 AssertionError，因为基元是使用 == 操作符进行比较的。

英The following example does not throw an AssertionError because the primitives are compared using the == operator.

import assert from '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);

"深度" 相等意味着子对象的可枚举 "自有" 属性也被评估：

英"Deep" equality means that the enumerable "own" properties of child objects are evaluated also:

import assert from 'node:assert';

const obj1 = {
  a: {
    b: 1,
  },
};
const obj2 = {
  a: {
    b: 2,
  },
};
const obj3 = {
  a: {
    b: 1,
  },
};
const obj4 = Object.create(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 = Object.create(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 {}

如果值不相等，则抛出 AssertionError，其 message 属性设置为等于 message 参数的值。如果未定义 message 参数，则分配默认错误消息。如果 message 参数是 Error 的实例，则将抛出错误而不是 AssertionError。

英If the values are not equal, an AssertionError is thrown with a message property set equal to the value of the message parameter. If the message parameter is undefined, a default error message is assigned. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError.

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

版本历史

版本	变更
v18.0.0	现在也比较正则表达式的 lastIndex 属性。
v9.0.0	现在比较可枚举的符号属性。
v9.0.0	现在使用 SameValueZero 比较来比较 `NaN`。
v8.5.0	现在可以正确地比较 `Error` 名称和消息。
v8.0.0	也比较 `Set` 和 `Map` 的内容。
v6.1.0	现在可以将具有循环引用的对象用作输入。
v6.4.0, v4.7.1	现在可以正确地处理类型化数组切片。
v5.10.1, v4.4.3	正确地处理非 `Uint8Array` 类型的数组。
v1.2.0	新增于: v1.2.0

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

测试 actual 和 expected 参数之间的深度相等。 "深度" 相等意味着子对象的可枚举 "自有" 属性也按以下规则递归计算。

英Tests for deep equality between the actual and expected parameters. "Deep" equality means that the enumerable "own" properties of child objects are recursively evaluated also by the following rules.

比较详情#

使用 Object.is() 比较原始值。
对象的 Type tags 应该是相同的。
使用 === 操作符比较对象的 [[Prototype]]。
仅考虑可枚举的 "自有" 属性。
Error 名称和消息总是被比较，即使它们不是可枚举的属性。
也比较了可枚举的自有 Symbol 属性。
对象封装器作为对象和展开的值进行比较。
Object 属性是无序比较的。
Map 键和 Set 项是无序比较的。
当双方不同或双方遇到循环引用时，则递归停止。
WeakMap 和 WeakSet 的比较不依赖于它们的值。有关更多详细信息，请参见下文。
RegExp 的 lastIndex、flags 和 source 总是被比较，即使它们不是可枚举的属性。

import assert from '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 properties
const date = new Date();
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(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 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
// - -0

const 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 = new WeakMap();
const weakMap2 = new WeakMap([[{}, {}]]);
const weakMap3 = new WeakMap();
weakMap3.unequal = true;

assert.deepStrictEqual(weakMap1, weakMap2);
// OK, because it is impossible to compare the entries

// Fails because weakMap3 has a property that weakMap1 does not contain:
assert.deepStrictEqual(weakMap1, weakMap3);
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
//   WeakMap {
// +   [items unknown]
// -   [items unknown],
// -   unequal: true
//   }const 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 properties
const date = new Date();
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(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 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
// - -0

const 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 = new WeakMap();
const weakMap2 = new WeakMap([[{}, {}]]);
const weakMap3 = new WeakMap();
weakMap3.unequal = true;

assert.deepStrictEqual(weakMap1, weakMap2);
// OK, because it is impossible to compare the entries

// Fails because weakMap3 has a property that weakMap1 does not contain:
assert.deepStrictEqual(weakMap1, weakMap3);
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
//   WeakMap {
// +   [items unknown]
// -   [items unknown],
// -   unequal: true
//   }

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

版本历史

版本	变更
v16.0.0	此 API 不再是实验的。
v13.6.0, v12.16.0	新增于: v13.6.0, v12.16.0

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

期望 string 输入与正则表达式不匹配。

英Expects the string input not to match the regular expression.

import assert from '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/);
// OK

如果值匹配，或者 string 参数的类型不是 string，则抛出 AssertionError，其 message 属性设置为等于 message 参数的值。如果未定义 message 参数，则分配默认错误消息。如果 message 参数是 Error 的实例，则将抛出错误而不是 AssertionError。

英If the values do match, or if the string argument is of another type than string, an AssertionError is thrown with a message property set equal to the value of the message parameter. If the message parameter is undefined, a default error message is assigned. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError.

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

新增于: v10.0.0

asyncFn <Function> | <Promise>
error <RegExp> | <Function>
message <string>

等待 asyncFn promise，或者，如果 asyncFn 是函数，则立即调用该函数并等待返回的 promise 完成。然后会检查 promise 是否没有被拒绝。

英Awaits the asyncFn promise or, if asyncFn is a function, immediately calls the function and awaits the returned promise to complete. It will then check that the promise is not rejected.

如果 asyncFn 是函数并且它同步抛出错误，则 assert.doesNotReject() 将返回使用使用该错误拒绝的 Promise。如果函数没有返回 promise，则 assert.doesNotReject() 将返回使用 ERR_INVALID_RETURN_VALUE 错误拒绝的 Promise。在这两种情况下，都会跳过错误句柄。

英If asyncFn is a function and it throws an error synchronously, assert.doesNotReject() will return a rejected Promise with that error. If the function does not return a promise, assert.doesNotReject() will return a rejected Promise with an ERR_INVALID_RETURN_VALUE error. In both cases the error handler is skipped.

使用 assert.doesNotReject() 实际上没有用，因为捕获拒绝然后再次拒绝它几乎没有什么好处。相反，请考虑在特定代码路径旁边添加不应拒绝的注释，并尽可能使错误消息具有表现力。

英Using assert.doesNotReject() is actually not useful because there is little benefit in catching a rejection and then rejecting it again. Instead, consider adding a comment next to the specific code path that should not reject and keep error messages as expressive as possible.

如果指定，则 error 可以是 Class、RegExp 或验证函数。有关详细信息，请参阅 assert.throws()。

英If specified, error can be a Class, RegExp, or a validation function. See assert.throws() for more details.

除了等待完成的异步性质外，其行为与 assert.doesNotThrow() 相同。

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

import assert from 'node:assert/strict';

await assert.doesNotReject(
  async () => {
    throw new TypeError('Wrong value');
  },
  SyntaxError,
);const assert = require('node:assert/strict');

(async () => {
  await assert.doesNotReject(
    async () => {
      throw new TypeError('Wrong value');
    },
    SyntaxError,
  );
})();

import assert from 'node:assert/strict';

assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
  .then(() => {
    // ...
  });const assert = require('node:assert/strict');

assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
  .then(() => {
    // ...
  });

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

版本历史

版本	变更
v5.11.0, v4.4.5	现在尊重 `message` 参数。
v4.2.0	参数 `error` 现在可以是箭头函数。
v0.1.21	新增于: v0.1.21

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

断言函数 fn 不会抛出错误。

英Asserts that the function fn does not throw an error.

使用 assert.doesNotThrow() 实际上没有用，因为捕获错误然后重新抛出它没有任何好处。相反，请考虑在不应该抛出的特定代码路径旁边添加注释，并尽可能保持错误消息的表现力。

英Using assert.doesNotThrow() is actually not useful because there is no benefit in catching an error and then rethrowing it. Instead, consider adding a comment next to the specific code path that should not throw and keep error messages as expressive as possible.

当 assert.doesNotThrow() 被调用时，它会立即调用 fn 函数。

英When assert.doesNotThrow() is called, it will immediately call the fn function.

如果抛出错误并且它与 error 参数指定的类型相同，则抛出 AssertionError。如果错误属于不同类型，或者 error 参数未定义，则错误将传播回调用者。

英If an error is thrown and it is the same type as that specified by the error parameter, then an AssertionError is thrown. If the error is of a different type, or if the error parameter is undefined, the error is propagated back to the caller.

如果指定，则 error 可以是 Class、RegExp 或验证函数。有关详细信息，请参阅 assert.throws()。

英If specified, error can be a Class, RegExp, or a validation function. See assert.throws() for more details.

例如，以下将抛出 TypeError，因为断言中没有匹配的错误类型：

英The following, for instance, will throw the TypeError because there is no matching error type in the assertion:

import assert from 'node:assert/strict';

assert.doesNotThrow(
  () => {
    throw new TypeError('Wrong value');
  },
  SyntaxError,
);const assert = require('node:assert/strict');

assert.doesNotThrow(
  () => {
    throw new TypeError('Wrong value');
  },
  SyntaxError,
);

但是，以下将导致使用消息 'Got unwanted exception...' 的 AssertionError：

英However, the following will result in an AssertionError with the message 'Got unwanted exception...':

import assert from 'node:assert/strict';

assert.doesNotThrow(
  () => {
    throw new TypeError('Wrong value');
  },
  TypeError,
);const assert = require('node:assert/strict');

assert.doesNotThrow(
  () => {
    throw new TypeError('Wrong value');
  },
  TypeError,
);

如果抛出 AssertionError 并且为 message 参数提供了值，则 message 的值将附加到 AssertionError 消息：

英If an AssertionError is thrown and a value is provided for the message parameter, the value of message will be appended to the AssertionError message:

import assert from 'node:assert/strict';

assert.doesNotThrow(
  () => {
    throw new TypeError('Wrong value');
  },
  /Wrong value/,
  'Whoops',
);
// Throws: AssertionError: Got unwanted exception: Whoopsconst assert = require('node:assert/strict');

assert.doesNotThrow(
  () => {
    throw new TypeError('Wrong value');
  },
  /Wrong value/,
  'Whoops',
);
// Throws: AssertionError: Got unwanted exception: Whoops

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

版本历史

版本	变更
v16.0.0, v14.18.0	在旧版断言模式下，状态从弃用更改为旧版。
v14.0.0	如果双方都是 NaN，则现在 NaN 被视为相同。
v0.1.21	新增于: v0.1.21

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

严格断言模式

英Strict assertion mode

assert.strictEqual() 的别名。

英An alias of assert.strictEqual().

旧版断言模式

英Legacy assertion mode

稳定性: 3 - 旧版：改用 assert.strictEqual()。

使用 == 操作符测试 actual 和 expected 参数之间的浅层强制相等性。 NaN 是特殊处理的，如果双方都是 NaN，则视为相同。

英Tests shallow, coercive equality between the actual and expected parameters using the == operator. NaN is specially handled and treated as being identical if both sides are NaN.

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

`assert.fail([message])`#

新增于: v0.1.21

message <string> | <Error> 默认值： 'Failed'

抛出带有提供的错误消息或默认错误消息的 AssertionError。如果 message 参数是 Error 的实例，则将抛出错误而不是 AssertionError。

英Throws an AssertionError with the provided error message or a default error message. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError.

import assert from 'node:assert/strict';

assert.fail();
// AssertionError [ERR_ASSERTION]: Failed

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

assert.fail(new TypeError('need array'));
// TypeError: need arrayconst assert = require('node:assert/strict');

assert.fail();
// AssertionError [ERR_ASSERTION]: Failed

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

assert.fail(new TypeError('need array'));
// TypeError: need array

可以使用带有两个以上参数的 assert.fail()，但不推荐使用。有关更多详细信息，请参见下文。

英Using assert.fail() with more than two arguments is possible but deprecated. See below for further details.

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

版本历史

版本	变更
v10.0.0	不推荐使用多个参数调用 `assert.fail()` 并触发警告。
v0.1.21	新增于: v0.1.21

稳定性: 0 - 弃用：请改用 assert.fail([message]) 或其他断言函数。

actual <any>
expected <any>
message <string> | <Error>
operator <string> 默认值： '!='
stackStartFn <Function> 默认值： assert.fail

如果 message 为假，则错误消息设置为由提供的 operator 分隔的 actual 和 expected 的值。如果只提供了两个 actual 和 expected 参数，则 operator 将默认为 '!='。如果 message 作为第三个参数提供，则它将用作错误消息，其他参数将作为抛出对象的属性存储。如果提供了 stackStartFn，则该函数之上的所有堆栈帧都将从堆栈跟踪中删除（参见 Error.captureStackTrace）。如果没有给出参数，则将使用默认消息 Failed。

英If message is falsy, the error message is set as the values of actual and expected separated by the provided operator. If just the two actual and expected arguments are provided, operator will default to '!='. If message is provided as third argument it will be used as the error message and the other arguments will be stored as properties on the thrown object. If stackStartFn is provided, all stack frames above that function will be removed from stacktrace (see Error.captureStackTrace). If no arguments are given, the default message Failed will be used.

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, 'fail');
// AssertionError [ERR_ASSERTION]: fail

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

assert.fail(1, 2, new TypeError('need array'));
// TypeError: need arrayconst 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, 'fail');
// AssertionError [ERR_ASSERTION]: fail

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

assert.fail(1, 2, new TypeError('need array'));
// TypeError: need array

在后三种情况下，actual、expected 和 operator 对错误消息没有影响。

英In the last three cases actual, expected, and operator have no influence on the error message.

使用 stackStartFn 截断异常堆栈跟踪的示例：

英Example use of stackStartFn for truncating the exception's stacktrace:

import assert from 'node:assert/strict';

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

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

`assert.ifError(value)`#

版本历史

版本	变更
v10.0.0	其现在被封装到包含完整堆栈跟踪的 [`AssertionError`][`AssertionError`] 中，而不是抛出原始错误。
v10.0.0	值现在可能仅为 `undefined` 或 `null`。之前所有的假值都与 `null` 一样处理并且没有抛出错误。
v0.1.97	新增于: v0.1.97

value <any>

如果 value 不是 undefined 或 null，则抛出 value。这在回调中测试 error 参数时很有用。堆栈跟踪包含来自传给 ifError() 的错误的所有帧，包括 ifError() 本身的潜在新帧。

英Throws value if value is not undefined or null. This is useful when testing the error argument in callbacks. The stack trace contains all frames from the error passed to ifError() including the potential new frames for ifError() itself.

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

// Create some random error frames.
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 errorFrameconst 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

// Create some random error frames.
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])`#

版本历史

版本	变更
v16.0.0	此 API 不再是实验的。
v13.6.0, v12.16.0	新增于: v13.6.0, v12.16.0

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

期望 string 输入与正则表达式匹配。

英Expects the string input to match the regular expression.

import assert from '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/);
// OK

如果值不匹配，或者 string 参数的类型不是 string，则抛出 AssertionError，其 message 属性设置为等于 message 参数的值。如果未定义 message 参数，则分配默认错误消息。如果 message 参数是 Error 的实例，则将抛出错误而不是 AssertionError。

英If the values do not match, or if the string argument is of another type than string, an AssertionError is thrown with a message property set equal to the value of the message parameter. If the message parameter is undefined, a default error message is assigned. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError.

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

版本历史

版本	变更
v16.0.0, v14.18.0	在旧版断言模式下，状态从弃用更改为旧版。
v14.0.0	如果双方都是 NaN，则现在 NaN 被视为相同。
v9.0.0	现在可以正确地比较 `Error` 名称和消息。
v8.0.0	也比较 `Set` 和 `Map` 的内容。
v6.4.0, v4.7.1	现在可以正确地处理类型化数组切片。
v6.1.0, v4.5.0	现在可以将具有循环引用的对象用作输入。
v5.10.1, v4.4.3	正确地处理非 `Uint8Array` 类型的数组。
v0.1.21	新增于: v0.1.21

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

严格断言模式

英Strict assertion mode

assert.notDeepStrictEqual() 的别名。

英An alias of assert.notDeepStrictEqual().

旧版断言模式

英Legacy assertion mode

稳定性: 3 - 旧版：改用 assert.notDeepStrictEqual()。

测试任何深度不相等。 assert.deepEqual() 的相反。

英Tests for any deep inequality. Opposite of assert.deepEqual().

import assert from 'node:assert';

const obj1 = {
  a: {
    b: 1,
  },
};
const obj2 = {
  a: {
    b: 2,
  },
};
const obj3 = {
  a: {
    b: 1,
  },
};
const obj4 = Object.create(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);
// OKconst assert = require('node:assert');

const obj1 = {
  a: {
    b: 1,
  },
};
const obj2 = {
  a: {
    b: 2,
  },
};
const obj3 = {
  a: {
    b: 1,
  },
};
const obj4 = Object.create(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

如果值深度相等，则会抛出 AssertionError，其 message 属性设置为等于 message 参数的值。如果未定义 message 参数，则分配默认错误消息。如果 message 参数是 Error 的实例，则将抛出错误而不是 AssertionError。

英If the values are deeply equal, an AssertionError is thrown with a message property set equal to the value of the message parameter. If the message parameter is undefined, a default error message is assigned. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError.

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

版本历史

版本	变更
v9.0.0	不再将 `-0` 和 `+0` 视为相等。
v9.0.0	现在使用 SameValueZero 比较来比较 `NaN`。
v9.0.0	现在可以正确地比较 `Error` 名称和消息。
v8.0.0	也比较 `Set` 和 `Map` 的内容。
v6.1.0	现在可以将具有循环引用的对象用作输入。
v6.4.0, v4.7.1	现在可以正确地处理类型化数组切片。
v5.10.1, v4.4.3	正确地处理非 `Uint8Array` 类型的数组。
v1.2.0	新增于: v1.2.0

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

检验深度严格不相等。 assert.deepStrictEqual() 的相反。

英Tests for deep strict inequality. Opposite of assert.deepStrictEqual().

import assert from 'node:assert/strict';

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

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

如果值是深度且严格相等的，则抛出 AssertionError，其 message 属性设置为等于 message 参数的值。如果未定义 message 参数，则分配默认错误消息。如果 message 参数是 Error 的实例，则将抛出错误而不是 AssertionError。

英If the values are deeply and strictly equal, an AssertionError is thrown with a message property set equal to the value of the message parameter. If the message parameter is undefined, a default error message is assigned. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError.

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

版本历史

版本	变更
v16.0.0, v14.18.0	在旧版断言模式下，状态从弃用更改为旧版。
v14.0.0	如果双方都是 NaN，则现在 NaN 被视为相同。
v0.1.21	新增于: v0.1.21

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

严格断言模式

英Strict assertion mode

assert.notStrictEqual() 的别名。

英An alias of assert.notStrictEqual().

旧版断言模式

英Legacy assertion mode

稳定性: 3 - 旧版：改用 assert.notStrictEqual()。

使用 != 操作符测试肤浅的强制性不平等。 NaN 是特殊处理的，如果双方都是 NaN，则视为相同。

英Tests shallow, coercive inequality with the != operator. NaN is specially handled and treated as being identical if both sides are NaN.

import assert from 'node:assert';

assert.notEqual(1, 2);
// OK

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

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

assert.notEqual(1, 2);
// OK

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

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

如果值相等，则抛出 AssertionError，其 message 属性设置为等于 message 参数的值。如果未定义 message 参数，则分配默认错误消息。如果 message 参数是 Error 的实例，则将抛出错误而不是 AssertionError。

英If the values are equal, an AssertionError is thrown with a message property set equal to the value of the message parameter. If the message parameter is undefined, a default error message is assigned. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError.

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

版本历史

版本	变更
v10.0.0	使用的比较从严格相等更改为 `Object.is()`。
v0.1.21	新增于: v0.1.21

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

测试由 Object.is() 确定的 actual 和 expected 参数之间的严格不相等。

英Tests strict inequality between the actual and expected parameters as determined by Object.is().

import assert from 'node:assert/strict';

assert.notStrictEqual(1, 2);
// OK

assert.notStrictEqual(1, 1);
// AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to:
//
// 1

assert.notStrictEqual(1, '1');
// OKconst assert = require('node:assert/strict');

assert.notStrictEqual(1, 2);
// OK

assert.notStrictEqual(1, 1);
// AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to:
//
// 1

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

如果值严格相等，则抛出 AssertionError，其 message 属性设置为等于 message 参数的值。如果未定义 message 参数，则分配默认错误消息。如果 message 参数是 Error 的实例，则将抛出错误而不是 AssertionError。

英If the values are strictly equal, an AssertionError is thrown with a message property set equal to the value of the message parameter. If the message parameter is undefined, a default error message is assigned. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError.

`assert.ok(value[, message])`#

版本历史

版本	变更
v10.0.0	无参数的 `assert.ok()` 现在将使用预定义的错误消息。
v0.1.21	新增于: v0.1.21

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

测试 value 是否为真。相当于 assert.equal(!!value, true, message)。

英Tests if value is truthy. It is equivalent to assert.equal(!!value, true, message).

如果 value 不是真值，则抛出 AssertionError，其 message 属性设置为等于 message 参数的值。如果 message 参数为 undefined，则分配默认错误消息。如果 message 参数是 Error 的实例，则将抛出错误而不是 AssertionError。如果根本没有传入任何参数，message 将被设置为字符串： 'No value argument passed to `assert.ok()`'。

英If value is not truthy, an AssertionError is thrown with a message property set equal to the value of the message parameter. If the message parameter is undefined, a default error message is assigned. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError. If no arguments are passed in at all message will be set to the string: 'No value argument passed to `assert.ok()`'.

请注意，在 repl 中，错误消息将与文件中抛出的错误消息不同！有关更多详细信息，请参见下文。

英Be aware that in the repl the error message will be different to the one thrown in a file! See below for further details.

import assert from 'node:assert/strict';

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

assert.ok();
// AssertionError: No value argument passed to `assert.ok()`

assert.ok(false, 'it\'s false');
// AssertionError: it's false

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

// In a file (e.g. test.js):
assert.ok(typeof 123 === '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)const assert = require('node:assert/strict');

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

assert.ok();
// AssertionError: No value argument passed to `assert.ok()`

assert.ok(false, 'it\'s false');
// AssertionError: it's false

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

// In a file (e.g. test.js):
assert.ok(typeof 123 === '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 assert from 'node:assert/strict';

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

// Using `assert()` works the same:
assert(0);
// AssertionError: The expression evaluated to a falsy value:
//
//   assert(0)

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

新增于: v10.0.0

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

等待 asyncFn promise，或者，如果 asyncFn 是函数，则立即调用该函数并等待返回的 promise 完成。然后将检查 promise 是否被拒绝。

英Awaits the asyncFn promise or, if asyncFn is a function, immediately calls the function and awaits the returned promise to complete. It will then check that the promise is rejected.

如果 asyncFn 是函数并且它同步抛出错误，则 assert.rejects() 将返回使用使用该错误拒绝的 Promise。如果函数没有返回 promise，则 assert.rejects() 将返回使用 ERR_INVALID_RETURN_VALUE 错误拒绝的 Promise。在这两种情况下，都会跳过错误句柄。

英If asyncFn is a function and it throws an error synchronously, assert.rejects() will return a rejected Promise with that error. If the function does not return a promise, assert.rejects() will return a rejected Promise with an ERR_INVALID_RETURN_VALUE error. In both cases the error handler is skipped.

除了等待完成的异步性质外，其行为与 assert.throws() 相同。

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

如果指定，则 error 可以是 Class、RegExp、验证函数、每个属性将被测试的对象，或者每个属性（包括不可枚举的 message 和 name 属性）将被测试的错误实例。

英If specified, error can be a Class, RegExp, a validation function, an object where each property will be tested for, or an instance of error where each property will be tested for including the non-enumerable message and name properties.

如果指定，则 message 将是 AssertionError 提供的消息（如果 asyncFn 没有被拒绝）。

英If specified, message will be the message provided by the AssertionError if the asyncFn fails to reject.

import assert from 'node:assert/strict';

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

(async () => {
  await assert.rejects(
    async () => {
      throw new TypeError('Wrong value');
    },
    {
      name: 'TypeError',
      message: 'Wrong value',
    },
  );
})();

import assert from 'node:assert/strict';

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

(async () => {
  await assert.rejects(
    async () => {
      throw new TypeError('Wrong value');
    },
    (err) => {
      assert.strictEqual(err.name, 'TypeError');
      assert.strictEqual(err.message, 'Wrong value');
      return true;
    },
  );
})();

import assert from 'node:assert/strict';

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

assert.rejects(
  Promise.reject(new Error('Wrong value')),
  Error,
).then(() => {
  // ...
});

error 不能是字符串。如果提供字符串作为第二个参数，则假定 error 被省略，而该字符串将用于 message。这可能会导致容易遗漏的错误。如果考虑使用字符串作为第二个参数，则请仔细阅读 assert.throws() 中的示例。

英error cannot be a string. If a string is provided as the second argument, then error is assumed to be omitted and the string will be used for message instead. This can lead to easy-to-miss mistakes. Please read the example in assert.throws() carefully if using a string as the second argument gets considered.

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

版本历史

版本	变更
v10.0.0	使用的比较从严格相等更改为 `Object.is()`。
v0.1.21	新增于: v0.1.21

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

测试由 Object.is() 确定的 actual 和 expected 参数之间的严格相等。

英Tests strict equality between the actual and expected parameters as determined by Object.is().

import assert from 'node:assert/strict';

assert.strictEqual(1, 2);
// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
//
// 1 !== 2

assert.strictEqual(1, 1);
// OK

assert.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 2

assert.strictEqual(1, '1', new TypeError('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 !== 2

assert.strictEqual(1, 1);
// OK

assert.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 2

assert.strictEqual(1, '1', new TypeError('Inputs are not identical'));
// TypeError: Inputs are not identical

如果值不严格相等，则抛出 AssertionError，其 message 属性设置为等于 message 参数的值。如果未定义 message 参数，则分配默认错误消息。如果 message 参数是 Error 的实例，则将抛出错误而不是 AssertionError。

英If the values are not strictly equal, an AssertionError is thrown with a message property set equal to the value of the message parameter. If the message parameter is undefined, a default error message is assigned. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError.

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

版本历史

版本	变更
v10.2.0	参数 `error` 现在可以是包含正则表达式的对象。
v9.9.0	参数 `error` 现在也可以是对象。
v4.2.0	参数 `error` 现在可以是箭头函数。
v0.1.21	新增于: v0.1.21

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

期望函数 fn 抛出错误。

英Expects the function fn to throw an error.

如果指定，则 error 可以是 Class、RegExp、验证函数、其中每个属性都将进行严格深度相等测试的验证对象，或者其中每个属性（包括不可枚举的 message 和 name 属性）都将进行严格深度相等测试的错误实例。使用对象时，也可以使用正则表达式来验证字符串属性。有关示例，请参见下文。

英If specified, error can be a Class, 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 deep equality including the non-enumerable message and name properties. When using an object, it is also possible to use a regular expression, when validating against a string property. See below for examples.

如果指定，且如果 fn 调用失败或错误验证失败，则 message 将附加到 AssertionError 提供的消息。

英If specified, message will be appended to the message provided by the AssertionError if the fn call fails to throw or in case the error validation fails.

自定义验证对象/错误实例：

英Custom validation object/error instance:

import assert from 'node:assert/strict';

const err = new TypeError('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 = new Error('Not found');
    // Copy all enumerable properties from `err` to `otherErr`.
    for (const [key, value] of Object.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 = new TypeError('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 = new Error('Not found');
    // Copy all enumerable properties from `err` to `otherErr`.
    for (const [key, value] of Object.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,
);

使用构造函数验证 instanceof：

英Validate instanceof using constructor:

import assert from 'node:assert/strict';

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  Error,
);const assert = require('node:assert/strict');

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  Error,
);

使用 RegExp 验证错误消息：

英Validate error message using RegExp:

使用正则表达式在错误对象上运行 .toString，因此还将包含错误名称。

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

import assert from 'node:assert/strict';

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  /^Error: Wrong value$/,
);const assert = require('node:assert/strict');

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  /^Error: Wrong value$/,
);

自定义错误验证：

英Custom error validation:

该函数必须返回 true 以指示通过了所有内部验证。否则它将因 AssertionError 而失败。

英The function must return true to indicate all internal validations passed. It will otherwise fail with an AssertionError.

import assert from 'node:assert/strict';

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  (err) => {
    assert(err instanceof Error);
    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.
    return true;
  },
  'unexpected error',
);const assert = require('node:assert/strict');

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  (err) => {
    assert(err instanceof Error);
    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.
    return true;
  },
  'unexpected error',
);

error 不能是字符串。如果提供字符串作为第二个参数，则假定 error 被省略，而该字符串将用于 message。这可能会导致容易遗漏的错误。使用与抛出的错误消息相同的消息将导致 ERR_AMBIGUOUS_ARGUMENT 错误。如果考虑使用字符串作为第二个参数，则请仔细阅读下面的示例：

英error cannot be a string. If a string is provided as the second argument, then error is assumed to be omitted and the string will be used for message instead. This can lead to easy-to-miss mistakes. Using the same message as the thrown error message is going to result in an ERR_AMBIGUOUS_ARGUMENT error. Please read the example below carefully if using a string as the second argument gets considered:

import assert from 'node:assert/strict';

function throwingFirst() {
  throw new Error('First');
}

function throwingSecond() {
  throw new Error('Second');
}

function notThrowing() {}

// 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');

function throwingFirst() {
  throw new Error('First');
}

function throwingSecond() {
  throw new Error('Second');
}

function notThrowing() {}

// 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]

由于容易混淆的符号，请避免将字符串作为第二个参数。

英Due to the confusing error-prone notation, avoid a string as the second argument.

断言#

严格断言模式#

旧版断言模式#

类：assert.AssertionError#

new assert.AssertionError(options)#

类：assert.CallTracker#

new assert.CallTracker()#

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

tracker.getCalls(fn)#

tracker.report()#

tracker.reset([fn])#

tracker.verify()#

assert(value[, message])#

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

比较详情#

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

比较详情#

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

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

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

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

assert.fail([message])#

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

assert.ifError(value)#

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

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

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

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

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

assert.ok(value[, message])#

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

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

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

`new assert.AssertionError(options)`#

类：`assert.CallTracker`#

`new assert.CallTracker()`#

`tracker.calls([fn][, exact])`#

`tracker.getCalls(fn)`#

`tracker.report()`#

`tracker.reset([fn])`#

`tracker.verify()`#

`assert(value[, message])`#

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

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

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

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

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

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

`assert.fail([message])`#

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

`assert.ifError(value)`#

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

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

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

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

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

`assert.ok(value[, message])`#

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

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

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