From 5a78c6c0a60a7cb34bff8ee983712e7847010840 Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Mon, 13 Nov 2017 16:44:30 -0200 Subject: [PATCH] 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 Backport-PR-URL: https://github.com/nodejs/node/pull/19230 PR-URL: https://github.com/nodejs/node/pull/17002 Reviewed-By: Refael Ackermann Reviewed-By: James M Snell Reviewed-By: Vse Mozhet Byt Reviewed-By: Anna Henningsen --- doc/api/assert.md | 91 +++++++++++++++++++++++------------------------ 1 file changed, 44 insertions(+), 47 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 6935a9db4bda64..058aff858be8e5 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -101,7 +101,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]) @@ -136,50 +136,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. @@ -202,7 +202,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]) @@ -298,7 +298,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]) @@ -314,7 +314,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 @@ -451,7 +451,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]) @@ -491,9 +491,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 ``` @@ -501,8 +498,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])