Skip to content

Commit

Permalink
doc: update Abstract Equality Comparison text in assert.md
Browse files Browse the repository at this point in the history
* 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]>
  • Loading branch information
Trott authored and targos committed Jan 14, 2022
1 parent 19db19b commit e6bed4e
Showing 1 changed file with 15 additions and 20 deletions.
35 changes: 15 additions & 20 deletions doc/api/assert.md
Original file line number Diff line number Diff line change
Expand Up @@ -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()`][]
Expand All @@ -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());
```

Expand Down Expand Up @@ -473,7 +471,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 both sides are
NaN.
- version: v12.0.0
pr-url: https://github.com/nodejs/node/pull/25008
Expand Down Expand Up @@ -523,8 +521,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.
Expand All @@ -541,8 +539,7 @@ are also recursively evaluated by the following rules.
* [`WeakMap`][] and [`WeakSet`][] comparison does not rely on their values.

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';
Expand Down Expand Up @@ -1142,7 +1139,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 both sides are
NaN.
-->

Expand All @@ -1159,8 +1156,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 `==` operator. `NaN` is specially handled
and treated as being identical if both sides are `NaN`.

```mjs
import assert from 'assert';
Expand Down Expand Up @@ -1477,7 +1474,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 both sides are
NaN.
- version: v9.0.0
pr-url: https://github.com/nodejs/node/pull/15001
Expand Down Expand Up @@ -1661,7 +1658,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 both sides are
NaN.
-->

Expand All @@ -1677,8 +1674,8 @@ 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
Tests shallow, coercive inequality with the
`!=` operator. `NaN` is specially handled and treated as being identical if
sides are `NaN`.

```mjs
Expand Down Expand Up @@ -2438,7 +2435,6 @@ 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
[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
Expand Down Expand Up @@ -2474,4 +2470,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

0 comments on commit e6bed4e

Please sign in to comment.