assert: allow printf-style messages as assertion error

Also add functions as allowed message input.
This allows to have leavy message computation to become cheaper.

Author: BridgeAR

doc/api/assert.md

@@ -1807,14 +1807,24 @@ argument gets considered.
 <!-- YAML
 added: v0.1.21
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/XXXXX
+    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()`][].
@@ -1843,8 +1853,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, () => {
+  // Do 'heavy' computations
+  return 'My error string';
+});
+// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2
 ```
 
 ```cjs

lib/assert.js

@@ -27,6 +27,7 @@ const {
   ArrayPrototypePush,
   ArrayPrototypeSlice,
   Error,
+  ErrorPrototypeToString,
   NumberIsNaN,
   ObjectAssign,
   ObjectDefineProperty,
@@ -53,7 +54,7 @@ const {
   },
 } = require('internal/errors');
 const AssertionError = require('internal/assert/assertion_error');
-const { inspect } = require('internal/util/inspect');
+const { inspect, format } = require('internal/util/inspect');
 const {
   isPromise,
   isRegExp,
@@ -142,9 +143,51 @@ function Assert(options) {
 // instance's custom options.
 
 function innerFail(obj) {
-  if (obj.message instanceof Error) throw obj.message;
+  if (obj.message.length === 0) {
+    obj.message = undefined;
+  } else if (typeof obj.message[0] === 'string') {
+    if (obj.message.length > 1) {
+      obj.message = format(...obj.message);
+    } else {
+      obj.message = obj.message[0];
+    }
+  } else if (isError(obj.message[0])) {
+    if (obj.message.length > 1) {
+      throw new ERR_AMBIGUOUS_ARGUMENT(
+        'message',
+        `The error message was passed as error object "${ErrorPrototypeToString(obj.message[0])}" has trailing arguments that would be ignored.`,
+      );
+    }
+    throw obj.message[0];
+  } else if (typeof obj.message[0] === 'function') {
+    if (obj.message.length > 1) {
+      throw new ERR_AMBIGUOUS_ARGUMENT(
+        'message',
+        `The error message with function "${obj.message[0].name || 'anonymous'}" has trailing arguments that would be ignored.`,
+      );
+    }
+    try {
+      obj.message = obj.message[0](obj.actual, obj.expected);
+      if (typeof obj.message !== 'string') {
+        obj.message = undefined;
+      }
+    } catch {
+      // Ignore and use default message instead
+      obj.message = undefined;
+    }
+  } else {
+    throw new ERR_INVALID_ARG_TYPE(
+      'message',
+      ['string', 'function'],
+      obj.message[0],
+    );
+  }
 
-  throw new AssertionError(obj);
+  const error = new AssertionError(obj);
+  if (obj.generatedMessage !== undefined) {
+    error.generatedMessage = obj.generatedMessage;
+  }
+  throw error;
 }
 
 /**
@@ -208,7 +251,7 @@ Assert.prototype.ok = function ok(...args) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-Assert.prototype.equal = function equal(actual, expected, message) {
+Assert.prototype.equal = function equal(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -233,7 +276,7 @@ Assert.prototype.equal = function equal(actual, expected, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-Assert.prototype.notEqual = function notEqual(actual, expected, message) {
+Assert.prototype.notEqual = function notEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -257,7 +300,7 @@ Assert.prototype.notEqual = function notEqual(actual, expected, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-Assert.prototype.deepEqual = function deepEqual(actual, expected, message) {
+Assert.prototype.deepEqual = function deepEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -281,7 +324,7 @@ Assert.prototype.deepEqual = function deepEqual(actual, expected, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-Assert.prototype.notDeepEqual = function notDeepEqual(actual, expected, message) {
+Assert.prototype.notDeepEqual = function notDeepEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -306,7 +349,7 @@ Assert.prototype.notDeepEqual = function notDeepEqual(actual, expected, message)
  * @param {string | Error} [message]
  * @returns {void}
  */
-Assert.prototype.deepStrictEqual = function deepStrictEqual(actual, expected, message) {
+Assert.prototype.deepStrictEqual = function deepStrictEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -332,7 +375,7 @@ Assert.prototype.deepStrictEqual = function deepStrictEqual(actual, expected, me
  * @returns {void}
  */
 Assert.prototype.notDeepStrictEqual = notDeepStrictEqual;
-function notDeepStrictEqual(actual, expected, message) {
+function notDeepStrictEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -356,7 +399,7 @@ function notDeepStrictEqual(actual, expected, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-Assert.prototype.strictEqual = function strictEqual(actual, expected, message) {
+Assert.prototype.strictEqual = function strictEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -379,7 +422,7 @@ Assert.prototype.strictEqual = function strictEqual(actual, expected, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-Assert.prototype.notStrictEqual = function notStrictEqual(actual, expected, message) {
+Assert.prototype.notStrictEqual = function notStrictEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -405,7 +448,7 @@ Assert.prototype.notStrictEqual = function notStrictEqual(actual, expected, mess
 Assert.prototype.partialDeepStrictEqual = function partialDeepStrictEqual(
   actual,
   expected,
-  message,
+  ...message
 ) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
@@ -462,7 +505,7 @@ function compareExceptionKey(actual, expected, key, message, keys, fn) {
     innerFail({
       actual,
       expected,
-      message,
+      message: [message],
       operator: fn.name,
       stackStartFn: fn,
       diff: this?.[kOptions]?.diff,
@@ -664,7 +707,7 @@ function expectsError(stackStartFn, actual, error, message) {
       actual: undefined,
       expected: error,
       operator: stackStartFn.name,
-      message: `Missing expected ${fnType}${details}`,
+      message: [`Missing expected ${fnType}${details}`],
       stackStartFn,
       diff: this?.[kOptions]?.diff,
     });
@@ -713,8 +756,8 @@ function expectsNoError(stackStartFn, actual, error, message) {
       actual,
       expected: error,
       operator: stackStartFn.name,
-      message: `Got unwanted ${fnType}${details}\n` +
-               `Actual message: "${actual?.message}"`,
+      message: [`Got unwanted ${fnType}${details}\n` +
+               `Actual message: "${actual?.message}"`],
       stackStartFn,
       diff: this?.[kOptions]?.diff,
     });
@@ -832,30 +875,26 @@ function internalMatch(string, regexp, message, fn) {
   const match = fn === Assert.prototype.match;
   if (typeof string !== 'string' ||
       RegExpPrototypeExec(regexp, string) !== null !== match) {
-    if (message instanceof Error) {
-      throw message;
-    }
 
-    const generatedMessage = !message;
+    const generatedMessage = message.length === 0;
 
     // 'The input was expected to not match the regular expression ' +
-    message ||= (typeof string !== 'string' ?
+    message[0] ||= (typeof string !== 'string' ?
       'The "string" argument must be of type string. Received type ' +
         `${typeof string} (${inspect(string)})` :
       (match ?
         'The input did not match the regular expression ' :
         'The input was expected to not match the regular expression ') +
           `${inspect(regexp)}. Input:\n\n${inspect(string)}\n`);
-    const err = new AssertionError({
+    innerFail({
       actual: string,
       expected: regexp,
       message,
       operator: fn.name,
       stackStartFn: fn,
       diff: this?.[kOptions]?.diff,
+      generatedMessage: generatedMessage,
     });
-    err.generatedMessage = generatedMessage;
-    throw err;
   }
 }
 
@@ -866,7 +905,7 @@ function internalMatch(string, regexp, message, fn) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-Assert.prototype.match = function match(string, regexp, message) {
+Assert.prototype.match = function match(string, regexp, ...message) {
   internalMatch(string, regexp, message, match);
 };
 
@@ -877,7 +916,7 @@ Assert.prototype.match = function match(string, regexp, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-Assert.prototype.doesNotMatch = function doesNotMatch(string, regexp, message) {
+Assert.prototype.doesNotMatch = function doesNotMatch(string, regexp, ...message) {
   internalMatch(string, regexp, message, doesNotMatch);
 };