Add a description with the reason why a test is pending

lib/context.js

@@ -80,9 +80,10 @@ Context.prototype.slow = function(ms) {
  *
  * @api private
  * @throws Pending
+ * @param {string} reason
  */
-Context.prototype.skip = function() {
-  this.runnable().skip();
+Context.prototype.skip = function(reason) {
+  this.runnable().skip(reason);
 };
 
 /**

lib/reporters/json.js

@@ -73,18 +73,25 @@ function JSONReporter(runner) {
  * @return {Object}
  */
 function clean(test) {
+  var res;
   var err = test.err || {};
   if (err instanceof Error) {
     err = errorJSON(err);
   }
 
-  return {
+  res = {
     title: test.title,
     fullTitle: test.fullTitle(),
     duration: test.duration,
     currentRetry: test.currentRetry(),
     err: cleanCycles(err)
   };
+
+  if (test.reason) {
+    res.reason = test.reason;
+  }
+
+  return res;
 }
 
 /**

lib/reporters/spec.js

@@ -55,7 +55,10 @@ function Spec(runner) {
 
   runner.on('pending', function(test) {
     var fmt = indent() + color('pending', '  - %s');
-    console.log(fmt, test.title);
+    console.log(
+      fmt,
+      test.title + (test.reason ? ' (' + test.reason + ')' : '')
+    );
   });
 
   runner.on('pass', function(test) {

lib/runnable.js

@@ -116,9 +116,14 @@ Runnable.prototype.enableTimeouts = function(enabled) {
  * @memberof Mocha.Runnable
  * @public
  * @api public
+ * @param {string} reason - Reason the Runnable is being skipped.
  */
-Runnable.prototype.skip = function() {
-  throw new Pending('sync skip');
+Runnable.prototype.skip = function(reason) {
+  if (arguments.length > 0) {
+    reason = String(reason);
+    this.reason = reason;
+  }
+  throw new Pending(reason || 'sync skip');
 };
 
 /**

test/integration/fixtures/pending/skip-with-reason.fixture.js

@@ -0,0 +1,12 @@
+'use strict';
+
+describe('skip in test with reason', function () {
+  it('should skip immediately with reason', function () {
+    this.skip('skip reason');
+    throw new Error('never thrown');
+  });
+
+  it('should run other tests in the suite', function () {
+    // Do nothing
+  });
+});

test/integration/pending.spec.js

@@ -64,6 +64,21 @@ describe('pending', function() {
           done();
         });
       });
+
+      it('should allow a skip reason', function(done) {
+        run('pending/skip-with-reason.fixture.js', args, function(err, res) {
+          if (err) {
+            done(err);
+            return;
+          }
+          assert.equal(res.stats.pending, 1);
+          assert.equal(res.stats.passes, 1);
+          assert.equal(res.stats.failures, 0);
+          assert.equal(res.code, 0);
+          assert.equal(res.pending[0].reason, 'skip reason');
+          done();
+        });
+      });
     });
 
     describe('in before', function() {

test/reporters/spec.spec.js

@@ -12,6 +12,7 @@ describe('Spec reporter', function() {
   var runner;
   var useColors;
   var expectedTitle = 'expectedTitle';
+  var expectedReason = 'expected reason';
 
   beforeEach(function() {
     stdout = [];
@@ -52,6 +53,19 @@ describe('Spec reporter', function() {
       var expectedArray = ['  - ' + expectedTitle + '\n'];
       expect(stdout, 'to equal', expectedArray);
     });
+    it('should return title and reason', function() {
+      var suite = {
+        title: expectedTitle,
+        reason: expectedReason
+      };
+      runner = createMockRunner('pending test', 'pending', null, null, suite);
+      Spec.call({epilogue: function() {}}, runner);
+      process.stdout.write = stdoutWrite;
+      var expectedArray = [
+        '  - ' + expectedTitle + ' (' + expectedReason + ')' + '\n'
+      ];
+      expect(stdout, 'to equal', expectedArray);
+    });
   });
   describe('on pass', function() {
     describe('if test speed is slow', function() {

test/reporters/xunit.spec.js

@@ -20,6 +20,7 @@ describe('XUnit reporter', function() {
   var expectedMessage = 'some message';
   var expectedStack = 'some-stack';
   var expectedWrite = null;
+  var expectedReason = 'some reason';
 
   beforeEach(function() {
     stdout = [];
@@ -255,7 +256,8 @@ describe('XUnit reporter', function() {
               return expectedClassName;
             }
           },
-          duration: 1000
+          duration: 1000,
+          reason: expectedReason
         };
         xunit.test.call(
           {