fixup! additional types, docs, and tests

BridgeAR · BridgeAR · commit ae6214e1bdd0 · 2025-09-12T00:57:04.000+02:00
diff --git a/doc/api/assert.md b/doc/api/assert.md
@@ -268,10 +268,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()`][].
 
@@ -287,6 +291,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
@@ -338,7 +345,7 @@ changes:
 
 * `actual` {any}
 * `expected` {any}
-* `message` {string|Error}
+* `message` {string|Error|Function}
 
 **Strict assertion mode**
 
@@ -487,6 +494,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
@@ -530,7 +540,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
@@ -792,14 +802,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.
 
@@ -1032,6 +1045,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
@@ -1046,7 +1062,7 @@ changes:
 
 * `actual` {any}
 * `expected` {any}
-* `message` {string|Error}
+* `message` {string|Error|Function}
 
 **Strict assertion mode**
 
@@ -1217,14 +1233,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.
 
@@ -1266,6 +1285,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
@@ -1301,7 +1323,7 @@ changes:
 
 * `actual` {any}
 * `expected` {any}
-* `message` {string|Error}
+* `message` {string|Error|Function}
 
 **Strict assertion mode**
 
@@ -1390,6 +1412,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.
@@ -1421,7 +1446,7 @@ changes:
 
 * `actual` {any}
 * `expected` {any}
-* `message` {string|Error}
+* `message` {string|Error|Function}
 
 Tests for deep strict inequality. Opposite of [`assert.deepStrictEqual()`][].
 
@@ -1450,6 +1475,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
@@ -1464,7 +1492,7 @@ changes:
 
 * `actual` {any}
 * `expected` {any}
-* `message` {string|Error}
+* `message` {string|Error|Function}
 
 **Strict assertion mode**
 
@@ -1514,14 +1542,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()`][].
@@ -1567,14 +1598,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)`.
@@ -1808,7 +1842,7 @@ argument gets considered.
 added: v0.1.21
 changes:
   - version: REPLACEME
-    pr-url: https://github.com/nodejs/node/pull/XXXXX
+    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
@@ -1859,11 +1893,11 @@ assert.strictEqual(apples, oranges, 'apples %s !== oranges %s', apples, oranges)
 assert.strictEqual(1, '1', new TypeError('Inputs are not identical'));
 // TypeError: Inputs are not identical
 
-assert.strictEqual(apples, oranges, () => {
+assert.strictEqual(apples, oranges, (actual, expected) => {
   // Do 'heavy' computations
-  return 'My error string';
+  return `I expected ${expected} but I got ${actual}`;
 });
-// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2
+// AssertionError [ERR_ASSERTION]: I expected oranges but I got apples
 ```
 
 ```cjs
@@ -1890,8 +1924,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
diff --git a/lib/assert.js b/lib/assert.js
@@ -248,7 +248,7 @@ Assert.prototype.ok = function ok(...args) {
  * The equality assertion tests shallow, coercive equality with ==.
  * @param {any} actual
  * @param {any} expected
- * @param {string | Error} [message]
+ * @param {string | Error | Function} [message]
  * @returns {void}
  */
 Assert.prototype.equal = function equal(actual, expected, ...message) {
@@ -273,7 +273,7 @@ Assert.prototype.equal = function equal(actual, expected, ...message) {
  * equal with !=.
  * @param {any} actual
  * @param {any} expected
- * @param {string | Error} [message]
+ * @param {string | Error | Function} [message]
  * @returns {void}
  */
 Assert.prototype.notEqual = function notEqual(actual, expected, ...message) {
@@ -297,7 +297,7 @@ Assert.prototype.notEqual = function notEqual(actual, expected, ...message) {
  * The deep equivalence assertion tests a deep equality relation.
  * @param {any} actual
  * @param {any} expected
- * @param {string | Error} [message]
+ * @param {string | Error | Function} [message]
  * @returns {void}
  */
 Assert.prototype.deepEqual = function deepEqual(actual, expected, ...message) {
@@ -321,7 +321,7 @@ Assert.prototype.deepEqual = function deepEqual(actual, expected, ...message) {
  * The deep non-equivalence assertion tests for any deep inequality.
  * @param {any} actual
  * @param {any} expected
- * @param {string | Error} [message]
+ * @param {string | Error | Function} [message]
  * @returns {void}
  */
 Assert.prototype.notDeepEqual = function notDeepEqual(actual, expected, ...message) {
@@ -346,7 +346,7 @@ Assert.prototype.notDeepEqual = function notDeepEqual(actual, expected, ...messa
  * relation.
  * @param {any} actual
  * @param {any} expected
- * @param {string | Error} [message]
+ * @param {string | Error | Function} [message]
  * @returns {void}
  */
 Assert.prototype.deepStrictEqual = function deepStrictEqual(actual, expected, ...message) {
@@ -371,7 +371,7 @@ Assert.prototype.deepStrictEqual = function deepStrictEqual(actual, expected, ..
  * inequality.
  * @param {any} actual
  * @param {any} expected
- * @param {string | Error} [message]
+ * @param {string | Error | Function} [message]
  * @returns {void}
  */
 Assert.prototype.notDeepStrictEqual = notDeepStrictEqual;
@@ -396,7 +396,7 @@ function notDeepStrictEqual(actual, expected, ...message) {
  * The strict equivalence assertion tests a strict equality relation.
  * @param {any} actual
  * @param {any} expected
- * @param {string | Error} [message]
+ * @param {string | Error | Function} [message]
  * @returns {void}
  */
 Assert.prototype.strictEqual = function strictEqual(actual, expected, ...message) {
@@ -419,7 +419,7 @@ Assert.prototype.strictEqual = function strictEqual(actual, expected, ...message
  * The strict non-equivalence assertion tests for any strict inequality.
  * @param {any} actual
  * @param {any} expected
- * @param {string | Error} [message]
+ * @param {string | Error | Function} [message]
  * @returns {void}
  */
 Assert.prototype.notStrictEqual = function notStrictEqual(actual, expected, ...message) {
@@ -442,7 +442,7 @@ Assert.prototype.notStrictEqual = function notStrictEqual(actual, expected, ...m
  * The strict equivalence assertion test between two objects
  * @param {any} actual
  * @param {any} expected
- * @param {string | Error} [message]
+ * @param {string | Error | Function} [message]
  * @returns {void}
  */
 Assert.prototype.partialDeepStrictEqual = function partialDeepStrictEqual(
@@ -902,7 +902,7 @@ function internalMatch(string, regexp, message, fn) {
  * Expects the `string` input to match the regular expression.
  * @param {string} string
  * @param {RegExp} regexp
- * @param {string | Error} [message]
+ * @param {string | Error | Function} [message]
  * @returns {void}
  */
 Assert.prototype.match = function match(string, regexp, ...message) {
@@ -913,7 +913,7 @@ Assert.prototype.match = function match(string, regexp, ...message) {
  * Expects the `string` input not to match the regular expression.
  * @param {string} string
  * @param {RegExp} regexp
- * @param {string | Error} [message]
+ * @param {string | Error | Function} [message]
  * @returns {void}
  */
 Assert.prototype.doesNotMatch = function doesNotMatch(string, regexp, ...message) {
diff --git a/test/parallel/test-assert.js b/test/parallel/test-assert.js
@@ -1738,5 +1738,27 @@ test('Ambiguous error messages fail', () => {
   );
 });
 
+test('Functions as error message', () => {
+  function errorMessage(actual, expected) {
+    return `Nice message including ${actual} and ${expected}`;
+  }
+
+  assert.throws(
+    () => assert.equal('foo', 'bar', errorMessage),
+    {
+      code: 'ERR_ASSERTION',
+      message: /Nice message including foo and bar/
+    }
+  );
+
+  assert.throws(
+    () => assert.doesNotMatch('foo', /foo/, errorMessage),
+    {
+      code: 'ERR_ASSERTION',
+      message: /Nice message including foo and \/foo\//
+    }
+  );
+});
+
 /* eslint-enable no-restricted-syntax */
 /* eslint-enable no-restricted-properties */
