From 7ecfe4971aa642d4f873cf26a8da3a76e27d0c2b Mon Sep 17 00:00:00 2001 From: Kai Cataldo Date: Mon, 2 Jan 2017 16:50:04 -0500 Subject: [PATCH] assert: update comments Remove the numbers from the comments to make it clear that assert does not follow the [CJS spec](http://wiki.commonjs.org/wiki/Unit_Testing/1.0). Additionally, clean up the existing comments for consistent formatting/language and ease of reading. PR-URL: https://github.com/nodejs/node/pull/10579 Fixes: https://github.com/nodejs/node/issues/9063 Reviewed-By: Rich Trott Reviewed-By: James M Snell Reviewed-By: Benjamin Gruenbaum Reviewed-By: Michael Dawson --- lib/assert.js | 74 +++++++++++++++++++++++++++++---------------------- 1 file changed, 42 insertions(+), 32 deletions(-) diff --git a/lib/assert.js b/lib/assert.js index 0458bb09816872..1dc6e16a13271f 100644 --- a/lib/assert.js +++ b/lib/assert.js @@ -30,16 +30,16 @@ const util = require('util'); const Buffer = require('buffer').Buffer; const pToString = (obj) => Object.prototype.toString.call(obj); -// 1. The assert module provides functions that throw +// The assert module provides functions that throw // AssertionError's when particular conditions are not met. The // assert module must conform to the following interface. const assert = module.exports = ok; -// 2. The AssertionError is defined in assert. +// The AssertionError is defined in assert. // new assert.AssertionError({ message: message, // actual: actual, -// expected: expected }) +// expected: expected }); assert.AssertionError = function AssertionError(options) { this.name = 'AssertionError'; @@ -75,7 +75,7 @@ function getMessage(self) { // other keys to the AssertionError's constructor - they will be // ignored. -// 3. All of the following functions must throw an AssertionError +// All of the following functions must throw an AssertionError // when a corresponding condition is not met, with a message that // may be undefined if not provided. All assertion methods provide // both the actual and expected values to the assertion error for @@ -94,7 +94,7 @@ function fail(actual, expected, message, operator, stackStartFunction) { // EXTENSION! allows for well behaved errors defined elsewhere. assert.fail = fail; -// 4. Pure assertion tests whether a value is truthy, as determined +// Pure assertion tests whether a value is truthy, as determined // by !!guard. // assert.ok(guard, message_opt); // This statement is equivalent to assert.equal(true, !!guard, @@ -106,7 +106,7 @@ function ok(value, message) { } assert.ok = ok; -// 5. The equality assertion tests shallow, coercive equality with +// The equality assertion tests shallow, coercive equality with // ==. // assert.equal(actual, expected, message_opt); @@ -114,8 +114,9 @@ assert.equal = function equal(actual, expected, message) { if (actual != expected) fail(actual, expected, message, '==', assert.equal); }; -// 6. The non-equality assertion tests for whether two objects are not equal -// with != assert.notEqual(actual, expected, message_opt); +// The non-equality assertion tests for whether two objects are not +// equal with !=. +// assert.notEqual(actual, expected, message_opt); assert.notEqual = function notEqual(actual, expected, message) { if (actual == expected) { @@ -123,7 +124,7 @@ assert.notEqual = function notEqual(actual, expected, message) { } }; -// 7. The equivalence assertion tests a deep equality relation. +// The equivalence assertion tests a deep equality relation. // assert.deepEqual(actual, expected, message_opt); /* eslint-disable no-restricted-properties */ @@ -141,18 +142,22 @@ assert.deepStrictEqual = function deepStrictEqual(actual, expected, message) { }; function _deepEqual(actual, expected, strict, memos) { - // 7.1. All identical values are equivalent, as determined by ===. + // All identical values are equivalent, as determined by ===. if (actual === expected) { return true; + + // If both values are instances of buffers, equivalence is + // determined by comparing the values and ensuring the result + // === 0. } else if (actual instanceof Buffer && expected instanceof Buffer) { return compare(actual, expected) === 0; - // 7.2. If the expected value is a Date object, the actual value is + // If the expected value is a Date object, the actual value is // equivalent if it is also a Date object that refers to the same time. } else if (util.isDate(actual) && util.isDate(expected)) { return actual.getTime() === expected.getTime(); - // 7.3 If the expected value is a RegExp object, the actual value is + // If the expected value is a RegExp object, the actual value is // equivalent if it is also a RegExp object with the same source and // properties (`global`, `multiline`, `lastIndex`, `ignoreCase`). } else if (util.isRegExp(actual) && util.isRegExp(expected)) { @@ -162,18 +167,18 @@ function _deepEqual(actual, expected, strict, memos) { actual.lastIndex === expected.lastIndex && actual.ignoreCase === expected.ignoreCase; - // 7.4. Other pairs that do not both pass typeof value == 'object', - // equivalence is determined by ==. + // If both values are primitives, equivalence is determined by + // == or, if checking for strict equivalence, ===. } else if ((actual === null || typeof actual !== 'object') && (expected === null || typeof expected !== 'object')) { return strict ? actual === expected : actual == expected; // If both values are instances of typed arrays, wrap their underlying - // ArrayBuffers in a Buffer each to increase performance + // ArrayBuffers in a Buffer to increase performance. // This optimization requires the arrays to have the same type as checked by - // Object.prototype.toString (aka pToString). Never perform binary - // comparisons for Float*Arrays, though, since e.g. +0 === -0 but their - // bit patterns are not identical. + // Object.prototype.toString (pToString). Never perform binary + // comparisons for Float*Arrays, though, since +0 === -0 is true despite the + // two values' bit patterns not being identical. } else if (ArrayBuffer.isView(actual) && ArrayBuffer.isView(expected) && pToString(actual) === pToString(expected) && !(actual instanceof Float32Array || @@ -185,7 +190,7 @@ function _deepEqual(actual, expected, strict, memos) { expected.byteOffset, expected.byteLength)) === 0; - // 7.5 For all other Object pairs, including Array objects, equivalence is + // For all other Object pairs, including Array objects, equivalence is // determined by having the same number of owned properties (as verified // with Object.prototype.hasOwnProperty.call), the same set of keys // (although not necessarily the same order), equivalent values for every @@ -215,7 +220,8 @@ function isArguments(object) { function objEquiv(a, b, strict, actualVisitedObjects) { if (a === null || a === undefined || b === null || b === undefined) return false; - // if one is a primitive, the other must be same + + // If one is a primitive, the other must be the same. if (util.isPrimitive(a) || util.isPrimitive(b)) return a === b; if (strict && Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) @@ -227,20 +233,23 @@ function objEquiv(a, b, strict, actualVisitedObjects) { const ka = Object.keys(a); const kb = Object.keys(b); var key, i; - // having the same number of owned properties (keys incorporates - // hasOwnProperty) + + // The pair must have the same number of owned properties (keys + // incorporates hasOwnProperty). if (ka.length !== kb.length) return false; - //the same set of keys (although not necessarily the same order), + + // The pair must have the same set of keys (although not + // necessarily in the same order). ka.sort(); kb.sort(); - //~~~cheap key test + // Cheap key test: for (i = ka.length - 1; i >= 0; i--) { if (ka[i] !== kb[i]) return false; } - //equivalent values for every corresponding key, and - //~~~possibly expensive deep test + // The pair must have equivalent values for every corresponding key. + // Possibly expensive deep test: for (i = ka.length - 1; i >= 0; i--) { key = ka[i]; if (!_deepEqual(a[key], b[key], strict, actualVisitedObjects)) @@ -249,7 +258,7 @@ function objEquiv(a, b, strict, actualVisitedObjects) { return true; } -// 8. The non-equivalence assertion tests for any deep inequality. +// The non-equivalence assertion tests for any deep inequality. // assert.notDeepEqual(actual, expected, message_opt); assert.notDeepEqual = function notDeepEqual(actual, expected, message) { @@ -266,7 +275,7 @@ function notDeepStrictEqual(actual, expected, message) { } -// 9. The strict equality assertion tests strict equality, as determined by ===. +// The strict equality assertion tests strict equality, as determined by ===. // assert.strictEqual(actual, expected, message_opt); assert.strictEqual = function strictEqual(actual, expected, message) { @@ -275,8 +284,9 @@ assert.strictEqual = function strictEqual(actual, expected, message) { } }; -// 10. The strict non-equality assertion tests for strict inequality, as -// determined by !==. assert.notStrictEqual(actual, expected, message_opt); +// The strict non-equality assertion tests for strict inequality, as +// determined by !==. +// assert.notStrictEqual(actual, expected, message_opt); assert.notStrictEqual = function notStrictEqual(actual, expected, message) { if (actual === expected) { @@ -298,7 +308,7 @@ function expectedException(actual, expected) { return true; } } catch (e) { - // Ignore. The instanceof check doesn't work for arrow functions. + // Ignore. The instanceof check doesn't work for arrow functions. } if (Error.isPrototypeOf(expected)) { @@ -356,7 +366,7 @@ function _throws(shouldThrow, block, expected, message) { } } -// 11. Expected to throw an error: +// Expected to throw an error. // assert.throws(block, Error_opt, message_opt); assert.throws = function(block, /*optional*/error, /*optional*/message) {