Allow async tests to optionally pass a verify fn to done() to improve error reporting

lib/runnable.js

@@ -142,6 +142,14 @@ Runnable.prototype.run = function(fn){
     try {
       this.fn.call(ctx, function(err){
         if (err instanceof Error) return done(err);
+        if (typeof(err) === 'function') { // verify fn was provided to done
+          try {
+            err();
+            return done(); // if no exceptions, success
+          } catch (x) {
+            return done(x); // else call done with the exception
+          }
+        }
         if (null != err) return done(new Error('done() invoked with non-Error: ' + err));
         done();
       });

mocha.js

@@ -513,6 +513,11 @@ module.exports = function(suite){
 
   suite.on('pre-require', function(context){
 
+    // noop variants
+
+    context.xdescribe = function(){};
+    context.xit = function(){};
+
     /**
      * Execute before running tests.
      */
@@ -1422,6 +1427,153 @@ exports.XUnit = require('./xunit')
 
 }); // module: reporters/index.js
 
+require.register("reporters/jscoverage.js", function(module, exports, require){
+
+/**
+ * Module dependencies.
+ */
+
+var Base = require('./base');
+
+/**
+ * Expose `JSON` containing coverage data.
+ */
+
+exports = module.exports = JsCoverageReporter;
+
+/**
+ * Initialize a new `JsCoverage` reporter.
+ *
+ * @param {Runner} runner
+ * @api public
+ */
+
+function JsCoverageReporter(runner) {
+  var self = this;
+  Base.call(this, runner);
+
+  var tests = []
+    , failures = []
+    , passes = [];
+
+  runner.on('test end', function(test){
+    tests.push(test);
+  });
+
+  runner.on('pass', function(test){
+    passes.push(test);
+  });
+
+  runner.on('fail', function(test){
+    failures.push(test);
+  });
+
+  runner.on('end', function(){
+    var coverage = global._$jscoverage || {};
+    var result = map(coverage);
+    result.stats = self.stats;
+    result.tests = tests.map(clean);
+    result.failures = failures.map(clean);
+    result.passes = passes.map(clean);
+
+    process.stdout.write(JSON.stringify(result));
+  });
+}
+
+/**
+ * Map jscoverage data to a JSON structure
+ * suitable for reporting.
+ *
+ * @param {Object} coverageMap jscoverage data
+ * @return {Object}
+ * @api private
+ */
+
+function map(coverageMap) {
+  var ret = {
+    instrumentation: 'node-jscoverage',
+    sloc: 0,
+    hits: 0,
+    misses: 0,
+    coverage: 0,
+    files: []
+  };
+
+  for (var filename in coverageMap) {
+    if (coverageMap.hasOwnProperty(filename)) {
+      var data = coverage(filename, coverageMap[filename]);
+      ret.files.push(data);
+      ret.hits += data.hits;
+      ret.misses += data.misses;
+      ret.sloc += data.sloc;
+    }
+  }
+
+  if (ret.sloc > 0) {
+    ret.coverage = (ret.hits / ret.sloc) * 100;
+  }
+
+  return ret;
+};
+
+/**
+ * Map jscoverage data for a single source file
+ * to a JSON structure suitable for reporting.
+ *
+ * @param {String} filename name of the source file
+ * @param {Object} data jscoverage coverage data
+ * @return {Object}
+ * @api private
+ */
+
+function coverage(filename, data) {
+  var ret = {
+    filename: filename,
+    coverage: 0,
+    hits: 0,
+    misses: 0,
+    sloc: 0,
+    source: {}
+  };
+
+  data.source.forEach(function (line, num) {
+    num++;
+
+    if (data[num] === 0) {
+      ret.misses++;
+      ret.sloc++;
+    } else if (data[num] !== undefined) {
+      ret.hits++;
+      ret.sloc++;
+    }
+
+    ret.source[num] = { line: line, coverage: (data[num] === undefined ? '' : data[num]) };
+  });
+
+  ret.coverage = (ret.hits / ret.sloc) * 100;
+
+  return ret;
+}
+
+/**
+ * Return a plain-object representation of `test`
+ * free of cyclic properties etc.
+ *
+ * @param {Object} test
+ * @return {Object}
+ * @api private
+ */
+
+function clean(test) {
+  return {
+      title: test.title
+    , fullTitle: test.fullTitle()
+    , duration: test.duration
+  }
+}
+
+}); // module: reporters/jscoverage.js
+
 require.register("reporters/json-stream.js", function(module, exports, require){
 
 /**
@@ -2295,6 +2447,14 @@ Runnable.prototype.run = function(fn){
     try {
       this.fn.call(ctx, function(err){
         if (err instanceof Error) return done(err);
+        if (typeof(err) === 'function') { // verify fn was provided to done
+          try {
+            err();
+            return done(); // if no exceptions, success
+          } catch (x) {
+            return done(x); // else call done with the exception
+          }
+        }
         if (null != err) return done(new Error('done() invoked with non-Error: ' + err));
         done();
       });

test/runnable.js

@@ -161,6 +161,42 @@ describe('Runnable(title, fn)', function(){
         })
       })
 
+      describe('when no exception is thrown async in done(fn)', function(){
+        it('should invoke the callback without an error', function(done){
+          var calls = 0;
+          var test = new Runnable('foo', function(done){
+            process.nextTick(function () {
+              done(function () {  // provide verify fn to done
+                var a = 1;
+                return 'bar';  // this is ignored, only thrown exeptions cause fail
+              });
+            });
+          });
+
+          test.run(function(err){
+            done(err);  // err should be undefined since no exceptions thrown in verify fn
+          });
+        })
+      })
+
+      describe('when an exception is thrown async in done(fn)', function(){
+        it('should invoke the callback with exception', function(done){
+          var calls = 0;
+          var test = new Runnable('foo', function(done){
+            process.nextTick(function () {
+              done(function () {  // provide verify fn to done
+                throw new Error('fail'); // is caught and reported               
+              });
+            });
+          });
+
+          test.run(function(err){
+            err.message.should.equal('fail');
+            done();
+          });
+        })
+      })      
+
       describe('when an error is passed', function(){
         it('should invoke the callback', function(done){
           var calls = 0;