diff --git a/doc/api/assert.md b/doc/api/assert.md index 32b462fbfc..7d384c215b 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -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 @@ -305,10 +326,14 @@ destructuring and call methods directly on the instance. * `value` {any} The input that is checked for being truthy. -* `message` {string|Error} +* `message` {string|Error|Function} An alias of [`assert.ok()`][]. @@ -324,6 +349,9 @@ changes: - version: v25.0.0 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 @@ -375,7 +403,7 @@ changes: * `actual` {any} * `expected` {any} -* `message` {string|Error} +* `message` {string|Error|Function} **Strict assertion mode** @@ -524,6 +552,9 @@ changes: - version: v25.0.0 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 @@ -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 @@ -829,6 +860,9 @@ 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. @@ -836,7 +870,7 @@ changes: * `string` {string} * `regexp` {RegExp} -* `message` {string|Error} +* `message` {string|Error|Function} Expects the `string` input not to match the regular expression. @@ -1069,6 +1103,9 @@ assert.doesNotThrow( * `value` {any} -* `message` {string|Error} +* `message` {string|Error|Function} Tests if `value` is truthy. It is equivalent to `assert.equal(!!value, true, message)`. @@ -1844,6 +1899,9 @@ argument gets considered.