Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: update Abstract Equality Comparison text in assert.md #41375

Merged
merged 9 commits into from
Jan 5, 2022
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 @@ -476,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 both sides are
NaN.
- version: v12.0.0
pr-url: https://github.com/nodejs/node/pull/25008
Expand Down Expand Up @@ -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.
Expand All @@ -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';
Expand Down Expand Up @@ -1152,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 both sides are
NaN.
-->

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

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

Expand All @@ -1687,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 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 @@ -2448,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://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 @@ -2484,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