Skip to content

Commit b2c7bad

Browse files
committed
doc: update Abstract Equality Comparison text in assert.md
* Update link to ECMAScript specification * Edit surprising-results material * Other minor edits
1 parent 231ec0a commit b2c7bad

File tree

1 file changed

+11
-14
lines changed

1 file changed

+11
-14
lines changed

doc/api/assert.md

Lines changed: 11 additions & 14 deletions
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 [Abstract Equality Comparison][] (`==`) 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

@@ -526,8 +524,8 @@ are also recursively evaluated by the following rules.
526524

527525
### Comparison details
528526

529-
* Primitive values are compared with the [Abstract Equality Comparison][]
530-
( `==` ) with the exception of `NaN`. It is treated as being identical in case
527+
* Primitive values are compared with the `==` operator,
528+
with the exception of `NaN`. It is treated as being identical in case
531529
both sides are `NaN`.
532530
* [Type tags][Object.prototype.toString()] of objects should be the same.
533531
* Only [enumerable "own" properties][] are considered.
@@ -546,8 +544,7 @@ are also recursively evaluated by the following rules.
546544
are not enumerable properties.
547545

548546
The following example does not throw an [`AssertionError`][] because the
549-
primitives are considered equal by the [Abstract Equality Comparison][]
550-
( `==` ).
547+
primitives are compared using the `==` operator.
551548

552549
```mjs
553550
import assert from 'assert';
@@ -1169,8 +1166,8 @@ An alias of [`assert.strictEqual()`][].
11691166
> Stability: 3 - Legacy: Use [`assert.strictEqual()`][] instead.
11701167
11711168
Tests shallow, coercive equality between the `actual` and `expected` parameters
1172-
using the [Abstract Equality Comparison][] ( `==` ). `NaN` is special handled
1173-
and treated as being identical in case both sides are `NaN`.
1169+
using the [Abstract Equality Comparison][] (`==`). `NaN` is specially handled
1170+
and treated as being identical if both sides are `NaN`.
11741171

11751172
```mjs
11761173
import assert from 'assert';
@@ -1688,7 +1685,7 @@ An alias of [`assert.notStrictEqual()`][].
16881685
> Stability: 3 - Legacy: Use [`assert.notStrictEqual()`][] instead.
16891686
16901687
Tests shallow, coercive inequality with the [Abstract Equality Comparison][]
1691-
(`!=` ). `NaN` is special handled and treated as being identical in case both
1688+
(`!=`). `NaN` is specially handled and treated as being identical in case both
16921689
sides are `NaN`.
16931690

16941691
```mjs
@@ -2448,7 +2445,7 @@ assert.throws(throwingFirst, /Second$/);
24482445
Due to the confusing error-prone notation, avoid a string as the second
24492446
argument.
24502447

2451-
[Abstract Equality Comparison]: https://tc39.github.io/ecma262/#sec-abstract-equality-comparison
2448+
[Abstract Equality Comparison]: https://262.ecma-international.org/#sec-abstract-equality-comparison
24522449
[Object wrappers]: https://developer.mozilla.org/en-US/docs/Glossary/Primitive#Primitive_wrapper_objects_in_JavaScript
24532450
[Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring
24542451
[SameValue Comparison]: https://tc39.github.io/ecma262/#sec-samevalue

0 commit comments

Comments
 (0)