Skip to content

Commit e6bed4e

Browse files
Trotttargos
authored andcommittedJan 14, 2022
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 PR-URL: #41375 Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]> Reviewed-By: Luigi Pinca <[email protected]>
1 parent 19db19b commit e6bed4e

File tree

1 file changed

+15
-20
lines changed

1 file changed

+15
-20
lines changed
 

‎doc/api/assert.md

+15-20
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ more on color support in terminal environments, read the tty
104104

105105
## Legacy assertion mode
106106

107-
Legacy assertion mode uses the [Abstract Equality Comparison][] in:
107+
Legacy assertion mode uses the `==` operator in:
108108

109109
* [`assert.deepEqual()`][]
110110
* [`assert.equal()`][]
@@ -121,13 +121,11 @@ import assert from 'assert';
121121
const assert = require('assert');
122122
```
123123

124-
Whenever possible, use the [strict assertion mode][] instead. Otherwise, the
125-
[Abstract Equality Comparison][] may cause surprising results. This is
126-
especially true for [`assert.deepEqual()`][], where the comparison rules are
127-
lax:
124+
Legacy assertion mode may have surprising results, especially when using
125+
[`assert.deepEqual()`][]:
128126

129127
```cjs
130-
// WARNING: This does not throw an AssertionError!
128+
// WARNING: This does not throw an AssertionError in legacy assertion mode!
131129
assert.deepEqual(/a/gi, new Date());
132130
```
133131

@@ -473,7 +471,7 @@ changes:
473471
Legacy.
474472
- version: v14.0.0
475473
pr-url: https://github.com/nodejs/node/pull/30766
476-
description: NaN is now treated as being identical in case both sides are
474+
description: NaN is now treated as being identical if both sides are
477475
NaN.
478476
- version: v12.0.0
479477
pr-url: https://github.com/nodejs/node/pull/25008
@@ -523,8 +521,8 @@ are also recursively evaluated by the following rules.
523521

524522
### Comparison details
525523

526-
* Primitive values are compared with the [Abstract Equality Comparison][]
527-
( `==` ) with the exception of `NaN`. It is treated as being identical in case
524+
* Primitive values are compared with the `==` operator,
525+
with the exception of `NaN`. It is treated as being identical in case
528526
both sides are `NaN`.
529527
* [Type tags][Object.prototype.toString()] of objects should be the same.
530528
* Only [enumerable "own" properties][] are considered.
@@ -541,8 +539,7 @@ are also recursively evaluated by the following rules.
541539
* [`WeakMap`][] and [`WeakSet`][] comparison does not rely on their values.
542540

543541
The following example does not throw an [`AssertionError`][] because the
544-
primitives are considered equal by the [Abstract Equality Comparison][]
545-
( `==` ).
542+
primitives are compared using the `==` operator.
546543

547544
```mjs
548545
import assert from 'assert';
@@ -1142,7 +1139,7 @@ changes:
11421139
Legacy.
11431140
- version: v14.0.0
11441141
pr-url: https://github.com/nodejs/node/pull/30766
1145-
description: NaN is now treated as being identical in case both sides are
1142+
description: NaN is now treated as being identical if both sides are
11461143
NaN.
11471144
-->
11481145

@@ -1159,8 +1156,8 @@ An alias of [`assert.strictEqual()`][].
11591156
> Stability: 3 - Legacy: Use [`assert.strictEqual()`][] instead.
11601157
11611158
Tests shallow, coercive equality between the `actual` and `expected` parameters
1162-
using the [Abstract Equality Comparison][] ( `==` ). `NaN` is special handled
1163-
and treated as being identical in case both sides are `NaN`.
1159+
using the `==` operator. `NaN` is specially handled
1160+
and treated as being identical if both sides are `NaN`.
11641161

11651162
```mjs
11661163
import assert from 'assert';
@@ -1477,7 +1474,7 @@ changes:
14771474
Legacy.
14781475
- version: v14.0.0
14791476
pr-url: https://github.com/nodejs/node/pull/30766
1480-
description: NaN is now treated as being identical in case both sides are
1477+
description: NaN is now treated as being identical if both sides are
14811478
NaN.
14821479
- version: v9.0.0
14831480
pr-url: https://github.com/nodejs/node/pull/15001
@@ -1661,7 +1658,7 @@ changes:
16611658
Legacy.
16621659
- version: v14.0.0
16631660
pr-url: https://github.com/nodejs/node/pull/30766
1664-
description: NaN is now treated as being identical in case both sides are
1661+
description: NaN is now treated as being identical if both sides are
16651662
NaN.
16661663
-->
16671664

@@ -1677,8 +1674,8 @@ An alias of [`assert.notStrictEqual()`][].
16771674

16781675
> Stability: 3 - Legacy: Use [`assert.notStrictEqual()`][] instead.
16791676
1680-
Tests shallow, coercive inequality with the [Abstract Equality Comparison][]
1681-
(`!=` ). `NaN` is special handled and treated as being identical in case both
1677+
Tests shallow, coercive inequality with the
1678+
`!=` operator. `NaN` is specially handled and treated as being identical if
16821679
sides are `NaN`.
16831680

16841681
```mjs
@@ -2438,7 +2435,6 @@ assert.throws(throwingFirst, /Second$/);
24382435
Due to the confusing error-prone notation, avoid a string as the second
24392436
argument.
24402437

2441-
[Abstract Equality Comparison]: https://tc39.github.io/ecma262/#sec-abstract-equality-comparison
24422438
[Object wrappers]: https://developer.mozilla.org/en-US/docs/Glossary/Primitive#Primitive_wrapper_objects_in_JavaScript
24432439
[Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring
24442440
[SameValue Comparison]: https://tc39.github.io/ecma262/#sec-samevalue
@@ -2474,4 +2470,3 @@ argument.
24742470
[`tracker.verify()`]: #trackerverify
24752471
[enumerable "own" properties]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties
24762472
[prototype-spec]: https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots
2477-
[strict assertion mode]: #strict-assertion-mode

0 commit comments

Comments
 (0)