Node.js 6.9.4 文档


assert (断言)#

查看英文文档

稳定性: 3 - 锁定的

assert 模块提供了一组简单的断言测试集合,用于测试不变量。 该模块是供 Node.js 内部使用的,但可以通过 require('assert') 在代码中使用。 assert 不是一个测试框架,也无意成为通用的断言库。

assert 模块的 API 是锁定的。 这意味着将不会新增或更改任何由该模块实现与公开的方法。

assert(value[, message])#

查看英文文档

assert.ok() 的别名。

const assert = require('assert');

assert(true);
// 通过
assert(1);
// 通过
assert(false);
// 抛出 "AssertionError: false == true"
assert(0);
// 抛出 "AssertionError: 0 == true"
assert(false, 'it\'s false');
// 抛出 "AssertionError: it's false"

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

查看英文文档

测试 actualexpected 参数是否深度相等。 原始值会使用相等运算符(==)进行比较。

只比较可枚举的自身属性。 deepEqual() 不测试对象的原型、连接符、或不可枚举的属性。 这会引起一些潜在的意料之外的结果。 例如,下面的例子不会抛出 AssertionError,因为 Error 对象的属性是不可枚举的:

// 注意:这不会抛出 AssertionError!
assert.deepEqual(Error('a'), Error('b'));

深度相等意味着子对象的可枚举的自身属性也会被比较:

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);
// 通过,对象与自身相等

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

assert.deepEqual(obj1, obj3);
// 通过,两个对象相等

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

如果两个值不相等,则抛出一个带有 message 属性的 AssertionError,其中 message 属性的值等于传入的 message 参数的值。 如果 message 参数为 undefined,则输出默认的错误信息。

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

查看英文文档

大多数情况下等同于 assert.deepEqual(),但有两个例外。 首先,原始值使用严格相等运算符(===)进行比较。 其次,对象对比包括严格比较它们的原型。

const assert = require('assert');

assert.deepEqual({a:1}, {a:'1'});
// 通过,因为 1 == '1'

assert.deepStrictEqual({a:1}, {a:'1'});
// 抛出 AssertionError: { a: 1 } deepStrictEqual { a: '1' }
// 因为 1 !== '1' 使用严格相等运算符

如果两个值不相等,则抛出一个带有 message 属性的 AssertionError,其中 message 属性的值等于传入的 message 参数的值。 如果 message 参数为 undefined,则输出默认的错误信息。

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

查看英文文档

断言 block 函数不会抛出错误。 查看 assert.throws() 了解更多。

当调用 assert.doesNotThrow() 时,它会立即调用 block 函数。

如果 block 函数抛出错误,并且错误类型与 error 参数指定的相同,则抛出 AssertionError。 如果错误类型不相同,或 error 参数是 undefined,则错误回传给调用者。

以下例子会抛出 TypeError,因为在断言中没有匹配的错误类型:

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

以下例子会抛出一个带有 'Got unwanted exception (TypeError)..' 信息的 AssertionError

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

如果抛出了 AssertionError,并且有为 message 参数传值,则 message 的值会被追加到 AssertionError 的消息中:

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

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

查看英文文档

使用相等运算符(==)来测试 actualexpected 参数是否相等。

const assert = require('assert');

assert.equal(1, 1);
// 通过,1 == 1
assert.equal(1, '1');
// 通过,1 == '1'

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

如果两个值不相等,则抛出一个带有 message 属性的 AssertionError,其中 message 属性的值等于传入的 message 参数的值。 如果 message 参数为 undefined,则输出默认的错误信息。

assert.fail(actual, expected, message, operator)#

查看英文文档

抛出 AssertionError。 如果 message 的值不为真,则错误信息为 actualexpected 的值,并以 operator 分隔。 否则,错误信息为 message 的值。

const assert = require('assert');

assert.fail(1, 2, undefined, '>');
// 抛出 AssertionError: 1 > 2

assert.fail(1, 2, 'whoops', '>');
// 抛出 AssertionError: whoops

assert.ifError(value)#

查看英文文档

如果 value 的值为真,抛出 value。 当测试回调函数的 error 参数时非常有用。

const assert = require('assert');

assert.ifError(0);
// 通过
assert.ifError(1);
// 抛出 1
assert.ifError('error');
// 抛出 'error'
assert.ifError(new Error());
// 抛出 Error

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

查看英文文档

测试 actualexpected 参数是否不深度相等。 与 assert.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.notDeepEqual(obj1, obj1);
// 抛出 AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }

assert.notDeepEqual(obj1, obj2);
// 通过,obj1 与 obj2 不深度相等

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

assert.notDeepEqual(obj1, obj4);
// 通过,obj1 与 obj4 不深度相等

如果两个值深度相等,则抛出一个带有 message 属性的 AssertionError,其中 message 属性的值等于传入的 message 参数的值。 如果 message 参数为 undefined,则输出默认的错误信息。

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

查看英文文档

测试 actualexpected 参数是否不深度严格相等。 与 assert.deepStrictEqual() 相反。

const assert = require('assert');

assert.notDeepEqual({a:1}, {a:'1'});
// 抛出 AssertionError: { a: 1 } notDeepEqual { a: '1' }

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

如果两个值深度严格相等,则抛出一个带有 message 属性的 AssertionError,其中 message 属性的值等于传入的 message 参数的值。 如果 message 参数为 undefined,则输出默认的错误信息。

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

查看英文文档

使用不等运算符(!=)来测试 actualexpected 参数是否不相等。

const assert = require('assert');

assert.notEqual(1, 2);
// 通过

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

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

如果两个值相等,则抛出一个带有 message 属性的 AssertionError,其中 message 属性的值等于传入的 message 参数的值。 如果 message 参数为 undefined,则输出默认的错误信息。

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

查看英文文档

使用严格不等运算符(!==)来测试 actualexpected 参数是否不严格相等。

const assert = require('assert');

assert.notStrictEqual(1, 2);
// 通过

assert.notStrictEqual(1, 1);
// 抛出 AssertionError: 1 !== 1

assert.notStrictEqual(1, '1');
// 通过

如果两个值严格相等,则抛出一个带有 message 属性的 AssertionError,其中 message 属性的值等于传入的 message 参数的值。 如果 message 参数为 undefined,则输出默认的错误信息。

assert.ok(value[, message])#

查看英文文档

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

如果 value 不为真值,则抛出一个带有 message 属性的 AssertionError,其中 message 属性的值等于传入的 message 参数的值。 如果 message 参数为 undefined,则输出默认的错误信息。

const assert = require('assert');

assert.ok(true);
// 通过
assert.ok(1);
// 通过
assert.ok(false);
// 抛出 "AssertionError: false == true"
assert.ok(0);
// 抛出 "AssertionError: 0 == true"
assert.ok(false, 'it\'s false');
// 抛出 "AssertionError: it's false"

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

查看英文文档

使用严格相等运算符(===)测试是否严格相等。

const assert = require('assert');

assert.strictEqual(1, 2);
// 抛出 AssertionError: 1 === 2

assert.strictEqual(1, 1);
// 通过

assert.strictEqual(1, '1');
// 抛出 AssertionError: 1 === '1'

如果两个值不严格相等,则抛出一个带有 message 属性的 AssertionError,其中 message 属性的值等于传入的 message 参数的值。 如果 message 参数为 undefined,则输出默认的错误信息。

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

查看英文文档

期望 block 函数抛出错误。

如果指定 error,它可以是一个构造函数、正则表达式、或校验函数。

如果指定 message,当 block 函数抛出错误时,message 会作为错误信息传给 AssertionError

使用构造函数的例子:

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

使用正则表达式的例子:

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

使用自定义校验函数的例子:

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  function(err) {
    if ( (err instanceof Error) && /value/.test(err) ) {
      return true;
    }
  },
  'unexpected error'
);

注意,error 参数不能是字符串。 如果第二个参数是字符串,则视为不传 error 参数,传入的字符串会被当作是 message 的值。 这可能会引起误解:

// 这是错误的!不要这么做!
assert.throws(myFunction, 'missing foo', 'did not throw with expected message');

// 应该这么做。
assert.throws(myFunction, /missing foo/, 'did not throw with expected message');