Skip to content

Commit

Permalink
assert: update comments
Browse files Browse the repository at this point in the history 
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: #10579
Fixes: #9063
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
  • Loading branch information
@kaicataldo @jasnell
kaicataldo authored and jasnell committed Jan 4, 2017
1 parent b8f6c1f commit 398229a
Showing 1 changed file with 42 additions and 32 deletions.
74 changes: 42 additions & 32 deletions lib/assert.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand All @@ -106,24 +106,25 @@ 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);

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) {
fail(actual, expected, message, '!=', assert.notEqual);
}
};

// 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 */
Expand All @@ -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)) {
Expand All @@ -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 ||
Expand All @@ -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
Expand Down Expand Up @@ -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))
Expand All @@ -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))
Expand All @@ -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) {
Expand All @@ -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) {
Expand All @@ -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) {
Expand All @@ -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)) {
Expand Down Expand Up @@ -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 throws(block, /*optional*/error, /*optional*/message) {
Expand Down

0 comments on commit 398229a

Please sign in to comment.