assert: allow printf-style messages as assertion error

doc/api/assert.md

@@ -1748,14 +1748,22 @@
 <!-- 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 a function is used, the function is called. If
+  that function call fails, the default message is generated instead.
+  `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()`][].
@@ -1784,8 +1792,17 @@
 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

@@ -49,7 +49,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,
@@ -87,7 +87,25 @@ const NO_EXCEPTION_SENTINEL = {};
 // display purposes.
 
 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])) {
+    throw obj.message[0];
+  } else if (typeof obj.message[0] === 'function') {
+    obj.message = obj.message[0]();
+  } else {
+    throw new ERR_INVALID_ARG_TYPE(
+      'message',
+      ['string', 'function'],
+      obj.message[0],
+    );
+  }
 
   throw new AssertionError(obj);
 }
@@ -141,7 +159,7 @@ assert.ok = ok;
  * @returns {void}
  */
 /* eslint-disable no-restricted-properties */
-assert.equal = function equal(actual, expected, message) {
+assert.equal = function equal(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -165,7 +183,7 @@ assert.equal = function equal(actual, expected, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-assert.notEqual = function notEqual(actual, expected, message) {
+assert.notEqual = function notEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -188,7 +206,7 @@ assert.notEqual = function notEqual(actual, expected, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-assert.deepEqual = function deepEqual(actual, expected, message) {
+assert.deepEqual = function deepEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -211,7 +229,7 @@ assert.deepEqual = function deepEqual(actual, expected, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-assert.notDeepEqual = function notDeepEqual(actual, expected, message) {
+assert.notDeepEqual = function notDeepEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -236,7 +254,7 @@ assert.notDeepEqual = function notDeepEqual(actual, expected, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-assert.deepStrictEqual = function deepStrictEqual(actual, expected, message) {
+assert.deepStrictEqual = function deepStrictEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -261,7 +279,7 @@ assert.deepStrictEqual = function deepStrictEqual(actual, expected, message) {
  * @returns {void}
  */
 assert.notDeepStrictEqual = notDeepStrictEqual;
-function notDeepStrictEqual(actual, expected, message) {
+function notDeepStrictEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -284,7 +302,7 @@ function notDeepStrictEqual(actual, expected, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-assert.strictEqual = function strictEqual(actual, expected, message) {
+assert.strictEqual = function strictEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -306,7 +324,7 @@ assert.strictEqual = function strictEqual(actual, expected, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-assert.notStrictEqual = function notStrictEqual(actual, expected, message) {
+assert.notStrictEqual = function notStrictEqual(actual, expected, ...message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
   }
@@ -331,7 +349,7 @@ assert.notStrictEqual = function notStrictEqual(actual, expected, message) {
 assert.partialDeepStrictEqual = function partialDeepStrictEqual(
   actual,
   expected,
-  message,
+  ...message,
 ) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
@@ -783,7 +801,7 @@ function internalMatch(string, regexp, message, fn) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-assert.match = function match(string, regexp, message) {
+assert.match = function match(string, regexp, ...message) {
   internalMatch(string, regexp, message, match);
 };
 
@@ -794,7 +812,7 @@ assert.match = function match(string, regexp, message) {
  * @param {string | Error} [message]
  * @returns {void}
  */
-assert.doesNotMatch = function doesNotMatch(string, regexp, message) {
+assert.doesNotMatch = function doesNotMatch(string, regexp, ...message) {
   internalMatch(string, regexp, message, doesNotMatch);
 };