From 044a68f095cf4b7b8260501113beaa096456758c Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sat, 1 Jan 2022 22:56:09 -0800 Subject: [PATCH 1/9] doc: update Abstract Equality Comparison text in assert.md * Remove link to ECMAScript specification because the term Abstract Equality Comparison is no longer used there. * Edit surprising-results material * Other minor edits --- doc/api/assert.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index c7e679ef814d8c..20e3e38d2230ae 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -104,7 +104,7 @@ more on color support in terminal environments, read the tty ## Legacy assertion mode -Legacy assertion mode uses the [Abstract Equality Comparison][] in: +Legacy assertion mode uses the [Abstract Equality Comparison][] (`==`) in: * [`assert.deepEqual()`][] * [`assert.equal()`][] @@ -121,13 +121,11 @@ import assert from 'assert'; const assert = require('assert'); ``` -Whenever possible, use the [strict assertion mode][] instead. Otherwise, the -[Abstract Equality Comparison][] may cause surprising results. This is -especially true for [`assert.deepEqual()`][], where the comparison rules are -lax: +Legacy assertion mode may have surprising results, especially when using +[`assert.deepEqual()`][]: ```cjs -// WARNING: This does not throw an AssertionError! +// WARNING: This does not throw an AssertionError in legacy assertion mode! assert.deepEqual(/a/gi, new Date()); ``` @@ -526,8 +524,8 @@ are also recursively evaluated by the following rules. ### Comparison details -* Primitive values are compared with the [Abstract Equality Comparison][] - ( `==` ) with the exception of `NaN`. It is treated as being identical in case +* Primitive values are compared with the `==` operator, + with the exception of `NaN`. It is treated as being identical in case both sides are `NaN`. * [Type tags][Object.prototype.toString()] of objects should be the same. * Only [enumerable "own" properties][] are considered. @@ -546,8 +544,7 @@ are also recursively evaluated by the following rules. are not enumerable properties. The following example does not throw an [`AssertionError`][] because the -primitives are considered equal by the [Abstract Equality Comparison][] -( `==` ). +primitives are compared using the `==` operator. ```mjs import assert from 'assert'; @@ -1169,8 +1166,8 @@ An alias of [`assert.strictEqual()`][]. > Stability: 3 - Legacy: Use [`assert.strictEqual()`][] instead. Tests shallow, coercive equality between the `actual` and `expected` parameters -using the [Abstract Equality Comparison][] ( `==` ). `NaN` is special handled -and treated as being identical in case both sides are `NaN`. +using the [Abstract Equality Comparison][] (`==`). `NaN` is specially handled +and treated as being identical if both sides are `NaN`. ```mjs import assert from 'assert'; @@ -1688,7 +1685,7 @@ An alias of [`assert.notStrictEqual()`][]. > Stability: 3 - Legacy: Use [`assert.notStrictEqual()`][] instead. Tests shallow, coercive inequality with the [Abstract Equality Comparison][] -(`!=` ). `NaN` is special handled and treated as being identical in case both +(`!=`). `NaN` is specially handled and treated as being identical in case both sides are `NaN`. ```mjs @@ -2448,7 +2445,7 @@ assert.throws(throwingFirst, /Second$/); Due to the confusing error-prone notation, avoid a string as the second argument. -[Abstract Equality Comparison]: https://tc39.github.io/ecma262/#sec-abstract-equality-comparison +[Abstract Equality Comparison]: https://262.ecma-international.org/#sec-abstract-equality-comparison [Object wrappers]: https://developer.mozilla.org/en-US/docs/Glossary/Primitive#Primitive_wrapper_objects_in_JavaScript [Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring [SameValue Comparison]: https://tc39.github.io/ecma262/#sec-samevalue From 9ba23452cdb22fe7ae0e082b45da87a3da024f24 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 2 Jan 2022 08:07:30 -0800 Subject: [PATCH 2/9] fixup! doc: update Abstract Equality Comparison text in assert.md --- doc/api/assert.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 20e3e38d2230ae..9bede93c55df5a 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -104,7 +104,7 @@ more on color support in terminal environments, read the tty ## Legacy assertion mode -Legacy assertion mode uses the [Abstract Equality Comparison][] (`==`) in: +Legacy assertion mode uses the `==` operator in: * [`assert.deepEqual()`][] * [`assert.equal()`][] @@ -1166,7 +1166,7 @@ An alias of [`assert.strictEqual()`][]. > Stability: 3 - Legacy: Use [`assert.strictEqual()`][] instead. Tests shallow, coercive equality between the `actual` and `expected` parameters -using the [Abstract Equality Comparison][] (`==`). `NaN` is specially handled +using the `==` operator. `NaN` is specially handled and treated as being identical if both sides are `NaN`. ```mjs @@ -1684,8 +1684,8 @@ An alias of [`assert.notStrictEqual()`][]. > Stability: 3 - Legacy: Use [`assert.notStrictEqual()`][] instead. -Tests shallow, coercive inequality with the [Abstract Equality Comparison][] -(`!=`). `NaN` is specially handled and treated as being identical in case both +Tests shallow, coercive inequality with the +`!=`. `NaN` is specially handled and treated as being identical in case both sides are `NaN`. ```mjs @@ -2445,7 +2445,6 @@ assert.throws(throwingFirst, /Second$/); Due to the confusing error-prone notation, avoid a string as the second argument. -[Abstract Equality Comparison]: https://262.ecma-international.org/#sec-abstract-equality-comparison [Object wrappers]: https://developer.mozilla.org/en-US/docs/Glossary/Primitive#Primitive_wrapper_objects_in_JavaScript [Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring [SameValue Comparison]: https://tc39.github.io/ecma262/#sec-samevalue From 8e24278867f5060bc764a2912e6cd2dea47d59e7 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 2 Jan 2022 08:10:55 -0800 Subject: [PATCH 3/9] fixup! fixup! doc: update Abstract Equality Comparison text in assert.md --- doc/api/assert.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 9bede93c55df5a..4ffaef09bc50de 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -474,7 +474,7 @@ changes: Legacy. - version: v14.0.0 pr-url: https://github.com/nodejs/node/pull/30766 - description: NaN is now treated as being identical in case both sides are + description: NaN is now treated as being identical if sides are NaN. - version: v12.0.0 pr-url: https://github.com/nodejs/node/pull/25008 @@ -1149,7 +1149,7 @@ changes: Legacy. - version: v14.0.0 pr-url: https://github.com/nodejs/node/pull/30766 - description: NaN is now treated as being identical in case both sides are + description: NaN is now treated as being identical if sides are NaN. --> @@ -1484,7 +1484,7 @@ changes: Legacy. - version: v14.0.0 pr-url: https://github.com/nodejs/node/pull/30766 - description: NaN is now treated as being identical in case both sides are + description: NaN is now treated as being identical if sides are NaN. - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15001 @@ -1668,7 +1668,7 @@ changes: Legacy. - version: v14.0.0 pr-url: https://github.com/nodejs/node/pull/30766 - description: NaN is now treated as being identical in case both sides are + description: NaN is now treated as being identical if sides are NaN. --> @@ -1685,7 +1685,7 @@ An alias of [`assert.notStrictEqual()`][]. > Stability: 3 - Legacy: Use [`assert.notStrictEqual()`][] instead. Tests shallow, coercive inequality with the -`!=`. `NaN` is specially handled and treated as being identical in case both +`!=`. `NaN` is specially handled and treated as being identical if sides are `NaN`. ```mjs From 37a8f8f3b1602cea08e98db4d24fa2568e62f195 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 2 Jan 2022 08:16:22 -0800 Subject: [PATCH 4/9] fixup! fixup! fixup! doc: update Abstract Equality Comparison text in assert.md --- doc/api/assert.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 4ffaef09bc50de..afe4f292753e8f 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -2480,4 +2480,3 @@ argument. [`tracker.verify()`]: #trackerverify [enumerable "own" properties]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties [prototype-spec]: https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots -[strict assertion mode]: #strict-assertion-mode From 0e8983782ee0f325c5f4b0781177fe4139bc2186 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 2 Jan 2022 09:41:51 -0800 Subject: [PATCH 5/9] Update doc/api/assert.md Co-authored-by: Antoine du Hamel --- doc/api/assert.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index afe4f292753e8f..52496ff2574d30 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -1685,7 +1685,7 @@ An alias of [`assert.notStrictEqual()`][]. > Stability: 3 - Legacy: Use [`assert.notStrictEqual()`][] instead. Tests shallow, coercive inequality with the -`!=`. `NaN` is specially handled and treated as being identical if +`!=` operator. `NaN` is specially handled and treated as being identical if sides are `NaN`. ```mjs From 2e953a349bc409cb5a5029b42731512da6b595a4 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 2 Jan 2022 11:29:54 -0800 Subject: [PATCH 6/9] Update doc/api/assert.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Tobias Nießen --- doc/api/assert.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 52496ff2574d30..8fb89cb0bde59a 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -474,7 +474,7 @@ changes: Legacy. - version: v14.0.0 pr-url: https://github.com/nodejs/node/pull/30766 - description: NaN is now treated as being identical if sides are + description: NaN is now treated as being identical if both sides are NaN. - version: v12.0.0 pr-url: https://github.com/nodejs/node/pull/25008 From 1b75578ed295b37117fac2dfa245e8fc2d5de2f9 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 2 Jan 2022 11:30:04 -0800 Subject: [PATCH 7/9] Update doc/api/assert.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Tobias Nießen --- doc/api/assert.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 8fb89cb0bde59a..0634910afb6c9a 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -1149,7 +1149,7 @@ changes: Legacy. - version: v14.0.0 pr-url: https://github.com/nodejs/node/pull/30766 - description: NaN is now treated as being identical if sides are + description: NaN is now treated as being identical if both sides are NaN. --> From f1a87222ff26ae4e40df00ccbc636ef860005166 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 2 Jan 2022 11:30:10 -0800 Subject: [PATCH 8/9] Update doc/api/assert.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Tobias Nießen --- doc/api/assert.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 0634910afb6c9a..d8950090edcc26 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -1668,7 +1668,7 @@ changes: Legacy. - version: v14.0.0 pr-url: https://github.com/nodejs/node/pull/30766 - description: NaN is now treated as being identical if sides are + description: NaN is now treated as being identical if both sides are NaN. --> From 6a08b00ee31b3170fa002c2a4315586b264a5812 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 2 Jan 2022 11:30:30 -0800 Subject: [PATCH 9/9] Update doc/api/assert.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Tobias Nießen --- doc/api/assert.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index d8950090edcc26..1295f3b16082ba 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -1484,7 +1484,7 @@ changes: Legacy. - version: v14.0.0 pr-url: https://github.com/nodejs/node/pull/30766 - description: NaN is now treated as being identical if sides are + description: NaN is now treated as being identical if both sides are NaN. - version: v9.0.0 pr-url: https://github.com/nodejs/node/pull/15001