Assertion Testing - 《Node.js 5.x 中文文档》

断言
assert(value[, message])
assert.deepEqual(actual, expected[, message])
assert.deepStrictEqual(actual, expected[, message])
assert.doesNotThrow(block[, error][, message])
assert.equal(actual, expected[, message])
assert.fail(actual, expected, message, operator)
assert.ifError(value)
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.strictEqual(actual, expected[, message])
assert.throws(block[, error][, message])

断言

assert 模块提供了一系列的测试接口。这些接口的设计初衷是服务于 Node.js 的开发和测试，现在也可以通过 require('assert') 在 Node.js 开发的应用中使用。不过有一点要记住，assert 模块不是一个测试框架，不建议用作通用的断言调试库。

当前 assert 模块的 API 处于锁定状态，这意味着该模块将不再添加新接口，也不会再修改既有的接口规范。

assert(value[, message])

等同于 assert.ok():

const assert = require('assert')
// 参数值 == true，无输出
assert(true)
assert(1)
// 参数值 != false，抛出错误
assert(0)
// => AssertionError: 0 == true
assert(false, "it's false")
// => AssertionError: it's false

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

判断参数 actual 和 expected 是否相等，使用 == 比较原始值（primitive value)。

deepEqual() 只会比较对象的自有、可枚举属性，不会对其他属性进行比较，所以在某些情况下结果会出人意料，比如在下面的示例中就不会抛出 AssertionError，这是因为 Error 对象的属性不是可枚举属性：

// WARNING: This does not throw an AssertionError!
assert.deepEqual(Error('a'), Error('b'));

方法名中的 Deep 一词意指会对传入的两个对象进行深度比较，包括对对象子级属性的比较：

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, object is equal to itself
assert.deepEqual(obj1, obj2);
// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }
// values of b are different
assert.deepEqual(obj1, obj3);
// OK, objects are equal
assert.deepEqual(obj1, obj4);
// AssertionError: { a: { b: 1 } } deepEqual {}
// 原型继承而来的属性不计入比较范围

如果 actual 和 expected 不相等，则抛出 AssertionError 错误和 message 错误信息。这里的 message 参数为可选字符串参数，如果未传入该参数，系统自动分配默认的错误信息。

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

与 assert.deepEqual() 的作用基本相同，两者的区别在于，assert.deepStrictEqual() 使用 === 判断原始值是否相等：

const assert = require('assert');
assert.deepEqual({a:1}, {a:'1'});
// OK, because 1 == '1'
assert.deepStrictEqual({a:1}, {a:'1'});
// AssertionError: { a: 1 } deepStrictEqual { a: '1' }
// because 1 !== '1' using strict equality

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

assert.doesNotThrow() 期望传入的 block 函数不会抛出错误，更多信息请查看 assert.thorws()。

调用 assert.doesNotThrow() 时，会立即执行 block 函数。

如果 block 函数抛出了错误，且错误类型与 error 参数指定的类型相符，就会抛出 AssertionError 错误；如果 block 函数抛出的错误类型与 error 参数指定的类型不符，或者未传入可选参数 error，则错误会被传递给函数的调用者。

由于传入的 error 参数为 SyntaxError 与 block 函数的错误不匹配，所以下面的示例代码将会抛出 block 函数产生的 TypeError：

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

如果 error 参数指定的错误与 block 函数抛出的错误匹配，则抛出 AssertionError：

assert.doesNotThrow(
    () => {
        throw new TypeError("Wrong Type");
    }, 
    TypeError
);

如果提供了可选参数 message 字符串，那么该字符串信息会被附加到 AssertionError 信息之后：

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

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

使用 == 比较 actual 参数和 expected 参数是否相等，如果参数是原始值，则比较值是否相等；如果参数是引用值，则比较内存地址是否相等：

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

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

抛出 AssertionError。如果参数 message == undefined，则错误信息为 actual #{operator} expected；如果参数 message != undefined，则错误信息为参数 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 === true)，则抛出 value，这对于测试回调函数中的 error 参数很有用：

const assert = require('assert');
assert.ifError(0); // OK
assert.ifError(1); // Throws 1
assert.ifError('error') // Throws 'error'
assert.ifError(new Error()); // Throws Error

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

与 assert.deepEqual() 的功能相反，测试 actual 参数和 expected 参数是否不相等：

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);
// OK, obj1 and obj2 are not deeply equal
assert.notDeepEqual(obj1, obj3);
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
assert.notDeepEqual(obj1, obj4);
// OK, obj1 and obj2 are not deeply equal

如果 actual 和 expected 相等，则抛出 AssertionError 错误和 message 错误信息。这里的 message 参数为可选字符串参数，如果未传入该参数，系统自动分配默认的错误信息。

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

与 assert.notDeepStrictEqual() 的功能相反，测试 actual 参数和 expected 参数是否不相等：

const assert = require('assert');
assert.notDeepEqual({a:1}, {a:'1'});
// AssertionError: { a: 1 } notDeepEqual { a: '1' }
assert.notDeepStrictEqual({a:1}, {a:'1'});
// OK

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

使用 != 比较 actual 参数和 expected 参数是否不相等，如果参数是原始值，则比较值是否不相等；如果参数是引用值，则比较内存地址是否不相等：

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

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

使用 !== 比较 actual 参数和 expected 参数是否不相等：

const assert = require('assert');
assert.notStrictEqual(1, 2);
// OK
assert.notStrictEqual(1, 1);
// AssertionError: 1 != 1
assert.notStrictEqual(1, '1');
// OK

assert.ok(value[, message])

测试 value 是否为真值，等同于 assert.equal(!!value, true, message):

const assert = require('assert');
assert.ok(true);  
// OK
assert.ok(1);     
// OK
assert.ok(false);
// throws "AssertionError: false == true"
assert.ok(0);
// throws "AssertionError: 0 == true"
assert.ok(false, 'it\'s false');
// throws "AssertionError: it's false"

如果 value 不为真值，则抛出 AssertionError 错误和 message 错误信息。这里的 message 参数为可选字符串参数，如果未传入该参数，系统自动分配默认的错误信息。

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

使用 === 比较 actual 参数和 expected 参数是否相等：

const assert = require('assert');
assert.strictEqual(1, 2);
// AssertionError: 1 === 2
assert.strictEqual(1, 1);
// OK
assert.strictEqual(1, '1');
// AssertionError: 1 === '1'

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

assert.throws() 期望传入的 block 函数会抛出错误（译者注：如果 block 函数抛出错误，assert.throws() 无返回值，表示正常；如果未抛出错误，则 assert.throws() 抛出 AssertionError 错误），可选参数 error 可以是构造函数、正则表达式和自定义的检验函数。

使用构造函数校验错误实例：

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