From 4917d8cfef828b77bdd8f15cb4cdb7f5ee6babb3 Mon Sep 17 00:00:00 2001
From: Rich Trott <rtrott@gmail.com>
Date: Sun, 9 Apr 2017 10:36:14 -0700
Subject: [PATCH] assert: improve assert.fail() API
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

assert.fail() has two possible function signatures, both of which are
not intuitive. It virtually guarantees that people who try to use
assert.fail() without carefully reading the docs will end up using it
incorrectly.

This change maintains backwards compatibility with the two valid uses
(arguments 1 2 and 4 supplied but argument 3 falsy, and argument 3
supplied but arguments 1 2 and 4 all falsy) but also adds the far more
intuitive first-argument-only and first-two-arguments-only
possibilities.

assert.fail('boom');
// AssertionError: boom

assert.fail('a', 'b');
// AssertionError: 'a' != 'b'

Backport-PR-URL: https://github.com/nodejs/node/pull/15479
PR-URL: https://github.com/nodejs/node/pull/12293
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 doc/api/assert.md                 |  9 ++++++++-
 lib/assert.js                     |  4 ++++
 test/parallel/test-assert-fail.js | 30 ++++++++++++++++++++++++++++++
 3 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/doc/api/assert.md b/doc/api/assert.md
index a0eb8d7a4a..b742e69d7f 100644
--- a/doc/api/assert.md
+++ b/doc/api/assert.md
@@ -194,6 +194,7 @@ If the values are not equal, an `AssertionError` is thrown with a `message`
 property set equal to the value of the `message` parameter. If the `message`
 parameter is undefined, a default error message is assigned.
 
+## assert.fail(message)
 ## assert.fail(actual, expected[, message[, operator[, stackStartFunction]]])
 <!-- YAML
 added: v0.1.21
@@ -201,7 +202,7 @@ added: v0.1.21
 * `actual` {any}
 * `expected` {any}
 * `message` {any}
-* `operator` {string}
+* `operator` {string} (default: '!=')
 * `stackStartFunction` {function} (default: `assert.fail`)
 
 Throws an `AssertionError`. If `message` is falsy, the error message is set as
@@ -221,6 +222,12 @@ assert.fail(1, 2, 'fail');
 
 assert.fail(1, 2, 'whoops', '>');
 // AssertionError: whoops
+
+assert.fail('boom');
+// AssertionError: boom
+
+assert.fail('a', 'b');
+// AssertionError: 'a' != 'b'
 ```
 
 Example use of `stackStartFunction` for truncating the exception's stacktrace:
diff --git a/lib/assert.js b/lib/assert.js
index cfc7addbcb..6bb8bc2b1b 100644
--- a/lib/assert.js
+++ b/lib/assert.js
@@ -77,6 +77,10 @@ function getMessage(self) {
 // display purposes.
 
 function fail(actual, expected, message, operator, stackStartFunction) {
+  if (arguments.length === 1)
+    message = actual;
+  if (arguments.length === 2)
+    operator = '!=';
   throw new assert.AssertionError({
     message: message,
     actual: actual,
diff --git a/test/parallel/test-assert-fail.js b/test/parallel/test-assert-fail.js
index 0423b35ec4..a64cfdb3ab 100644
--- a/test/parallel/test-assert-fail.js
+++ b/test/parallel/test-assert-fail.js
@@ -3,6 +3,36 @@
 require('../common');
 const assert = require('assert');
 
+// no args
+assert.throws(
+  () => { assert.fail(); },
+  /^AssertionError: undefined undefined undefined$/
+);
+
+// one arg = message
+assert.throws(
+  () => { assert.fail('custom message'); },
+  /^AssertionError: custom message$/
+);
+
+// two args only, operator defaults to '!='
+assert.throws(
+  () => { assert.fail('first', 'second'); },
+  /^AssertionError: 'first' != 'second'$/
+);
+
+// three args
+assert.throws(
+  () => { assert.fail('ignored', 'ignored', 'another custom message'); },
+  /^AssertionError: another custom message$/
+);
+
+// no third arg (but a fourth arg)
+assert.throws(
+  () => { assert.fail('first', 'second', undefined, 'operator'); },
+  /^AssertionError: 'first' operator 'second'$/
+);
+
 // The stackFrameFunction should exclude the foo frame
 assert.throws(
   function foo() { assert.fail('first', 'second', 'message', '!==', foo); },