From 37828f9923fd8ed6c8a4ca6dcc0eac9ef3ab9148 Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Mon, 13 Nov 2017 16:44:30 -0200 Subject: [PATCH 1/2] doc: improve assert documentation 1) Separate all loose and strict functions. 2) Stronger outline the used comparison rules in (not)deepStrictEqual 3) Fix SameValue comparison info --- doc/api/assert.md | 90 +++++++++++++++++++++++------------------------ 1 file changed, 44 insertions(+), 46 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 72ee3da3db95b9..e6d267ff63d8b2 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -104,7 +104,7 @@ assert.deepEqual(obj1, obj4); If the values are not equal, an `AssertionError` is thrown with a `message` property set equal to the value of the `message` parameter. If the `message` parameter is undefined, a default error message is assigned. If the `message` -parameter is an instance of an `Error` then it will be thrown instead of the +parameter is an instance of an [`Error`][] then it will be thrown instead of the `AssertionError`. ## assert.deepStrictEqual(actual, expected[, message]) @@ -137,50 +137,50 @@ changes: * `expected` {any} * `message` {any} -Identical to [`assert.deepEqual()`][] with the following exceptions: +Tests for deep equality between the `actual` and `expected` parameters. +"Deep" equality means that the enumerable "own" properties of child objects +are recursively evaluated also by the following rules. -1. Primitive values besides `NaN` are compared using the [Strict Equality - Comparison][] ( `===` ). Set and Map values, Map keys and `NaN` are compared - using the [SameValueZero][] comparison (which means they are free of the - [caveats][]). -2. [`[[Prototype]]`][prototype-spec] of objects are compared using +### Comparison details + +* Primitive values are compared using the [SameValue Comparison][], used by + [`Object.is()`][]. +* [Type tags][Object.prototype.toString()] of objects should be the same. +* [`[[Prototype]]`][prototype-spec] of objects are compared using the [Strict Equality Comparison][] too. -3. [Type tags][Object.prototype.toString()] of objects should be the same. -4. [Object wrappers][] are compared both as objects and unwrapped values. -5. `0` and `-0` are not considered equal. -6. Enumerable own [`Symbol`][] properties are compared as well. +* Only [enumerable "own" properties][] are considered. +* [`Error`][] names and messages are always compared, even if these are not + enumerable properties. +* Enumerable own [`Symbol`][] properties are compared as well. +* [Object wrappers][] are compared both as objects and unwrapped values. +* Object properties are compared unordered. +* Map keys and Set items are compared unordered. +* Recursion stops when both sides differ or both sides encounter a circular + reference. ```js 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 +// because 1 !== '1' using SameValue comparison // The following objects don't have own properties const date = new Date(); const object = {}; const fakeDate = {}; - Object.setPrototypeOf(fakeDate, Date.prototype); -assert.deepEqual(object, fakeDate); -// OK, doesn't check [[Prototype]] assert.deepStrictEqual(object, fakeDate); // AssertionError: {} deepStrictEqual Date {} // Different [[Prototype]] -assert.deepEqual(date, fakeDate); -// OK, doesn't check type tags assert.deepStrictEqual(date, fakeDate); // AssertionError: 2017-03-11T14:25:31.849Z deepStrictEqual Date {} // Different type tags assert.deepStrictEqual(NaN, NaN); -// OK, because of the SameValueZero comparison +// OK, because of the SameValue comparison assert.deepStrictEqual(new Number(1), new Number(2)); // Fails because the wrapped number is unwrapped and compared as well. @@ -203,7 +203,7 @@ assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 }); If the values are not equal, an `AssertionError` is thrown with a `message` property set equal to the value of the `message` parameter. If the `message` parameter is undefined, a default error message is assigned. If the `message` -parameter is an instance of an `Error` then it will be thrown instead of the +parameter is an instance of an [`Error`][] then it will be thrown instead of the `AssertionError`. ## assert.doesNotThrow(block[, error][, message]) @@ -299,7 +299,7 @@ assert.equal({ a: { b: 1 } }, { a: { b: 1 } }); If the values are not equal, an `AssertionError` is thrown with a `message` property set equal to the value of the `message` parameter. If the `message` parameter is undefined, a default error message is assigned. If the `message` -parameter is an instance of an `Error` then it will be thrown instead of the +parameter is an instance of an [`Error`][] then it will be thrown instead of the `AssertionError`. ## assert.fail([message]) @@ -315,7 +315,7 @@ added: v0.1.21 Throws an `AssertionError`. If `message` is falsy, the error message is set as the values of `actual` and `expected` separated by the provided `operator`. If -the `message` parameter is an instance of an `Error` then it will be thrown +the `message` parameter is an instance of an [`Error`][] then it will be thrown instead of the `AssertionError`. If just the two `actual` and `expected` arguments are provided, `operator` will default to `'!='`. If `message` is provided only it will be used as the error message, the other arguments will be @@ -450,7 +450,7 @@ assert.notDeepEqual(obj1, obj4); If the values are deeply equal, an `AssertionError` is thrown with a `message` property set equal to the value of the `message` parameter. If the `message` parameter is undefined, a default error message is assigned. If the `message` -parameter is an instance of an `Error` then it will be thrown instead of the +parameter is an instance of an [`Error`][] then it will be thrown instead of the `AssertionError`. ## assert.notDeepStrictEqual(actual, expected[, message]) @@ -488,9 +488,6 @@ Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][]. ```js const assert = require('assert'); -assert.notDeepEqual({ a: 1 }, { a: '1' }); -// AssertionError: { a: 1 } notDeepEqual { a: '1' } - assert.notDeepStrictEqual({ a: 1 }, { a: '1' }); // OK ``` @@ -498,8 +495,8 @@ assert.notDeepStrictEqual({ a: 1 }, { a: '1' }); If the values are deeply and strictly equal, an `AssertionError` is thrown with a `message` property set equal to the value of the `message` parameter. If the `message` parameter is undefined, a default error message is assigned. If the -`message` parameter is an instance of an `Error` then it will be thrown instead -of the `AssertionError`. +`message` parameter is an instance of an [`Error`][] then it will be thrown +instead of the `AssertionError`. ## assert.notEqual(actual, expected[, message]) + +When using the `strict mode`, any `assert` function will use the equality used in +the strict function mode. So [`assert.deepEqual()`][] will, for example, work the +same as [`assert.deepStrictEqual()`][]. + +It can be accessed using: + +```js +const assert = require('assert').strict; +``` + +## Legacy mode + +> Stability: 0 - Deprecated: Use strict mode instead. + +When accessing `assert` directly instead of using the `strict` property, the +[Abstract Equality Comparison][] will be used for any function without a +"strict" in its name (e.g. [`assert.deepEqual()`][]). + +It can be accessed using: + +```js +const assert = require('assert'); +``` + +It is recommended to use the [`strict mode`][] instead as the +[Abstract Equality Comparison][] can often have surprising results. Especially +in case of [`assert.deepEqual()`][] as the used comparison rules there are very +lax. + +E.g. + +```js +// WARNING: This does not throw an AssertionError! +assert.deepEqual(/a/gi, new Date()); +``` + ## assert(value[, message])