2012-02-27 11:07:12 -08:00
|
|
|
# Assert
|
2010-10-28 23:18:16 +11:00
|
|
|
|
2018-04-01 10:13:03 +02:00
|
|
|
<!--introduced_in=v0.1.21-->
|
2017-01-22 19:16:21 -08:00
|
|
|
|
2017-02-10 14:11:22 -08:00
|
|
|
> Stability: 2 - Stable
|
2012-03-02 15:14:03 -08:00
|
|
|
|
2020-06-22 13:56:08 -04:00
|
|
|
<!-- source_link=lib/assert.js -->
|
|
|
|
|
2022-04-20 10:23:41 +02:00
|
|
|
The `node:assert` module provides a set of assertion functions for verifying
|
2020-02-06 10:27:52 -10:00
|
|
|
invariants.
|
2018-04-01 10:11:24 +02:00
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
## Strict assertion mode
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2017-11-13 18:15:24 -02:00
|
|
|
<!-- YAML
|
2018-03-18 14:45:41 +01:00
|
|
|
added: v9.9.0
|
2017-11-13 18:15:24 -02:00
|
|
|
changes:
|
2020-10-20, Version 15.0.0 (Current)
Notable changes:
Deprecations and Removals:
- **build**: remove --build-v8-with-gn configure option (Yang Guo)
(https://github.com/nodejs/node/pull/27576)
- **build**: drop support for VS2017 (Michaël Zasso)
(https://github.com/nodejs/node/pull/33694)
- **doc**: move DEP0018 to End-of-Life (Rich Trott)
(https://github.com/nodejs/node/pull/35316)
- **fs**: deprecation warning on recursive rmdir (Ian Sutherland)
(https://github.com/nodejs/node/pull/35562)
- **lib**: add EventTarget-related browser globals (Anna Henningsen)
(https://github.com/nodejs/node/pull/35496)
- **net**: remove long deprecated server.connections property (James M
Snell) (https://github.com/nodejs/node/pull/33647)
- **repl**: remove deprecated repl.memory function (Ruben Bridgewater)
(https://github.com/nodejs/node/pull/33286)
- **repl**: remove deprecated repl.turnOffEditorMode() function (Ruben
Bridgewater) (https://github.com/nodejs/node/pull/33286)
- **repl**: remove deprecated repl.parseREPLKeyword() function (Ruben
Bridgewater) (https://github.com/nodejs/node/pull/33286)
- **repl**: remove deprecated bufferedCommand property (Ruben
Bridgewater) (https://github.com/nodejs/node/pull/33286)
- **repl**: remove deprecated .rli (Ruben Bridgewater)
(https://github.com/nodejs/node/pull/33286)
- **src**: remove deprecated node debug command (James M Snell)
(https://github.com/nodejs/node/pull/33648)
- **timers**: introduce timers/promises (James M Snell)
(https://github.com/nodejs/node/pull/33950)
- **util**: change default value of `maxStringLength` to 10000
(unknown) (https://github.com/nodejs/node/pull/32744)
- **wasi**: drop --experimental-wasm-bigint requirement (Colin Ihrig)
(https://github.com/nodejs/node/pull/35415)
npm 7 (https://github.com/nodejs/node/pull/35631):
Node.js 15 comes with a new major release of npm, npm 7. npm 7 comes
with many new features - including npm workspaces and a new
package-lock.json format. npm 7 also includes yarn.lock file support.
One of the big changes in npm 7 is that peer dependencies are now
installed by default.
Throw On Unhandled Rejections
(https://github.com/nodejs/node/pull/33021):
As of Node.js 15, the default mode for `unhandledRejection` is changed
to `throw` (from `warn`). In `throw` mode, if an `unhandledRejection`
hook is not set, the `unhandledRejection` is raised as an uncaught
exception. Users that have an `unhandledRejection` hook should see no
change in behavior, and it’s still possible to switch modes using the
`--unhandled-rejections=mode` process flag.
QUIC (https://github.com/nodejs/node/pull/32379):
Node.js 15 comes with experimental support QUIC, which can be enabled
by compiling Node.js with the `--experimental-quic` configuration flag.
The Node.js QUIC implementation is exposed by the core `net` module.
V8 8.6 (https://github.com/nodejs/node/pull/35415):
The V8 JavaScript engine has been updated to V8 8.6 (V8 8.4 is the
latest available in Node.js 14). Along with performance tweaks and
improvements the V8 update also brings the following language features:
* `Promise.any()` (from V8 8.5)
* `AggregateError` (from V8 8.5)
* `String.prototype.replaceAll()` (from V8 8.5)
* Logical assignment operators `&&=`, `||=`, and `??=` (from V8 8.5)
Other Notable Changes:
- **assert**: add `assert/strict` alias module (ExE Boss)
(https://github.com/nodejs/node/pull/34001)
- **dns**: add dns/promises alias (shisama)
(https://github.com/nodejs/node/pull/32953)
- **fs**: reimplement read and write streams using stream.construct
(Robert Nagy) (https://github.com/nodejs/node/pull/29656)
- **http2**: allow Host in HTTP/2 requests (Alba Mendez)
(https://github.com/nodejs/node/pull/34664)
- **lib**: add EventTarget-related browser globals (Anna Henningsen)
(https://github.com/nodejs/node/pull/35496)
- **lib**: unflag AbortController (James M Snell)
(https://github.com/nodejs/node/pull/33527)
- **lib**: initial experimental AbortController implementation (James M
Snell) (https://github.com/nodejs/node/pull/33527)
- **net**: autoDestroy Socket (Robert Nagy)
(https://github.com/nodejs/node/pull/31806)
- **src**: disallow JS execution inside FreeEnvironment (Anna
Henningsen) (https://github.com/nodejs/node/pull/33874)
- **stream**: construct (Robert Nagy)
(https://github.com/nodejs/node/pull/29656)
- **worker**: make MessageEvent class more Web-compatible (Anna
Henningsen) (https://github.com/nodejs/node/pull/35496)
Semver-Major Commits:
- **assert**: add `assert/strict` alias module (ExE Boss)
(https://github.com/nodejs/node/pull/34001)
- **build**: reset embedder string to "-node.0" (Michaël Zasso)
(https://github.com/nodejs/node/pull/35415)
- **build**: remove --build-v8-with-gn configure option (Yang Guo)
(https://github.com/nodejs/node/pull/27576)
- **build**: drop support for VS2017 (Michaël Zasso)
(https://github.com/nodejs/node/pull/33694)
- **crypto**: refactoring internals, add WebCrypto (James M Snell)
(https://github.com/nodejs/node/pull/35093)
- **crypto**: move node\_crypto files to src/crypto (James M Snell)
(https://github.com/nodejs/node/pull/35093)
- **deps**: V8: cherry-pick d76abfed3512 (Michaël Zasso)
(https://github.com/nodejs/node/pull/35415)
- **deps**: V8: cherry-pick 717543bbf0ef (Michaël Zasso)
(https://github.com/nodejs/node/pull/35415)
- **deps**: V8: cherry-pick 6be2f6e26e8d (Michaël Zasso)
(https://github.com/nodejs/node/pull/35415)
- **deps**: fix V8 build issue with inline methods (Jiawen Geng)
(https://github.com/nodejs/node/pull/35415)
- **deps**: fix platform-embedded-file-writer-win for ARM64 (Michaël
Zasso) (https://github.com/nodejs/node/pull/35415)
- **deps**: update V8 postmortem metadata script (Colin Ihrig)
(https://github.com/nodejs/node/pull/35415)
- **deps**: update V8 to 8.6.395 (Michaël Zasso)
(https://github.com/nodejs/node/pull/35415)
- **deps**: upgrade npm to 7.0.0 (Myles Borins)
(https://github.com/nodejs/node/pull/35631)
- **deps**: update npm to 7.0.0-rc.3 (Myles Borins)
(https://github.com/nodejs/node/pull/35474)
- **deps**: V8: cherry-pick 0d6debcc5f08 (Gus Caplan)
(https://github.com/nodejs/node/pull/33600)
- **dns**: add dns/promises alias (shisama)
(https://github.com/nodejs/node/pull/32953)
- **doc**: move DEP0018 to End-of-Life (Rich Trott)
(https://github.com/nodejs/node/pull/35316)
- **doc**: update support macos version for 15.x (Ash Cripps)
(https://github.com/nodejs/node/pull/35022)
- **fs**: deprecation warning on recursive rmdir (Ian Sutherland)
(https://github.com/nodejs/node/pull/35562)
- **fs**: reimplement read and write streams using stream.construct
(Robert Nagy) (https://github.com/nodejs/node/pull/29656)
- **http**: fixed socket.setEncoding fatal error (iskore)
(https://github.com/nodejs/node/pull/33405)
- **http**: emit 'error' on aborted server request (Robert Nagy)
(https://github.com/nodejs/node/pull/33172)
- **http**: cleanup end argument handling (Robert Nagy)
(https://github.com/nodejs/node/pull/31818)
- **http2**: allow Host in HTTP/2 requests (Alba Mendez)
(https://github.com/nodejs/node/pull/34664)
- **http2**: add `invalidheaders` test (Pranshu Srivastava)
(https://github.com/nodejs/node/pull/33161)
- **http2**: refactor state code validation for the http2Stream class
(rickyes) (https://github.com/nodejs/node/pull/33535)
- **http2**: header field valid checks (Pranshu Srivastava)
(https://github.com/nodejs/node/pull/33193)
- **lib**: add EventTarget-related browser globals (Anna Henningsen)
(https://github.com/nodejs/node/pull/35496)
- **lib**: remove ERR\_INVALID\_OPT\_VALUE and
ERR\_INVALID\_OPT\_VALUE\_ENCODING (Denys Otrishko)
(https://github.com/nodejs/node/pull/34682)
- **lib**: handle one of args case in ERR\_MISSING\_ARGS (Denys
Otrishko) (https://github.com/nodejs/node/pull/34022)
- **lib**: remove NodeError from the prototype of errors with code
(Michaël Zasso) (https://github.com/nodejs/node/pull/33857)
- **lib**: unflag AbortController (James M Snell)
(https://github.com/nodejs/node/pull/33527)
- **lib**: initial experimental AbortController implementation (James M
Snell) (https://github.com/nodejs/node/pull/33527)
- **net**: check args in net.connect() and socket.connect() calls
(Denys Otrishko) (https://github.com/nodejs/node/pull/34022)
- **net**: remove long deprecated server.connections property (James M
Snell) (https://github.com/nodejs/node/pull/33647)
- **net**: autoDestroy Socket (Robert Nagy)
(https://github.com/nodejs/node/pull/31806)
- **process**: update v8 fast api calls usage (Maya Lekova)
(https://github.com/nodejs/node/pull/35415)
- **process**: change default --unhandled-rejections=throw (Dan
Fabulich) (https://github.com/nodejs/node/pull/33021)
- **process**: use v8 fast api calls for hrtime (Gus Caplan)
(https://github.com/nodejs/node/pull/33600)
- **process**: delay throwing an error using `throwDeprecation` (Ruben
Bridgewater) (https://github.com/nodejs/node/pull/32312)
- **repl**: remove deprecated repl.memory function (Ruben Bridgewater)
(https://github.com/nodejs/node/pull/33286)
- **repl**: remove deprecated repl.turnOffEditorMode() function (Ruben
Bridgewater) (https://github.com/nodejs/node/pull/33286)
- **repl**: remove deprecated repl.parseREPLKeyword() function (Ruben
Bridgewater) (https://github.com/nodejs/node/pull/33286)
- **repl**: remove deprecated bufferedCommand property (Ruben
Bridgewater) (https://github.com/nodejs/node/pull/33286)
- **repl**: remove deprecated .rli (Ruben Bridgewater)
(https://github.com/nodejs/node/pull/33286)
- **src**: implement NodePlatform::PostJob (Clemens Backes)
(https://github.com/nodejs/node/pull/35415)
- **src**: update NODE\_MODULE\_VERSION to 88 (Michaël Zasso)
(https://github.com/nodejs/node/pull/35415)
- **src**: error reporting on CPUUsage (Yash Ladha)
(https://github.com/nodejs/node/pull/34762)
- **src**: use node:moduleName as builtin module filename (Michaël
Zasso) (https://github.com/nodejs/node/pull/35498)
- **src**: enable wasm trap handler on windows (Gus Caplan)
(https://github.com/nodejs/node/pull/35033)
- **src**: update NODE\_MODULE\_VERSION to 86 (Michaël Zasso)
(https://github.com/nodejs/node/pull/33579)
- **src**: disallow JS execution inside FreeEnvironment (Anna
Henningsen) (https://github.com/nodejs/node/pull/33874)
- **src**: remove \_third\_party\_main support (Anna Henningsen)
(https://github.com/nodejs/node/pull/33971)
- **src**: remove deprecated node debug command (James M Snell)
(https://github.com/nodejs/node/pull/33648)
- **src**: remove unused CancelPendingDelayedTasks (Anna Henningsen)
(https://github.com/nodejs/node/pull/32859)
- **stream**: try to wait for flush to complete before 'finish' (Robert
Nagy) (https://github.com/nodejs/node/pull/34314)
- **stream**: cleanup and fix Readable.wrap (Robert Nagy)
(https://github.com/nodejs/node/pull/34204)
- **stream**: add promises version to utility functions (rickyes)
(https://github.com/nodejs/node/pull/33991)
- **stream**: fix writable.end callback behavior (Robert Nagy)
(https://github.com/nodejs/node/pull/34101)
- **stream**: construct (Robert Nagy)
(https://github.com/nodejs/node/pull/29656)
- **stream**: write should throw on unknown encoding (Robert Nagy)
(https://github.com/nodejs/node/pull/33075)
- **stream**: fix \_final and 'prefinish' timing (Robert Nagy)
(https://github.com/nodejs/node/pull/32780)
- **stream**: simplify Transform stream implementation (Robert Nagy)
(https://github.com/nodejs/node/pull/32763)
- **stream**: use callback to properly propagate error (Robert Nagy)
(https://github.com/nodejs/node/pull/29179)
- **test**: update tests after increasing typed array size to 4GB
(Kim-Anh Tran) (https://github.com/nodejs/node/pull/35415)
- **test**: fix tests for npm 7.0.0 (Myles Borins)
(https://github.com/nodejs/node/pull/35631)
- **test**: fix test suite to work with npm 7 (Myles Borins)
(https://github.com/nodejs/node/pull/35474)
- **test**: update WPT harness and tests (Michaël Zasso)
(https://github.com/nodejs/node/pull/33770)
- **timers**: introduce timers/promises (James M Snell)
(https://github.com/nodejs/node/pull/33950)
- **tools**: disable x86 safe exception handlers in V8 (Michaël Zasso)
(https://github.com/nodejs/node/pull/35415)
- **tools**: update V8 gypfiles for 8.6 (Ujjwal Sharma)
(https://github.com/nodejs/node/pull/35415)
- **tools**: update V8 gypfiles for 8.5 (Ujjwal Sharma)
(https://github.com/nodejs/node/pull/35415)
- **url**: file URL path normalization (Daijiro Wachi)
(https://github.com/nodejs/node/pull/35477)
- **url**: verify domain is not empty after "ToASCII" (Michaël Zasso)
(https://github.com/nodejs/node/pull/33770)
- **url**: remove U+0000 case in the fragment state (Michaël Zasso)
(https://github.com/nodejs/node/pull/33770)
- **url**: remove gopher from special schemes (Michaël Zasso)
(https://github.com/nodejs/node/pull/33325)
- **url**: forbid lt and gt in url host code point (Yash Ladha)
(https://github.com/nodejs/node/pull/33328)
- **util**: change default value of `maxStringLength` to 10000
(unknown) (https://github.com/nodejs/node/pull/32744)
- **wasi**: drop --experimental-wasm-bigint requirement (Colin Ihrig)
(https://github.com/nodejs/node/pull/35415)
- **win, child_process**: sanitize env variables (Bartosz Sosnowski)
(https://github.com/nodejs/node/pull/35210)
- **worker**: make MessageEvent class more Web-compatible (Anna
Henningsen) (https://github.com/nodejs/node/pull/35496)
- **worker**: set trackUnmanagedFds to true by default (Anna
Henningsen) (https://github.com/nodejs/node/pull/34394)
- **worker**: rename error code to be more accurate (Anna Henningsen)
(https://github.com/nodejs/node/pull/33872)
PR-URL: https://github.com/nodejs/node/pull/35014
2020-09-01 21:16:46 +01:00
|
|
|
- version: v15.0.0
|
2020-06-21 15:10:00 +02:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/34001
|
2022-04-20 10:23:41 +02:00
|
|
|
description: Exposed as `require('node:assert/strict')`.
|
2020-04-24 18:43:06 +02:00
|
|
|
- version:
|
|
|
|
- v13.9.0
|
|
|
|
- v12.16.2
|
2020-10-01 20:21:07 +02:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/31635
|
2020-02-04 09:41:55 -08:00
|
|
|
description: Changed "strict mode" to "strict assertion mode" and "legacy
|
|
|
|
mode" to "legacy assertion mode" to avoid confusion with the
|
2020-07-12 09:33:11 +09:00
|
|
|
more usual meaning of "strict mode".
|
2018-03-18 14:45:41 +01:00
|
|
|
- version: v9.9.0
|
2018-02-04 16:30:04 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/17615
|
2020-02-04 09:41:55 -08:00
|
|
|
description: Added error diffs to the strict assertion mode.
|
2018-03-18 14:45:41 +01:00
|
|
|
- version: v9.9.0
|
2017-11-13 18:15:24 -02:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/17002
|
2020-02-04 09:41:55 -08:00
|
|
|
description: Added strict assertion mode to the assert module.
|
2017-11-13 18:15:24 -02:00
|
|
|
-->
|
|
|
|
|
2020-02-06 10:27:52 -10:00
|
|
|
In strict assertion mode, non-strict methods behave like their corresponding
|
|
|
|
strict methods. For example, [`assert.deepEqual()`][] will behave like
|
|
|
|
[`assert.deepStrictEqual()`][].
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
In strict assertion mode, error messages for objects display a diff. In legacy
|
|
|
|
assertion mode, error messages for objects display the objects, often truncated.
|
2017-12-09 19:38:20 -02:00
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
To use strict assertion mode:
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import { strict as assert } from 'node:assert';
|
2021-03-04 15:00:25 -08:00
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert').strict;
|
2017-11-13 18:15:24 -02:00
|
|
|
```
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2020-06-21 15:10:00 +02:00
|
|
|
```
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2018-04-26 03:06:10 +02:00
|
|
|
Example error diff:
|
2017-12-09 19:38:20 -02:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import { strict as assert } from 'node:assert';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.deepEqual([[[1, 2, 3]], 4, 5], [[[1, 2, '3']], 4, 5]);
|
|
|
|
// AssertionError: Expected inputs to be strictly deep-equal:
|
|
|
|
// + actual - expected ... Lines skipped
|
|
|
|
//
|
|
|
|
// [
|
|
|
|
// [
|
|
|
|
// ...
|
|
|
|
// 2,
|
|
|
|
// + 3
|
|
|
|
// - '3'
|
|
|
|
// ],
|
|
|
|
// ...
|
|
|
|
// 5
|
|
|
|
// ]
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2017-12-09 19:38:20 -02:00
|
|
|
|
|
|
|
assert.deepEqual([[[1, 2, 3]], 4, 5], [[[1, 2, '3']], 4, 5]);
|
2018-07-03 02:06:57 +02:00
|
|
|
// AssertionError: Expected inputs to be strictly deep-equal:
|
|
|
|
// + actual - expected ... Lines skipped
|
2018-04-26 03:06:10 +02:00
|
|
|
//
|
|
|
|
// [
|
|
|
|
// [
|
|
|
|
// ...
|
|
|
|
// 2,
|
2018-07-03 02:06:57 +02:00
|
|
|
// + 3
|
|
|
|
// - '3'
|
2018-04-26 03:06:10 +02:00
|
|
|
// ],
|
|
|
|
// ...
|
|
|
|
// 5
|
|
|
|
// ]
|
2017-12-09 19:38:20 -02:00
|
|
|
```
|
|
|
|
|
2020-02-08 15:19:13 -10:00
|
|
|
To deactivate the colors, use the `NO_COLOR` or `NODE_DISABLE_COLORS`
|
|
|
|
environment variables. This will also deactivate the colors in the REPL. For
|
|
|
|
more on color support in terminal environments, read the tty
|
2021-07-04 20:39:17 -07:00
|
|
|
[`getColorDepth()`][] documentation.
|
2019-11-14 16:45:24 +05:30
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
## Legacy assertion mode
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2022-01-07 20:00:55 -08:00
|
|
|
Legacy assertion mode uses the [`==` operator][] in:
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2019-06-19 22:05:44 -06:00
|
|
|
* [`assert.deepEqual()`][]
|
|
|
|
* [`assert.equal()`][]
|
|
|
|
* [`assert.notDeepEqual()`][]
|
|
|
|
* [`assert.notEqual()`][]
|
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
To use legacy assertion mode:
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2021-03-08 16:05:29 +01:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert';
|
2021-03-04 15:00:25 -08:00
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert');
|
2017-11-13 18:15:24 -02:00
|
|
|
```
|
|
|
|
|
2022-01-05 12:35:02 -08:00
|
|
|
Legacy assertion mode may have surprising results, especially when using
|
|
|
|
[`assert.deepEqual()`][]:
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```cjs
|
2022-01-05 12:35:02 -08:00
|
|
|
// WARNING: This does not throw an AssertionError in legacy assertion mode!
|
2017-11-13 18:15:24 -02:00
|
|
|
assert.deepEqual(/a/gi, new Date());
|
|
|
|
```
|
|
|
|
|
2020-02-06 10:27:52 -10:00
|
|
|
## Class: assert.AssertionError
|
|
|
|
|
|
|
|
* Extends: {errors.Error}
|
|
|
|
|
2022-04-20 10:23:41 +02:00
|
|
|
Indicates the failure of an assertion. All errors thrown by the `node:assert`
|
|
|
|
module will be instances of the `AssertionError` class.
|
2020-02-06 10:27:52 -10:00
|
|
|
|
|
|
|
### `new assert.AssertionError(options)`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2020-02-06 10:27:52 -10:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.21
|
|
|
|
-->
|
|
|
|
|
|
|
|
* `options` {Object}
|
|
|
|
* `message` {string} If provided, the error message is set to this value.
|
|
|
|
* `actual` {any} The `actual` property on the error instance.
|
|
|
|
* `expected` {any} The `expected` property on the error instance.
|
|
|
|
* `operator` {string} The `operator` property on the error instance.
|
|
|
|
* `stackStartFn` {Function} If provided, the generated stack trace omits
|
|
|
|
frames before this function.
|
|
|
|
|
2025-02-05 14:59:37 +01:00
|
|
|
A subclass of {Error} that indicates the failure of an assertion.
|
2020-02-06 10:27:52 -10:00
|
|
|
|
|
|
|
All instances contain the built-in `Error` properties (`message` and `name`)
|
|
|
|
and:
|
|
|
|
|
|
|
|
* `actual` {any} Set to the `actual` argument for methods such as
|
|
|
|
[`assert.strictEqual()`][].
|
|
|
|
* `expected` {any} Set to the `expected` value for methods such as
|
|
|
|
[`assert.strictEqual()`][].
|
|
|
|
* `generatedMessage` {boolean} Indicates if the message was auto-generated
|
|
|
|
(`true`) or not.
|
|
|
|
* `code` {string} Value is always `ERR_ASSERTION` to show that the error is an
|
|
|
|
assertion error.
|
|
|
|
* `operator` {string} Set to the passed in operator value.
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
// Generate an AssertionError to compare the error message later:
|
|
|
|
const { message } = new assert.AssertionError({
|
|
|
|
actual: 1,
|
|
|
|
expected: 2,
|
2022-11-17 08:19:12 -05:00
|
|
|
operator: 'strictEqual',
|
2021-03-04 15:00:25 -08:00
|
|
|
});
|
|
|
|
|
|
|
|
// Verify error output:
|
|
|
|
try {
|
|
|
|
assert.strictEqual(1, 2);
|
|
|
|
} catch (err) {
|
|
|
|
assert(err instanceof assert.AssertionError);
|
|
|
|
assert.strictEqual(err.message, message);
|
|
|
|
assert.strictEqual(err.name, 'AssertionError');
|
|
|
|
assert.strictEqual(err.actual, 1);
|
|
|
|
assert.strictEqual(err.expected, 2);
|
|
|
|
assert.strictEqual(err.code, 'ERR_ASSERTION');
|
|
|
|
assert.strictEqual(err.operator, 'strictEqual');
|
|
|
|
assert.strictEqual(err.generatedMessage, true);
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert');
|
2020-02-06 10:27:52 -10:00
|
|
|
|
|
|
|
// Generate an AssertionError to compare the error message later:
|
|
|
|
const { message } = new assert.AssertionError({
|
|
|
|
actual: 1,
|
|
|
|
expected: 2,
|
2022-11-17 08:19:12 -05:00
|
|
|
operator: 'strictEqual',
|
2020-02-06 10:27:52 -10:00
|
|
|
});
|
|
|
|
|
|
|
|
// Verify error output:
|
|
|
|
try {
|
|
|
|
assert.strictEqual(1, 2);
|
|
|
|
} catch (err) {
|
|
|
|
assert(err instanceof assert.AssertionError);
|
|
|
|
assert.strictEqual(err.message, message);
|
|
|
|
assert.strictEqual(err.name, 'AssertionError');
|
|
|
|
assert.strictEqual(err.actual, 1);
|
|
|
|
assert.strictEqual(err.expected, 2);
|
|
|
|
assert.strictEqual(err.code, 'ERR_ASSERTION');
|
|
|
|
assert.strictEqual(err.operator, 'strictEqual');
|
|
|
|
assert.strictEqual(err.generatedMessage, true);
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2020-02-27 11:41:05 +00:00
|
|
|
## Class: `assert.CallTracker`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2020-04-28 15:19:14 +02:00
|
|
|
<!-- YAML
|
2020-09-28 10:54:13 -07:00
|
|
|
added:
|
|
|
|
- v14.2.0
|
|
|
|
- v12.19.0
|
2023-04-29 09:57:08 +03:00
|
|
|
changes:
|
2023-05-02 09:36:58 +02:00
|
|
|
- version: v20.1.0
|
2023-04-29 09:57:08 +03:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/47740
|
|
|
|
description: the `assert.CallTracker` class has been deprecated and will be
|
|
|
|
removed in a future version.
|
2020-04-28 15:19:14 +02:00
|
|
|
-->
|
|
|
|
|
2023-04-29 09:57:08 +03:00
|
|
|
> Stability: 0 - Deprecated
|
2020-04-28 15:19:14 +02:00
|
|
|
|
2023-04-29 09:57:08 +03:00
|
|
|
This feature is deprecated and will be removed in a future version.
|
|
|
|
Please consider using alternatives such as the
|
|
|
|
[`mock`][] helper function.
|
2020-02-27 11:41:05 +00:00
|
|
|
|
2020-09-22 20:29:28 -07:00
|
|
|
### `new assert.CallTracker()`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2020-02-27 11:41:05 +00:00
|
|
|
<!-- YAML
|
2020-09-28 10:54:13 -07:00
|
|
|
added:
|
|
|
|
- v14.2.0
|
|
|
|
- v12.19.0
|
2020-02-27 11:41:05 +00:00
|
|
|
-->
|
|
|
|
|
|
|
|
Creates a new [`CallTracker`][] object which can be used to track if functions
|
|
|
|
were called a specific number of times. The `tracker.verify()` must be called
|
|
|
|
for the verification to take place. The usual pattern would be to call it in a
|
|
|
|
[`process.on('exit')`][] handler.
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert';
|
|
|
|
import process from 'node:process';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
const tracker = new assert.CallTracker();
|
|
|
|
|
|
|
|
function func() {}
|
|
|
|
|
|
|
|
// callsfunc() must be called exactly 1 time before tracker.verify().
|
|
|
|
const callsfunc = tracker.calls(func, 1);
|
|
|
|
|
|
|
|
callsfunc();
|
|
|
|
|
|
|
|
// Calls tracker.verify() and verifies if all tracker.calls() functions have
|
|
|
|
// been called exact times.
|
|
|
|
process.on('exit', () => {
|
|
|
|
tracker.verify();
|
|
|
|
});
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert');
|
2024-07-04 15:49:38 -04:00
|
|
|
const process = require('node:process');
|
2020-02-27 11:41:05 +00:00
|
|
|
|
|
|
|
const tracker = new assert.CallTracker();
|
|
|
|
|
|
|
|
function func() {}
|
|
|
|
|
|
|
|
// callsfunc() must be called exactly 1 time before tracker.verify().
|
|
|
|
const callsfunc = tracker.calls(func, 1);
|
|
|
|
|
|
|
|
callsfunc();
|
|
|
|
|
|
|
|
// Calls tracker.verify() and verifies if all tracker.calls() functions have
|
|
|
|
// been called exact times.
|
|
|
|
process.on('exit', () => {
|
|
|
|
tracker.verify();
|
|
|
|
});
|
|
|
|
```
|
|
|
|
|
|
|
|
### `tracker.calls([fn][, exact])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2020-02-27 11:41:05 +00:00
|
|
|
<!-- YAML
|
2020-09-28 10:54:13 -07:00
|
|
|
added:
|
|
|
|
- v14.2.0
|
|
|
|
- v12.19.0
|
2020-02-27 11:41:05 +00:00
|
|
|
-->
|
|
|
|
|
2021-02-15 13:21:50 -05:00
|
|
|
* `fn` {Function} **Default:** A no-op function.
|
|
|
|
* `exact` {number} **Default:** `1`.
|
2024-02-14 00:37:42 +03:00
|
|
|
* Returns: {Function} A function that wraps `fn`.
|
2020-02-27 11:41:05 +00:00
|
|
|
|
|
|
|
The wrapper function is expected to be called exactly `exact` times. If the
|
|
|
|
function has not been called exactly `exact` times when
|
|
|
|
[`tracker.verify()`][] is called, then [`tracker.verify()`][] will throw an
|
|
|
|
error.
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
// Creates call tracker.
|
|
|
|
const tracker = new assert.CallTracker();
|
|
|
|
|
|
|
|
function func() {}
|
|
|
|
|
|
|
|
// Returns a function that wraps func() that must be called exact times
|
|
|
|
// before tracker.verify().
|
|
|
|
const callsfunc = tracker.calls(func);
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert');
|
2020-02-27 11:41:05 +00:00
|
|
|
|
|
|
|
// Creates call tracker.
|
|
|
|
const tracker = new assert.CallTracker();
|
|
|
|
|
|
|
|
function func() {}
|
|
|
|
|
|
|
|
// Returns a function that wraps func() that must be called exact times
|
|
|
|
// before tracker.verify().
|
|
|
|
const callsfunc = tracker.calls(func);
|
|
|
|
```
|
|
|
|
|
2022-08-11 22:27:34 +03:00
|
|
|
### `tracker.getCalls(fn)`
|
|
|
|
|
|
|
|
<!-- YAML
|
2022-10-11 14:54:19 -05:00
|
|
|
added:
|
|
|
|
- v18.8.0
|
|
|
|
- v16.18.0
|
2022-08-11 22:27:34 +03:00
|
|
|
-->
|
|
|
|
|
2024-02-14 00:37:42 +03:00
|
|
|
* `fn` {Function}
|
2022-08-11 22:27:34 +03:00
|
|
|
|
2024-02-14 00:37:42 +03:00
|
|
|
* Returns: {Array} An array with all the calls to a tracked function.
|
2022-08-11 22:27:34 +03:00
|
|
|
|
|
|
|
* Object {Object}
|
|
|
|
* `thisArg` {Object}
|
|
|
|
* `arguments` {Array} the arguments passed to the tracked function
|
|
|
|
|
|
|
|
```mjs
|
|
|
|
import assert from 'node:assert';
|
|
|
|
|
|
|
|
const tracker = new assert.CallTracker();
|
|
|
|
|
|
|
|
function func() {}
|
|
|
|
const callsfunc = tracker.calls(func);
|
|
|
|
callsfunc(1, 2, 3);
|
|
|
|
|
|
|
|
assert.deepStrictEqual(tracker.getCalls(callsfunc),
|
2023-03-30 03:17:18 +09:00
|
|
|
[{ thisArg: undefined, arguments: [1, 2, 3] }]);
|
2022-08-11 22:27:34 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
|
|
|
const assert = require('node:assert');
|
|
|
|
|
|
|
|
// Creates call tracker.
|
|
|
|
const tracker = new assert.CallTracker();
|
|
|
|
|
|
|
|
function func() {}
|
|
|
|
const callsfunc = tracker.calls(func);
|
|
|
|
callsfunc(1, 2, 3);
|
|
|
|
|
|
|
|
assert.deepStrictEqual(tracker.getCalls(callsfunc),
|
2023-03-30 03:17:18 +09:00
|
|
|
[{ thisArg: undefined, arguments: [1, 2, 3] }]);
|
2022-08-11 22:27:34 +03:00
|
|
|
```
|
|
|
|
|
2020-02-27 11:41:05 +00:00
|
|
|
### `tracker.report()`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2020-02-27 11:41:05 +00:00
|
|
|
<!-- YAML
|
2020-09-28 10:54:13 -07:00
|
|
|
added:
|
|
|
|
- v14.2.0
|
|
|
|
- v12.19.0
|
2020-02-27 11:41:05 +00:00
|
|
|
-->
|
|
|
|
|
2024-02-14 00:37:42 +03:00
|
|
|
* Returns: {Array} An array of objects containing information about the wrapper
|
|
|
|
functions returned by [`tracker.calls()`][].
|
2020-02-27 11:41:05 +00:00
|
|
|
* Object {Object}
|
|
|
|
* `message` {string}
|
|
|
|
* `actual` {number} The actual number of times the function was called.
|
|
|
|
* `expected` {number} The number of times the function was expected to be
|
|
|
|
called.
|
|
|
|
* `operator` {string} The name of the function that is wrapped.
|
|
|
|
* `stack` {Object} A stack trace of the function.
|
|
|
|
|
|
|
|
The arrays contains information about the expected and actual number of calls of
|
|
|
|
the functions that have not been called the expected number of times.
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
// Creates call tracker.
|
|
|
|
const tracker = new assert.CallTracker();
|
|
|
|
|
|
|
|
function func() {}
|
|
|
|
|
|
|
|
// Returns a function that wraps func() that must be called exact times
|
|
|
|
// before tracker.verify().
|
|
|
|
const callsfunc = tracker.calls(func, 2);
|
|
|
|
|
|
|
|
// Returns an array containing information on callsfunc()
|
2023-03-30 03:17:18 +09:00
|
|
|
console.log(tracker.report());
|
2021-03-04 15:00:25 -08:00
|
|
|
// [
|
|
|
|
// {
|
|
|
|
// message: 'Expected the func function to be executed 2 time(s) but was
|
|
|
|
// executed 0 time(s).',
|
|
|
|
// actual: 0,
|
|
|
|
// expected: 2,
|
|
|
|
// operator: 'func',
|
|
|
|
// stack: stack trace
|
|
|
|
// }
|
|
|
|
// ]
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert');
|
2020-02-27 11:41:05 +00:00
|
|
|
|
|
|
|
// Creates call tracker.
|
|
|
|
const tracker = new assert.CallTracker();
|
|
|
|
|
|
|
|
function func() {}
|
|
|
|
|
|
|
|
// Returns a function that wraps func() that must be called exact times
|
|
|
|
// before tracker.verify().
|
|
|
|
const callsfunc = tracker.calls(func, 2);
|
|
|
|
|
|
|
|
// Returns an array containing information on callsfunc()
|
2023-03-30 03:17:18 +09:00
|
|
|
console.log(tracker.report());
|
2020-02-27 11:41:05 +00:00
|
|
|
// [
|
|
|
|
// {
|
|
|
|
// message: 'Expected the func function to be executed 2 time(s) but was
|
|
|
|
// executed 0 time(s).',
|
|
|
|
// actual: 0,
|
|
|
|
// expected: 2,
|
|
|
|
// operator: 'func',
|
|
|
|
// stack: stack trace
|
|
|
|
// }
|
|
|
|
// ]
|
|
|
|
```
|
|
|
|
|
2022-08-11 22:27:34 +03:00
|
|
|
### `tracker.reset([fn])`
|
|
|
|
|
|
|
|
<!-- YAML
|
2022-10-11 14:54:19 -05:00
|
|
|
added:
|
|
|
|
- v18.8.0
|
|
|
|
- v16.18.0
|
2022-08-11 22:27:34 +03:00
|
|
|
-->
|
|
|
|
|
|
|
|
* `fn` {Function} a tracked function to reset.
|
|
|
|
|
2023-05-06 22:41:58 +03:00
|
|
|
Reset calls of the call tracker.
|
|
|
|
If a tracked function is passed as an argument, the calls will be reset for it.
|
2024-02-14 00:37:42 +03:00
|
|
|
If no arguments are passed, all tracked functions will be reset.
|
2022-08-11 22:27:34 +03:00
|
|
|
|
|
|
|
```mjs
|
|
|
|
import assert from 'node:assert';
|
|
|
|
|
|
|
|
const tracker = new assert.CallTracker();
|
|
|
|
|
|
|
|
function func() {}
|
|
|
|
const callsfunc = tracker.calls(func);
|
|
|
|
|
|
|
|
callsfunc();
|
|
|
|
// Tracker was called once
|
2023-03-30 03:17:18 +09:00
|
|
|
assert.strictEqual(tracker.getCalls(callsfunc).length, 1);
|
2022-08-11 22:27:34 +03:00
|
|
|
|
|
|
|
tracker.reset(callsfunc);
|
2023-03-30 03:17:18 +09:00
|
|
|
assert.strictEqual(tracker.getCalls(callsfunc).length, 0);
|
2022-08-11 22:27:34 +03:00
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
|
|
|
const assert = require('node:assert');
|
|
|
|
|
2023-03-30 03:17:18 +09:00
|
|
|
const tracker = new assert.CallTracker();
|
|
|
|
|
2022-08-11 22:27:34 +03:00
|
|
|
function func() {}
|
|
|
|
const callsfunc = tracker.calls(func);
|
|
|
|
|
|
|
|
callsfunc();
|
|
|
|
// Tracker was called once
|
2023-03-30 03:17:18 +09:00
|
|
|
assert.strictEqual(tracker.getCalls(callsfunc).length, 1);
|
2022-08-11 22:27:34 +03:00
|
|
|
|
|
|
|
tracker.reset(callsfunc);
|
2023-03-30 03:17:18 +09:00
|
|
|
assert.strictEqual(tracker.getCalls(callsfunc).length, 0);
|
2022-08-11 22:27:34 +03:00
|
|
|
```
|
|
|
|
|
2020-02-27 11:41:05 +00:00
|
|
|
### `tracker.verify()`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2020-02-27 11:41:05 +00:00
|
|
|
<!-- YAML
|
2020-09-28 10:54:13 -07:00
|
|
|
added:
|
|
|
|
- v14.2.0
|
|
|
|
- v12.19.0
|
2020-02-27 11:41:05 +00:00
|
|
|
-->
|
|
|
|
|
|
|
|
Iterates through the list of functions passed to
|
|
|
|
[`tracker.calls()`][] and will throw an error for functions that
|
|
|
|
have not been called the expected number of times.
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
// Creates call tracker.
|
|
|
|
const tracker = new assert.CallTracker();
|
|
|
|
|
|
|
|
function func() {}
|
|
|
|
|
|
|
|
// Returns a function that wraps func() that must be called exact times
|
|
|
|
// before tracker.verify().
|
|
|
|
const callsfunc = tracker.calls(func, 2);
|
|
|
|
|
|
|
|
callsfunc();
|
|
|
|
|
|
|
|
// Will throw an error since callsfunc() was only called once.
|
|
|
|
tracker.verify();
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert');
|
2020-02-27 11:41:05 +00:00
|
|
|
|
|
|
|
// Creates call tracker.
|
|
|
|
const tracker = new assert.CallTracker();
|
|
|
|
|
|
|
|
function func() {}
|
|
|
|
|
|
|
|
// Returns a function that wraps func() that must be called exact times
|
|
|
|
// before tracker.verify().
|
|
|
|
const callsfunc = tracker.calls(func, 2);
|
|
|
|
|
|
|
|
callsfunc();
|
|
|
|
|
|
|
|
// Will throw an error since callsfunc() was only called once.
|
|
|
|
tracker.verify();
|
|
|
|
```
|
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert(value[, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.5.9
|
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2018-05-02 16:13:16 +02:00
|
|
|
* `value` {any} The input that is checked for being truthy.
|
|
|
|
* `message` {string|Error}
|
2010-10-28 23:18:16 +11:00
|
|
|
|
2017-03-19 20:49:47 -07:00
|
|
|
An alias of [`assert.ok()`][].
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.deepEqual(actual, expected[, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.21
|
2017-02-21 23:39:15 +01:00
|
|
|
changes:
|
2025-04-03 01:37:44 +02:00
|
|
|
- version: REPLACEME
|
|
|
|
pr-url: https://github.com/nodejs/node/pull/57622
|
|
|
|
description: Recursion now stops when either side encounters a circular
|
|
|
|
reference.
|
2024-06-17 14:18:32 +02:00
|
|
|
- version:
|
|
|
|
- v22.2.0
|
|
|
|
- v20.15.0
|
2024-05-13 03:46:13 +08:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/51805
|
|
|
|
description: Error cause and errors properties are now compared as well.
|
2022-04-19, Version 18.0.0 (Current)
Notable Changes:
Deprecations and Removals:
- (SEMVER-MAJOR) fs: runtime deprecate string coercion in `fs.write`,
`fs.writeFileSync`
(Livia Medeiros) (https://github.com/nodejs/node/pull/42607)
- (SEMVER-MAJOR) dns: remove `dns.lookup` and `dnsPromises.lookup`
options type coercion
(Antoine du Hamel) (https://github.com/nodejs/node/pull/41431)
- (SEMVER-MAJOR) process: runtime deprecate multipleResolves
(Benjamin Gruenbaum) (https://github.com/nodejs/node/pull/41896)
- (SEMVER-MAJOR) stream: remove thenable support (Robert Nagy)
(https://github.com/nodejs/node/pull/40773)
- (SEMVER-MAJOR) tls: move tls.parseCertString to end-of-life
(Tobias Nießen) (https://github.com/nodejs/node/pull/41479)
fetch (experimental):
An experimental fetch API is available on the global scope by default.
The implementation is based upon https://undici.nodejs.org/#/,
an HTTP/1.1 client written for Node.js by contributors to the project.
Through this addition, the following globals are made available: `fetch`
, `FormData`, `Headers`, `Request`, `Response`.
Disable this API with the `--no-experimental-fetch` command-line flag.
Contributed by Michaël Zasso in https://github.com/nodejs/node/pull/41811.
HTTP Timeouts:
`server.headersTimeout`, which limits the amount of time the parser will
wait to receive the complete HTTP headers, is now set to `60000` (60
seconds) by default.
`server.requestTimeout`, which sets the timeout value in milliseconds
for receiving the entire request from the client, is now set to `300000`
(5 minutes) by default.
If these timeouts expire, the server responds with status 408 without
forwarding the request to the request listener and then closes the
connection.
Both timeouts must be set to a non-zero value to protect against
potential Denial-of-Service attacks in case the server is deployed
without a reverse proxy in front.
Contributed by Paolo Insogna in https://github.com/nodejs/node/pull/41263.
Test Runner module (experimental):
The `node:test` module facilitates the creation of JavaScript tests that
report results in TAP format. This module is only available under the
`node:` scheme.
Contributed by Colin Ihrig in https://github.com/nodejs/node/pull/42325.
Toolchain and Compiler Upgrades:
- Prebuilt binaries for Linux are now built on Red Hat Enterprise Linux
(RHEL) 8 and are compatible with Linux distributions based on glibc
2.28 or later, for example, Debian 10, RHEL 8, Ubuntu 20.04.
- Prebuilt binaries for macOS now require macOS 10.15 or later.
- For AIX the minimum supported architecture has been raised from Power
7 to Power 8.
Prebuilt binaries for 32-bit Windows will initially not be available due
to issues building the V8 dependency in Node.js. We hope to restore
32-bit Windows binaries for Node.js 18 with a future V8 update.
Node.js does not support running on operating systems that are no longer
supported by their vendor. For operating systems where their vendor has
planned to end support earlier than April 2025, such as Windows 8.1
(January 2023) and Windows Server 2012 R2 (October 2023), support for
Node.js 18 will end at the earlier date.
Full details about the supported toolchains and compilers are documented
in the Node.js `BUILDING.md` file.
Contributed by Richard Lau in https://github.com/nodejs/node/pull/42292,
https://github.com/nodejs/node/pull/42604 and https://github.com/nodejs/node/pull/42659
, and Michaël Zasso in https://github.com/nodejs/node/pull/42105 and
https://github.com/nodejs/node/pull/42666.
V8 10.1:
The V8 engine is updated to version 10.1, which is part of Chromium 101.
Compared to the version included in Node.js 17.9.0, the following new
features are included:
- The `findLast` and `findLastIndex` array methods.
- Improvements to the `Intl.Locale` API.
- The `Intl.supportedValuesOf` function.
- Improved performance of class fields and private class methods (the
initialization of them is now as fast as ordinary property stores).
The data format returned by the serialization API (`v8.serialize(value)`)
has changed, and cannot be deserialized by earlier versions of Node.js.
On the other hand, it is still possible to deserialize the previous
format, as the API is backwards-compatible.
Contributed by Michaël Zasso in https://github.com/nodejs/node/pull/42657.
Web Streams API (experimental):
Node.js now exposes the experimental implementation of the Web Streams
API on the global scope. This means the following APIs are now globally
available:
- `ReadableStream`, `ReadableStreamDefaultReader`,
`ReadableStreamBYOBReader`, `ReadableStreamBYOBRequest`,
`ReadableByteStreamController`, `ReadableStreamDefaultController`,
`TransformStream`, `TransformStreamDefaultController`, `WritableStream`,
`WritableStreamDefaultWriter`, `WritableStreamDefaultController`,
`ByteLengthQueuingStrategy`, `CountQueuingStrategy`, `TextEncoderStream`,
`TextDecoderStream`, `CompressionStream`, `DecompressionStream`.
Contributed James Snell in https://github.com/nodejs/node/pull/39062,
and Antoine du Hamel in https://github.com/nodejs/node/pull/42225.
Other Notable Changes:
- (SEMVER-MAJOR) buffer: expose Blob as a global
(James M Snell) (https://github.com/nodejs/node/pull/41270)
- (SEMVER-MAJOR) child\_process: improve argument validation
(Rich Trott) (https://github.com/nodejs/node/pull/41305)
- doc: add RafaelGSS to collaborators
(RafaelGSS) (https://github.com/nodejs/node/pull/42718)
- (SEMVER-MAJOR) http: make TCP noDelay enabled by default
(Paolo Insogna) (https://github.com/nodejs/node/pull/42163)
- (SEMVER-MAJOR) net: make `server.address()` return an integer for
`family`
(Antoine du Hamel) (https://github.com/nodejs/node/pull/41431)
- (SEMVER-MAJOR) worker: expose BroadcastChannel as a global
(James M Snell) (https://github.com/nodejs/node/pull/41271)
- (SEMVER-MAJOR) worker: graduate BroadcastChannel to supported
(James M Snell) (https://github.com/nodejs/node/pull/41271)
Semver-Major Commits:
- (SEMVER-MAJOR) assert,util: compare RegExp.lastIndex while using deep
equal checks
(Ruben Bridgewater) (https://github.com/nodejs/node/pull/41020)
- (SEMVER-MAJOR) buffer: refactor `byteLength` to remove outdated
optimizations
(Rongjian Zhang) (https://github.com/nodejs/node/pull/38545)
- (SEMVER-MAJOR) buffer: expose Blob as a global
(James M Snell) (https://github.com/nodejs/node/pull/41270)
- (SEMVER-MAJOR) buffer: graduate Blob from experimental
(James M Snell) (https://github.com/nodejs/node/pull/41270)
- (SEMVER-MAJOR) build: make x86 Windows support temporarily
experimental
(Michaël Zasso) (https://github.com/nodejs/node/pull/42666)
- (SEMVER-MAJOR) build: bump macOS deployment target to 10.15
(Richard Lau) (https://github.com/nodejs/node/pull/42292)
- (SEMVER-MAJOR) build: downgrade Windows 8.1 and server 2012 R2 to
experimental
(Michaël Zasso) (https://github.com/nodejs/node/pull/42105)
- (SEMVER-MAJOR) child\_process: improve argument validation
(Rich Trott) (https://github.com/nodejs/node/pull/41305)
- (SEMVER-MAJOR) cluster: make `kill` to be just `process.kill`
(Bar Admoni) (https://github.com/nodejs/node/pull/34312)
- (SEMVER-MAJOR) crypto: cleanup validation
(Mohammed Keyvanzadeh) (https://github.com/nodejs/node/pull/39841)
- (SEMVER-MAJOR) crypto: prettify othername in PrintGeneralName
(Tobias Nießen) (https://github.com/nodejs/node/pull/42123)
- (SEMVER-MAJOR) crypto: fix X509Certificate toLegacyObject
(Tobias Nießen) (https://github.com/nodejs/node/pull/42124)
- (SEMVER-MAJOR) crypto: use RFC2253 format in PrintGeneralName
(Tobias Nießen) (https://github.com/nodejs/node/pull/42002)
- (SEMVER-MAJOR) crypto: change default check(Host|Email) behavior
(Tobias Nießen) (https://github.com/nodejs/node/pull/41600)
- (SEMVER-MAJOR) deps: V8: cherry-pick semver-major commits from 10.2
(Michaël Zasso) (https://github.com/nodejs/node/pull/42657)
- (SEMVER-MAJOR) deps: update V8 to 10.1.124.6
(Michaël Zasso) (https://github.com/nodejs/node/pull/42657)
- (SEMVER-MAJOR) deps: update V8 to 9.8.177.9
(Michaël Zasso) (https://github.com/nodejs/node/pull/41610)
- (SEMVER-MAJOR) deps: update V8 to 9.7.106.18
(Michaël Zasso) (https://github.com/nodejs/node/pull/40907)
- (SEMVER-MAJOR) dns: remove `dns.lookup` and `dnsPromises.lookup`
options type coercion
(Antoine du Hamel) (https://github.com/nodejs/node/pull/41431)
- (SEMVER-MAJOR) doc: update minimum glibc requirements for Linux
(Richard Lau) (https://github.com/nodejs/node/pull/42659)
- (SEMVER-MAJOR) doc: update AIX minimum supported arch
(Richard Lau) (https://github.com/nodejs/node/pull/42604)
- (SEMVER-MAJOR) fs: runtime deprecate string coercion in `fs.write`,
`fs.writeFileSync`
(Livia Medeiros) (https://github.com/nodejs/node/pull/42607)
- (SEMVER-MAJOR) http: refactor headersTimeout and requestTimeout logic
(Paolo Insogna) (https://github.com/nodejs/node/pull/41263)
- (SEMVER-MAJOR) http: make TCP noDelay enabled by default
(Paolo Insogna) (https://github.com/nodejs/node/pull/42163)
- (SEMVER-MAJOR) lib: enable fetch by default
(Michaël Zasso) (https://github.com/nodejs/node/pull/41811)
- (SEMVER-MAJOR) lib: replace validator and error
(Mohammed Keyvanzadeh) (https://github.com/nodejs/node/pull/41678)
- (SEMVER-MAJOR) module,repl: support 'node:'-only core modules
(Colin Ihrig) (https://github.com/nodejs/node/pull/42325)
- (SEMVER-MAJOR) net: make `server.address()` return an integer for
`family`
(Antoine du Hamel) (https://github.com/nodejs/node/pull/41431)
- (SEMVER-MAJOR) process: disallow some uses of Object.defineProperty()
on process.env
(Himself65) (https://github.com/nodejs/node/pull/28006)
- (SEMVER-MAJOR) process: runtime deprecate multipleResolves
(Benjamin Gruenbaum) (https://github.com/nodejs/node/pull/41896)
- (SEMVER-MAJOR) readline: fix question still called after closed
(Xuguang Mei) (https://github.com/nodejs/node/pull/42464)
- (SEMVER-MAJOR) stream: remove thenable support
(Robert Nagy) (https://github.com/nodejs/node/pull/40773)
- (SEMVER-MAJOR) stream: expose web streams globals, remove runtime
experimental warning
(Antoine du Hamel) (https://github.com/nodejs/node/pull/42225)
- (SEMVER-MAJOR) stream: need to cleanup event listeners if last stream
is readable
(Xuguang Mei) (https://github.com/nodejs/node/pull/41954)
- (SEMVER-MAJOR) stream: revert revert `map` spec compliance
(Benjamin Gruenbaum) (https://github.com/nodejs/node/pull/41933)
- (SEMVER-MAJOR) stream: throw invalid arg type from End Of Stream
(Jithil P Ponnan) (https://github.com/nodejs/node/pull/41766)
- (SEMVER-MAJOR) stream: don't emit finish after destroy
(Robert Nagy) (https://github.com/nodejs/node/pull/40852)
- (SEMVER-MAJOR) stream: add errored and closed props
(Robert Nagy) (https://github.com/nodejs/node/pull/40696)
- (SEMVER-MAJOR) test: add initial test module
(Colin Ihrig) (https://github.com/nodejs/node/pull/42325)
- (SEMVER-MAJOR) timers: refactor internal classes to ES2015 syntax
(Rabbit) (https://github.com/nodejs/node/pull/37408)
- (SEMVER-MAJOR) tls: represent registeredID numerically always
(Tobias Nießen) (https://github.com/nodejs/node/pull/41561)
- (SEMVER-MAJOR) tls: move tls.parseCertString to end-of-life
(Tobias Nießen) (https://github.com/nodejs/node/pull/41479)
- (SEMVER-MAJOR) url: throw on NULL in IPv6 hostname
(Rich Trott) (https://github.com/nodejs/node/pull/42313)
- (SEMVER-MAJOR) v8: make v8.writeHeapSnapshot() error codes consistent
(Darshan Sen) (https://github.com/nodejs/node/pull/42577)
- (SEMVER-MAJOR) v8: make writeHeapSnapshot throw if fopen fails
(Antonio Román) (https://github.com/nodejs/node/pull/41373)
- (SEMVER-MAJOR) worker: expose BroadcastChannel as a global
(James M Snell) (https://github.com/nodejs/node/pull/41271)
- (SEMVER-MAJOR) worker: graduate BroadcastChannel to supported
(James M Snell) (https://github.com/nodejs/node/pull/41271)
PR-URL: https://github.com/nodejs/node/pull/42262
2022-03-08 01:39:47 +00:00
|
|
|
- version: v18.0.0
|
2021-12-02 09:01:40 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/41020
|
|
|
|
description: Regular expressions lastIndex property is now compared as well.
|
2021-09-04 15:29:35 +02:00
|
|
|
- version:
|
|
|
|
- v16.0.0
|
|
|
|
- v14.18.0
|
2021-04-06 10:20:53 -07:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/38113
|
|
|
|
description: In Legacy assertion mode, changed status from Deprecated to
|
|
|
|
Legacy.
|
2020-03-10 17:16:08 +00:00
|
|
|
- version: v14.0.0
|
2019-12-02 13:12:52 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/30766
|
2022-01-05 12:35:02 -08:00
|
|
|
description: NaN is now treated as being identical if both sides are
|
2019-12-02 13:12:52 +01:00
|
|
|
NaN.
|
2019-03-22 13:19:46 +00:00
|
|
|
- version: v12.0.0
|
2018-12-13 07:33:31 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/25008
|
|
|
|
description: The type tags are now properly compared and there are a couple
|
|
|
|
minor comparison adjustments to make the check less surprising.
|
2017-09-01 09:50:47 -07:00
|
|
|
- version: v9.0.0
|
2017-08-25 19:18:23 -03:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/15001
|
2020-10-01 20:35:23 +02:00
|
|
|
description: The `Error` names and messages are now properly compared.
|
2017-03-15 20:26:14 -07:00
|
|
|
- version: v8.0.0
|
2017-03-31 14:46:07 +11:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/12142
|
2020-10-01 20:35:23 +02:00
|
|
|
description: The `Set` and `Map` content is also compared.
|
2020-10-01 20:23:33 +02:00
|
|
|
- version:
|
2021-09-04 15:29:35 +02:00
|
|
|
- v6.4.0
|
|
|
|
- v4.7.1
|
2017-02-21 23:39:15 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/8002
|
|
|
|
description: Typed array slices are handled correctly now.
|
2020-10-01 20:23:33 +02:00
|
|
|
- version:
|
2021-09-04 15:29:35 +02:00
|
|
|
- v6.1.0
|
|
|
|
- v4.5.0
|
2017-02-21 23:39:15 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/6432
|
|
|
|
description: Objects with circular references can be used as inputs now.
|
2020-10-01 20:23:33 +02:00
|
|
|
- version:
|
2021-09-04 15:29:35 +02:00
|
|
|
- v5.10.1
|
|
|
|
- v4.4.3
|
2017-02-21 23:39:15 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/5910
|
|
|
|
description: Handle non-`Uint8Array` typed arrays correctly.
|
2016-05-10 23:08:33 -07:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2017-02-24 23:17:53 -08:00
|
|
|
* `actual` {any}
|
|
|
|
* `expected` {any}
|
2018-05-02 16:13:16 +02:00
|
|
|
* `message` {string|Error}
|
2010-10-28 23:18:16 +11:00
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
**Strict assertion mode**
|
2017-11-13 18:15:24 -02:00
|
|
|
|
|
|
|
An alias of [`assert.deepStrictEqual()`][].
|
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
**Legacy assertion mode**
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2021-04-06 10:20:53 -07:00
|
|
|
> Stability: 3 - Legacy: Use [`assert.deepStrictEqual()`][] instead.
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2018-12-13 07:33:31 +01:00
|
|
|
Tests for deep equality between the `actual` and `expected` parameters. Consider
|
|
|
|
using [`assert.deepStrictEqual()`][] instead. [`assert.deepEqual()`][] can have
|
2020-02-08 17:44:34 -10:00
|
|
|
surprising results.
|
2018-12-13 07:33:31 +01:00
|
|
|
|
2020-02-08 17:44:34 -10:00
|
|
|
_Deep equality_ means that the enumerable "own" properties of child objects
|
2018-12-13 07:33:31 +01:00
|
|
|
are also recursively evaluated by the following rules.
|
|
|
|
|
|
|
|
### Comparison details
|
|
|
|
|
2022-01-07 20:00:55 -08:00
|
|
|
* Primitive values are compared with the [`==` operator][],
|
2025-02-05 14:59:37 +01:00
|
|
|
with the exception of {NaN}. It is treated as being identical in case
|
|
|
|
both sides are {NaN}.
|
2018-12-13 07:33:31 +01:00
|
|
|
* [Type tags][Object.prototype.toString()] of objects should be the same.
|
|
|
|
* Only [enumerable "own" properties][] are considered.
|
2025-02-05 14:59:37 +01:00
|
|
|
* {Error} names, messages, causes, and errors are always compared,
|
2024-05-13 03:46:13 +08:00
|
|
|
even if these are not enumerable properties.
|
2018-12-13 07:33:31 +01:00
|
|
|
* [Object wrappers][] are compared both as objects and unwrapped values.
|
|
|
|
* `Object` properties are compared unordered.
|
2025-02-05 14:59:37 +01:00
|
|
|
* {Map} keys and {Set} items are compared unordered.
|
2025-04-03 01:37:44 +02:00
|
|
|
* Recursion stops when both sides differ or either side encounters a circular
|
2018-12-13 07:33:31 +01:00
|
|
|
reference.
|
|
|
|
* Implementation does not test the [`[[Prototype]]`][prototype-spec] of
|
|
|
|
objects.
|
2025-02-05 14:59:37 +01:00
|
|
|
* {Symbol} properties are not compared.
|
|
|
|
* {WeakMap} and {WeakSet} comparison does not rely on their values
|
2024-06-18 08:18:40 +02:00
|
|
|
but only on their instances.
|
2025-02-05 14:59:37 +01:00
|
|
|
* {RegExp} lastIndex, flags, and source are always compared, even if these
|
2021-12-02 09:01:40 +01:00
|
|
|
are not enumerable properties.
|
2017-02-03 06:02:29 +08:00
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
The following example does not throw an [`AssertionError`][] because the
|
2022-01-07 20:00:55 -08:00
|
|
|
primitives are compared using the [`==` operator][].
|
2015-10-12 13:58:00 -07:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert';
|
2021-03-04 15:00:25 -08:00
|
|
|
// WARNING: This does not throw an AssertionError!
|
|
|
|
|
|
|
|
assert.deepEqual('+00000000', false);
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert');
|
2016-01-17 18:39:07 +01:00
|
|
|
// WARNING: This does not throw an AssertionError!
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2018-12-13 07:33:31 +01:00
|
|
|
assert.deepEqual('+00000000', false);
|
2016-01-17 18:39:07 +01:00
|
|
|
```
|
2010-10-28 23:18:16 +11:00
|
|
|
|
2015-12-19 19:08:13 -08:00
|
|
|
"Deep" equality means that the enumerable "own" properties of child objects
|
|
|
|
are evaluated also:
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
const obj1 = {
|
|
|
|
a: {
|
2022-11-17 08:19:12 -05:00
|
|
|
b: 1,
|
|
|
|
},
|
2021-03-04 15:00:25 -08:00
|
|
|
};
|
|
|
|
const obj2 = {
|
|
|
|
a: {
|
2022-11-17 08:19:12 -05:00
|
|
|
b: 2,
|
|
|
|
},
|
2021-03-04 15:00:25 -08:00
|
|
|
};
|
|
|
|
const obj3 = {
|
|
|
|
a: {
|
2022-11-17 08:19:12 -05:00
|
|
|
b: 1,
|
|
|
|
},
|
2021-03-04 15:00:25 -08:00
|
|
|
};
|
2023-01-09 21:38:36 -08:00
|
|
|
const obj4 = { __proto__: obj1 };
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.deepEqual(obj1, obj1);
|
|
|
|
// OK
|
|
|
|
|
|
|
|
// Values of b are different:
|
|
|
|
assert.deepEqual(obj1, obj2);
|
|
|
|
// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }
|
|
|
|
|
|
|
|
assert.deepEqual(obj1, obj3);
|
|
|
|
// OK
|
|
|
|
|
|
|
|
// Prototypes are ignored:
|
|
|
|
assert.deepEqual(obj1, obj4);
|
|
|
|
// AssertionError: { a: { b: 1 } } deepEqual {}
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert');
|
2016-01-17 18:39:07 +01:00
|
|
|
|
|
|
|
const obj1 = {
|
2017-04-21 17:38:31 +03:00
|
|
|
a: {
|
2022-11-17 08:19:12 -05:00
|
|
|
b: 1,
|
|
|
|
},
|
2016-01-17 18:39:07 +01:00
|
|
|
};
|
|
|
|
const obj2 = {
|
2017-04-21 17:38:31 +03:00
|
|
|
a: {
|
2022-11-17 08:19:12 -05:00
|
|
|
b: 2,
|
|
|
|
},
|
2016-01-17 18:39:07 +01:00
|
|
|
};
|
|
|
|
const obj3 = {
|
2017-04-21 17:38:31 +03:00
|
|
|
a: {
|
2022-11-17 08:19:12 -05:00
|
|
|
b: 1,
|
|
|
|
},
|
2016-07-14 22:41:29 -07:00
|
|
|
};
|
2023-01-09 21:38:36 -08:00
|
|
|
const obj4 = { __proto__: obj1 };
|
2016-01-17 18:39:07 +01:00
|
|
|
|
|
|
|
assert.deepEqual(obj1, obj1);
|
2018-05-02 16:13:16 +02:00
|
|
|
// OK
|
2016-01-17 18:39:07 +01:00
|
|
|
|
2018-05-02 16:13:16 +02:00
|
|
|
// Values of b are different:
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.deepEqual(obj1, obj2);
|
2016-11-08 21:04:57 +01:00
|
|
|
// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }
|
2016-01-17 18:39:07 +01:00
|
|
|
|
|
|
|
assert.deepEqual(obj1, obj3);
|
2018-05-02 16:13:16 +02:00
|
|
|
// OK
|
2016-01-17 18:39:07 +01:00
|
|
|
|
2018-05-02 16:13:16 +02:00
|
|
|
// Prototypes are ignored:
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.deepEqual(obj1, obj4);
|
2016-11-08 21:04:57 +01:00
|
|
|
// AssertionError: { a: { b: 1 } } deepEqual {}
|
2016-01-17 18:39:07 +01:00
|
|
|
```
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
If the values are not equal, an [`AssertionError`][] is thrown with a `message`
|
2015-12-19 19:08:13 -08:00
|
|
|
property set equal to the value of the `message` parameter. If the `message`
|
2017-09-09 20:36:47 -05:00
|
|
|
parameter is undefined, a default error message is assigned. If the `message`
|
2025-02-05 14:59:37 +01:00
|
|
|
parameter is an instance of {Error} then it will be thrown instead of the
|
2019-06-20 17:13:31 +02:00
|
|
|
[`AssertionError`][].
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.deepStrictEqual(actual, expected[, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v1.2.0
|
2017-02-21 23:39:15 +01:00
|
|
|
changes:
|
2025-04-03 01:37:44 +02:00
|
|
|
- version: REPLACEME
|
|
|
|
pr-url: https://github.com/nodejs/node/pull/57622
|
|
|
|
description: Recursion now stops when either side encounters a circular
|
|
|
|
reference.
|
2024-06-17 14:18:32 +02:00
|
|
|
- version:
|
|
|
|
- v22.2.0
|
|
|
|
- v20.15.0
|
2024-05-13 03:46:13 +08:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/51805
|
|
|
|
description: Error cause and errors properties are now compared as well.
|
2022-04-19, Version 18.0.0 (Current)
Notable Changes:
Deprecations and Removals:
- (SEMVER-MAJOR) fs: runtime deprecate string coercion in `fs.write`,
`fs.writeFileSync`
(Livia Medeiros) (https://github.com/nodejs/node/pull/42607)
- (SEMVER-MAJOR) dns: remove `dns.lookup` and `dnsPromises.lookup`
options type coercion
(Antoine du Hamel) (https://github.com/nodejs/node/pull/41431)
- (SEMVER-MAJOR) process: runtime deprecate multipleResolves
(Benjamin Gruenbaum) (https://github.com/nodejs/node/pull/41896)
- (SEMVER-MAJOR) stream: remove thenable support (Robert Nagy)
(https://github.com/nodejs/node/pull/40773)
- (SEMVER-MAJOR) tls: move tls.parseCertString to end-of-life
(Tobias Nießen) (https://github.com/nodejs/node/pull/41479)
fetch (experimental):
An experimental fetch API is available on the global scope by default.
The implementation is based upon https://undici.nodejs.org/#/,
an HTTP/1.1 client written for Node.js by contributors to the project.
Through this addition, the following globals are made available: `fetch`
, `FormData`, `Headers`, `Request`, `Response`.
Disable this API with the `--no-experimental-fetch` command-line flag.
Contributed by Michaël Zasso in https://github.com/nodejs/node/pull/41811.
HTTP Timeouts:
`server.headersTimeout`, which limits the amount of time the parser will
wait to receive the complete HTTP headers, is now set to `60000` (60
seconds) by default.
`server.requestTimeout`, which sets the timeout value in milliseconds
for receiving the entire request from the client, is now set to `300000`
(5 minutes) by default.
If these timeouts expire, the server responds with status 408 without
forwarding the request to the request listener and then closes the
connection.
Both timeouts must be set to a non-zero value to protect against
potential Denial-of-Service attacks in case the server is deployed
without a reverse proxy in front.
Contributed by Paolo Insogna in https://github.com/nodejs/node/pull/41263.
Test Runner module (experimental):
The `node:test` module facilitates the creation of JavaScript tests that
report results in TAP format. This module is only available under the
`node:` scheme.
Contributed by Colin Ihrig in https://github.com/nodejs/node/pull/42325.
Toolchain and Compiler Upgrades:
- Prebuilt binaries for Linux are now built on Red Hat Enterprise Linux
(RHEL) 8 and are compatible with Linux distributions based on glibc
2.28 or later, for example, Debian 10, RHEL 8, Ubuntu 20.04.
- Prebuilt binaries for macOS now require macOS 10.15 or later.
- For AIX the minimum supported architecture has been raised from Power
7 to Power 8.
Prebuilt binaries for 32-bit Windows will initially not be available due
to issues building the V8 dependency in Node.js. We hope to restore
32-bit Windows binaries for Node.js 18 with a future V8 update.
Node.js does not support running on operating systems that are no longer
supported by their vendor. For operating systems where their vendor has
planned to end support earlier than April 2025, such as Windows 8.1
(January 2023) and Windows Server 2012 R2 (October 2023), support for
Node.js 18 will end at the earlier date.
Full details about the supported toolchains and compilers are documented
in the Node.js `BUILDING.md` file.
Contributed by Richard Lau in https://github.com/nodejs/node/pull/42292,
https://github.com/nodejs/node/pull/42604 and https://github.com/nodejs/node/pull/42659
, and Michaël Zasso in https://github.com/nodejs/node/pull/42105 and
https://github.com/nodejs/node/pull/42666.
V8 10.1:
The V8 engine is updated to version 10.1, which is part of Chromium 101.
Compared to the version included in Node.js 17.9.0, the following new
features are included:
- The `findLast` and `findLastIndex` array methods.
- Improvements to the `Intl.Locale` API.
- The `Intl.supportedValuesOf` function.
- Improved performance of class fields and private class methods (the
initialization of them is now as fast as ordinary property stores).
The data format returned by the serialization API (`v8.serialize(value)`)
has changed, and cannot be deserialized by earlier versions of Node.js.
On the other hand, it is still possible to deserialize the previous
format, as the API is backwards-compatible.
Contributed by Michaël Zasso in https://github.com/nodejs/node/pull/42657.
Web Streams API (experimental):
Node.js now exposes the experimental implementation of the Web Streams
API on the global scope. This means the following APIs are now globally
available:
- `ReadableStream`, `ReadableStreamDefaultReader`,
`ReadableStreamBYOBReader`, `ReadableStreamBYOBRequest`,
`ReadableByteStreamController`, `ReadableStreamDefaultController`,
`TransformStream`, `TransformStreamDefaultController`, `WritableStream`,
`WritableStreamDefaultWriter`, `WritableStreamDefaultController`,
`ByteLengthQueuingStrategy`, `CountQueuingStrategy`, `TextEncoderStream`,
`TextDecoderStream`, `CompressionStream`, `DecompressionStream`.
Contributed James Snell in https://github.com/nodejs/node/pull/39062,
and Antoine du Hamel in https://github.com/nodejs/node/pull/42225.
Other Notable Changes:
- (SEMVER-MAJOR) buffer: expose Blob as a global
(James M Snell) (https://github.com/nodejs/node/pull/41270)
- (SEMVER-MAJOR) child\_process: improve argument validation
(Rich Trott) (https://github.com/nodejs/node/pull/41305)
- doc: add RafaelGSS to collaborators
(RafaelGSS) (https://github.com/nodejs/node/pull/42718)
- (SEMVER-MAJOR) http: make TCP noDelay enabled by default
(Paolo Insogna) (https://github.com/nodejs/node/pull/42163)
- (SEMVER-MAJOR) net: make `server.address()` return an integer for
`family`
(Antoine du Hamel) (https://github.com/nodejs/node/pull/41431)
- (SEMVER-MAJOR) worker: expose BroadcastChannel as a global
(James M Snell) (https://github.com/nodejs/node/pull/41271)
- (SEMVER-MAJOR) worker: graduate BroadcastChannel to supported
(James M Snell) (https://github.com/nodejs/node/pull/41271)
Semver-Major Commits:
- (SEMVER-MAJOR) assert,util: compare RegExp.lastIndex while using deep
equal checks
(Ruben Bridgewater) (https://github.com/nodejs/node/pull/41020)
- (SEMVER-MAJOR) buffer: refactor `byteLength` to remove outdated
optimizations
(Rongjian Zhang) (https://github.com/nodejs/node/pull/38545)
- (SEMVER-MAJOR) buffer: expose Blob as a global
(James M Snell) (https://github.com/nodejs/node/pull/41270)
- (SEMVER-MAJOR) buffer: graduate Blob from experimental
(James M Snell) (https://github.com/nodejs/node/pull/41270)
- (SEMVER-MAJOR) build: make x86 Windows support temporarily
experimental
(Michaël Zasso) (https://github.com/nodejs/node/pull/42666)
- (SEMVER-MAJOR) build: bump macOS deployment target to 10.15
(Richard Lau) (https://github.com/nodejs/node/pull/42292)
- (SEMVER-MAJOR) build: downgrade Windows 8.1 and server 2012 R2 to
experimental
(Michaël Zasso) (https://github.com/nodejs/node/pull/42105)
- (SEMVER-MAJOR) child\_process: improve argument validation
(Rich Trott) (https://github.com/nodejs/node/pull/41305)
- (SEMVER-MAJOR) cluster: make `kill` to be just `process.kill`
(Bar Admoni) (https://github.com/nodejs/node/pull/34312)
- (SEMVER-MAJOR) crypto: cleanup validation
(Mohammed Keyvanzadeh) (https://github.com/nodejs/node/pull/39841)
- (SEMVER-MAJOR) crypto: prettify othername in PrintGeneralName
(Tobias Nießen) (https://github.com/nodejs/node/pull/42123)
- (SEMVER-MAJOR) crypto: fix X509Certificate toLegacyObject
(Tobias Nießen) (https://github.com/nodejs/node/pull/42124)
- (SEMVER-MAJOR) crypto: use RFC2253 format in PrintGeneralName
(Tobias Nießen) (https://github.com/nodejs/node/pull/42002)
- (SEMVER-MAJOR) crypto: change default check(Host|Email) behavior
(Tobias Nießen) (https://github.com/nodejs/node/pull/41600)
- (SEMVER-MAJOR) deps: V8: cherry-pick semver-major commits from 10.2
(Michaël Zasso) (https://github.com/nodejs/node/pull/42657)
- (SEMVER-MAJOR) deps: update V8 to 10.1.124.6
(Michaël Zasso) (https://github.com/nodejs/node/pull/42657)
- (SEMVER-MAJOR) deps: update V8 to 9.8.177.9
(Michaël Zasso) (https://github.com/nodejs/node/pull/41610)
- (SEMVER-MAJOR) deps: update V8 to 9.7.106.18
(Michaël Zasso) (https://github.com/nodejs/node/pull/40907)
- (SEMVER-MAJOR) dns: remove `dns.lookup` and `dnsPromises.lookup`
options type coercion
(Antoine du Hamel) (https://github.com/nodejs/node/pull/41431)
- (SEMVER-MAJOR) doc: update minimum glibc requirements for Linux
(Richard Lau) (https://github.com/nodejs/node/pull/42659)
- (SEMVER-MAJOR) doc: update AIX minimum supported arch
(Richard Lau) (https://github.com/nodejs/node/pull/42604)
- (SEMVER-MAJOR) fs: runtime deprecate string coercion in `fs.write`,
`fs.writeFileSync`
(Livia Medeiros) (https://github.com/nodejs/node/pull/42607)
- (SEMVER-MAJOR) http: refactor headersTimeout and requestTimeout logic
(Paolo Insogna) (https://github.com/nodejs/node/pull/41263)
- (SEMVER-MAJOR) http: make TCP noDelay enabled by default
(Paolo Insogna) (https://github.com/nodejs/node/pull/42163)
- (SEMVER-MAJOR) lib: enable fetch by default
(Michaël Zasso) (https://github.com/nodejs/node/pull/41811)
- (SEMVER-MAJOR) lib: replace validator and error
(Mohammed Keyvanzadeh) (https://github.com/nodejs/node/pull/41678)
- (SEMVER-MAJOR) module,repl: support 'node:'-only core modules
(Colin Ihrig) (https://github.com/nodejs/node/pull/42325)
- (SEMVER-MAJOR) net: make `server.address()` return an integer for
`family`
(Antoine du Hamel) (https://github.com/nodejs/node/pull/41431)
- (SEMVER-MAJOR) process: disallow some uses of Object.defineProperty()
on process.env
(Himself65) (https://github.com/nodejs/node/pull/28006)
- (SEMVER-MAJOR) process: runtime deprecate multipleResolves
(Benjamin Gruenbaum) (https://github.com/nodejs/node/pull/41896)
- (SEMVER-MAJOR) readline: fix question still called after closed
(Xuguang Mei) (https://github.com/nodejs/node/pull/42464)
- (SEMVER-MAJOR) stream: remove thenable support
(Robert Nagy) (https://github.com/nodejs/node/pull/40773)
- (SEMVER-MAJOR) stream: expose web streams globals, remove runtime
experimental warning
(Antoine du Hamel) (https://github.com/nodejs/node/pull/42225)
- (SEMVER-MAJOR) stream: need to cleanup event listeners if last stream
is readable
(Xuguang Mei) (https://github.com/nodejs/node/pull/41954)
- (SEMVER-MAJOR) stream: revert revert `map` spec compliance
(Benjamin Gruenbaum) (https://github.com/nodejs/node/pull/41933)
- (SEMVER-MAJOR) stream: throw invalid arg type from End Of Stream
(Jithil P Ponnan) (https://github.com/nodejs/node/pull/41766)
- (SEMVER-MAJOR) stream: don't emit finish after destroy
(Robert Nagy) (https://github.com/nodejs/node/pull/40852)
- (SEMVER-MAJOR) stream: add errored and closed props
(Robert Nagy) (https://github.com/nodejs/node/pull/40696)
- (SEMVER-MAJOR) test: add initial test module
(Colin Ihrig) (https://github.com/nodejs/node/pull/42325)
- (SEMVER-MAJOR) timers: refactor internal classes to ES2015 syntax
(Rabbit) (https://github.com/nodejs/node/pull/37408)
- (SEMVER-MAJOR) tls: represent registeredID numerically always
(Tobias Nießen) (https://github.com/nodejs/node/pull/41561)
- (SEMVER-MAJOR) tls: move tls.parseCertString to end-of-life
(Tobias Nießen) (https://github.com/nodejs/node/pull/41479)
- (SEMVER-MAJOR) url: throw on NULL in IPv6 hostname
(Rich Trott) (https://github.com/nodejs/node/pull/42313)
- (SEMVER-MAJOR) v8: make v8.writeHeapSnapshot() error codes consistent
(Darshan Sen) (https://github.com/nodejs/node/pull/42577)
- (SEMVER-MAJOR) v8: make writeHeapSnapshot throw if fopen fails
(Antonio Román) (https://github.com/nodejs/node/pull/41373)
- (SEMVER-MAJOR) worker: expose BroadcastChannel as a global
(James M Snell) (https://github.com/nodejs/node/pull/41271)
- (SEMVER-MAJOR) worker: graduate BroadcastChannel to supported
(James M Snell) (https://github.com/nodejs/node/pull/41271)
PR-URL: https://github.com/nodejs/node/pull/42262
2022-03-08 01:39:47 +00:00
|
|
|
- version: v18.0.0
|
2021-12-02 09:01:40 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/41020
|
|
|
|
description: Regular expressions lastIndex property is now compared as well.
|
2017-09-01 09:50:47 -07:00
|
|
|
- version: v9.0.0
|
2017-08-19 02:06:27 -03:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/15169
|
|
|
|
description: Enumerable symbol properties are now compared.
|
2017-09-01 09:50:47 -07:00
|
|
|
- version: v9.0.0
|
2017-08-19 02:54:49 -03:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/15036
|
2018-04-29 20:46:41 +03:00
|
|
|
description: The `NaN` is now compared using the
|
2018-02-12 02:31:55 -05:00
|
|
|
[SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero)
|
|
|
|
comparison.
|
2017-09-10 04:58:50 +02:00
|
|
|
- version: v8.5.0
|
2017-09-13 10:50:43 +02:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/15001
|
2020-10-01 20:35:23 +02:00
|
|
|
description: The `Error` names and messages are now properly compared.
|
2017-03-15 20:26:14 -07:00
|
|
|
- version: v8.0.0
|
2017-03-31 14:46:07 +11:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/12142
|
2020-10-01 20:35:23 +02:00
|
|
|
description: The `Set` and `Map` content is also compared.
|
2020-10-01 20:23:33 +02:00
|
|
|
- version:
|
|
|
|
- v6.4.0
|
|
|
|
- v4.7.1
|
2017-02-21 23:39:15 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/8002
|
|
|
|
description: Typed array slices are handled correctly now.
|
|
|
|
- version: v6.1.0
|
|
|
|
pr-url: https://github.com/nodejs/node/pull/6432
|
|
|
|
description: Objects with circular references can be used as inputs now.
|
2020-10-01 20:23:33 +02:00
|
|
|
- version:
|
|
|
|
- v5.10.1
|
|
|
|
- v4.4.3
|
2017-02-21 23:39:15 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/5910
|
|
|
|
description: Handle non-`Uint8Array` typed arrays correctly.
|
2016-05-10 23:08:33 -07:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2017-02-24 23:17:53 -08:00
|
|
|
* `actual` {any}
|
|
|
|
* `expected` {any}
|
2018-05-02 16:13:16 +02:00
|
|
|
* `message` {string|Error}
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2017-11-13 16:44:30 -02:00
|
|
|
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.
|
2017-02-03 06:02:29 +08:00
|
|
|
|
2017-11-13 16:44:30 -02:00
|
|
|
### Comparison details
|
|
|
|
|
2022-01-12 22:17:05 -08:00
|
|
|
* Primitive values are compared using [`Object.is()`][].
|
2017-11-13 16:44:30 -02:00
|
|
|
* [Type tags][Object.prototype.toString()] of objects should be the same.
|
|
|
|
* [`[[Prototype]]`][prototype-spec] of objects are compared using
|
2022-01-10 02:13:23 -08:00
|
|
|
the [`===` operator][].
|
2017-11-13 16:44:30 -02:00
|
|
|
* Only [enumerable "own" properties][] are considered.
|
2025-02-05 14:59:37 +01:00
|
|
|
* {Error} names, messages, causes, and errors are always compared,
|
2024-05-13 03:46:13 +08:00
|
|
|
even if these are not enumerable properties.
|
|
|
|
`errors` is also compared.
|
2025-02-05 14:59:37 +01:00
|
|
|
* Enumerable own {Symbol} properties are compared as well.
|
2017-11-13 16:44:30 -02:00
|
|
|
* [Object wrappers][] are compared both as objects and unwrapped values.
|
2018-04-29 20:46:41 +03:00
|
|
|
* `Object` properties are compared unordered.
|
2025-02-05 14:59:37 +01:00
|
|
|
* {Map} keys and {Set} items are compared unordered.
|
2025-04-03 01:37:44 +02:00
|
|
|
* Recursion stops when both sides differ or either side encounters a circular
|
2017-11-13 16:44:30 -02:00
|
|
|
reference.
|
2025-02-05 14:59:37 +01:00
|
|
|
* {WeakMap} and {WeakSet} instances are **not** compared structurally.
|
2025-01-20 15:18:21 -05:00
|
|
|
They are only equal if they reference the same object. Any comparison between
|
|
|
|
different `WeakMap` or `WeakSet` instances will result in inequality,
|
|
|
|
even if they contain the same entries.
|
2025-02-05 14:59:37 +01:00
|
|
|
* {RegExp} lastIndex, flags, and source are always compared, even if these
|
2021-12-02 09:01:40 +01:00
|
|
|
are not enumerable properties.
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
// This fails because 1 !== '1'.
|
2021-10-07 21:16:40 +07:00
|
|
|
assert.deepStrictEqual({ a: 1 }, { a: '1' });
|
2021-03-04 15:00:25 -08:00
|
|
|
// AssertionError: Expected inputs to be strictly deep-equal:
|
|
|
|
// + actual - expected
|
|
|
|
//
|
|
|
|
// {
|
|
|
|
// + a: 1
|
|
|
|
// - a: '1'
|
|
|
|
// }
|
|
|
|
|
|
|
|
// The following objects don't have own properties
|
|
|
|
const date = new Date();
|
|
|
|
const object = {};
|
|
|
|
const fakeDate = {};
|
|
|
|
Object.setPrototypeOf(fakeDate, Date.prototype);
|
|
|
|
|
|
|
|
// Different [[Prototype]]:
|
|
|
|
assert.deepStrictEqual(object, fakeDate);
|
|
|
|
// AssertionError: Expected inputs to be strictly deep-equal:
|
|
|
|
// + actual - expected
|
|
|
|
//
|
|
|
|
// + {}
|
|
|
|
// - Date {}
|
|
|
|
|
|
|
|
// Different type tags:
|
|
|
|
assert.deepStrictEqual(date, fakeDate);
|
|
|
|
// AssertionError: Expected inputs to be strictly deep-equal:
|
|
|
|
// + actual - expected
|
|
|
|
//
|
|
|
|
// + 2018-04-26T00:49:08.604Z
|
|
|
|
// - Date {}
|
|
|
|
|
|
|
|
assert.deepStrictEqual(NaN, NaN);
|
2022-01-12 22:17:05 -08:00
|
|
|
// OK because Object.is(NaN, NaN) is true.
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
// Different unwrapped numbers:
|
|
|
|
assert.deepStrictEqual(new Number(1), new Number(2));
|
|
|
|
// AssertionError: Expected inputs to be strictly deep-equal:
|
|
|
|
// + actual - expected
|
|
|
|
//
|
|
|
|
// + [Number: 1]
|
|
|
|
// - [Number: 2]
|
|
|
|
|
|
|
|
assert.deepStrictEqual(new String('foo'), Object('foo'));
|
|
|
|
// OK because the object and the string are identical when unwrapped.
|
|
|
|
|
|
|
|
assert.deepStrictEqual(-0, -0);
|
|
|
|
// OK
|
|
|
|
|
2022-01-12 22:17:05 -08:00
|
|
|
// Different zeros:
|
2021-03-04 15:00:25 -08:00
|
|
|
assert.deepStrictEqual(0, -0);
|
|
|
|
// AssertionError: Expected inputs to be strictly deep-equal:
|
|
|
|
// + actual - expected
|
|
|
|
//
|
|
|
|
// + 0
|
|
|
|
// - -0
|
|
|
|
|
|
|
|
const symbol1 = Symbol();
|
|
|
|
const symbol2 = Symbol();
|
|
|
|
assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol1]: 1 });
|
|
|
|
// OK, because it is the same symbol on both objects.
|
|
|
|
|
|
|
|
assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 });
|
|
|
|
// AssertionError [ERR_ASSERTION]: Inputs identical but not reference equal:
|
|
|
|
//
|
|
|
|
// {
|
2024-11-08 12:18:04 +00:00
|
|
|
// Symbol(): 1
|
2021-03-04 15:00:25 -08:00
|
|
|
// }
|
|
|
|
|
|
|
|
const weakMap1 = new WeakMap();
|
2025-01-20 15:18:21 -05:00
|
|
|
const weakMap2 = new WeakMap();
|
|
|
|
const obj = {};
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2025-01-20 15:18:21 -05:00
|
|
|
weakMap1.set(obj, 'value');
|
|
|
|
weakMap2.set(obj, 'value');
|
|
|
|
|
|
|
|
// Comparing different instances fails, even with same contents
|
2021-03-04 15:00:25 -08:00
|
|
|
assert.deepStrictEqual(weakMap1, weakMap2);
|
2025-01-20 15:18:21 -05:00
|
|
|
// AssertionError: Values have same structure but are not reference-equal:
|
|
|
|
//
|
|
|
|
// WeakMap {
|
|
|
|
// <items unknown>
|
|
|
|
// }
|
|
|
|
|
|
|
|
// Comparing the same instance to itself succeeds
|
|
|
|
assert.deepStrictEqual(weakMap1, weakMap1);
|
|
|
|
// OK
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2025-01-20 15:18:21 -05:00
|
|
|
const weakSet1 = new WeakSet();
|
|
|
|
const weakSet2 = new WeakSet();
|
|
|
|
weakSet1.add(obj);
|
|
|
|
weakSet2.add(obj);
|
|
|
|
|
|
|
|
// Comparing different instances fails, even with same contents
|
|
|
|
assert.deepStrictEqual(weakSet1, weakSet2);
|
2025-01-23 14:24:28 -05:00
|
|
|
// AssertionError: Values have same structure but are not reference-equal:
|
2021-03-04 15:00:25 -08:00
|
|
|
// + actual - expected
|
|
|
|
//
|
2025-01-23 14:24:28 -05:00
|
|
|
// WeakSet {
|
|
|
|
// <items unknown>
|
|
|
|
// }
|
2025-01-20 15:18:21 -05:00
|
|
|
|
|
|
|
// Comparing the same instance to itself succeeds
|
|
|
|
assert.deepStrictEqual(weakSet1, weakSet1);
|
|
|
|
// OK
|
2021-03-04 15:00:25 -08:00
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2018-04-26 03:06:10 +02:00
|
|
|
// This fails because 1 !== '1'.
|
2017-06-01 02:07:25 +03:00
|
|
|
assert.deepStrictEqual({ a: 1 }, { a: '1' });
|
2018-07-03 02:06:57 +02:00
|
|
|
// AssertionError: Expected inputs to be strictly deep-equal:
|
|
|
|
// + actual - expected
|
|
|
|
//
|
2018-04-26 03:06:10 +02:00
|
|
|
// {
|
2018-07-03 02:06:57 +02:00
|
|
|
// + a: 1
|
|
|
|
// - a: '1'
|
2018-04-26 03:06:10 +02:00
|
|
|
// }
|
2017-02-01 03:51:54 +08:00
|
|
|
|
|
|
|
// The following objects don't have own properties
|
|
|
|
const date = new Date();
|
|
|
|
const object = {};
|
|
|
|
const fakeDate = {};
|
|
|
|
Object.setPrototypeOf(fakeDate, Date.prototype);
|
|
|
|
|
2018-04-26 03:06:10 +02:00
|
|
|
// Different [[Prototype]]:
|
2017-02-01 03:51:54 +08:00
|
|
|
assert.deepStrictEqual(object, fakeDate);
|
2018-07-03 02:06:57 +02:00
|
|
|
// AssertionError: Expected inputs to be strictly deep-equal:
|
|
|
|
// + actual - expected
|
|
|
|
//
|
|
|
|
// + {}
|
|
|
|
// - Date {}
|
2017-02-01 03:51:54 +08:00
|
|
|
|
2018-04-26 03:06:10 +02:00
|
|
|
// Different type tags:
|
2017-02-01 03:51:54 +08:00
|
|
|
assert.deepStrictEqual(date, fakeDate);
|
2018-07-03 02:06:57 +02:00
|
|
|
// AssertionError: Expected inputs to be strictly deep-equal:
|
|
|
|
// + actual - expected
|
|
|
|
//
|
|
|
|
// + 2018-04-26T00:49:08.604Z
|
|
|
|
// - Date {}
|
2017-08-26 22:44:07 -03:00
|
|
|
|
2017-08-19 02:54:49 -03:00
|
|
|
assert.deepStrictEqual(NaN, NaN);
|
2022-01-12 22:17:05 -08:00
|
|
|
// OK because Object.is(NaN, NaN) is true.
|
2017-08-26 22:44:07 -03:00
|
|
|
|
2018-04-26 03:06:10 +02:00
|
|
|
// Different unwrapped numbers:
|
2017-08-26 22:44:07 -03:00
|
|
|
assert.deepStrictEqual(new Number(1), new Number(2));
|
2018-07-03 02:06:57 +02:00
|
|
|
// AssertionError: Expected inputs to be strictly deep-equal:
|
|
|
|
// + actual - expected
|
|
|
|
//
|
|
|
|
// + [Number: 1]
|
|
|
|
// - [Number: 2]
|
2018-04-26 03:06:10 +02:00
|
|
|
|
2017-08-26 22:44:07 -03:00
|
|
|
assert.deepStrictEqual(new String('foo'), Object('foo'));
|
|
|
|
// OK because the object and the string are identical when unwrapped.
|
2017-08-19 02:50:57 -03:00
|
|
|
|
|
|
|
assert.deepStrictEqual(-0, -0);
|
|
|
|
// OK
|
2018-04-26 03:06:10 +02:00
|
|
|
|
2022-01-12 22:17:05 -08:00
|
|
|
// Different zeros:
|
2017-08-19 02:50:57 -03:00
|
|
|
assert.deepStrictEqual(0, -0);
|
2018-07-03 02:06:57 +02:00
|
|
|
// AssertionError: Expected inputs to be strictly deep-equal:
|
|
|
|
// + actual - expected
|
|
|
|
//
|
|
|
|
// + 0
|
|
|
|
// - -0
|
2017-08-19 02:06:27 -03:00
|
|
|
|
|
|
|
const symbol1 = Symbol();
|
|
|
|
const symbol2 = Symbol();
|
|
|
|
assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol1]: 1 });
|
|
|
|
// OK, because it is the same symbol on both objects.
|
2018-07-03 02:06:57 +02:00
|
|
|
|
2017-08-19 02:06:27 -03:00
|
|
|
assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 });
|
2018-07-03 02:06:57 +02:00
|
|
|
// AssertionError [ERR_ASSERTION]: Inputs identical but not reference equal:
|
|
|
|
//
|
2018-04-26 03:06:10 +02:00
|
|
|
// {
|
2024-11-08 12:18:04 +00:00
|
|
|
// Symbol(): 1
|
2018-04-26 03:06:10 +02:00
|
|
|
// }
|
2018-01-19 11:03:02 +01:00
|
|
|
|
|
|
|
const weakMap1 = new WeakMap();
|
2025-01-20 15:18:21 -05:00
|
|
|
const weakMap2 = new WeakMap();
|
|
|
|
const obj = {};
|
2018-01-19 11:03:02 +01:00
|
|
|
|
2025-01-20 15:18:21 -05:00
|
|
|
weakMap1.set(obj, 'value');
|
|
|
|
weakMap2.set(obj, 'value');
|
|
|
|
|
|
|
|
// Comparing different instances fails, even with same contents
|
2018-01-19 11:03:02 +01:00
|
|
|
assert.deepStrictEqual(weakMap1, weakMap2);
|
2025-01-20 15:18:21 -05:00
|
|
|
// AssertionError: Values have same structure but are not reference-equal:
|
|
|
|
//
|
|
|
|
// WeakMap {
|
|
|
|
// <items unknown>
|
|
|
|
// }
|
|
|
|
|
|
|
|
// Comparing the same instance to itself succeeds
|
|
|
|
assert.deepStrictEqual(weakMap1, weakMap1);
|
|
|
|
// OK
|
2018-04-26 03:06:10 +02:00
|
|
|
|
2025-01-20 15:18:21 -05:00
|
|
|
const weakSet1 = new WeakSet();
|
|
|
|
const weakSet2 = new WeakSet();
|
|
|
|
weakSet1.add(obj);
|
|
|
|
weakSet2.add(obj);
|
|
|
|
|
|
|
|
// Comparing different instances fails, even with same contents
|
|
|
|
assert.deepStrictEqual(weakSet1, weakSet2);
|
2025-01-23 14:24:28 -05:00
|
|
|
// AssertionError: Values have same structure but are not reference-equal:
|
2018-07-03 02:06:57 +02:00
|
|
|
// + actual - expected
|
|
|
|
//
|
2025-01-23 14:24:28 -05:00
|
|
|
// WeakSet {
|
|
|
|
// <items unknown>
|
|
|
|
// }
|
2025-01-20 15:18:21 -05:00
|
|
|
|
|
|
|
// Comparing the same instance to itself succeeds
|
|
|
|
assert.deepStrictEqual(weakSet1, weakSet1);
|
|
|
|
// OK
|
2016-01-17 18:39:07 +01:00
|
|
|
```
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
If the values are not equal, an [`AssertionError`][] is thrown with a `message`
|
2015-12-19 19:08:13 -08:00
|
|
|
property set equal to the value of the `message` parameter. If the `message`
|
2017-09-09 20:36:47 -05:00
|
|
|
parameter is undefined, a default error message is assigned. If the `message`
|
2025-02-05 14:59:37 +01:00
|
|
|
parameter is an instance of {Error} then it will be thrown instead of the
|
2017-09-09 20:36:47 -05:00
|
|
|
`AssertionError`.
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2019-12-12 22:51:43 +01:00
|
|
|
## `assert.doesNotMatch(string, regexp[, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2019-12-12 22:51:43 +01:00
|
|
|
<!-- YAML
|
2020-04-24 18:43:06 +02:00
|
|
|
added:
|
|
|
|
- v13.6.0
|
|
|
|
- v12.16.0
|
2021-04-06 09:54:49 -07:00
|
|
|
changes:
|
2021-03-03 15:36:13 +00:00
|
|
|
- version: v16.0.0
|
2021-04-06 09:54:49 -07:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/38111
|
|
|
|
description: This API is no longer experimental.
|
2019-12-12 22:51:43 +01:00
|
|
|
-->
|
|
|
|
|
|
|
|
* `string` {string}
|
|
|
|
* `regexp` {RegExp}
|
|
|
|
* `message` {string|Error}
|
|
|
|
|
|
|
|
Expects the `string` input not to match the regular expression.
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2019-12-12 22:51:43 +01:00
|
|
|
|
|
|
|
assert.doesNotMatch('I will fail', /fail/);
|
|
|
|
// AssertionError [ERR_ASSERTION]: The input was expected to not match the ...
|
|
|
|
|
|
|
|
assert.doesNotMatch(123, /pass/);
|
|
|
|
// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.
|
|
|
|
|
|
|
|
assert.doesNotMatch('I will pass', /different/);
|
|
|
|
// OK
|
|
|
|
```
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.doesNotMatch('I will fail', /fail/);
|
|
|
|
// AssertionError [ERR_ASSERTION]: The input was expected to not match the ...
|
|
|
|
|
|
|
|
assert.doesNotMatch(123, /pass/);
|
|
|
|
// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.
|
|
|
|
|
|
|
|
assert.doesNotMatch('I will pass', /different/);
|
|
|
|
// OK
|
|
|
|
```
|
|
|
|
|
|
|
|
If the values do match, or if the `string` argument is of another type than
|
|
|
|
`string`, 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
|
2025-02-05 14:59:37 +01:00
|
|
|
instance of {Error} then it will be thrown instead of the
|
2019-12-12 22:51:43 +01:00
|
|
|
[`AssertionError`][].
|
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.doesNotReject(asyncFn[, error][, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2018-01-12 00:16:41 +01:00
|
|
|
<!-- YAML
|
2018-03-02 09:53:46 -08:00
|
|
|
added: v10.0.0
|
2018-01-12 00:16:41 +01:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2018-09-04 01:10:29 +02:00
|
|
|
* `asyncFn` {Function|Promise}
|
2018-01-12 00:16:41 +01:00
|
|
|
* `error` {RegExp|Function}
|
2018-09-04 01:10:29 +02:00
|
|
|
* `message` {string}
|
2025-02-28 09:33:00 -05:00
|
|
|
* Returns: {Promise}
|
2018-01-12 00:16:41 +01:00
|
|
|
|
2018-09-04 01:10:29 +02:00
|
|
|
Awaits the `asyncFn` promise or, if `asyncFn` is a function, immediately
|
|
|
|
calls the function and awaits the returned promise to complete. It will then
|
|
|
|
check that the promise is not rejected.
|
2018-04-08 23:28:30 +02:00
|
|
|
|
2018-09-04 01:10:29 +02:00
|
|
|
If `asyncFn` is a function and it throws an error synchronously,
|
2018-04-29 20:46:41 +03:00
|
|
|
`assert.doesNotReject()` will return a rejected `Promise` with that error. If
|
|
|
|
the function does not return a promise, `assert.doesNotReject()` will return a
|
|
|
|
rejected `Promise` with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases
|
|
|
|
the error handler is skipped.
|
2018-03-12 22:15:49 +01:00
|
|
|
|
2018-10-26 19:27:40 +03:00
|
|
|
Using `assert.doesNotReject()` is actually not useful because there is little
|
|
|
|
benefit in catching a rejection and then rejecting it again. Instead, consider
|
|
|
|
adding a comment next to the specific code path that should not reject and keep
|
|
|
|
error messages as expressive as possible.
|
2018-01-12 00:16:41 +01:00
|
|
|
|
2025-02-05 14:59:37 +01:00
|
|
|
If specified, `error` can be a [`Class`][], {RegExp} or a validation
|
2018-04-09 01:31:59 +02:00
|
|
|
function. See [`assert.throws()`][] for more details.
|
|
|
|
|
2018-03-11 14:05:04 +02:00
|
|
|
Besides the async nature to await the completion behaves identically to
|
2018-01-12 00:16:41 +01:00
|
|
|
[`assert.doesNotThrow()`][].
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
await assert.doesNotReject(
|
|
|
|
async () => {
|
|
|
|
throw new TypeError('Wrong value');
|
|
|
|
},
|
2022-11-17 08:19:12 -05:00
|
|
|
SyntaxError,
|
2021-03-04 15:00:25 -08:00
|
|
|
);
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2018-01-12 00:16:41 +01:00
|
|
|
(async () => {
|
|
|
|
await assert.doesNotReject(
|
|
|
|
async () => {
|
|
|
|
throw new TypeError('Wrong value');
|
|
|
|
},
|
2022-11-17 08:19:12 -05:00
|
|
|
SyntaxError,
|
2018-01-12 00:16:41 +01:00
|
|
|
);
|
|
|
|
})();
|
|
|
|
```
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
|
|
|
|
.then(() => {
|
|
|
|
// ...
|
|
|
|
});
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2018-04-08 23:28:30 +02:00
|
|
|
assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
|
|
|
|
.then(() => {
|
|
|
|
// ...
|
|
|
|
});
|
2018-01-12 00:16:41 +01:00
|
|
|
```
|
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.doesNotThrow(fn[, error][, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.21
|
2017-02-21 23:39:15 +01:00
|
|
|
changes:
|
2020-10-01 20:23:33 +02:00
|
|
|
- version:
|
|
|
|
- v5.11.0
|
|
|
|
- v4.4.5
|
2017-02-21 23:39:15 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/2407
|
|
|
|
description: The `message` parameter is respected now.
|
|
|
|
- version: v4.2.0
|
|
|
|
pr-url: https://github.com/nodejs/node/pull/3276
|
|
|
|
description: The `error` parameter can now be an arrow function.
|
2016-05-10 23:08:33 -07:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2018-09-04 01:10:29 +02:00
|
|
|
* `fn` {Function}
|
2017-02-24 23:17:53 -08:00
|
|
|
* `error` {RegExp|Function}
|
2018-09-04 01:10:29 +02:00
|
|
|
* `message` {string}
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2018-09-04 01:10:29 +02:00
|
|
|
Asserts that the function `fn` does not throw an error.
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2018-10-26 19:27:40 +03:00
|
|
|
Using `assert.doesNotThrow()` is actually not useful because there
|
|
|
|
is no benefit in catching an error and then rethrowing it. Instead, consider
|
2018-02-10 16:50:20 +01:00
|
|
|
adding a comment next to the specific code path that should not throw and keep
|
|
|
|
error messages as expressive as possible.
|
|
|
|
|
2018-09-04 01:10:29 +02:00
|
|
|
When `assert.doesNotThrow()` is called, it will immediately call the `fn`
|
2015-12-19 19:08:13 -08:00
|
|
|
function.
|
|
|
|
|
|
|
|
If an error is thrown and it is the same type as that specified by the `error`
|
2019-06-20 17:13:31 +02:00
|
|
|
parameter, then an [`AssertionError`][] is thrown. If the error is of a
|
|
|
|
different type, or if the `error` parameter is undefined, the error is
|
|
|
|
propagated back to the caller.
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2025-02-05 14:59:37 +01:00
|
|
|
If specified, `error` can be a [`Class`][], {RegExp}, or a validation
|
2018-04-09 01:31:59 +02:00
|
|
|
function. See [`assert.throws()`][] for more details.
|
|
|
|
|
2025-02-05 14:59:37 +01:00
|
|
|
The following, for instance, will throw the {TypeError} because there is no
|
2015-12-19 19:08:13 -08:00
|
|
|
matching error type in the assertion:
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.doesNotThrow(
|
|
|
|
() => {
|
|
|
|
throw new TypeError('Wrong value');
|
|
|
|
},
|
2022-11-17 08:19:12 -05:00
|
|
|
SyntaxError,
|
2021-03-04 15:00:25 -08:00
|
|
|
);
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.doesNotThrow(
|
2016-01-24 11:15:51 +02:00
|
|
|
() => {
|
2016-01-17 18:39:07 +01:00
|
|
|
throw new TypeError('Wrong value');
|
|
|
|
},
|
2022-11-17 08:19:12 -05:00
|
|
|
SyntaxError,
|
2016-01-17 18:39:07 +01:00
|
|
|
);
|
|
|
|
```
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
However, the following will result in an [`AssertionError`][] with the message
|
2018-04-29 20:46:41 +03:00
|
|
|
'Got unwanted exception...':
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.doesNotThrow(
|
|
|
|
() => {
|
|
|
|
throw new TypeError('Wrong value');
|
|
|
|
},
|
2022-11-17 08:19:12 -05:00
|
|
|
TypeError,
|
2021-03-04 15:00:25 -08:00
|
|
|
);
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.doesNotThrow(
|
2016-01-24 11:15:51 +02:00
|
|
|
() => {
|
2016-01-17 18:39:07 +01:00
|
|
|
throw new TypeError('Wrong value');
|
|
|
|
},
|
2022-11-17 08:19:12 -05:00
|
|
|
TypeError,
|
2016-01-17 18:39:07 +01:00
|
|
|
);
|
|
|
|
```
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
If an [`AssertionError`][] is thrown and a value is provided for the `message`
|
|
|
|
parameter, the value of `message` will be appended to the [`AssertionError`][]
|
2015-12-19 19:08:13 -08:00
|
|
|
message:
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.doesNotThrow(
|
|
|
|
() => {
|
|
|
|
throw new TypeError('Wrong value');
|
|
|
|
},
|
|
|
|
/Wrong value/,
|
2022-11-17 08:19:12 -05:00
|
|
|
'Whoops',
|
2021-03-04 15:00:25 -08:00
|
|
|
);
|
|
|
|
// Throws: AssertionError: Got unwanted exception: Whoops
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.doesNotThrow(
|
2016-01-24 11:15:51 +02:00
|
|
|
() => {
|
2016-01-17 18:39:07 +01:00
|
|
|
throw new TypeError('Wrong value');
|
|
|
|
},
|
2018-04-09 01:31:59 +02:00
|
|
|
/Wrong value/,
|
2022-11-17 08:19:12 -05:00
|
|
|
'Whoops',
|
2016-01-17 18:39:07 +01:00
|
|
|
);
|
2018-04-29 20:46:41 +03:00
|
|
|
// Throws: AssertionError: Got unwanted exception: Whoops
|
2016-01-17 18:39:07 +01:00
|
|
|
```
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.equal(actual, expected[, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.21
|
2019-12-02 13:12:52 +01:00
|
|
|
changes:
|
2021-09-04 15:29:35 +02:00
|
|
|
- version:
|
|
|
|
- v16.0.0
|
|
|
|
- v14.18.0
|
2021-04-06 10:20:53 -07:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/38113
|
|
|
|
description: In Legacy assertion mode, changed status from Deprecated to
|
|
|
|
Legacy.
|
2020-03-10 17:16:08 +00:00
|
|
|
- version: v14.0.0
|
2019-12-02 13:12:52 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/30766
|
2022-01-05 12:35:02 -08:00
|
|
|
description: NaN is now treated as being identical if both sides are
|
2019-12-02 13:12:52 +01:00
|
|
|
NaN.
|
2016-05-10 23:08:33 -07:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2017-02-24 23:17:53 -08:00
|
|
|
* `actual` {any}
|
|
|
|
* `expected` {any}
|
2018-05-02 16:13:16 +02:00
|
|
|
* `message` {string|Error}
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
**Strict assertion mode**
|
2017-11-13 18:15:24 -02:00
|
|
|
|
|
|
|
An alias of [`assert.strictEqual()`][].
|
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
**Legacy assertion mode**
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2021-04-06 10:20:53 -07:00
|
|
|
> Stability: 3 - Legacy: Use [`assert.strictEqual()`][] instead.
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2015-12-19 19:08:13 -08:00
|
|
|
Tests shallow, coercive equality between the `actual` and `expected` parameters
|
2022-01-07 20:00:55 -08:00
|
|
|
using the [`==` operator][]. `NaN` is specially handled
|
2022-01-05 12:35:02 -08:00
|
|
|
and treated as being identical if both sides are `NaN`.
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.equal(1, 1);
|
|
|
|
// OK, 1 == 1
|
|
|
|
assert.equal(1, '1');
|
|
|
|
// OK, 1 == '1'
|
|
|
|
assert.equal(NaN, NaN);
|
|
|
|
// OK
|
|
|
|
|
|
|
|
assert.equal(1, 2);
|
|
|
|
// AssertionError: 1 == 2
|
|
|
|
assert.equal({ a: { b: 1 } }, { a: { b: 1 } });
|
|
|
|
// AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert');
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.equal(1, 1);
|
2016-11-08 21:04:57 +01:00
|
|
|
// OK, 1 == 1
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.equal(1, '1');
|
2016-11-08 21:04:57 +01:00
|
|
|
// OK, 1 == '1'
|
2019-12-02 13:12:52 +01:00
|
|
|
assert.equal(NaN, NaN);
|
|
|
|
// OK
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.equal(1, 2);
|
2016-11-08 21:04:57 +01:00
|
|
|
// AssertionError: 1 == 2
|
2017-06-01 02:07:25 +03:00
|
|
|
assert.equal({ a: { b: 1 } }, { a: { b: 1 } });
|
2018-03-25 22:27:38 +08:00
|
|
|
// AssertionError: { a: { b: 1 } } == { a: { b: 1 } }
|
2016-01-17 18:39:07 +01:00
|
|
|
```
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
If the values are not equal, an [`AssertionError`][] is thrown with a `message`
|
2015-12-19 19:08:13 -08:00
|
|
|
property set equal to the value of the `message` parameter. If the `message`
|
2017-09-09 20:36:47 -05:00
|
|
|
parameter is undefined, a default error message is assigned. If the `message`
|
2025-02-05 14:59:37 +01:00
|
|
|
parameter is an instance of {Error} then it will be thrown instead of the
|
2017-09-09 20:36:47 -05:00
|
|
|
`AssertionError`.
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.fail([message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2018-01-28 12:07:18 +01:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.21
|
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2018-05-02 16:13:16 +02:00
|
|
|
* `message` {string|Error} **Default:** `'Failed'`
|
2018-01-28 12:07:18 +01:00
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
Throws an [`AssertionError`][] with the provided error message or a default
|
2025-02-05 14:59:37 +01:00
|
|
|
error message. If the `message` parameter is an instance of {Error} then
|
2019-06-20 17:13:31 +02:00
|
|
|
it will be thrown instead of the [`AssertionError`][].
|
2018-01-28 12:07:18 +01:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.fail();
|
|
|
|
// AssertionError [ERR_ASSERTION]: Failed
|
|
|
|
|
|
|
|
assert.fail('boom');
|
|
|
|
// AssertionError [ERR_ASSERTION]: boom
|
|
|
|
|
|
|
|
assert.fail(new TypeError('need array'));
|
|
|
|
// TypeError: need array
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2018-01-28 12:07:18 +01:00
|
|
|
|
|
|
|
assert.fail();
|
|
|
|
// AssertionError [ERR_ASSERTION]: Failed
|
|
|
|
|
|
|
|
assert.fail('boom');
|
|
|
|
// AssertionError [ERR_ASSERTION]: boom
|
|
|
|
|
|
|
|
assert.fail(new TypeError('need array'));
|
|
|
|
// TypeError: need array
|
|
|
|
```
|
|
|
|
|
|
|
|
Using `assert.fail()` with more than two arguments is possible but deprecated.
|
|
|
|
See below for further details.
|
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.fail(actual, expected[, message[, operator[, stackStartFn]]])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.21
|
2018-01-28 12:07:18 +01:00
|
|
|
changes:
|
2018-03-02 09:53:46 -08:00
|
|
|
- version: v10.0.0
|
2018-02-04 16:30:04 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/18418
|
2018-04-09 19:30:22 +03:00
|
|
|
description: Calling `assert.fail()` with more than one argument is
|
|
|
|
deprecated and emits a warning.
|
2016-05-10 23:08:33 -07:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2019-10-01 18:57:09 +03:00
|
|
|
> Stability: 0 - Deprecated: Use `assert.fail([message])` or other assert
|
|
|
|
> functions instead.
|
|
|
|
|
2017-02-24 23:17:53 -08:00
|
|
|
* `actual` {any}
|
|
|
|
* `expected` {any}
|
2018-05-02 16:13:16 +02:00
|
|
|
* `message` {string|Error}
|
2018-04-02 04:44:32 +03:00
|
|
|
* `operator` {string} **Default:** `'!='`
|
2018-08-01 16:05:22 -07:00
|
|
|
* `stackStartFn` {Function} **Default:** `assert.fail`
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2018-01-28 12:07:18 +01:00
|
|
|
If `message` is falsy, the error message is set as the values of `actual` and
|
|
|
|
`expected` separated by the provided `operator`. If just the two `actual` and
|
|
|
|
`expected` arguments are provided, `operator` will default to `'!='`. If
|
|
|
|
`message` is provided as third argument it will be used as the error message and
|
|
|
|
the other arguments will be stored as properties on the thrown object. If
|
2018-08-01 16:05:22 -07:00
|
|
|
`stackStartFn` is provided, all stack frames above that function will be
|
2019-10-02 00:31:57 -04:00
|
|
|
removed from stacktrace (see [`Error.captureStackTrace`][]). If no arguments are
|
2018-01-28 12:07:18 +01:00
|
|
|
given, the default message `Failed` will be used.
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.fail('a', 'b');
|
|
|
|
// AssertionError [ERR_ASSERTION]: 'a' != 'b'
|
|
|
|
|
|
|
|
assert.fail(1, 2, undefined, '>');
|
|
|
|
// AssertionError [ERR_ASSERTION]: 1 > 2
|
|
|
|
|
|
|
|
assert.fail(1, 2, 'fail');
|
|
|
|
// AssertionError [ERR_ASSERTION]: fail
|
|
|
|
|
|
|
|
assert.fail(1, 2, 'whoops', '>');
|
|
|
|
// AssertionError [ERR_ASSERTION]: whoops
|
|
|
|
|
|
|
|
assert.fail(1, 2, new TypeError('need array'));
|
|
|
|
// TypeError: need array
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2018-01-28 12:07:18 +01:00
|
|
|
assert.fail('a', 'b');
|
|
|
|
// AssertionError [ERR_ASSERTION]: 'a' != 'b'
|
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.fail(1, 2, undefined, '>');
|
2017-07-02 18:06:35 +02:00
|
|
|
// AssertionError [ERR_ASSERTION]: 1 > 2
|
|
|
|
|
|
|
|
assert.fail(1, 2, 'fail');
|
|
|
|
// AssertionError [ERR_ASSERTION]: fail
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.fail(1, 2, 'whoops', '>');
|
2017-07-02 18:06:35 +02:00
|
|
|
// AssertionError [ERR_ASSERTION]: whoops
|
2017-09-09 20:36:47 -05:00
|
|
|
|
|
|
|
assert.fail(1, 2, new TypeError('need array'));
|
|
|
|
// TypeError: need array
|
2017-07-02 18:06:35 +02:00
|
|
|
```
|
|
|
|
|
2018-01-28 12:07:18 +01:00
|
|
|
In the last three cases `actual`, `expected`, and `operator` have no
|
2017-07-02 18:06:35 +02:00
|
|
|
influence on the error message.
|
|
|
|
|
2018-08-01 16:05:22 -07:00
|
|
|
Example use of `stackStartFn` for truncating the exception's stacktrace:
|
2018-01-28 12:07:18 +01:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
function suppressFrame() {
|
|
|
|
assert.fail('a', 'b', undefined, '!==', suppressFrame);
|
|
|
|
}
|
|
|
|
suppressFrame();
|
|
|
|
// AssertionError [ERR_ASSERTION]: 'a' !== 'b'
|
|
|
|
// at repl:1:1
|
|
|
|
// at ContextifyScript.Script.runInThisContext (vm.js:44:33)
|
|
|
|
// ...
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2017-07-02 18:06:35 +02:00
|
|
|
function suppressFrame() {
|
|
|
|
assert.fail('a', 'b', undefined, '!==', suppressFrame);
|
|
|
|
}
|
|
|
|
suppressFrame();
|
|
|
|
// AssertionError [ERR_ASSERTION]: 'a' !== 'b'
|
|
|
|
// at repl:1:1
|
|
|
|
// at ContextifyScript.Script.runInThisContext (vm.js:44:33)
|
|
|
|
// ...
|
2016-01-17 18:39:07 +01:00
|
|
|
```
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.ifError(value)`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.97
|
2018-01-19 10:35:39 +01:00
|
|
|
changes:
|
2018-03-02 09:53:46 -08:00
|
|
|
- version: v10.0.0
|
2018-01-19 10:35:39 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/18247
|
|
|
|
description: Instead of throwing the original error it is now wrapped into
|
2019-06-20 17:13:31 +02:00
|
|
|
an [`AssertionError`][] that contains the full stack trace.
|
2018-03-02 09:53:46 -08:00
|
|
|
- version: v10.0.0
|
2018-01-23 14:07:18 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/18247
|
2018-05-02 16:13:16 +02:00
|
|
|
description: Value may now only be `undefined` or `null`. Before all falsy
|
|
|
|
values were handled the same as `null` and did not throw.
|
2016-05-10 23:08:33 -07:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2017-02-24 23:17:53 -08:00
|
|
|
* `value` {any}
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2018-01-23 14:07:18 +01:00
|
|
|
Throws `value` if `value` is not `undefined` or `null`. This is useful when
|
2018-04-26 03:06:10 +02:00
|
|
|
testing the `error` argument in callbacks. The stack trace contains all frames
|
|
|
|
from the error passed to `ifError()` including the potential new frames for
|
2018-08-26 19:02:27 +03:00
|
|
|
`ifError()` itself.
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.ifError(null);
|
|
|
|
// OK
|
|
|
|
assert.ifError(0);
|
|
|
|
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0
|
|
|
|
assert.ifError('error');
|
|
|
|
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error'
|
|
|
|
assert.ifError(new Error());
|
|
|
|
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error
|
|
|
|
|
|
|
|
// Create some random error frames.
|
|
|
|
let err;
|
|
|
|
(function errorFrame() {
|
|
|
|
err = new Error('test error');
|
|
|
|
})();
|
|
|
|
|
|
|
|
(function ifErrorFrame() {
|
|
|
|
assert.ifError(err);
|
|
|
|
})();
|
|
|
|
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error
|
|
|
|
// at ifErrorFrame
|
|
|
|
// at errorFrame
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2018-01-19 01:20:18 +09:00
|
|
|
assert.ifError(null);
|
|
|
|
// OK
|
2016-11-08 21:04:57 +01:00
|
|
|
assert.ifError(0);
|
2018-01-23 14:07:18 +01:00
|
|
|
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0
|
2016-11-08 21:04:57 +01:00
|
|
|
assert.ifError('error');
|
2018-01-19 10:35:39 +01:00
|
|
|
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error'
|
2016-11-08 21:04:57 +01:00
|
|
|
assert.ifError(new Error());
|
2018-01-19 10:35:39 +01:00
|
|
|
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error
|
2018-04-26 03:06:10 +02:00
|
|
|
|
|
|
|
// Create some random error frames.
|
|
|
|
let err;
|
|
|
|
(function errorFrame() {
|
|
|
|
err = new Error('test error');
|
|
|
|
})();
|
|
|
|
|
|
|
|
(function ifErrorFrame() {
|
|
|
|
assert.ifError(err);
|
|
|
|
})();
|
|
|
|
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error
|
|
|
|
// at ifErrorFrame
|
|
|
|
// at errorFrame
|
2016-01-17 18:39:07 +01:00
|
|
|
```
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-12-12 22:51:43 +01:00
|
|
|
## `assert.match(string, regexp[, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2019-12-12 22:51:43 +01:00
|
|
|
<!-- YAML
|
2020-04-24 18:43:06 +02:00
|
|
|
added:
|
|
|
|
- v13.6.0
|
|
|
|
- v12.16.0
|
2021-04-06 09:54:49 -07:00
|
|
|
changes:
|
2021-03-03 15:36:13 +00:00
|
|
|
- version: v16.0.0
|
2021-04-06 09:54:49 -07:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/38111
|
|
|
|
description: This API is no longer experimental.
|
2019-12-12 22:51:43 +01:00
|
|
|
-->
|
|
|
|
|
|
|
|
* `string` {string}
|
|
|
|
* `regexp` {RegExp}
|
|
|
|
* `message` {string|Error}
|
|
|
|
|
|
|
|
Expects the `string` input to match the regular expression.
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.match('I will fail', /pass/);
|
|
|
|
// AssertionError [ERR_ASSERTION]: The input did not match the regular ...
|
|
|
|
|
|
|
|
assert.match(123, /pass/);
|
|
|
|
// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.
|
|
|
|
|
|
|
|
assert.match('I will pass', /pass/);
|
|
|
|
// OK
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2019-12-12 22:51:43 +01:00
|
|
|
|
|
|
|
assert.match('I will fail', /pass/);
|
|
|
|
// AssertionError [ERR_ASSERTION]: The input did not match the regular ...
|
|
|
|
|
|
|
|
assert.match(123, /pass/);
|
|
|
|
// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.
|
|
|
|
|
|
|
|
assert.match('I will pass', /pass/);
|
|
|
|
// OK
|
|
|
|
```
|
|
|
|
|
|
|
|
If the values do not match, or if the `string` argument is of another type than
|
|
|
|
`string`, 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
|
2025-02-05 14:59:37 +01:00
|
|
|
instance of {Error} then it will be thrown instead of the
|
2019-12-12 22:51:43 +01:00
|
|
|
[`AssertionError`][].
|
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.notDeepEqual(actual, expected[, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.21
|
2017-08-25 19:18:23 -03:00
|
|
|
changes:
|
2021-09-04 15:29:35 +02:00
|
|
|
- version:
|
|
|
|
- v16.0.0
|
|
|
|
- v14.18.0
|
2021-04-06 10:20:53 -07:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/38113
|
|
|
|
description: In Legacy assertion mode, changed status from Deprecated to
|
|
|
|
Legacy.
|
2020-03-10 17:16:08 +00:00
|
|
|
- version: v14.0.0
|
2019-12-02 13:12:52 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/30766
|
2022-01-05 12:35:02 -08:00
|
|
|
description: NaN is now treated as being identical if both sides are
|
2019-12-02 13:12:52 +01:00
|
|
|
NaN.
|
2017-09-01 09:50:47 -07:00
|
|
|
- version: v9.0.0
|
2017-08-25 19:18:23 -03:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/15001
|
2020-10-01 20:35:23 +02:00
|
|
|
description: The `Error` names and messages are now properly compared.
|
2017-08-25 19:18:23 -03:00
|
|
|
- version: v8.0.0
|
|
|
|
pr-url: https://github.com/nodejs/node/pull/12142
|
2020-10-01 20:35:23 +02:00
|
|
|
description: The `Set` and `Map` content is also compared.
|
2020-10-01 20:23:33 +02:00
|
|
|
- version:
|
2021-09-04 15:29:35 +02:00
|
|
|
- v6.4.0
|
|
|
|
- v4.7.1
|
2017-08-25 19:18:23 -03:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/8002
|
|
|
|
description: Typed array slices are handled correctly now.
|
2020-10-01 20:23:33 +02:00
|
|
|
- version:
|
2021-09-04 15:29:35 +02:00
|
|
|
- v6.1.0
|
|
|
|
- v4.5.0
|
2017-08-25 19:18:23 -03:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/6432
|
|
|
|
description: Objects with circular references can be used as inputs now.
|
2020-10-01 20:23:33 +02:00
|
|
|
- version:
|
2021-09-04 15:29:35 +02:00
|
|
|
- v5.10.1
|
|
|
|
- v4.4.3
|
2017-08-25 19:18:23 -03:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/5910
|
|
|
|
description: Handle non-`Uint8Array` typed arrays correctly.
|
2016-05-10 23:08:33 -07:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2017-02-24 23:17:53 -08:00
|
|
|
* `actual` {any}
|
|
|
|
* `expected` {any}
|
2018-05-02 16:13:16 +02:00
|
|
|
* `message` {string|Error}
|
2010-10-28 23:18:16 +11:00
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
**Strict assertion mode**
|
2017-11-13 18:15:24 -02:00
|
|
|
|
|
|
|
An alias of [`assert.notDeepStrictEqual()`][].
|
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
**Legacy assertion mode**
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2021-04-06 10:20:53 -07:00
|
|
|
> Stability: 3 - Legacy: Use [`assert.notDeepStrictEqual()`][] instead.
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2016-01-30 11:12:55 -08:00
|
|
|
Tests for any deep inequality. Opposite of [`assert.deepEqual()`][].
|
2010-10-28 23:18:16 +11:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
const obj1 = {
|
|
|
|
a: {
|
2022-11-17 08:19:12 -05:00
|
|
|
b: 1,
|
|
|
|
},
|
2021-03-04 15:00:25 -08:00
|
|
|
};
|
|
|
|
const obj2 = {
|
|
|
|
a: {
|
2022-11-17 08:19:12 -05:00
|
|
|
b: 2,
|
|
|
|
},
|
2021-03-04 15:00:25 -08:00
|
|
|
};
|
|
|
|
const obj3 = {
|
|
|
|
a: {
|
2022-11-17 08:19:12 -05:00
|
|
|
b: 1,
|
|
|
|
},
|
2021-03-04 15:00:25 -08:00
|
|
|
};
|
2023-01-09 21:38:36 -08:00
|
|
|
const obj4 = { __proto__: obj1 };
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.notDeepEqual(obj1, obj1);
|
|
|
|
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
|
|
|
|
|
|
|
|
assert.notDeepEqual(obj1, obj2);
|
|
|
|
// OK
|
|
|
|
|
|
|
|
assert.notDeepEqual(obj1, obj3);
|
|
|
|
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
|
|
|
|
|
|
|
|
assert.notDeepEqual(obj1, obj4);
|
|
|
|
// OK
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert');
|
2016-01-17 18:39:07 +01:00
|
|
|
|
|
|
|
const obj1 = {
|
2017-04-21 17:38:31 +03:00
|
|
|
a: {
|
2022-11-17 08:19:12 -05:00
|
|
|
b: 1,
|
|
|
|
},
|
2016-01-17 18:39:07 +01:00
|
|
|
};
|
|
|
|
const obj2 = {
|
2017-04-21 17:38:31 +03:00
|
|
|
a: {
|
2022-11-17 08:19:12 -05:00
|
|
|
b: 2,
|
|
|
|
},
|
2016-01-17 18:39:07 +01:00
|
|
|
};
|
|
|
|
const obj3 = {
|
2017-04-21 17:38:31 +03:00
|
|
|
a: {
|
2022-11-17 08:19:12 -05:00
|
|
|
b: 1,
|
|
|
|
},
|
2016-07-29 08:57:45 +05:30
|
|
|
};
|
2023-01-09 21:38:36 -08:00
|
|
|
const obj4 = { __proto__: obj1 };
|
2016-01-17 18:39:07 +01:00
|
|
|
|
2016-01-31 00:47:14 +09:00
|
|
|
assert.notDeepEqual(obj1, obj1);
|
2016-11-08 21:04:57 +01:00
|
|
|
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
|
2016-01-17 18:39:07 +01:00
|
|
|
|
2016-01-31 00:47:14 +09:00
|
|
|
assert.notDeepEqual(obj1, obj2);
|
2018-05-02 16:13:16 +02:00
|
|
|
// OK
|
2016-01-17 18:39:07 +01:00
|
|
|
|
2016-01-31 00:47:14 +09:00
|
|
|
assert.notDeepEqual(obj1, obj3);
|
2016-11-08 21:04:57 +01:00
|
|
|
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }
|
2016-01-17 18:39:07 +01:00
|
|
|
|
2016-01-31 00:47:14 +09:00
|
|
|
assert.notDeepEqual(obj1, obj4);
|
2018-05-02 16:13:16 +02:00
|
|
|
// OK
|
2016-01-17 18:39:07 +01:00
|
|
|
```
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
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
|
2025-02-05 14:59:37 +01:00
|
|
|
`message` parameter is an instance of {Error} then it will be thrown
|
2019-06-20 17:13:31 +02:00
|
|
|
instead of the `AssertionError`.
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.notDeepStrictEqual(actual, expected[, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v1.2.0
|
2017-08-25 19:18:23 -03:00
|
|
|
changes:
|
2017-09-01 09:50:47 -07:00
|
|
|
- version: v9.0.0
|
|
|
|
pr-url: https://github.com/nodejs/node/pull/15398
|
2018-04-29 20:46:41 +03:00
|
|
|
description: The `-0` and `+0` are not considered equal anymore.
|
2017-09-01 09:50:47 -07:00
|
|
|
- version: v9.0.0
|
2017-08-19 02:54:49 -03:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/15036
|
2018-04-29 20:46:41 +03:00
|
|
|
description: The `NaN` is now compared using the
|
2018-02-12 02:31:55 -05:00
|
|
|
[SameValueZero](https://tc39.github.io/ecma262/#sec-samevaluezero)
|
|
|
|
comparison.
|
2017-09-01 09:50:47 -07:00
|
|
|
- version: v9.0.0
|
2017-08-25 19:18:23 -03:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/15001
|
2020-10-01 20:35:23 +02:00
|
|
|
description: The `Error` names and messages are now properly compared.
|
2017-08-25 19:18:23 -03:00
|
|
|
- version: v8.0.0
|
|
|
|
pr-url: https://github.com/nodejs/node/pull/12142
|
2020-10-01 20:35:23 +02:00
|
|
|
description: The `Set` and `Map` content is also compared.
|
2020-10-01 20:23:33 +02:00
|
|
|
- version:
|
|
|
|
- v6.4.0
|
|
|
|
- v4.7.1
|
2017-08-25 19:18:23 -03:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/8002
|
|
|
|
description: Typed array slices are handled correctly now.
|
|
|
|
- version: v6.1.0
|
|
|
|
pr-url: https://github.com/nodejs/node/pull/6432
|
|
|
|
description: Objects with circular references can be used as inputs now.
|
2020-10-01 20:23:33 +02:00
|
|
|
- version:
|
|
|
|
- v5.10.1
|
|
|
|
- v4.4.3
|
2017-08-25 19:18:23 -03:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/5910
|
|
|
|
description: Handle non-`Uint8Array` typed arrays correctly.
|
2016-05-10 23:08:33 -07:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2017-02-24 23:17:53 -08:00
|
|
|
* `actual` {any}
|
|
|
|
* `expected` {any}
|
2018-05-02 16:13:16 +02:00
|
|
|
* `message` {string|Error}
|
2010-10-28 23:18:16 +11:00
|
|
|
|
2016-01-30 11:12:55 -08:00
|
|
|
Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][].
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
|
|
|
|
// OK
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2017-06-01 02:07:25 +03:00
|
|
|
assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
|
2016-11-08 21:04:57 +01:00
|
|
|
// OK
|
2016-01-17 18:39:07 +01:00
|
|
|
```
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
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
|
2025-02-05 14:59:37 +01:00
|
|
|
the `message` parameter is an instance of {Error} then it will be thrown
|
2019-06-20 17:13:31 +02:00
|
|
|
instead of the [`AssertionError`][].
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.notEqual(actual, expected[, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.21
|
2019-12-02 13:12:52 +01:00
|
|
|
changes:
|
2021-09-04 15:29:35 +02:00
|
|
|
- version:
|
|
|
|
- v16.0.0
|
|
|
|
- v14.18.0
|
2021-04-06 10:20:53 -07:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/38113
|
|
|
|
description: In Legacy assertion mode, changed status from Deprecated to
|
|
|
|
Legacy.
|
2020-03-10 17:16:08 +00:00
|
|
|
- version: v14.0.0
|
2019-12-02 13:12:52 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/30766
|
2022-01-05 12:35:02 -08:00
|
|
|
description: NaN is now treated as being identical if both sides are
|
2019-12-02 13:12:52 +01:00
|
|
|
NaN.
|
2016-05-10 23:08:33 -07:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2017-02-24 23:17:53 -08:00
|
|
|
* `actual` {any}
|
|
|
|
* `expected` {any}
|
2018-05-02 16:13:16 +02:00
|
|
|
* `message` {string|Error}
|
2015-11-04 10:48:45 -05:00
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
**Strict assertion mode**
|
2017-11-13 18:15:24 -02:00
|
|
|
|
|
|
|
An alias of [`assert.notStrictEqual()`][].
|
|
|
|
|
2020-02-04 09:41:55 -08:00
|
|
|
**Legacy assertion mode**
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2021-04-06 10:20:53 -07:00
|
|
|
> Stability: 3 - Legacy: Use [`assert.notStrictEqual()`][] instead.
|
2017-11-13 18:15:24 -02:00
|
|
|
|
2022-01-07 20:00:55 -08:00
|
|
|
Tests shallow, coercive inequality with the [`!=` operator][]. `NaN` is
|
|
|
|
specially handled and treated as being identical if both sides are `NaN`.
|
2010-10-28 23:18:16 +11:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.notEqual(1, 2);
|
|
|
|
// OK
|
|
|
|
|
|
|
|
assert.notEqual(1, 1);
|
|
|
|
// AssertionError: 1 != 1
|
|
|
|
|
|
|
|
assert.notEqual(1, '1');
|
|
|
|
// AssertionError: 1 != '1'
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert');
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.notEqual(1, 2);
|
2016-11-08 21:04:57 +01:00
|
|
|
// OK
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.notEqual(1, 1);
|
2016-11-08 21:04:57 +01:00
|
|
|
// AssertionError: 1 != 1
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.notEqual(1, '1');
|
2016-11-08 21:04:57 +01:00
|
|
|
// AssertionError: 1 != '1'
|
2016-01-17 18:39:07 +01:00
|
|
|
```
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
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`
|
2025-02-05 14:59:37 +01:00
|
|
|
parameter is an instance of {Error} then it will be thrown instead of the
|
2017-09-09 20:36:47 -05:00
|
|
|
`AssertionError`.
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.notStrictEqual(actual, expected[, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.21
|
2017-11-13 20:34:16 -02:00
|
|
|
changes:
|
2018-03-02 09:53:46 -08:00
|
|
|
- version: v10.0.0
|
2017-11-13 20:34:16 -02:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/17003
|
2020-10-01 20:35:23 +02:00
|
|
|
description: Used comparison changed from Strict Equality to `Object.is()`.
|
2016-05-10 23:08:33 -07:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2017-02-24 23:17:53 -08:00
|
|
|
* `actual` {any}
|
|
|
|
* `expected` {any}
|
2018-05-02 16:13:16 +02:00
|
|
|
* `message` {string|Error}
|
2010-10-28 23:18:16 +11:00
|
|
|
|
2017-11-13 16:44:30 -02:00
|
|
|
Tests strict inequality between the `actual` and `expected` parameters as
|
2022-01-12 22:17:05 -08:00
|
|
|
determined by [`Object.is()`][].
|
2015-01-28 19:48:56 +03:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.notStrictEqual(1, 2);
|
|
|
|
// OK
|
|
|
|
|
|
|
|
assert.notStrictEqual(1, 1);
|
|
|
|
// AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to:
|
|
|
|
//
|
|
|
|
// 1
|
|
|
|
|
|
|
|
assert.notStrictEqual(1, '1');
|
|
|
|
// OK
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.notStrictEqual(1, 2);
|
2016-11-08 21:04:57 +01:00
|
|
|
// OK
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.notStrictEqual(1, 1);
|
2018-07-03 02:06:57 +02:00
|
|
|
// AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to:
|
|
|
|
//
|
|
|
|
// 1
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.notStrictEqual(1, '1');
|
2016-11-08 21:04:57 +01:00
|
|
|
// OK
|
2016-01-17 18:39:07 +01:00
|
|
|
```
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
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
|
2025-02-05 14:59:37 +01:00
|
|
|
`message` parameter is an instance of {Error} then it will be thrown
|
2019-06-20 17:13:31 +02:00
|
|
|
instead of the `AssertionError`.
|
2015-12-19 19:08:13 -08:00
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.ok(value[, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.21
|
2018-01-15 23:37:09 +01:00
|
|
|
changes:
|
2018-03-02 09:53:46 -08:00
|
|
|
- version: v10.0.0
|
2018-02-04 16:30:04 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/18319
|
2018-04-29 20:46:41 +03:00
|
|
|
description: The `assert.ok()` (no arguments) will now use a predefined
|
|
|
|
error message.
|
2016-05-10 23:08:33 -07:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2017-02-24 23:17:53 -08:00
|
|
|
* `value` {any}
|
2018-05-02 16:13:16 +02:00
|
|
|
* `message` {string|Error}
|
2016-01-25 19:56:21 -08:00
|
|
|
|
|
|
|
Tests if `value` is truthy. It is equivalent to
|
|
|
|
`assert.equal(!!value, true, message)`.
|
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
If `value` is not truthy, an [`AssertionError`][] is thrown with a `message`
|
2016-01-25 19:56:21 -08:00
|
|
|
property set equal to the value of the `message` parameter. If the `message`
|
2017-09-09 20:36:47 -05:00
|
|
|
parameter is `undefined`, a default error message is assigned. If the `message`
|
2025-02-05 14:59:37 +01:00
|
|
|
parameter is an instance of {Error} then it will be thrown instead of the
|
2017-09-09 20:36:47 -05:00
|
|
|
`AssertionError`.
|
2018-01-23 14:38:34 +01:00
|
|
|
If no arguments are passed in at all `message` will be set to the string:
|
2018-04-29 20:46:41 +03:00
|
|
|
``'No value argument passed to `assert.ok()`'``.
|
2016-01-25 19:56:21 -08:00
|
|
|
|
2017-12-09 20:20:07 -02:00
|
|
|
Be aware that in the `repl` the error message will be different to the one
|
|
|
|
thrown in a file! See below for further details.
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.ok(true);
|
|
|
|
// OK
|
|
|
|
assert.ok(1);
|
|
|
|
// OK
|
|
|
|
|
|
|
|
assert.ok();
|
|
|
|
// AssertionError: No value argument passed to `assert.ok()`
|
|
|
|
|
|
|
|
assert.ok(false, 'it\'s false');
|
|
|
|
// AssertionError: it's false
|
|
|
|
|
|
|
|
// In the repl:
|
|
|
|
assert.ok(typeof 123 === 'string');
|
|
|
|
// AssertionError: false == true
|
|
|
|
|
|
|
|
// In a file (e.g. test.js):
|
|
|
|
assert.ok(typeof 123 === 'string');
|
|
|
|
// AssertionError: The expression evaluated to a falsy value:
|
|
|
|
//
|
|
|
|
// assert.ok(typeof 123 === 'string')
|
|
|
|
|
|
|
|
assert.ok(false);
|
|
|
|
// AssertionError: The expression evaluated to a falsy value:
|
|
|
|
//
|
|
|
|
// assert.ok(false)
|
|
|
|
|
|
|
|
assert.ok(0);
|
|
|
|
// AssertionError: The expression evaluated to a falsy value:
|
|
|
|
//
|
|
|
|
// assert.ok(0)
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2016-01-25 19:56:21 -08:00
|
|
|
|
2016-11-08 21:04:57 +01:00
|
|
|
assert.ok(true);
|
|
|
|
// OK
|
|
|
|
assert.ok(1);
|
|
|
|
// OK
|
2017-12-09 20:20:07 -02:00
|
|
|
|
2018-01-23 14:38:34 +01:00
|
|
|
assert.ok();
|
2018-04-26 03:06:10 +02:00
|
|
|
// AssertionError: No value argument passed to `assert.ok()`
|
2018-01-23 14:38:34 +01:00
|
|
|
|
2016-01-25 19:56:21 -08:00
|
|
|
assert.ok(false, 'it\'s false');
|
2018-04-26 03:06:10 +02:00
|
|
|
// AssertionError: it's false
|
2017-12-09 20:20:07 -02:00
|
|
|
|
|
|
|
// In the repl:
|
|
|
|
assert.ok(typeof 123 === 'string');
|
2018-04-26 03:06:10 +02:00
|
|
|
// AssertionError: false == true
|
2017-12-09 20:20:07 -02:00
|
|
|
|
|
|
|
// In a file (e.g. test.js):
|
|
|
|
assert.ok(typeof 123 === 'string');
|
2018-04-26 03:06:10 +02:00
|
|
|
// AssertionError: The expression evaluated to a falsy value:
|
2017-12-09 20:20:07 -02:00
|
|
|
//
|
|
|
|
// assert.ok(typeof 123 === 'string')
|
|
|
|
|
|
|
|
assert.ok(false);
|
2018-04-26 03:06:10 +02:00
|
|
|
// AssertionError: The expression evaluated to a falsy value:
|
2017-12-09 20:20:07 -02:00
|
|
|
//
|
|
|
|
// assert.ok(false)
|
|
|
|
|
|
|
|
assert.ok(0);
|
2018-04-26 03:06:10 +02:00
|
|
|
// AssertionError: The expression evaluated to a falsy value:
|
2017-12-09 20:20:07 -02:00
|
|
|
//
|
|
|
|
// assert.ok(0)
|
2021-03-04 15:00:25 -08:00
|
|
|
```
|
|
|
|
|
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
// Using `assert()` works the same:
|
|
|
|
assert(0);
|
|
|
|
// AssertionError: The expression evaluated to a falsy value:
|
|
|
|
//
|
|
|
|
// assert(0)
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert');
|
2017-12-09 20:20:07 -02:00
|
|
|
|
|
|
|
// Using `assert()` works the same:
|
|
|
|
assert(0);
|
2018-04-26 03:06:10 +02:00
|
|
|
// AssertionError: The expression evaluated to a falsy value:
|
2017-12-09 20:20:07 -02:00
|
|
|
//
|
|
|
|
// assert(0)
|
2016-01-25 19:56:21 -08:00
|
|
|
```
|
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.rejects(asyncFn[, error][, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2018-01-12 00:16:41 +01:00
|
|
|
<!-- YAML
|
2018-03-02 09:53:46 -08:00
|
|
|
added: v10.0.0
|
2018-01-12 00:16:41 +01:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2018-09-04 01:10:29 +02:00
|
|
|
* `asyncFn` {Function|Promise}
|
2018-04-09 01:31:59 +02:00
|
|
|
* `error` {RegExp|Function|Object|Error}
|
2018-09-04 01:10:29 +02:00
|
|
|
* `message` {string}
|
2025-02-28 09:33:00 -05:00
|
|
|
* Returns: {Promise}
|
2018-01-12 00:16:41 +01:00
|
|
|
|
2018-09-04 01:10:29 +02:00
|
|
|
Awaits the `asyncFn` promise or, if `asyncFn` is a function, immediately
|
|
|
|
calls the function and awaits the returned promise to complete. It will then
|
|
|
|
check that the promise is rejected.
|
2018-01-12 00:16:41 +01:00
|
|
|
|
2018-09-04 01:10:29 +02:00
|
|
|
If `asyncFn` is a function and it throws an error synchronously,
|
2018-04-29 20:46:41 +03:00
|
|
|
`assert.rejects()` will return a rejected `Promise` with that error. If the
|
2018-04-09 00:38:41 +02:00
|
|
|
function does not return a promise, `assert.rejects()` will return a rejected
|
2018-04-29 20:46:41 +03:00
|
|
|
`Promise` with an [`ERR_INVALID_RETURN_VALUE`][] error. In both cases the error
|
2018-04-09 00:38:41 +02:00
|
|
|
handler is skipped.
|
2018-01-12 00:16:41 +01:00
|
|
|
|
2018-03-11 14:05:04 +02:00
|
|
|
Besides the async nature to await the completion behaves identically to
|
2018-01-12 00:16:41 +01:00
|
|
|
[`assert.throws()`][].
|
|
|
|
|
2025-02-05 14:59:37 +01:00
|
|
|
If specified, `error` can be a [`Class`][], {RegExp}, a validation function,
|
2018-04-09 01:31:59 +02:00
|
|
|
an object where each property will be tested for, or an instance of error where
|
|
|
|
each property will be tested for including the non-enumerable `message` and
|
|
|
|
`name` properties.
|
2018-01-12 00:16:41 +01:00
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
If specified, `message` will be the message provided by the [`AssertionError`][]
|
|
|
|
if the `asyncFn` fails to reject.
|
2018-01-12 00:16:41 +01:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
await assert.rejects(
|
|
|
|
async () => {
|
|
|
|
throw new TypeError('Wrong value');
|
|
|
|
},
|
|
|
|
{
|
|
|
|
name: 'TypeError',
|
2022-11-17 08:19:12 -05:00
|
|
|
message: 'Wrong value',
|
|
|
|
},
|
2021-03-04 15:00:25 -08:00
|
|
|
);
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2018-01-12 00:16:41 +01:00
|
|
|
(async () => {
|
|
|
|
await assert.rejects(
|
|
|
|
async () => {
|
2018-04-08 23:28:30 +02:00
|
|
|
throw new TypeError('Wrong value');
|
2018-01-12 00:16:41 +01:00
|
|
|
},
|
2018-04-08 23:28:30 +02:00
|
|
|
{
|
|
|
|
name: 'TypeError',
|
2022-11-17 08:19:12 -05:00
|
|
|
message: 'Wrong value',
|
|
|
|
},
|
2018-01-12 00:16:41 +01:00
|
|
|
);
|
|
|
|
})();
|
|
|
|
```
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
await assert.rejects(
|
|
|
|
async () => {
|
|
|
|
throw new TypeError('Wrong value');
|
|
|
|
},
|
|
|
|
(err) => {
|
|
|
|
assert.strictEqual(err.name, 'TypeError');
|
|
|
|
assert.strictEqual(err.message, 'Wrong value');
|
|
|
|
return true;
|
2022-11-17 08:19:12 -05:00
|
|
|
},
|
2021-03-04 15:00:25 -08:00
|
|
|
);
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2020-01-09 01:14:44 -06:00
|
|
|
(async () => {
|
|
|
|
await assert.rejects(
|
|
|
|
async () => {
|
|
|
|
throw new TypeError('Wrong value');
|
|
|
|
},
|
|
|
|
(err) => {
|
|
|
|
assert.strictEqual(err.name, 'TypeError');
|
|
|
|
assert.strictEqual(err.message, 'Wrong value');
|
|
|
|
return true;
|
2022-11-17 08:19:12 -05:00
|
|
|
},
|
2020-01-09 01:14:44 -06:00
|
|
|
);
|
|
|
|
})();
|
|
|
|
```
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.rejects(
|
|
|
|
Promise.reject(new Error('Wrong value')),
|
2022-11-17 08:19:12 -05:00
|
|
|
Error,
|
2021-03-04 15:00:25 -08:00
|
|
|
).then(() => {
|
|
|
|
// ...
|
|
|
|
});
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2018-01-12 00:16:41 +01:00
|
|
|
assert.rejects(
|
2018-04-08 23:28:30 +02:00
|
|
|
Promise.reject(new Error('Wrong value')),
|
2022-11-17 08:19:12 -05:00
|
|
|
Error,
|
2018-01-12 00:16:41 +01:00
|
|
|
).then(() => {
|
|
|
|
// ...
|
|
|
|
});
|
|
|
|
```
|
|
|
|
|
2019-06-20 14:10:15 -06:00
|
|
|
`error` cannot be a string. If a string is provided as the second
|
2018-04-08 23:28:30 +02:00
|
|
|
argument, then `error` is assumed to be omitted and the string will be used for
|
|
|
|
`message` instead. This can lead to easy-to-miss mistakes. Please read the
|
|
|
|
example in [`assert.throws()`][] carefully if using a string as the second
|
|
|
|
argument gets considered.
|
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.strictEqual(actual, expected[, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2018-03-11 14:05:04 +02:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.21
|
|
|
|
changes:
|
2018-03-02 09:53:46 -08:00
|
|
|
- version: v10.0.0
|
2018-03-11 14:05:04 +02:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/17003
|
2020-10-01 20:35:23 +02:00
|
|
|
description: Used comparison changed from Strict Equality to `Object.is()`.
|
2018-03-11 14:05:04 +02:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2018-03-11 14:05:04 +02:00
|
|
|
* `actual` {any}
|
|
|
|
* `expected` {any}
|
2018-05-02 16:13:16 +02:00
|
|
|
* `message` {string|Error}
|
2018-03-11 14:05:04 +02:00
|
|
|
|
|
|
|
Tests strict equality between the `actual` and `expected` parameters as
|
2022-01-12 22:17:05 -08:00
|
|
|
determined by [`Object.is()`][].
|
2018-03-11 14:05:04 +02:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.strictEqual(1, 2);
|
|
|
|
// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
|
|
|
|
//
|
|
|
|
// 1 !== 2
|
|
|
|
|
|
|
|
assert.strictEqual(1, 1);
|
|
|
|
// OK
|
|
|
|
|
|
|
|
assert.strictEqual('Hello foobar', 'Hello World!');
|
|
|
|
// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
|
|
|
|
// + actual - expected
|
|
|
|
//
|
|
|
|
// + 'Hello foobar'
|
|
|
|
// - 'Hello World!'
|
|
|
|
// ^
|
|
|
|
|
|
|
|
const apples = 1;
|
|
|
|
const oranges = 2;
|
|
|
|
assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`);
|
|
|
|
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2
|
|
|
|
|
|
|
|
assert.strictEqual(1, '1', new TypeError('Inputs are not identical'));
|
|
|
|
// TypeError: Inputs are not identical
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2018-03-11 14:05:04 +02:00
|
|
|
|
|
|
|
assert.strictEqual(1, 2);
|
2018-07-03 02:06:57 +02:00
|
|
|
// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
|
|
|
|
//
|
|
|
|
// 1 !== 2
|
2018-03-11 14:05:04 +02:00
|
|
|
|
|
|
|
assert.strictEqual(1, 1);
|
|
|
|
// OK
|
|
|
|
|
2018-07-03 02:06:57 +02:00
|
|
|
assert.strictEqual('Hello foobar', 'Hello World!');
|
|
|
|
// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
|
|
|
|
// + actual - expected
|
|
|
|
//
|
|
|
|
// + 'Hello foobar'
|
|
|
|
// - 'Hello World!'
|
|
|
|
// ^
|
2019-06-06 15:12:14 +08:00
|
|
|
|
|
|
|
const apples = 1;
|
|
|
|
const oranges = 2;
|
|
|
|
assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`);
|
|
|
|
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2
|
|
|
|
|
|
|
|
assert.strictEqual(1, '1', new TypeError('Inputs are not identical'));
|
|
|
|
// TypeError: Inputs are not identical
|
2018-03-11 14:05:04 +02:00
|
|
|
```
|
|
|
|
|
2019-06-20 17:13:31 +02:00
|
|
|
If the values are not strictly equal, an [`AssertionError`][] is thrown with a
|
2018-03-11 14:05:04 +02:00
|
|
|
`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
|
2025-02-05 14:59:37 +01:00
|
|
|
`message` parameter is an instance of {Error} then it will be thrown
|
2019-06-20 17:13:31 +02:00
|
|
|
instead of the [`AssertionError`][].
|
2018-03-11 14:05:04 +02:00
|
|
|
|
2019-12-23 12:27:50 -08:00
|
|
|
## `assert.throws(fn[, error][, message])`
|
2021-10-10 21:55:04 -07:00
|
|
|
|
2016-05-10 23:08:33 -07:00
|
|
|
<!-- YAML
|
|
|
|
added: v0.1.21
|
2017-02-21 23:39:15 +01:00
|
|
|
changes:
|
2018-05-14 20:01:36 +02:00
|
|
|
- version: v10.2.0
|
2018-05-14 19:35:45 +02:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/20485
|
|
|
|
description: The `error` parameter can be an object containing regular
|
|
|
|
expressions now.
|
2018-03-18 14:45:41 +01:00
|
|
|
- version: v9.9.0
|
2018-02-04 16:30:04 +01:00
|
|
|
pr-url: https://github.com/nodejs/node/pull/17584
|
2017-12-09 22:54:44 -02:00
|
|
|
description: The `error` parameter can now be an object as well.
|
2017-02-21 23:39:15 +01:00
|
|
|
- version: v4.2.0
|
|
|
|
pr-url: https://github.com/nodejs/node/pull/3276
|
|
|
|
description: The `error` parameter can now be an arrow function.
|
2016-05-10 23:08:33 -07:00
|
|
|
-->
|
2019-09-06 01:42:22 -04:00
|
|
|
|
2018-09-04 01:10:29 +02:00
|
|
|
* `fn` {Function}
|
2018-04-09 01:31:59 +02:00
|
|
|
* `error` {RegExp|Function|Object|Error}
|
2018-09-04 01:10:29 +02:00
|
|
|
* `message` {string}
|
2010-10-28 23:18:16 +11:00
|
|
|
|
2018-09-04 01:10:29 +02:00
|
|
|
Expects the function `fn` to throw an error.
|
2016-04-03 12:11:10 -07:00
|
|
|
|
2025-02-05 14:59:37 +01:00
|
|
|
If specified, `error` can be a [`Class`][], {RegExp}, a validation function,
|
2018-05-02 19:26:32 +02:00
|
|
|
a validation object where each property will be tested for strict deep equality,
|
|
|
|
or an instance of error where each property will be tested for strict deep
|
|
|
|
equality including the non-enumerable `message` and `name` properties. When
|
|
|
|
using an object, it is also possible to use a regular expression, when
|
|
|
|
validating against a string property. See below for examples.
|
2016-04-03 12:11:10 -07:00
|
|
|
|
2018-09-04 01:10:29 +02:00
|
|
|
If specified, `message` will be appended to the message provided by the
|
|
|
|
`AssertionError` if the `fn` call fails to throw or in case the error validation
|
|
|
|
fails.
|
2010-12-02 11:07:47 -08:00
|
|
|
|
2018-06-04 12:32:54 -07:00
|
|
|
Custom validation object/error instance:
|
2018-04-26 03:06:10 +02:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2018-04-26 03:06:10 +02:00
|
|
|
const err = new TypeError('Wrong value');
|
|
|
|
err.code = 404;
|
2018-05-02 19:26:32 +02:00
|
|
|
err.foo = 'bar';
|
|
|
|
err.info = {
|
|
|
|
nested: true,
|
2022-11-17 08:19:12 -05:00
|
|
|
baz: 'text',
|
2018-05-02 19:26:32 +02:00
|
|
|
};
|
|
|
|
err.reg = /abc/i;
|
2018-04-26 03:06:10 +02:00
|
|
|
|
|
|
|
assert.throws(
|
|
|
|
() => {
|
|
|
|
throw err;
|
|
|
|
},
|
|
|
|
{
|
|
|
|
name: 'TypeError',
|
2018-05-02 19:26:32 +02:00
|
|
|
message: 'Wrong value',
|
|
|
|
info: {
|
|
|
|
nested: true,
|
2022-11-17 08:19:12 -05:00
|
|
|
baz: 'text',
|
|
|
|
},
|
2019-06-20 14:10:15 -06:00
|
|
|
// Only properties on the validation object will be tested for.
|
2018-05-02 19:26:32 +02:00
|
|
|
// Using nested objects requires all properties to be present. Otherwise
|
|
|
|
// the validation is going to fail.
|
2022-11-17 08:19:12 -05:00
|
|
|
},
|
2018-05-02 19:26:32 +02:00
|
|
|
);
|
|
|
|
|
|
|
|
// Using regular expressions to validate error properties:
|
2022-04-22 00:18:22 +08:00
|
|
|
assert.throws(
|
2018-05-02 19:26:32 +02:00
|
|
|
() => {
|
|
|
|
throw err;
|
|
|
|
},
|
|
|
|
{
|
|
|
|
// The `name` and `message` properties are strings and using regular
|
|
|
|
// expressions on those will match against the string. If they fail, an
|
|
|
|
// error is thrown.
|
|
|
|
name: /^TypeError$/,
|
|
|
|
message: /Wrong/,
|
|
|
|
foo: 'bar',
|
|
|
|
info: {
|
|
|
|
nested: true,
|
|
|
|
// It is not possible to use regular expressions for nested properties!
|
2022-11-17 08:19:12 -05:00
|
|
|
baz: 'text',
|
2018-05-02 19:26:32 +02:00
|
|
|
},
|
|
|
|
// The `reg` property contains a regular expression and only if the
|
|
|
|
// validation object contains an identical regular expression, it is going
|
|
|
|
// to pass.
|
2022-11-17 08:19:12 -05:00
|
|
|
reg: /abc/i,
|
|
|
|
},
|
2018-04-26 03:06:10 +02:00
|
|
|
);
|
|
|
|
|
|
|
|
// Fails due to the different `message` and `name` properties:
|
2022-04-22 00:18:22 +08:00
|
|
|
assert.throws(
|
2021-03-04 15:00:25 -08:00
|
|
|
() => {
|
|
|
|
const otherErr = new Error('Not found');
|
|
|
|
// Copy all enumerable properties from `err` to `otherErr`.
|
|
|
|
for (const [key, value] of Object.entries(err)) {
|
|
|
|
otherErr[key] = value;
|
|
|
|
}
|
|
|
|
throw otherErr;
|
|
|
|
},
|
|
|
|
// The error's `message` and `name` properties will also be checked when using
|
|
|
|
// an error as validation object.
|
2022-11-17 08:19:12 -05:00
|
|
|
err,
|
2021-03-04 15:00:25 -08:00
|
|
|
);
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
const err = new TypeError('Wrong value');
|
|
|
|
err.code = 404;
|
|
|
|
err.foo = 'bar';
|
|
|
|
err.info = {
|
|
|
|
nested: true,
|
2022-11-17 08:19:12 -05:00
|
|
|
baz: 'text',
|
2021-03-04 15:00:25 -08:00
|
|
|
};
|
|
|
|
err.reg = /abc/i;
|
|
|
|
|
2018-04-26 03:06:10 +02:00
|
|
|
assert.throws(
|
2021-03-04 15:00:25 -08:00
|
|
|
() => {
|
|
|
|
throw err;
|
|
|
|
},
|
|
|
|
{
|
|
|
|
name: 'TypeError',
|
|
|
|
message: 'Wrong value',
|
|
|
|
info: {
|
|
|
|
nested: true,
|
2022-11-17 08:19:12 -05:00
|
|
|
baz: 'text',
|
|
|
|
},
|
2021-03-04 15:00:25 -08:00
|
|
|
// Only properties on the validation object will be tested for.
|
|
|
|
// Using nested objects requires all properties to be present. Otherwise
|
|
|
|
// the validation is going to fail.
|
2022-11-17 08:19:12 -05:00
|
|
|
},
|
2021-03-04 15:00:25 -08:00
|
|
|
);
|
|
|
|
|
|
|
|
// Using regular expressions to validate error properties:
|
2022-04-22 00:18:22 +08:00
|
|
|
assert.throws(
|
2021-03-04 15:00:25 -08:00
|
|
|
() => {
|
|
|
|
throw err;
|
|
|
|
},
|
|
|
|
{
|
|
|
|
// The `name` and `message` properties are strings and using regular
|
|
|
|
// expressions on those will match against the string. If they fail, an
|
|
|
|
// error is thrown.
|
|
|
|
name: /^TypeError$/,
|
|
|
|
message: /Wrong/,
|
|
|
|
foo: 'bar',
|
|
|
|
info: {
|
|
|
|
nested: true,
|
|
|
|
// It is not possible to use regular expressions for nested properties!
|
2022-11-17 08:19:12 -05:00
|
|
|
baz: 'text',
|
2021-03-04 15:00:25 -08:00
|
|
|
},
|
|
|
|
// The `reg` property contains a regular expression and only if the
|
|
|
|
// validation object contains an identical regular expression, it is going
|
|
|
|
// to pass.
|
2022-11-17 08:19:12 -05:00
|
|
|
reg: /abc/i,
|
|
|
|
},
|
2021-03-04 15:00:25 -08:00
|
|
|
);
|
|
|
|
|
|
|
|
// Fails due to the different `message` and `name` properties:
|
2022-04-22 00:18:22 +08:00
|
|
|
assert.throws(
|
2018-04-26 03:06:10 +02:00
|
|
|
() => {
|
|
|
|
const otherErr = new Error('Not found');
|
2019-06-17 16:35:10 +02:00
|
|
|
// Copy all enumerable properties from `err` to `otherErr`.
|
|
|
|
for (const [key, value] of Object.entries(err)) {
|
|
|
|
otherErr[key] = value;
|
|
|
|
}
|
2018-04-26 03:06:10 +02:00
|
|
|
throw otherErr;
|
|
|
|
},
|
2019-06-17 16:35:10 +02:00
|
|
|
// The error's `message` and `name` properties will also be checked when using
|
|
|
|
// an error as validation object.
|
2022-11-17 08:19:12 -05:00
|
|
|
err,
|
2018-04-26 03:06:10 +02:00
|
|
|
);
|
|
|
|
```
|
|
|
|
|
2010-12-02 11:07:47 -08:00
|
|
|
Validate instanceof using constructor:
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.throws(
|
|
|
|
() => {
|
|
|
|
throw new Error('Wrong value');
|
|
|
|
},
|
2022-11-17 08:19:12 -05:00
|
|
|
Error,
|
2021-03-04 15:00:25 -08:00
|
|
|
);
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.throws(
|
2016-01-24 11:15:51 +02:00
|
|
|
() => {
|
2016-01-17 18:39:07 +01:00
|
|
|
throw new Error('Wrong value');
|
|
|
|
},
|
2022-11-17 08:19:12 -05:00
|
|
|
Error,
|
2016-01-17 18:39:07 +01:00
|
|
|
);
|
|
|
|
```
|
2010-12-02 11:07:47 -08:00
|
|
|
|
2025-02-05 14:59:37 +01:00
|
|
|
Validate error message using {RegExp}:
|
2010-12-02 11:07:47 -08:00
|
|
|
|
2017-12-11 05:04:17 -02:00
|
|
|
Using a regular expression runs `.toString` on the error object, and will
|
|
|
|
therefore also include the error name.
|
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.throws(
|
|
|
|
() => {
|
|
|
|
throw new Error('Wrong value');
|
|
|
|
},
|
2022-11-17 08:19:12 -05:00
|
|
|
/^Error: Wrong value$/,
|
2021-03-04 15:00:25 -08:00
|
|
|
);
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.throws(
|
2016-01-24 11:15:51 +02:00
|
|
|
() => {
|
2016-01-17 18:39:07 +01:00
|
|
|
throw new Error('Wrong value');
|
|
|
|
},
|
2022-11-17 08:19:12 -05:00
|
|
|
/^Error: Wrong value$/,
|
2016-01-17 18:39:07 +01:00
|
|
|
);
|
|
|
|
```
|
2010-12-02 11:07:47 -08:00
|
|
|
|
|
|
|
Custom error validation:
|
|
|
|
|
2019-06-14 16:14:50 +02:00
|
|
|
The function must return `true` to indicate all internal validations passed.
|
2019-06-20 17:13:31 +02:00
|
|
|
It will otherwise fail with an [`AssertionError`][].
|
2019-06-14 16:14:50 +02:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
assert.throws(
|
|
|
|
() => {
|
|
|
|
throw new Error('Wrong value');
|
|
|
|
},
|
|
|
|
(err) => {
|
|
|
|
assert(err instanceof Error);
|
|
|
|
assert(/value/.test(err));
|
|
|
|
// Avoid returning anything from validation functions besides `true`.
|
|
|
|
// Otherwise, it's not clear what part of the validation failed. Instead,
|
|
|
|
// throw an error about the specific validation that failed (as done in this
|
|
|
|
// example) and add as much helpful debugging information to that error as
|
|
|
|
// possible.
|
|
|
|
return true;
|
|
|
|
},
|
2022-11-17 08:19:12 -05:00
|
|
|
'unexpected error',
|
2021-03-04 15:00:25 -08:00
|
|
|
);
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2016-01-17 18:39:07 +01:00
|
|
|
assert.throws(
|
2016-01-24 11:15:51 +02:00
|
|
|
() => {
|
2016-01-17 18:39:07 +01:00
|
|
|
throw new Error('Wrong value');
|
|
|
|
},
|
2019-05-20 00:30:45 +02:00
|
|
|
(err) => {
|
|
|
|
assert(err instanceof Error);
|
|
|
|
assert(/value/.test(err));
|
2019-11-20 06:53:45 -08:00
|
|
|
// Avoid returning anything from validation functions besides `true`.
|
|
|
|
// Otherwise, it's not clear what part of the validation failed. Instead,
|
|
|
|
// throw an error about the specific validation that failed (as done in this
|
|
|
|
// example) and add as much helpful debugging information to that error as
|
|
|
|
// possible.
|
2019-05-20 00:30:45 +02:00
|
|
|
return true;
|
2016-01-17 18:39:07 +01:00
|
|
|
},
|
2022-11-17 08:19:12 -05:00
|
|
|
'unexpected error',
|
2016-01-17 18:39:07 +01:00
|
|
|
);
|
|
|
|
```
|
2015-11-13 19:21:49 -08:00
|
|
|
|
2019-06-20 14:10:15 -06:00
|
|
|
`error` cannot be a string. If a string is provided as the second
|
2016-04-03 12:11:10 -07:00
|
|
|
argument, then `error` is assumed to be omitted and the string will be used for
|
2018-04-26 03:06:10 +02:00
|
|
|
`message` instead. This can lead to easy-to-miss mistakes. Using the same
|
|
|
|
message as the thrown error message is going to result in an
|
|
|
|
`ERR_AMBIGUOUS_ARGUMENT` error. Please read the example below carefully if using
|
|
|
|
a string as the second argument gets considered:
|
2016-04-03 12:11:10 -07:00
|
|
|
|
2021-03-04 15:00:25 -08:00
|
|
|
```mjs
|
2022-04-20 10:23:41 +02:00
|
|
|
import assert from 'node:assert/strict';
|
2021-03-04 15:00:25 -08:00
|
|
|
|
|
|
|
function throwingFirst() {
|
|
|
|
throw new Error('First');
|
|
|
|
}
|
|
|
|
|
|
|
|
function throwingSecond() {
|
|
|
|
throw new Error('Second');
|
|
|
|
}
|
|
|
|
|
|
|
|
function notThrowing() {}
|
|
|
|
|
|
|
|
// The second argument is a string and the input function threw an Error.
|
|
|
|
// The first case will not throw as it does not match for the error message
|
|
|
|
// thrown by the input function!
|
|
|
|
assert.throws(throwingFirst, 'Second');
|
|
|
|
// In the next example the message has no benefit over the message from the
|
|
|
|
// error and since it is not clear if the user intended to actually match
|
|
|
|
// against the error message, Node.js throws an `ERR_AMBIGUOUS_ARGUMENT` error.
|
|
|
|
assert.throws(throwingSecond, 'Second');
|
|
|
|
// TypeError [ERR_AMBIGUOUS_ARGUMENT]
|
|
|
|
|
|
|
|
// The string is only used (as message) in case the function does not throw:
|
|
|
|
assert.throws(notThrowing, 'Second');
|
|
|
|
// AssertionError [ERR_ASSERTION]: Missing expected exception: Second
|
|
|
|
|
|
|
|
// If it was intended to match for the error message do this instead:
|
|
|
|
// It does not throw because the error messages match.
|
|
|
|
assert.throws(throwingSecond, /Second$/);
|
|
|
|
|
|
|
|
// If the error message does not match, an AssertionError is thrown.
|
|
|
|
assert.throws(throwingFirst, /Second$/);
|
|
|
|
// AssertionError [ERR_ASSERTION]
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
2022-04-20 10:23:41 +02:00
|
|
|
const assert = require('node:assert/strict');
|
2021-03-04 15:00:25 -08:00
|
|
|
|
2017-12-09 21:47:49 -02:00
|
|
|
function throwingFirst() {
|
|
|
|
throw new Error('First');
|
|
|
|
}
|
2019-11-27 22:56:21 -08:00
|
|
|
|
2017-12-09 21:47:49 -02:00
|
|
|
function throwingSecond() {
|
|
|
|
throw new Error('Second');
|
|
|
|
}
|
2019-11-27 22:56:21 -08:00
|
|
|
|
2017-12-09 21:47:49 -02:00
|
|
|
function notThrowing() {}
|
|
|
|
|
|
|
|
// The second argument is a string and the input function threw an Error.
|
2018-04-26 03:06:10 +02:00
|
|
|
// The first case will not throw as it does not match for the error message
|
|
|
|
// thrown by the input function!
|
2017-12-09 21:47:49 -02:00
|
|
|
assert.throws(throwingFirst, 'Second');
|
2018-04-26 03:06:10 +02:00
|
|
|
// In the next example the message has no benefit over the message from the
|
|
|
|
// error and since it is not clear if the user intended to actually match
|
2018-07-03 02:06:57 +02:00
|
|
|
// against the error message, Node.js throws an `ERR_AMBIGUOUS_ARGUMENT` error.
|
2017-12-09 21:47:49 -02:00
|
|
|
assert.throws(throwingSecond, 'Second');
|
2018-04-26 03:06:10 +02:00
|
|
|
// TypeError [ERR_AMBIGUOUS_ARGUMENT]
|
2017-12-09 21:47:49 -02:00
|
|
|
|
|
|
|
// The string is only used (as message) in case the function does not throw:
|
|
|
|
assert.throws(notThrowing, 'Second');
|
|
|
|
// AssertionError [ERR_ASSERTION]: Missing expected exception: Second
|
|
|
|
|
|
|
|
// If it was intended to match for the error message do this instead:
|
2018-07-03 02:06:57 +02:00
|
|
|
// It does not throw because the error messages match.
|
2017-12-09 21:47:49 -02:00
|
|
|
assert.throws(throwingSecond, /Second$/);
|
2018-07-03 02:06:57 +02:00
|
|
|
|
2019-06-17 16:35:10 +02:00
|
|
|
// If the error message does not match, an AssertionError is thrown.
|
2017-12-09 21:47:49 -02:00
|
|
|
assert.throws(throwingFirst, /Second$/);
|
2019-06-17 16:35:10 +02:00
|
|
|
// AssertionError [ERR_ASSERTION]
|
2016-04-03 12:11:10 -07:00
|
|
|
```
|
|
|
|
|
2019-11-20 06:53:45 -08:00
|
|
|
Due to the confusing error-prone notation, avoid a string as the second
|
|
|
|
argument.
|
2017-12-09 21:47:49 -02:00
|
|
|
|
2024-11-23 18:45:49 +01:00
|
|
|
## `assert.partialDeepStrictEqual(actual, expected[, message])`
|
|
|
|
|
|
|
|
<!-- YAML
|
2025-01-05 13:33:23 -05:00
|
|
|
added:
|
|
|
|
- v23.4.0
|
|
|
|
- v22.13.0
|
2025-03-11 01:48:58 +01:00
|
|
|
changes:
|
|
|
|
- version: REPLACEME
|
|
|
|
pr-url: https://github.com/nodejs/node/pull/57370
|
|
|
|
description: partialDeepStrictEqual is now Stable. Previously, it had been Experimental.
|
2024-11-23 18:45:49 +01:00
|
|
|
-->
|
|
|
|
|
|
|
|
* `actual` {any}
|
|
|
|
* `expected` {any}
|
|
|
|
* `message` {string|Error}
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
Tests for partial 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. "Partial" equality means
|
|
|
|
that only properties that exist on the `expected` parameter are going to be
|
|
|
|
compared.
|
2024-11-23 18:45:49 +01:00
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
This method always passes the same test cases as [`assert.deepStrictEqual()`][],
|
|
|
|
behaving as a super set of it.
|
2024-11-23 18:45:49 +01:00
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
### Comparison details
|
2024-11-23 18:45:49 +01:00
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
* Primitive values are compared using [`Object.is()`][].
|
|
|
|
* [Type tags][Object.prototype.toString()] of objects should be the same.
|
|
|
|
* [`[[Prototype]]`][prototype-spec] of objects are not compared.
|
|
|
|
* Only [enumerable "own" properties][] are considered.
|
|
|
|
* {Error} names, messages, causes, and errors are always compared,
|
|
|
|
even if these are not enumerable properties.
|
|
|
|
`errors` is also compared.
|
|
|
|
* 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.
|
|
|
|
* {WeakMap} and {WeakSet} instances are **not** compared structurally.
|
|
|
|
They are only equal if they reference the same object. Any comparison between
|
|
|
|
different `WeakMap` or `WeakSet` instances will result in inequality,
|
|
|
|
even if they contain the same entries.
|
|
|
|
* {RegExp} lastIndex, flags, and source are always compared, even if these
|
|
|
|
are not enumerable properties.
|
|
|
|
* Holes in sparse arrays are ignored.
|
2024-11-23 18:45:49 +01:00
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
```mjs
|
|
|
|
import assert from 'node:assert';
|
2024-11-23 18:45:49 +01:00
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
{ a: { b: { c: 1 } } },
|
|
|
|
{ a: { b: { c: 1 } } },
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// OK
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
{ a: 1, b: 2, c: 3 },
|
|
|
|
{ b: 2 },
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// OK
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
[1, 2, 3, 4, 5, 6, 7, 8, 9],
|
|
|
|
[4, 5, 8],
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// OK
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
new Set([{ a: 1 }, { b: 1 }]),
|
|
|
|
new Set([{ a: 1 }]),
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// OK
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
new Map([['key1', 'value1'], ['key2', 'value2']]),
|
|
|
|
new Map([['key2', 'value2']]),
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// OK
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(123n, 123n);
|
2024-11-23 18:45:49 +01:00
|
|
|
// OK
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
[1, 2, 3, 4, 5, 6, 7, 8, 9],
|
|
|
|
[5, 4, 8],
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// AssertionError
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
{ a: 1 },
|
|
|
|
{ a: 1, b: 2 },
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// AssertionError
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
{ a: { b: 2 } },
|
|
|
|
{ a: { b: '2' } },
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// AssertionError
|
|
|
|
```
|
|
|
|
|
|
|
|
```cjs
|
|
|
|
const assert = require('node:assert');
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
{ a: { b: { c: 1 } } },
|
|
|
|
{ a: { b: { c: 1 } } },
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// OK
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
{ a: 1, b: 2, c: 3 },
|
|
|
|
{ b: 2 },
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// OK
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
[1, 2, 3, 4, 5, 6, 7, 8, 9],
|
|
|
|
[4, 5, 8],
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// OK
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
new Set([{ a: 1 }, { b: 1 }]),
|
|
|
|
new Set([{ a: 1 }]),
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// OK
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
new Map([['key1', 'value1'], ['key2', 'value2']]),
|
|
|
|
new Map([['key2', 'value2']]),
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// OK
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(123n, 123n);
|
|
|
|
// OK
|
|
|
|
|
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
[1, 2, 3, 4, 5, 6, 7, 8, 9],
|
|
|
|
[5, 4, 8],
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// AssertionError
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
{ a: 1 },
|
|
|
|
{ a: 1, b: 2 },
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// AssertionError
|
|
|
|
|
2025-03-07 14:18:55 +01:00
|
|
|
assert.partialDeepStrictEqual(
|
|
|
|
{ a: { b: 2 } },
|
|
|
|
{ a: { b: '2' } },
|
|
|
|
);
|
2024-11-23 18:45:49 +01:00
|
|
|
// AssertionError
|
|
|
|
```
|
|
|
|
|
2020-09-17 18:53:37 +02:00
|
|
|
[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
|
2022-01-07 20:00:55 -08:00
|
|
|
[`!=` operator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Inequality
|
2022-01-10 02:13:23 -08:00
|
|
|
[`===` operator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality
|
2022-01-07 20:00:55 -08:00
|
|
|
[`==` operator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Equality
|
2021-07-04 20:39:17 -07:00
|
|
|
[`AssertionError`]: #class-assertassertionerror
|
|
|
|
[`CallTracker`]: #class-assertcalltracker
|
2018-04-09 01:31:59 +02:00
|
|
|
[`Class`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes
|
2021-07-04 20:39:17 -07:00
|
|
|
[`ERR_INVALID_RETURN_VALUE`]: errors.md#err_invalid_return_value
|
|
|
|
[`Error.captureStackTrace`]: errors.md#errorcapturestacktracetargetobject-constructoropt
|
2017-05-08 09:30:13 -07:00
|
|
|
[`Object.is()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is
|
2021-07-04 20:39:17 -07:00
|
|
|
[`assert.deepEqual()`]: #assertdeepequalactual-expected-message
|
|
|
|
[`assert.deepStrictEqual()`]: #assertdeepstrictequalactual-expected-message
|
|
|
|
[`assert.doesNotThrow()`]: #assertdoesnotthrowfn-error-message
|
|
|
|
[`assert.equal()`]: #assertequalactual-expected-message
|
|
|
|
[`assert.notDeepEqual()`]: #assertnotdeepequalactual-expected-message
|
|
|
|
[`assert.notDeepStrictEqual()`]: #assertnotdeepstrictequalactual-expected-message
|
|
|
|
[`assert.notEqual()`]: #assertnotequalactual-expected-message
|
|
|
|
[`assert.notStrictEqual()`]: #assertnotstrictequalactual-expected-message
|
|
|
|
[`assert.ok()`]: #assertokvalue-message
|
|
|
|
[`assert.strictEqual()`]: #assertstrictequalactual-expected-message
|
|
|
|
[`assert.throws()`]: #assertthrowsfn-error-message
|
|
|
|
[`getColorDepth()`]: tty.md#writestreamgetcolordepthenv
|
2023-04-29 09:57:08 +03:00
|
|
|
[`mock`]: test.md#mocking
|
2021-07-04 20:39:17 -07:00
|
|
|
[`process.on('exit')`]: process.md#event-exit
|
|
|
|
[`tracker.calls()`]: #trackercallsfn-exact
|
|
|
|
[`tracker.verify()`]: #trackerverify
|
2017-02-01 03:51:54 +08:00
|
|
|
[enumerable "own" properties]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties
|
2017-05-08 09:30:13 -07:00
|
|
|
[prototype-spec]: https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots
|