Fail when test resolution method is overspecified

Users may register `Runnable`s as asynchronous in one of two ways:

- Via callback (by defining the body function to have an arity of one)
- Via promise (by returning a Promise object from the body function)

When both a callback function is specified *and* a Promise object is
returned, the `Runnable`'s resolution condition is ambiguous.
Practically speaking, users are most likely to make this mistake as they
transition between asynchronous styles.

Currently, Mocha silently prefers the callback amd ignores the Promise
object. Update the implementation of the `Runnable` class to fail
immediately when the test resolution method is over-specified in this
way.

lib/runnable.js

@@ -350,7 +350,7 @@ Runnable.prototype.run = function(fn) {
   }
 
   function callFnAsync(fn) {
-    fn.call(ctx, function(err) {
+    var result = fn.call(ctx, function(err) {
       if (err instanceof Error || toString.call(err) === '[object Error]') {
         return done(err);
       }
@@ -361,6 +361,10 @@ Runnable.prototype.run = function(fn) {
         }
         return done(new Error('done() invoked with non-Error: ' + err));
       }
+      if (result && utils.isPromise(result)) {
+        return done(new Error('Asynchronous resolution method is overspecified. Specify a callback *or* return a Promise, not both.'));
+      }
+
       done();
     });
   }

lib/utils.js

@@ -748,3 +748,13 @@ exports.stackTraceFilter = function() {
     return stack.join('\n');
   };
 };
+
+/**
+ * Crude, but effective.
+ * @api
+ * @param {*} value
+ * @returns {boolean} Whether or not `value` is a Promise
+ */
+exports.isPromise = function isPromise(value) {
+  return typeof value === 'object' && typeof value.then === 'function';
+};

test/acceptance/overspecified-async.js

@@ -0,0 +1,8 @@
+describe('overspecified asynchronous resolution method', function() {
+  it('should fail when multiple methods are used', function(done) {
+    setTimeout(done, 0);
+
+    // uncomment
+    // return { then: function() {} };
+  });
+});

test/utils.js

@@ -182,4 +182,18 @@ describe('utils', function() {
       });
     });
   });
+
+  describe('.isPromise', function() {
+    it('should return true if the value is Promise-ish', function() {
+      utils.isPromise({then: function() {}}).should.be.true;
+    });
+
+    it('should return false if the value is not an object', function() {
+      utils.isPromise(1).should.be.false;
+    });
+
+    it('should return false if the value is an object w/o a "then" function', function() {
+      utils.isPromise({}).should.be.false;
+    });
+  });
 });