1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: improve assert documentation

Browse Source 
1) Separate all loose and strict functions.
2) Stronger outline the used comparison rules in (not)deepStrictEqual
3) Fix SameValue comparison info

PR-URL: https://github.com/nodejs/node/pull/17002
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
This commit is contained in:
Ruben Bridgewater 2017-11-13 16:44:30 -02:00 committed by Anna Henningsen
parent 8075d82ecf
commit 06ab6f2f13
No known key found for this signature in database
GPG Key ID: 9C63F3A6CD2AD8F9
1 changed files with 44 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
doc/api/assert.md
View File

@ -104,7 +104,7 @@ assert.deepEqual(obj1, obj4);
If the values are not equal, an `AssertionError` is thrown with a `message`
property set equal to the value of the `message` parameter. If the `message`
parameter is undefined, a default error message is assigned. If the `message`
parameter is an instance of an `Error` then it will be thrown instead of the
parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.
## assert.deepStrictEqual(actual, expected[, message])
@ -137,50 +137,50 @@ changes:
* `expected` {any}
* `message` {any}
Identical to [`assert.deepEqual()`][] with the following exceptions:
Tests for deep equality between the `actual` and `expected` parameters.
"Deep" equality means that the enumerable "own" properties of child objects
are recursively evaluated also by the following rules.
1. Primitive values besides `NaN` are compared using the [Strict Equality
Comparison][] ( `===` ). Set and Map values, Map keys and `NaN` are compared
using the [SameValueZero][] comparison (which means they are free of the
[caveats][]).
2. [`[[Prototype]]`][prototype-spec] of objects are compared using
### Comparison details
* Primitive values are compared using the [SameValue Comparison][], used by
[`Object.is()`][].
* [Type tags][Object.prototype.toString()] of objects should be the same.
* [`[[Prototype]]`][prototype-spec] of objects are compared using
the [Strict Equality Comparison][] too.
3. [Type tags][Object.prototype.toString()] of objects should be the same.
4. [Object wrappers][] are compared both as objects and unwrapped values.
5. `0` and `-0` are not considered equal.
6. Enumerable own [`Symbol`][] properties are compared as well.
* Only [enumerable "own" properties][] are considered.
* [`Error`][] names and messages are always compared, even if these are not
enumerable properties.
* Enumerable own [`Symbol`][] properties are compared as well.
* [Object wrappers][] are compared both as objects and unwrapped values.
* Object properties are compared unordered.
* Map keys and Set items are compared unordered.
* Recursion stops when both sides differ or both sides encounter a circular
reference.
```js
const assert = require('assert');
assert.deepEqual({ a: 1 }, { a: '1' });
// OK, because 1 == '1'
assert.deepStrictEqual({ a: 1 }, { a: '1' });
// AssertionError: { a: 1 } deepStrictEqual { a: '1' }
// because 1 !== '1' using strict equality
// because 1 !== '1' using SameValue comparison
// The following objects don't have own properties
const date = new Date();
const object = {};
const fakeDate = {};
Object.setPrototypeOf(fakeDate, Date.prototype);
assert.deepEqual(object, fakeDate);
// OK, doesn't check [[Prototype]]
assert.deepStrictEqual(object, fakeDate);
// AssertionError: {} deepStrictEqual Date {}
// Different [[Prototype]]
assert.deepEqual(date, fakeDate);
// OK, doesn't check type tags
assert.deepStrictEqual(date, fakeDate);
// AssertionError: 2017-03-11T14:25:31.849Z deepStrictEqual Date {}
// Different type tags
assert.deepStrictEqual(NaN, NaN);
// OK, because of the SameValueZero comparison
// OK, because of the SameValue comparison
assert.deepStrictEqual(new Number(1), new Number(2));
// Fails because the wrapped number is unwrapped and compared as well.
@ -203,7 +203,7 @@ assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 });
If the values are not equal, an `AssertionError` is thrown with a `message`
property set equal to the value of the `message` parameter. If the `message`
parameter is undefined, a default error message is assigned. If the `message`
parameter is an instance of an `Error` then it will be thrown instead of the
parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.
## assert.doesNotThrow(block[, error][, message])
@ -299,7 +299,7 @@ assert.equal({ a: { b: 1 } }, { a: { b: 1 } });
If the values are not equal, an `AssertionError` is thrown with a `message`
property set equal to the value of the `message` parameter. If the `message`
parameter is undefined, a default error message is assigned. If the `message`
parameter is an instance of an `Error` then it will be thrown instead of the
parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.
## assert.fail([message])
@ -315,7 +315,7 @@ added: v0.1.21
Throws an `AssertionError`. If `message` is falsy, the error message is set as
the values of `actual` and `expected` separated by the provided `operator`. If
the `message` parameter is an instance of an `Error` then it will be thrown
the `message` parameter is an instance of an [`Error`][] then it will be thrown
instead of the `AssertionError`. If just the two `actual` and `expected`
arguments are provided, `operator` will default to `'!='`. If `message` is
provided only it will be used as the error message, the other arguments will be
@ -450,7 +450,7 @@ assert.notDeepEqual(obj1, obj4);
If the values are deeply equal, an `AssertionError` is thrown with a `message`
property set equal to the value of the `message` parameter. If the `message`
parameter is undefined, a default error message is assigned. If the `message`
parameter is an instance of an `Error` then it will be thrown instead of the
parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.
## assert.notDeepStrictEqual(actual, expected[, message])
@ -488,9 +488,6 @@ Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][].
```js
const assert = require('assert');
assert.notDeepEqual({ a: 1 }, { a: '1' });
// AssertionError: { a: 1 } notDeepEqual { a: '1' }
assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
// OK
```
@ -498,8 +495,8 @@ assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
If the values are deeply and strictly equal, an `AssertionError` is thrown with
a `message` property set equal to the value of the `message` parameter. If the
`message` parameter is undefined, a default error message is assigned. If the
`message` parameter is an instance of an `Error` then it will be thrown instead
of the `AssertionError`.
`message` parameter is an instance of an [`Error`][] then it will be thrown
instead of the `AssertionError`.
## assert.notEqual(actual, expected[, message])
<!-- YAML
@ -525,10 +522,10 @@ assert.notEqual(1, '1');
// AssertionError: 1 != '1'
```
If the values are equal, an `AssertionError` is thrown with a `message`
property set equal to the value of the `message` parameter. If the `message`
parameter is undefined, a default error message is assigned. If the `message`
parameter is an instance of an `Error` then it will be thrown instead of the
If the values are equal, an `AssertionError` is thrown with a `message` property
set equal to the value of the `message` parameter. If the `message` parameter is
undefined, a default error message is assigned. If the `message` parameter is an
instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.
## assert.notStrictEqual(actual, expected[, message])
@ -543,7 +540,8 @@ changes:
* `expected` {any}
* `message` {any}
Tests equality determined by the [`Object.is()`][] comparison.
Tests strict inequality between the `actual` and `expected` parameters as
determined by the [SameValue Comparison][].
```js
const assert = require('assert');
@ -558,11 +556,11 @@ assert.notStrictEqual(1, '1');
// OK
```
If the values are strictly equal, an `AssertionError` is thrown with a
`message` property set equal to the value of the `message` parameter. If the
`message` parameter is undefined, a default error message is assigned. If the
`message` parameter is an instance of an `Error` then it will be thrown instead
of the `AssertionError`.
If the values are strictly equal, an `AssertionError` is thrown with a `message`
property set equal to the value of the `message` parameter. If the `message`
parameter is undefined, a default error message is assigned. If the `message`
parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.
## assert.ok(value[, message])
<!-- YAML
@ -577,7 +575,7 @@ Tests if `value` is truthy. It is equivalent to
If `value` is not truthy, an `AssertionError` is thrown with a `message`
property set equal to the value of the `message` parameter. If the `message`
parameter is `undefined`, a default error message is assigned. If the `message`
parameter is an instance of an `Error` then it will be thrown instead of the
parameter is an instance of an [`Error`][] then it will be thrown instead of the
`AssertionError`.
```js
@ -607,7 +605,8 @@ changes:
* `expected` {any}
* `message` {any}
Tests equality determined by the [`Object.is()`][] comparison.
Tests strict equality between the `actual` and `expected` parameters as
determined by the [SameValue Comparison][].
```js
const assert = require('assert');
@ -625,8 +624,8 @@ assert.strictEqual(1, '1');
If the values are not strictly equal, an `AssertionError` is thrown with a
`message` property set equal to the value of the `message` parameter. If the
`message` parameter is undefined, a default error message is assigned. If the
`message` parameter is an instance of an `Error` then it will be thrown instead
of the `AssertionError`.
`message` parameter is an instance of an [`Error`][] then it will be thrown
instead of the `AssertionError`.
## assert.throws(block[, error][, message])
<!-- YAML
@ -712,9 +711,8 @@ assert.throws(myFunction, /missing foo/, 'did not throw with expected message');
[`assert.throws()`]: #assert_assert_throws_block_error_message
[Abstract Equality Comparison]: https://tc39.github.io/ecma262/#sec-abstract-equality-comparison
[Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring
[SameValueZero]: https://tc39.github.io/ecma262/#sec-samevaluezero
[SameValue Comparison]: https://tc39.github.io/ecma262/#sec-samevalue
[Strict Equality Comparison]: https://tc39.github.io/ecma262/#sec-strict-equality-comparison
[caveats]: #assert_caveats
[enumerable "own" properties]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties
[mdn-equality-guide]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness
[prototype-spec]: https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots