diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/assert.md | 123 | ||||
-rw-r--r-- | doc/api/deprecations.md | 9 |
2 files changed, 119 insertions, 13 deletions
diff --git a/doc/api/assert.md b/doc/api/assert.md index d2b54111158..d337a09b328 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -7,6 +7,57 @@ The `assert` module provides a simple set of assertion tests that can be used to test invariants. +A `strict` and a `legacy` mode exist, while it is recommended to only use +[`strict mode`][]. + +For more information about the used equality comparisons see +[MDN's guide on equality comparisons and sameness][mdn-equality-guide]. + +## Strict mode +<!-- YAML +added: REPLACEME +changes: + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/17002 + description: Added strict mode to the assert module. +--> + +When using the `strict mode`, any `assert` function will use the equality used in +the strict function mode. So [`assert.deepEqual()`][] will, for example, work the +same as [`assert.deepStrictEqual()`][]. + +It can be accessed using: + +```js +const assert = require('assert').strict; +``` + +## Legacy mode + +> Stability: 0 - Deprecated: Use strict mode instead. + +When accessing `assert` directly instead of using the `strict` property, the +[Abstract Equality Comparison][] will be used for any function without a +"strict" in its name (e.g. [`assert.deepEqual()`][]). + +It can be accessed using: + +```js +const assert = require('assert'); +``` + +It is recommended to use the [`strict mode`][] instead as the +[Abstract Equality Comparison][] can often have surprising results. Especially +in case of [`assert.deepEqual()`][] as the used comparison rules there are very +lax. + +E.g. + +```js +// WARNING: This does not throw an AssertionError! +assert.deepEqual(/a/gi, new Date()); +``` + ## assert(value[, message]) <!-- YAML added: v0.5.9 @@ -37,6 +88,14 @@ changes: * `expected` {any} * `message` {any} +**Strict mode** + +An alias of [`assert.deepStrictEqual()`][]. + +**Legacy mode** + +> Stability: 0 - Deprecated: Use [`assert.deepStrictEqual()`][] instead. + Tests for deep equality between the `actual` and `expected` parameters. Primitive values are compared with the [Abstract Equality Comparison][] ( `==` ). @@ -126,16 +185,26 @@ changes: Generally identical to `assert.deepEqual()` with a few exceptions: -1. Primitive values are compared using the [Strict Equality Comparison][] - ( `===` ). Set values and Map keys are compared using the [SameValueZero][] +### Comparison details + +* Primitive values are compared using the [Strict Equality Comparison][] + ( `===` ). +* Set values and Map keys are compared using the [SameValueZero][] comparison. (Which means they are free of the [caveats][]). -2. [`[[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. +* [Type tags][Object.prototype.toString()] of objects should be the same. +* [`[[Prototype]]`][prototype-spec] of objects are compared using + the [Strict Equality Comparison][]. +* Only [enumerable "own" properties][] are considered. +* [`Error`][] messages are always compared, even though this property is + non-enumerable. +* [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'); +const assert = require('assert').strict; assert.deepEqual({ a: 1 }, { a: '1' }); // OK, because 1 == '1' @@ -251,6 +320,14 @@ added: v0.1.21 * `expected` {any} * `message` {any} +**Strict mode** + +An alias of [`assert.strictEqual()`][]. + +**Legacy mode** + +> Stability: 0 - Deprecated: Use [`assert.strictEqual()`][] instead. + Tests shallow, coercive equality between the `actual` and `expected` parameters using the [Abstract Equality Comparison][] ( `==` ). @@ -292,7 +369,7 @@ If `stackStartFunction` is provided, all stack frames above that function will be removed from stacktrace (see [`Error.captureStackTrace`]). ```js -const assert = require('assert'); +const assert = require('assert').strict; assert.fail(1, 2, undefined, '>'); // AssertionError [ERR_ASSERTION]: 1 > 2 @@ -340,7 +417,7 @@ Throws `value` if `value` is truthy. This is useful when testing the `error` argument in callbacks. ```js -const assert = require('assert'); +const assert = require('assert').strict; assert.ifError(null); // OK @@ -362,6 +439,14 @@ added: v0.1.21 * `expected` {any} * `message` {any} +**Strict mode** + +An alias of [`assert.notDeepStrictEqual()`][]. + +**Legacy mode** + +> Stability: 0 - Deprecated: Use [`assert.notDeepStrictEqual()`][] instead. + Tests for any deep inequality. Opposite of [`assert.deepEqual()`][]. ```js @@ -412,7 +497,7 @@ added: v1.2.0 Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][]. ```js -const assert = require('assert'); +const assert = require('assert').strict; assert.notDeepEqual({ a: 1 }, { a: '1' }); // AssertionError: { a: 1 } notDeepEqual { a: '1' } @@ -433,6 +518,14 @@ added: v0.1.21 * `expected` {any} * `message` {any} +**Strict mode** + +An alias of [`assert.notStrictEqual()`][]. + +**Legacy mode** + +> Stability: 0 - Deprecated: Use [`assert.notStrictEqual()`][] instead. + Tests shallow, coercive inequality with the [Abstract Equality Comparison][] ( `!=` ). @@ -465,7 +558,7 @@ Tests strict inequality as determined by the [Strict Equality Comparison][] ( `!==` ). ```js -const assert = require('assert'); +const assert = require('assert').strict; assert.notStrictEqual(1, 2); // OK @@ -496,7 +589,7 @@ property set equal to the value of the `message` parameter. If the `message` parameter is `undefined`, a default error message is assigned. ```js -const assert = require('assert'); +const assert = require('assert').strict; assert.ok(true); // OK @@ -522,7 +615,7 @@ Tests strict equality as determined by the [Strict Equality Comparison][] ( `===` ). ```js -const assert = require('assert'); +const assert = require('assert').strict; assert.strictEqual(1, 2); // AssertionError: 1 === 2 @@ -643,8 +736,12 @@ For more information, see [`TypeError`]: errors.html#errors_class_typeerror [`assert.deepEqual()`]: #assert_assert_deepequal_actual_expected_message [`assert.deepStrictEqual()`]: #assert_assert_deepstrictequal_actual_expected_message +[`assert.notDeepStrictEqual()`]: #assert_assert_notdeepstrictequal_actual_expected_message +[`assert.notStrictEqual()`]: #assert_assert_notstrictequal_actual_expected_message [`assert.ok()`]: #assert_assert_ok_value_message +[`assert.strictEqual()`]: #assert_assert_strictequal_actual_expected_message [`assert.throws()`]: #assert_assert_throws_block_error_message +[`strict mode`]: #assert_strict_mode [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 diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index efa939c5779..12a73f8878c 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -684,6 +684,15 @@ Type: Runtime cause a lot of issues. See https://github.com/nodejs/node/issues/14328 for more details. +<a id="DEP0089"></a> +### DEP0089: require('assert') + +Type: Documentation-only + +Importing assert directly is not recommended as the exposed functions will use +loose equality checks. Use `require('assert').strict` instead. The API is the +same as the legacy assert but it will always use strict equality checks. + <a id="DEP0098"></a> ### DEP0098: AsyncHooks Embedder AsyncResource.emit{Before,After} APIs |