From 8a987b4c8b7c45f5280e7e081fb3564e6e0880b7 Mon Sep 17 00:00:00 2001
From: Sylvain Leroux <sylvain@chicoree.fr>
Date: Fri, 5 Jan 2018 20:11:37 +0100
Subject: [PATCH] feat: Add the `.fail([message])` interface

Fix #1116.
The `assert.fail` interface should accept being called with
only 1 arguments to fail with a custom message.
---
 lib/chai/interface/assert.js | 15 +++++++++++++++
 lib/chai/interface/expect.js | 15 ++++++++++++++-
 lib/chai/interface/should.js | 14 ++++++++++++++
 test/assert.js               | 28 +++++++++++++++++++++++++++-
 test/expect.js               | 22 ++++++++++++++++++----
 test/should.js               | 22 ++++++++++++++++++----
 6 files changed, 106 insertions(+), 10 deletions(-)

diff --git a/lib/chai/interface/assert.js b/lib/chai/interface/assert.js
index 7772e2c4b..5f46c804c 100644
--- a/lib/chai/interface/assert.js
+++ b/lib/chai/interface/assert.js
@@ -41,10 +41,18 @@ module.exports = function (chai, util) {
   };
 
   /**
+   * ### .fail([message])
    * ### .fail(actual, expected, [message], [operator])
    *
    * Throw a failure. Node.js `assert` module-compatible.
    *
+   *     assert.fail();
+   *     assert.fail("custom error message");
+   *     assert.fail(1, 2);
+   *     assert.fail(1, 2, "custom error message");
+   *     assert.fail(1, 2, "custom error message", ">");
+   *     assert.fail(1, 2, undefined, ">");
+   *
    * @name fail
    * @param {Mixed} actual
    * @param {Mixed} expected
@@ -55,6 +63,13 @@ module.exports = function (chai, util) {
    */
 
   assert.fail = function (actual, expected, message, operator) {
+    if (arguments.length < 2) {
+        // Comply with Node's fail([message]) interface
+
+        message = actual;
+        actual = undefined;
+    }
+
     message = message || 'assert.fail()';
     throw new chai.AssertionError(message, {
         actual: actual
diff --git a/lib/chai/interface/expect.js b/lib/chai/interface/expect.js
index 8c34072fb..3c46c1a87 100644
--- a/lib/chai/interface/expect.js
+++ b/lib/chai/interface/expect.js
@@ -10,9 +10,17 @@ module.exports = function (chai, util) {
   };
 
   /**
+   * ### .fail([message])
    * ### .fail(actual, expected, [message], [operator])
    *
-   * Throw a failure.
+   * Throw a failure.   
+   *
+   *     expect.fail();
+   *     expect.fail("custom error message");
+   *     expect.fail(1, 2);
+   *     expect.fail(1, 2, "custom error message");
+   *     expect.fail(1, 2, "custom error message", ">");
+   *     expect.fail(1, 2, undefined, ">");
    *
    * @name fail
    * @param {Mixed} actual
@@ -24,6 +32,11 @@ module.exports = function (chai, util) {
    */
 
   chai.expect.fail = function (actual, expected, message, operator) {
+    if (arguments.length < 2) {
+        message = actual;
+        actual = undefined;
+    }
+
     message = message || 'expect.fail()';
     throw new chai.AssertionError(message, {
         actual: actual
diff --git a/lib/chai/interface/should.js b/lib/chai/interface/should.js
index d7525b955..5406e5e44 100644
--- a/lib/chai/interface/should.js
+++ b/lib/chai/interface/should.js
@@ -42,10 +42,19 @@ module.exports = function (chai, util) {
     var should = {};
 
     /**
+     * ### .fail([message])
      * ### .fail(actual, expected, [message], [operator])
      *
      * Throw a failure.
      *
+     *     should.fail();
+     *     should.fail("custom error message");
+     *     should.fail(1, 2);
+     *     should.fail(1, 2, "custom error message");
+     *     should.fail(1, 2, "custom error message", ">");
+     *     should.fail(1, 2, undefined, ">");
+     *
+     *
      * @name fail
      * @param {Mixed} actual
      * @param {Mixed} expected
@@ -56,6 +65,11 @@ module.exports = function (chai, util) {
      */
 
     should.fail = function (actual, expected, message, operator) {
+      if (arguments.length < 2) {
+          message = actual;
+          actual = undefined;
+      }
+
       message = message || 'should.fail()';
       throw new chai.AssertionError(message, {
           actual: actual
diff --git a/test/assert.js b/test/assert.js
index d23cb3709..354cbe34b 100644
--- a/test/assert.js
+++ b/test/assert.js
@@ -14,12 +14,38 @@ describe('assert', function () {
     }, "expected foo to equal `bar`");
   });
 
+  describe("fail", function() {
+    it('should accept a message as the 3rd argument', function () {
+      err(function() {
+        assert.fail(0, 1, 'this has failed');
+      }, /this has failed/);
+    });
+
+    it('should accept a message as the only argument', function () {
+      err(function() {
+        assert.fail('this has failed');
+      }, /this has failed/);
+    });
+
+    it('should produce a default message when called without any arguments', function () {
+      err(function() {
+        assert.fail();
+      }, /assert\.fail()/);
+    });
+  });
+
   it('fail', function () {
     chai.expect(function () {
-      assert.fail(0, 1, 'this has failed');
+      assert.fail('this has failed');
     }).to.throw(chai.AssertionError, /this has failed/);
   });
 
+  it('fail', function () {
+    chai.expect(function () {
+      assert.fail();
+    }).to.throw(chai.AssertionError, /assert\.fail/);
+  });
+
   it('isTrue', function () {
     assert.isTrue(true);
 
diff --git a/test/expect.js b/test/expect.js
index dd16994a0..8d658f2ff 100644
--- a/test/expect.js
+++ b/test/expect.js
@@ -236,10 +236,24 @@ describe('expect', function () {
     , 'of', 'same', 'but', 'does' ].forEach(test);
   });
 
-  it('fail', function () {
-    err(function() {
-      expect.fail(0, 1, 'this has failed');
-    }, /this has failed/);
+  describe("fail", function() {
+    it('should accept a message as the 3rd argument', function () {
+      err(function() {
+        expect.fail(0, 1, 'this has failed');
+      }, /this has failed/);
+    });
+
+    it('should accept a message as the only argument', function () {
+      err(function() {
+        expect.fail('this has failed');
+      }, /this has failed/);
+    });
+
+    it('should produce a default message when called without any arguments', function () {
+      err(function() {
+        expect.fail();
+      }, /expect\.fail()/);
+    });
   });
 
   it('true', function(){
diff --git a/test/should.js b/test/should.js
index 2b62af318..1eb10a46f 100644
--- a/test/should.js
+++ b/test/should.js
@@ -233,10 +233,24 @@ describe('should', function() {
     , 'of', 'same', 'but', 'does' ].forEach(test);
   });
 
-  it('fail', function () {
-    err(function() {
-      should.fail(0, 1, 'this has failed');
-    }, 'this has failed');
+  describe("fail", function() {
+    it('should accept a message as the 3rd argument', function () {
+      err(function() {
+        should.fail(0, 1, 'this has failed');
+      }, /this has failed/);
+    });
+
+    it('should accept a message as the only argument', function () {
+      err(function() {
+        should.fail('this has failed');
+      }, /this has failed/);
+    });
+
+    it('should produce a default message when called without any arguments', function () {
+      err(function() {
+        should.fail();
+      }, /should\.fail()/);
+    });
   });
 
   it('root exist', function () {