Skip to content

Commit 5a78c6c

Browse files
BridgeARMylesBorins
authored andcommitted
doc: improve assert documentation
1) Separate all loose and strict functions. 2) Stronger outline the used comparison rules in (not)deepStrictEqual 3) Fix SameValue comparison info Backport-PR-URL: #19230 PR-URL: #17002 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Anna Henningsen <[email protected]>
1 parent fed51b3 commit 5a78c6c

File tree

1 file changed

+44
-47
lines changed

1 file changed

+44
-47
lines changed

doc/api/assert.md

+44-47
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ assert.deepEqual(obj1, obj4);
101101
If the values are not equal, an `AssertionError` is thrown with a `message`
102102
property set equal to the value of the `message` parameter. If the `message`
103103
parameter is undefined, a default error message is assigned. If the `message`
104-
parameter is an instance of an `Error` then it will be thrown instead of the
104+
parameter is an instance of an [`Error`][] then it will be thrown instead of the
105105
`AssertionError`.
106106

107107
## assert.deepStrictEqual(actual, expected[, message])
@@ -136,50 +136,50 @@ changes:
136136
* `expected` {any}
137137
* `message` {any}
138138

139-
Identical to [`assert.deepEqual()`][] with the following exceptions:
139+
Tests for deep equality between the `actual` and `expected` parameters.
140+
"Deep" equality means that the enumerable "own" properties of child objects
141+
are recursively evaluated also by the following rules.
140142

141-
1. Primitive values besides `NaN` are compared using the [Strict Equality
142-
Comparison][] ( `===` ). Set and Map values, Map keys and `NaN` are compared
143-
using the [SameValueZero][] comparison (which means they are free of the
144-
[caveats][]).
145-
2. [`[[Prototype]]`][prototype-spec] of objects are compared using
143+
### Comparison details
144+
145+
* Primitive values are compared using the [SameValue Comparison][], used by
146+
[`Object.is()`][].
147+
* [Type tags][Object.prototype.toString()] of objects should be the same.
148+
* [`[[Prototype]]`][prototype-spec] of objects are compared using
146149
the [Strict Equality Comparison][] too.
147-
3. [Type tags][Object.prototype.toString()] of objects should be the same.
148-
4. [Object wrappers][] are compared both as objects and unwrapped values.
149-
5. `0` and `-0` are not considered equal.
150-
6. Enumerable own [`Symbol`][] properties are compared as well.
150+
* Only [enumerable "own" properties][] are considered.
151+
* [`Error`][] names and messages are always compared, even if these are not
152+
enumerable properties.
153+
* Enumerable own [`Symbol`][] properties are compared as well.
154+
* [Object wrappers][] are compared both as objects and unwrapped values.
155+
* Object properties are compared unordered.
156+
* Map keys and Set items are compared unordered.
157+
* Recursion stops when both sides differ or both sides encounter a circular
158+
reference.
151159

152160
```js
153161
const assert = require('assert');
154162

155-
assert.deepEqual({ a: 1 }, { a: '1' });
156-
// OK, because 1 == '1'
157-
158163
assert.deepStrictEqual({ a: 1 }, { a: '1' });
159164
// AssertionError: { a: 1 } deepStrictEqual { a: '1' }
160-
// because 1 !== '1' using strict equality
165+
// because 1 !== '1' using SameValue comparison
161166

162167
// The following objects don't have own properties
163168
const date = new Date();
164169
const object = {};
165170
const fakeDate = {};
166-
167171
Object.setPrototypeOf(fakeDate, Date.prototype);
168172

169-
assert.deepEqual(object, fakeDate);
170-
// OK, doesn't check [[Prototype]]
171173
assert.deepStrictEqual(object, fakeDate);
172174
// AssertionError: {} deepStrictEqual Date {}
173175
// Different [[Prototype]]
174176

175-
assert.deepEqual(date, fakeDate);
176-
// OK, doesn't check type tags
177177
assert.deepStrictEqual(date, fakeDate);
178178
// AssertionError: 2017-03-11T14:25:31.849Z deepStrictEqual Date {}
179179
// Different type tags
180180

181181
assert.deepStrictEqual(NaN, NaN);
182-
// OK, because of the SameValueZero comparison
182+
// OK, because of the SameValue comparison
183183

184184
assert.deepStrictEqual(new Number(1), new Number(2));
185185
// Fails because the wrapped number is unwrapped and compared as well.
@@ -202,7 +202,7 @@ assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 });
202202
If the values are not equal, an `AssertionError` is thrown with a `message`
203203
property set equal to the value of the `message` parameter. If the `message`
204204
parameter is undefined, a default error message is assigned. If the `message`
205-
parameter is an instance of an `Error` then it will be thrown instead of the
205+
parameter is an instance of an [`Error`][] then it will be thrown instead of the
206206
`AssertionError`.
207207

208208
## assert.doesNotThrow(block[, error][, message])
@@ -298,7 +298,7 @@ assert.equal({ a: { b: 1 } }, { a: { b: 1 } });
298298
If the values are not equal, an `AssertionError` is thrown with a `message`
299299
property set equal to the value of the `message` parameter. If the `message`
300300
parameter is undefined, a default error message is assigned. If the `message`
301-
parameter is an instance of an `Error` then it will be thrown instead of the
301+
parameter is an instance of an [`Error`][] then it will be thrown instead of the
302302
`AssertionError`.
303303

304304
## assert.fail([message])
@@ -314,7 +314,7 @@ added: v0.1.21
314314

315315
Throws an `AssertionError`. If `message` is falsy, the error message is set as
316316
the values of `actual` and `expected` separated by the provided `operator`. If
317-
the `message` parameter is an instance of an `Error` then it will be thrown
317+
the `message` parameter is an instance of an [`Error`][] then it will be thrown
318318
instead of the `AssertionError`. If just the two `actual` and `expected`
319319
arguments are provided, `operator` will default to `'!='`. If `message` is
320320
provided only it will be used as the error message, the other arguments will be
@@ -451,7 +451,7 @@ assert.notDeepEqual(obj1, obj4);
451451
If the values are deeply equal, an `AssertionError` is thrown with a `message`
452452
property set equal to the value of the `message` parameter. If the `message`
453453
parameter is undefined, a default error message is assigned. If the `message`
454-
parameter is an instance of an `Error` then it will be thrown instead of the
454+
parameter is an instance of an [`Error`][] then it will be thrown instead of the
455455
`AssertionError`.
456456

457457
## assert.notDeepStrictEqual(actual, expected[, message])
@@ -491,18 +491,15 @@ Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][].
491491
```js
492492
const assert = require('assert');
493493

494-
assert.notDeepEqual({ a: 1 }, { a: '1' });
495-
// AssertionError: { a: 1 } notDeepEqual { a: '1' }
496-
497494
assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
498495
// OK
499496
```
500497

501498
If the values are deeply and strictly equal, an `AssertionError` is thrown with
502499
a `message` property set equal to the value of the `message` parameter. If the
503500
`message` parameter is undefined, a default error message is assigned. If the
504-
`message` parameter is an instance of an `Error` then it will be thrown instead
505-
of the `AssertionError`.
501+
`message` parameter is an instance of an [`Error`][] then it will be thrown
502+
instead of the `AssertionError`.
506503

507504
## assert.notEqual(actual, expected[, message])
508505
<!-- YAML
@@ -528,10 +525,10 @@ assert.notEqual(1, '1');
528525
// AssertionError: 1 != '1'
529526
```
530527

531-
If the values are equal, an `AssertionError` is thrown with a `message`
532-
property set equal to the value of the `message` parameter. If the `message`
533-
parameter is undefined, a default error message is assigned. If the `message`
534-
parameter is an instance of an `Error` then it will be thrown instead of the
528+
If the values are equal, an `AssertionError` is thrown with a `message` property
529+
set equal to the value of the `message` parameter. If the `message` parameter is
530+
undefined, a default error message is assigned. If the `message` parameter is an
531+
instance of an [`Error`][] then it will be thrown instead of the
535532
`AssertionError`.
536533

537534
## assert.notStrictEqual(actual, expected[, message])
@@ -542,8 +539,8 @@ added: v0.1.21
542539
* `expected` {any}
543540
* `message` {any}
544541

545-
Tests strict inequality as determined by the [Strict Equality Comparison][]
546-
( `!==` ).
542+
Tests strict inequality between the `actual` and `expected` parameters as
543+
determined by the [SameValue Comparison][].
547544

548545
```js
549546
const assert = require('assert');
@@ -558,11 +555,11 @@ assert.notStrictEqual(1, '1');
558555
// OK
559556
```
560557

561-
If the values are strictly equal, an `AssertionError` is thrown with a
562-
`message` property set equal to the value of the `message` parameter. If the
563-
`message` parameter is undefined, a default error message is assigned. If the
564-
`message` parameter is an instance of an `Error` then it will be thrown instead
565-
of the `AssertionError`.
558+
If the values are strictly equal, an `AssertionError` is thrown with a `message`
559+
property set equal to the value of the `message` parameter. If the `message`
560+
parameter is undefined, a default error message is assigned. If the `message`
561+
parameter is an instance of an [`Error`][] then it will be thrown instead of the
562+
`AssertionError`.
566563

567564
## assert.ok(value[, message])
568565
<!-- YAML
@@ -577,7 +574,7 @@ Tests if `value` is truthy. It is equivalent to
577574
If `value` is not truthy, an `AssertionError` is thrown with a `message`
578575
property set equal to the value of the `message` parameter. If the `message`
579576
parameter is `undefined`, a default error message is assigned. If the `message`
580-
parameter is an instance of an `Error` then it will be thrown instead of the
577+
parameter is an instance of an [`Error`][] then it will be thrown instead of the
581578
`AssertionError`.
582579

583580
```js
@@ -603,8 +600,8 @@ added: v0.1.21
603600
* `expected` {any}
604601
* `message` {any}
605602

606-
Tests strict equality as determined by the [Strict Equality Comparison][]
607-
( `===` ).
603+
Tests strict equality between the `actual` and `expected` parameters as
604+
determined by the [SameValue Comparison][].
608605

609606
```js
610607
const assert = require('assert');
@@ -622,8 +619,8 @@ assert.strictEqual(1, '1');
622619
If the values are not strictly equal, an `AssertionError` is thrown with a
623620
`message` property set equal to the value of the `message` parameter. If the
624621
`message` parameter is undefined, a default error message is assigned. If the
625-
`message` parameter is an instance of an `Error` then it will be thrown instead
626-
of the `AssertionError`.
622+
`message` parameter is an instance of an [`Error`][] then it will be thrown
623+
instead of the `AssertionError`.
627624

628625
## assert.throws(block[, error][, message])
629626
<!-- YAML
@@ -736,8 +733,8 @@ For more information, see
736733
[Abstract Equality Comparison]: https://tc39.github.io/ecma262/#sec-abstract-equality-comparison
737734
[Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring
738735
[SameValueZero]: https://tc39.github.io/ecma262/#sec-samevaluezero
736+
[SameValue Comparison]: https://tc39.github.io/ecma262/#sec-samevalue
739737
[Strict Equality Comparison]: https://tc39.github.io/ecma262/#sec-strict-equality-comparison
740-
[caveats]: #assert_caveats
741738
[enumerable "own" properties]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties
742739
[mdn-equality-guide]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness
743740
[prototype-spec]: https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots

0 commit comments

Comments
 (0)