Skip to content

assert: allow printf-style messages as assertion error #58849

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Oct 17, 2025
+433 −77
Merged

assert: allow printf-style messages as assertion error #58849

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
591a6e3
assert: allow printf-style messages as assertion error
BridgeAR Jun 26, 2025
32e43c2
fixup!
BridgeAR Oct 6, 2025
a41a7a5
fixup!
BridgeAR Oct 6, 2025
7dea1a2
fixup!
BridgeAR Oct 7, 2025
67d2b7b
fixup! add more tests
BridgeAR Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 97 additions & 13 deletions doc/api/assert.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,27 @@ strict methods. For example, [`assert.deepEqual()`][] will behave like
In strict assertion mode, error messages for objects display a diff. In legacy
assertion mode, error messages for objects display the objects, often truncated.

### Message parameter semantics

For assertion methods that accept an optional `message` parameter, the message
may be provided in one of the following forms:

* **string**: Used as-is. If additional arguments are supplied after the
`message` string, they are treated as printf-like substitutions (see
[`util.format()`][]).
* **Error**: If an `Error` instance is provided as `message`, that error is
thrown directly instead of an `AssertionError`.
* **function**: A function of the form `(actual, expected) => string`. It is
called only when the assertion fails and should return a string to be used as
the error message. Non-string return values are ignored and the default
message is used instead.

If additional arguments are passed along with an `Error` or a function as
`message`, the call is rejected with `ERR_AMBIGUOUS_ARGUMENT`.

If the first item is neither a string, `Error`, nor function, `ERR_INVALID_ARG_TYPE`
is thrown.

To use strict assertion mode:

```mjs
Expand Down Expand Up @@ -305,10 +326,14 @@ destructuring and call methods directly on the instance.

<!-- YAML
added: v0.5.9
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/58849
description: Message may now be a `printf`-like format string or function.
-->

* `value` {any} The input that is checked for being truthy.
* `message` {string|Error}
* `message` {string|Error|Function}

An alias of [`assert.ok()`][].

Expand All @@ -324,6 +349,9 @@ changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/57627
description: Invalid dates are now considered equal.
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/58849
description: Message may now be a `printf`-like format string or function.
- version: v24.0.0
pr-url: https://github.com/nodejs/node/pull/57622
description: Recursion now stops when either side encounters a circular
Expand Down Expand Up @@ -375,7 +403,7 @@ changes:

* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {string|Error|Function}

**Strict assertion mode**

Expand Down Expand Up @@ -524,6 +552,9 @@ changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/57627
description: Invalid dates are now considered equal.
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/58849
description: Message may now be a `printf`-like format string or function.
- version: v24.0.0
pr-url: https://github.com/nodejs/node/pull/57622
description: Recursion now stops when either side encounters a circular
Expand Down Expand Up @@ -567,7 +598,7 @@ changes:

* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {string|Error|Function}

Tests for deep equality between the `actual` and `expected` parameters.
"Deep" equality means that the enumerable "own" properties of child objects
Expand Down Expand Up @@ -829,14 +860,17 @@ added:
- v13.6.0
- v12.16.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/58849
description: Message may now be a `printf`-like format string or function.
- version: v16.0.0
pr-url: https://github.com/nodejs/node/pull/38111
description: This API is no longer experimental.
-->

* `string` {string}
* `regexp` {RegExp}
* `message` {string|Error}
* `message` {string|Error|Function}

Expects the `string` input not to match the regular expression.

Expand Down Expand Up @@ -1069,6 +1103,9 @@ assert.doesNotThrow(
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/58849
description: Message may now be a `printf`-like format string or function.
- version:
- v16.0.0
- v14.18.0
Expand All @@ -1083,7 +1120,7 @@ changes:

* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {string|Error|Function}

**Strict assertion mode**

Expand Down Expand Up @@ -1254,14 +1291,17 @@ added:
- v13.6.0
- v12.16.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/58849
description: Message may now be a `printf`-like format string or function.
- version: v16.0.0
pr-url: https://github.com/nodejs/node/pull/38111
description: This API is no longer experimental.
-->

* `string` {string}
* `regexp` {RegExp}
* `message` {string|Error}
* `message` {string|Error|Function}

Expects the `string` input to match the regular expression.

Expand Down Expand Up @@ -1303,6 +1343,9 @@ instance of {Error} then it will be thrown instead of the
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/58849
description: Message may now be a `printf`-like format string or function.
- version:
- v16.0.0
- v14.18.0
Expand Down Expand Up @@ -1338,7 +1381,7 @@ changes:

* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {string|Error|Function}

**Strict assertion mode**

Expand Down Expand Up @@ -1427,6 +1470,9 @@ instead of the `AssertionError`.
<!-- YAML
added: v1.2.0
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/58849
description: Message may now be a `printf`-like format string or function.
- version: v9.0.0
pr-url: https://github.com/nodejs/node/pull/15398
description: The `-0` and `+0` are not considered equal anymore.
Expand Down Expand Up @@ -1458,7 +1504,7 @@ changes:

* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {string|Error|Function}

Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][].

Expand Down Expand Up @@ -1487,6 +1533,9 @@ instead of the [`AssertionError`][].
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/58849
description: Message may now be a `printf`-like format string or function.
- version:
- v16.0.0
- v14.18.0
Expand All @@ -1501,7 +1550,7 @@ changes:

* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {string|Error|Function}

**Strict assertion mode**

Expand Down Expand Up @@ -1551,14 +1600,17 @@ parameter is an instance of {Error} then it will be thrown instead of the
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/58849
description: Message may now be a `printf`-like format string or function.
- version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/17003
description: Used comparison changed from Strict Equality to `Object.is()`.
-->

* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {string|Error|Function}

Tests strict inequality between the `actual` and `expected` parameters as
determined by [`Object.is()`][].
Expand Down Expand Up @@ -1604,14 +1656,17 @@ instead of the `AssertionError`.
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/58849
description: Message may now be a `printf`-like format string or function.
- version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/18319
description: The `assert.ok()` (no arguments) will now use a predefined
error message.
-->

* `value` {any}
* `message` {string|Error}
* `message` {string|Error|Function}

Tests if `value` is truthy. It is equivalent to
`assert.equal(!!value, true, message)`.
Expand Down Expand Up @@ -1844,14 +1899,24 @@ argument gets considered.
<!-- YAML
added: v0.1.21
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/58849
description: Message may now be a `printf`-like format string or function.
- version: v10.0.0
pr-url: https://github.com/nodejs/node/pull/17003
description: Used comparison changed from Strict Equality to `Object.is()`.
-->

* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {string|Error|Function} Postfix `printf`-like arguments in case
it's used as format string.
If message is a function, it is called in case of a comparison failure. The
function receives the `actual` and `expected` arguments and has to return a
string that is going to be used as error message.
`printf`-like format strings and functions are beneficial for performance
reasons in case arguments are passed through. In addition, it allows nice
formatting with ease.

Tests strict equality between the `actual` and `expected` parameters as
determined by [`Object.is()`][].
Expand Down Expand Up @@ -1880,8 +1945,17 @@ const oranges = 2;
assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`);
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2

assert.strictEqual(apples, oranges, 'apples %s !== oranges %s', apples, oranges);
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2

assert.strictEqual(1, '1', new TypeError('Inputs are not identical'));
// TypeError: Inputs are not identical

assert.strictEqual(apples, oranges, (actual, expected) => {
// Do 'heavy' computations
return `I expected ${expected} but I got ${actual}`;
});
// AssertionError [ERR_ASSERTION]: I expected oranges but I got apples
```

```cjs
Expand All @@ -1908,8 +1982,17 @@ const oranges = 2;
assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`);
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2

assert.strictEqual(apples, oranges, 'apples %s !== oranges %s', apples, oranges);
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2

assert.strictEqual(1, '1', new TypeError('Inputs are not identical'));
// TypeError: Inputs are not identical

assert.strictEqual(apples, oranges, (actual, expected) => {
// Do 'heavy' computations
return `I expected ${expected} but I got ${actual}`;
});
// AssertionError [ERR_ASSERTION]: I expected oranges but I got apples
```

If the values are not strictly equal, an [`AssertionError`][] is thrown with a
Expand Down Expand Up @@ -2295,7 +2378,7 @@ changes:

* `actual` {any}
* `expected` {any}
* `message` {string|Error}
* `message` {string|Error|Function}

Tests for partial deep equality between the `actual` and `expected` parameters.
"Deep" equality means that the enumerable "own" properties of child objects
Expand Down Expand Up @@ -2460,5 +2543,6 @@ assert.partialDeepStrictEqual(
[`assert.strictEqual()`]: #assertstrictequalactual-expected-message
[`assert.throws()`]: #assertthrowsfn-error-message
[`getColorDepth()`]: tty.md#writestreamgetcolordepthenv
[`util.format()`]: util.md#utilformatformat-args
[enumerable "own" properties]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties
[prototype-spec]: https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots
Loading
Loading