Node.js v16.13.0 文档

目录

assert 断言#

中英对照

稳定性: 2 - 稳定

源代码: lib/assert.js

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

严格断言模式#

中英对照

版本历史
版本变更
v15.0.0

暴露为 require('assert/strict')。

v13.9.0, v12.16.2

将“严格模式”更改为“严格断言模式”，将“旧版模式”更改为“旧版断言模式”，以避免与“严格模式”更常见的含义混淆。

v9.9.0

添加错误差异到严格断言模式。

v9.9.0

添加严格断言模式到断言模块。

v9.9.0

新增于: v9.9.0

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

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

使用严格断言模式：

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

错误差异的示例：

import { strict as assert } from '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('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() 文档。

旧版断言模式#

中英对照

旧版断言模式在以下方法中使用抽象相等比较：

要使用旧版断言模式：

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

尽可能改用严格断言模式。 否则，抽象相等比较可能会导致意外的结果。 对于 assert.deepEqual() 尤其如此，其比较规则很宽松：

// 注意：这不会抛出 AssertionError！
assert.deepEqual(/a/gi, new Date());

assert.AssertionError 类#

中英对照

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

new assert.AssertionError(options)#

中英对照

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

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

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

import assert from 'assert';

// 生成 AssertionError，以便稍后比较错误信息：
const { message } = new assert.AssertionError({
  actual: 1,
  expected: 2,
  operator: 'strictEqual'
});

// 验证错误的输出：
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('assert');

// 生成 AssertionError，以便稍后比较错误信息：
const { message } = new assert.AssertionError({
  actual: 1,
  expected: 2,
  operator: 'strictEqual'
});

// 验证错误的输出：
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 - 实验

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

new assert.CallTracker()#

中英对照

新增于: v14.2.0, v12.19.0

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

import assert from 'assert';
import process from 'process';

const tracker = new assert.CallTracker();

function func() {}

// callfunc() 必须在 tracker.verify() 之前恰好被调用 1 次。
const callsfunc = tracker.calls(func, 1);

callsfunc();

// 调用 tracker.verify() 并验证是否所有 tracker.calls() 函数都已被准确调用。
process.on('exit', () => {
  tracker.verify();
});const assert = require('assert');

const tracker = new assert.CallTracker();

function func() {}

// callfunc() 必须在 tracker.verify() 之前恰好被调用 1 次。
const callsfunc = tracker.calls(func, 1);

callsfunc();

// 调用 tracker.verify() 并验证是否所有 tracker.calls() 函数都已被准确调用。
process.on('exit', () => {
  tracker.verify();
});

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

中英对照

新增于: v14.2.0, v12.19.0

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

import assert from 'assert';

// 创建调用跟踪器。
const tracker = new assert.CallTracker();

function func() {}

// 返回封装 func() 的函数，其必须在 tracker.verify() 之前调用准确次数。
const callsfunc = tracker.calls(func);const assert = require('assert');

// 创建调用跟踪器。
const tracker = new assert.CallTracker();

function func() {}

// 返回封装 func() 的函数，其必须在 tracker.verify() 之前调用准确次数。
const callsfunc = tracker.calls(func);

tracker.report()#

中英对照

新增于: v14.2.0, v12.19.0

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

import assert from 'assert';

// 创建调用跟踪器。
const tracker = new assert.CallTracker();

function func() {}

function foo() {}

// 返回封装 func() 的函数，其必须在 tracker.verify() 之前调用准确次数。
const callsfunc = tracker.calls(func, 2);

// 返回包含 callfunc() 信息的数组()
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('assert');

// 创建调用跟踪器。
const tracker = new assert.CallTracker();

function func() {}

function foo() {}

// 返回封装 func() 的函数，其必须在 tracker.verify() 之前调用准确次数。
const callsfunc = tracker.calls(func, 2);

// 返回包含 callfunc() 信息的数组()
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.verify()#

中英对照

新增于: v14.2.0, v12.19.0

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

import assert from 'assert';

// 创建调用跟踪器。
const tracker = new assert.CallTracker();

function func() {}

// 返回封装 func() 的函数，其必须在 tracker.verify() 之前调用准确次数。
const callsfunc = tracker.calls(func, 2);

callsfunc();

// 会抛出错误，因为 callfunc() 只被调用了一次。
tracker.verify();const assert = require('assert');

// 创建调用跟踪器。
const tracker = new assert.CallTracker();

function func() {}

// 返回封装 func() 的函数，其必须在 tracker.verify() 之前调用准确次数。
const callsfunc = tracker.calls(func, 2);

callsfunc();

// 会抛出错误，因为 callfunc() 只被调用了一次。
tracker.verify();

assert(value[, message])#

中英对照

新增于: v0.5.9

assert.ok() 的别名。

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

中英对照

版本历史
版本变更
v16.0.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

严格断言模式

assert.deepStrictEqual() 的别名。

旧版断言模式

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

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

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

比较详情#

中英对照

  • 除 NaN 外，原始值使用抽象相等比较（==）进行比较。 如果双方都是 NaN，则视为相同。
  • 对象的类型标签应该是一样的。
  • 仅考虑自有属性。
  • Error 名称和消息总是被比较，即使它们不是可枚举的属性。
  • 对象封装器作为对象和未封装的值进行比较。
  • Object 属性是无序比较的。
  • Map 键和 Set 项是无序比较的。
  • 当双方不同或双方遇到循环引用时，则递归停止。
  • 实现不测试对象的 [[Prototype]]。
  • 不比较 Symbol 属性。
  • WeakMap 和 WeakSet 的比较不依赖于它们的值。

以下示例不会抛出 AssertionError，因为抽象相等比较（==）认为原始值相等。

import assert from 'assert';
// 注意：这不会抛出 AssertionError！

assert.deepEqual('+00000000', false);const assert = require('assert');
// 注意：这不会抛出 AssertionError！

assert.deepEqual('+00000000', false);

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

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

// b 的值不同：
assert.deepEqual(obj1, obj2);
// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }

assert.deepEqual(obj1, obj3);
// OK

// 原型被忽略：
assert.deepEqual(obj1, obj4);
// AssertionError: { a: { b: 1 } } deepEqual {}const assert = require('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

// b 的值不同：
assert.deepEqual(obj1, obj2);
// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }

assert.deepEqual(obj1, obj3);
// OK

// 原型被忽略：
assert.deepEqual(obj1, obj4);
// AssertionError: { a: { b: 1 } } deepEqual {}

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

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

中英对照

版本历史
版本变更
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 和 expected 参数之间的深度相等。 "深度"相等意味着子对象的可枚举"自有"属性也按照以下规则递归地评估。

比较详情#

中英对照 

import assert from 'assert/strict';

// 这失败了，因为 1 !== '1'。
assert.deepStrictEqual({ a: 1 }, { a: '1' });
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
//   {
// +   a: 1
// -   a: '1'
//   }

// 以下对象没有自有的属性
const date = new Date();
const object = {};
const fakeDate = {};
Object.setPrototypeOf(fakeDate, Date.prototype);

// 不同的原型：
assert.deepStrictEqual(object, fakeDate);
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + {}
// - Date {}

// 不同的类型标签：
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，因为 SameValue 比较

// 不同的解封装数字：
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，因为对象和字符串在解封装时是相同的。

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

// 使用 SameValue 比较的不同零：
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，因为它是两个对象上的相同符号。

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，因为无法比较条目

// 失败，因为 weakMap3 有一个 weakMap1 不包含的属性：
assert.deepStrictEqual(weakMap1, weakMap3);
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
//   WeakMap {
// +   [items unknown]
// -   [items unknown],
// -   unequal: true
//   }const assert = require('assert/strict');

// 这失败了，因为 1 !== '1'。
assert.deepStrictEqual({ a: 1 }, { a: '1' });
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
//   {
// +   a: 1
// -   a: '1'
//   }

// 以下对象没有自有的属性
const date = new Date();
const object = {};
const fakeDate = {};
Object.setPrototypeOf(fakeDate, Date.prototype);

// 不同的原型：
assert.deepStrictEqual(object, fakeDate);
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + {}
// - Date {}

// 不同的类型标签：
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，因为 SameValue 比较

// 不同的解封装数字：
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，因为对象和字符串在解封装时是相同的。

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

// 使用 SameValue 比较的不同零：
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，因为它是两个对象上的相同符号。

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，因为无法比较条目

// 失败，因为 weakMap3 有一个 weakMap1 不包含的属性：
assert.deepStrictEqual(weakMap1, weakMap3);
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
//   WeakMap {
// +   [items unknown]
// -   [items unknown],
// -   unequal: true
//   }

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

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

中英对照

版本历史
版本变更
v16.0.0

此 API 不再是实验的。

v13.6.0, v12.16.0

新增于: v13.6.0, v12.16.0

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

import assert from '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('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。

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

中英对照

新增于: v10.0.0

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

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

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

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

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

import assert from 'assert/strict';

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

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

assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
  .then(() => {
    // ...
  });const assert = require('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 不会抛出错误。

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

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

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

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

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

import assert from 'assert/strict';

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

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

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

import assert from 'assert/strict';

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

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

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

import assert from 'assert/strict';

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

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

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

中英对照

版本历史
版本变更
v16.0.0

在旧版断言模式下，状态从弃用更改为旧版。

v14.0.0

如果双方都是 NaN，则现在 NaN 被视为相同。

v0.1.21

新增于: v0.1.21

严格断言模式

assert.strictEqual() 的别名。

旧版断言模式

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

使用抽象相等比较（==）测试 actual 和 expected 参数之间的浅层强制相等。 NaN 是特殊处理的，如果双方都是 NaN，则视为相同。

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

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

assert.fail([message])#

中英对照

新增于: v0.1.21

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

import assert from '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('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()，但不推荐使用。 有关更多详细信息，请参见下文。

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

中英对照

版本历史
版本变更
v10.0.0

不推荐使用多个参数调用 assert.fail() 并触发警告。

v0.1.21

新增于: v0.1.21

稳定性: 0 - 弃用: 改为使用 assert.fail([message]) 或其他 assert 函数。

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

import assert from '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('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 对错误消息没有影响。

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

import assert from '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('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][] 中，而不是抛出原始错误。

v10.0.0

值现在可能仅为 undefined 或 null。 之前所有的假值都与 null 一样处理并且没有抛出错误。

v0.1.97

新增于: v0.1.97

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

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

// 创建一些随机错误帧。
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('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

// 创建一些随机错误帧。
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 输入与正则表达式匹配。

import assert from '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('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。

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

中英对照

版本历史
版本变更
v16.0.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

严格断言模式

assert.notDeepStrictEqual() 的别名。

旧版断言模式

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

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

import assert from '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('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。

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

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

import assert from 'assert/strict';

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

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

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

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

中英对照

版本历史
版本变更
v16.0.0

在旧版断言模式下，状态从弃用更改为旧版。

v14.0.0

如果双方都是 NaN，则现在 NaN 被视为相同。

v0.1.21

新增于: v0.1.21

严格断言模式

assert.notStrictEqual() 的别名。

旧版断言模式

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

使用抽象相等比较（!=）测试浅层强制不相等。 NaN 是特殊处理的，如果双方都是 NaN，则视为相同。

import assert from 'assert';

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

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

assert.notEqual(1, '1');
// AssertionError: 1 != '1'const assert = require('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。

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

中英对照

版本历史
版本变更
v10.0.0

使用的比较从严格相等更改为 Object.is()。

v0.1.21

新增于: v0.1.21

测试由 SameValue 比较 确定的 actual 和 expected 参数之间的严格不相等。

import assert from '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('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。

assert.ok(value[, message])#

中英对照

版本历史
版本变更
v10.0.0

无参数的 assert.ok() 现在将使用预定义的错误消息。

v0.1.21

新增于: v0.1.21

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

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

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

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

// 在交互式解释器中：
assert.ok(typeof 123 === 'string');
// AssertionError: false == true

// 在文件中（例如 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('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

// 在交互式解释器中：
assert.ok(typeof 123 === 'string');
// AssertionError: false == true

// 在文件中（例如 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 'assert/strict';

// 使用 `assert()` 的工作一样：
assert(0);
// AssertionError: The expression evaluated to a falsy value:
//
//   assert(0)const assert = require('assert');

// 使用 `assert()` 的工作一样：
assert(0);
// AssertionError: The expression evaluated to a falsy value:
//
//   assert(0)

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

中英对照

新增于: v10.0.0

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

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

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

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

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

import assert from 'assert/strict';

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

(async () => {
  await assert.rejects(
    async () => {
      throw new TypeError('Wrong value');
    },
    {
      name: 'TypeError',
      message: 'Wrong value'
    }
  );
})();
import assert from '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('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 'assert/strict';

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

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

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

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

中英对照

版本历史
版本变更
v10.0.0

使用的比较从严格相等更改为 Object.is()。

v0.1.21

新增于: v0.1.21

测试由 SameValue 比较 确定的 actual 和 expected 参数之间的严格相等。

import assert from '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('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。

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

中英对照

版本历史
版本变更
v10.2.0

参数 error 现在可以是包含正则表达式的对象。

v9.9.0

参数 error 现在也可以是对象。

v4.2.0

参数 error 现在可以是箭头函数。

v0.1.21

新增于: v0.1.21

期望函数 fn 抛出错误。

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

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

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

import assert from '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'
    }
    // 只会测试验证对象上的属性。
    // 使用嵌套对象需要存在所有属性。
    // 否则验证将失败。
  }
);

// 使用正则表达式验证错误属性：
throws(
  () => {
    throw err;
  },
  {
    // `name` 和 `message` 属性是字符串，在这些属性上使用正则表达式将匹配字符串。
    // 如果失败，则会抛出错误。
    name: /^TypeError$/,
    message: /Wrong/,
    foo: 'bar',
    info: {
      nested: true,
      // 不能对嵌套属性使用正则表达式！
      baz: 'text'
    },
    // `reg` 属性包含正则表达式，只有当验证对象包含相同的正则表达式时，它才会通过。
    reg: /abc/i
  }
);

// 由于不同的 `message` 和 `name` 属性而失败：
throws(
  () => {
    const otherErr = new Error('Not found');
    // 将所有可枚举属性从 `err` 复制到 `otherErr`。
    for (const [key, value] of Object.entries(err)) {
      otherErr[key] = value;
    }
    throw otherErr;
  },
  // 当使用错误作为验证对象时，错误的 `message` 和 `name` 属性也将被检查。
  err
);const assert = require('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'
    }
    // 只会测试验证对象上的属性。
    // 使用嵌套对象需要存在所有属性。
    // 否则验证将失败。
  }
);

// 使用正则表达式验证错误属性：
throws(
  () => {
    throw err;
  },
  {
    // `name` 和 `message` 属性是字符串，在这些属性上使用正则表达式将匹配字符串。
    // 如果失败，则会抛出错误。
    name: /^TypeError$/,
    message: /Wrong/,
    foo: 'bar',
    info: {
      nested: true,
      // 不能对嵌套属性使用正则表达式！
      baz: 'text'
    },
    // `reg` 属性包含正则表达式，只有当验证对象包含相同的正则表达式时，它才会通过。
    reg: /abc/i
  }
);

// 由于不同的 `message` 和 `name` 属性而失败：
throws(
  () => {
    const otherErr = new Error('Not found');
    // 将所有可枚举属性从 `err` 复制到 `otherErr`。
    for (const [key, value] of Object.entries(err)) {
      otherErr[key] = value;
    }
    throw otherErr;
  },
  // 当使用错误作为验证对象时，错误的 `message` 和 `name` 属性也将被检查。
  err
);

使用构造函数验证 instanceof：

import assert from 'assert/strict';

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

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

使用 RegExp 验证错误消息：

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

import assert from 'assert/strict';

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

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

自定义错误验证：

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

import assert from 'assert/strict';

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  (err) => {
    assert(err instanceof Error);
    assert(/value/.test(err));
    // 避免从验证函数返回除 `true` 之外的任何内容。
    // 否则，不清楚验证的哪一部分失败。而是，抛出有关失败的特定验证的错误（如本示例中所做的那样），并尽可能多地向该错误添加有用的调试信息。
    return true;
  },
  'unexpected error'
);const assert = require('assert/strict');

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  (err) => {
    assert(err instanceof Error);
    assert(/value/.test(err));
    // 避免从验证函数返回除 `true` 之外的任何内容。
    // 否则，不清楚验证的哪一部分失败。而是，抛出有关失败的特定验证的错误（如本示例中所做的那样），并尽可能多地向该错误添加有用的调试信息。
    return true;
  },
  'unexpected error'
);

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

import assert from 'assert/strict';

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

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

function notThrowing() {}

// 第二个参数是字符串，且输入函数抛出错误。
// 第一种情况不会抛出错误，因为它与输入函数抛出的错误消息不匹配！
assert.throws(throwingFirst, 'Second');
// 在下一个示例中，该消息与错误消息相比没有任何好处，并且由于不清楚用户是否打算实际匹配错误消息，Node.js 会抛出 `ERR_AMBIGUOUS_ARGUMENT` 错误。
assert.throws(throwingSecond, 'Second');
// TypeError [ERR_AMBIGUOUS_ARGUMENT]

// 该字符串仅在函数不抛出的情况下（作为消息）使用：
assert.throws(notThrowing, 'Second');
// AssertionError [ERR_ASSERTION]: Missing expected exception: Second

// 如果它旨在匹配错误消息，则执行以下操作：
// 它不会抛出错误，因为错误消息匹配。
assert.throws(throwingSecond, /Second$/);

// 如果错误消息不匹配，则抛出 AssertionError。
assert.throws(throwingFirst, /Second$/);
// AssertionError [ERR_ASSERTION]const assert = require('assert/strict');

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

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

function notThrowing() {}

// 第二个参数是字符串，且输入函数抛出错误。
// 第一种情况不会抛出错误，因为它与输入函数抛出的错误消息不匹配！
assert.throws(throwingFirst, 'Second');
// 在下一个示例中，该消息与错误消息相比没有任何好处，并且由于不清楚用户是否打算实际匹配错误消息，Node.js 会抛出 `ERR_AMBIGUOUS_ARGUMENT` 错误。
assert.throws(throwingSecond, 'Second');
// TypeError [ERR_AMBIGUOUS_ARGUMENT]

// 该字符串仅在函数不抛出的情况下（作为消息）使用：
assert.throws(notThrowing, 'Second');
// AssertionError [ERR_ASSERTION]: Missing expected exception: Second

// 如果它旨在匹配错误消息，则执行以下操作：
// 它不会抛出错误，因为错误消息匹配。
assert.throws(throwingSecond, /Second$/);

// 如果错误消息不匹配，则抛出 AssertionError。
assert.throws(throwingFirst, /Second$/);
// AssertionError [ERR_ASSERTION]

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

返回顶部