assert: deprecate assert.fail partially

Using `assert.fail()` with more than one argument is not intuitive
to use and has no benefit over using a message on its own.

Therefore this introduces a runtime deprecation in case it is used
in that way.

PR-URL: https://github.com/nodejs/node/pull/18418
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anatoli Papirovski <apapirovski@mac.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

1 files changed, 47 insertions, 23 deletions

diff --git a/doc/api/assert.md b/doc/api/assert.md
index dc9a902695..7bade14184 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -415,30 +415,64 @@ parameter is an instance of an [`Error`][] then it will be thrown instead of the
 `AssertionError`.
 
 ## assert.fail([message])
+<!-- YAML
+added: v0.1.21
+-->
+* `message` {any} **Default:** `'Failed'`
+
+Throws an `AssertionError` with the provided error message or a default error
+message. If the `message` parameter is an instance of an [`Error`][] then it
+will be thrown instead of the `AssertionError`.
+
+```js
+const assert = require('assert').strict;
+
+assert.fail();
+// AssertionError [ERR_ASSERTION]: Failed
+
+assert.fail('boom');
+// AssertionError [ERR_ASSERTION]: boom
+
+assert.fail(new TypeError('need array'));
+// TypeError: need array
+```
+
+Using `assert.fail()` with more than two arguments is possible but deprecated.
+See below for further details.
+
 ## assert.fail(actual, expected[, message[, operator[, stackStartFunction]]])
 <!-- YAML
 added: v0.1.21
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/REPLACEME
+    description: Calling `assert.fail` with more than one argument is deprecated
+                 and emits a warning.
 -->
 * `actual` {any}
 * `expected` {any}
-* `message` {any} **Default:** `'Failed'`
+* `message` {any}
 * `operator` {string} **Default:** '!='
 * `stackStartFunction` {Function} **Default:** `assert.fail`
 
-Throws an `AssertionError`. If `message` is falsy, the error message is set as
-the values of `actual` and `expected` separated by the provided `operator`. If
-the `message` parameter is an instance of an [`Error`][] then it will be thrown
-instead of the `AssertionError`. If just the two `actual` and `expected`
-arguments are provided, `operator` will default to `'!='`. If `message` is
-provided only it will be used as the error message, the other arguments will be
-stored as properties on the thrown object. If `stackStartFunction` is provided,
-all stack frames above that function will be removed from stacktrace (see
-[`Error.captureStackTrace`]). If no arguments are given, the default message
-`Failed` will be used.
+> Stability: 0 - Deprecated: Use `assert.fail([message])` or other assert
+> functions instead.
+
+If `message` is falsy, the error message is set as the values of `actual` and
+`expected` separated by the provided `operator`. If just the two `actual` and
+`expected` arguments are provided, `operator` will default to `'!='`. If
+`message` is provided as third argument it will be used as the error message and
+the other arguments will be stored as properties on the thrown object. If
+`stackStartFunction` is provided, all stack frames above that function will be
+removed from stacktrace (see [`Error.captureStackTrace`]). If no arguments are
+given, the default message `Failed` will be used.
 
 ```js
 const assert = require('assert').strict;
 
+assert.fail('a', 'b');
+// AssertionError [ERR_ASSERTION]: 'a' != 'b'
+
 assert.fail(1, 2, undefined, '>');
 // AssertionError [ERR_ASSERTION]: 1 > 2
 
@@ -452,21 +486,11 @@ assert.fail(1, 2, new TypeError('need array'));
 // TypeError: need array
 ```
 
-*Note*: In the last two cases `actual`, `expected`, and `operator` have no
+In the last three cases `actual`, `expected`, and `operator` have no
 influence on the error message.
 
-```js
-assert.fail();
-// AssertionError [ERR_ASSERTION]: Failed
-
-assert.fail('boom');
-// AssertionError [ERR_ASSERTION]: boom
-
-assert.fail('a', 'b');
-// AssertionError [ERR_ASSERTION]: 'a' != 'b'
-```
-
 Example use of `stackStartFunction` for truncating the exception's stacktrace:
+
 ```js
 function suppressFrame() {
   assert.fail('a', 'b', undefined, '!==', suppressFrame);