【译文】Nodejs官方文档（Part 3 断言测试）

摘要：断言稳定级别锁定断言模块提供了一个简单断言集，用于测试不变量。但是要注意，断言模块并不是一个测试框架，也不是一个通用的断言库。断言模块的已经锁定。版本加入测试深且强不等，与对立。版本加入测试是否为真。

稳定级别：3 - 锁定

断言模块提供了一个简单断言集，用于测试不变量。本模块原本是Node.js的内部使用，但也可以通过require("assert")在应用中使用。但是要注意，断言模块并不是一个测试框架，也不是一个通用的断言库。

断言模块的API已经锁定。意味着在未来，本模块应用和暴露的方法都不会有任何修改或者增加。

v0.5.9版本加入

是assert.ok()的alias。

const assert = require("assert");

assert(true);  // OK
assert(1);     // OK
assert(false);
  // throws "AssertionError: false == true"
assert(0);
  // throws "AssertionError: 0 == true"
assert(false, "it"s false");
  // throws "AssertionError: it"s false"

v0.1.21版本加入

用于测试 actual和expected的深等于。基本数据类型的值将会用等价运算符( == )作比较。

本方法只适用于可枚举且返回自身的属性。 deepEqual()不能用于测试对象原型、附加符号、不可枚举的属性。这一点可能会导致一些意想不到的结果。比如，下面的例子不会抛出AssertionError，因为Error对象的属性是不可枚举的。

// WARNING: This does not throw an 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);
  // OK, 一个对象和自身肯定是相等的

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

assert.deepEqual(obj1, obj3);
  // OK, 两个对象是相等的

assert.deepEqual(obj1, obj4);
  // AssertionError: { a: { b: 1 } } deepEqual {}
  // 对象原型不能用于比较

如果传入的两个参数不相等，将会抛出一个AssertionError，它会自带一个message属性，可由message传参设置。如果message传参是undefined，就会给它赋值一个默认的错误信息。

v1.2.0版本加入

与assert.deepEqual()只有两个区别。第一，基本数据类型的值是用强等价运算符（===）来比较的。第二，对象之间的比较要求它们的原型（prototype）也一致。

如果传入的两个参数不相等，将会抛出一个AssertionError，它会自带一个message属性，可由message传参设置。如果message传参是undefined，就会给它赋值一个默认的错误信息。

v0.1.21版本加入

断言block方法不会抛出错误，关于抛出（throw）可参加assert.throw()了解更多细节。

当assert.doesNotThrow()被调用的时候，它会立即调用block方法。

如果有错误抛出，并且错误类型与传参中的错误类型一致，此方法将抛出一个AssertionError。如果错误类型不一致，或者传参error未定义，那么错误会被回传给调用者。

比如下例中，将会抛出一个TypeError，因为错误类型不一致。

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

但下例中就会抛出AssertionError并附带message“Got unwanted exception (TypeError)..”。

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

当有AssertionError抛出的时候，如果传参中定义了message参数，那么它将会被附到AssertionError的message后面。

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

v0.1.21版本加入

用等价运算符（==）比较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 } }

如果传入的两个参数不相等，将会抛出一个AssertionError，它会自带一个message属性，可由message传参设置。如果message传参是undefined，就会给它赋值一个默认的错误信息。

v0.1.21版本加入

抛出AssertionError。如果message也就是比较结果为假，那么错误信息输出actual和expected的值，用传入的运算符隔开；如果结果为真，错误信息输出传入的message。

const assert = require("assert");

assert.fail(1, 2, undefined, ">");
  // AssertionError: 1 > 2

assert.fail(1, 2, "whoops", ">");
  // AssertionError: whoops

v0.1.97版本加入

如果value为真则输出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

v0.1.21版本加入

测试深不等，与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);
  // 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

如果传入的两个参数深相等，将会抛出一个AssertionError，它会自带一个message属性，可由message传参设置。如果message传参是undefined，就会给它赋值一个默认的错误信息。

v1.2.0版本加入

测试深且强不等，与assert.deepStrictEqual()对立。

const assert = require("assert");

assert.notDeepEqual({a:1}, {a:"1"});
  // AssertionError: { a: 1 } notDeepEqual { a: "1" }

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

如果传入的两个参数深且强相等，将会抛出一个AssertionError，它会自带一个message属性，可由message传参设置。如果message传参是undefined，就会给它赋值一个默认的错误信息。

v0.1.21版本加入

用不等价运算符（!=）测试浅不等。

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传参是undefined，就会给它赋值一个默认的错误信息。

v0.1.21版本加入

用强不等运算符（!==）测试强不等。

const assert = require("assert");

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

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

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

如果传入的两个参数强等，将会抛出一个AssertionError，它会自带一个message属性，可由message传参设置。如果message传参是undefined，就会给它赋值一个默认的错误信息。

v0.1.21版本加入

测试value是否为真。其实与assert.equal(!!value, true, message)等价。

如果value不为真，抛出AssertionError，附带message信息与传入message一致。如果message传参是undefined，就会给它赋值一个默认的错误信息。

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"

v0.1.21版本加入

用强等运算符（===）测试传参是否强等于。

const assert = require("assert");

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

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

assert.strictEqual(1, "1");
  // AssertionError: 1 === "1"

如果传入的两个参数不是强等，将会抛出一个AssertionError，它会自带一个message属性，可由message传参设置。如果message传参是undefined，就会给它赋值一个默认的错误信息。

v0.1.21版本加入

期望block方法抛出错误。

如果传入自定义error，可以是构造函数、正则表达式或验证函数。

如果传入message但没有错误抛出，message将是AssertionError附带的。

用构造函数验证实例：

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

用正则表达式验证error：

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

自定义error验证：

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

请注意error参数可以为字符串。如果第二个传参是个字符串，那么error参数将会被忽略，直接用这个字符串作为输出的message。但这可能会导致很容易被忽略的问题：

// THIS IS A MISTAKE! DO NOT DO THIS!
assert.throws(myFunction, "missing foo", "did not throw with expected message");

// Do this instead.
assert.throws(myFunction, /missing foo/, "did not throw with expected message");

请查看：全文目录