Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

assert: update comments #10579

Closed
wants to merge 1 commit into from
Closed

assert: update comments #10579

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 42 additions & 32 deletions lib/assert.js
View file
Open in desktop
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