Support for --tags to include/exclude tests based on some optional tagging

bin/_mocha

@@ -98,6 +98,8 @@ program
   .option('--trace', 'trace function calls')
   .option('--trace-deprecation', 'show stack traces on deprecations')
   .option('--watch-extensions <ext>,...', 'additional extensions to monitor with --watch', list, [])
+  .option('--tags <tags>', 'only include tests with the given tags', list, [])
+  .option('--skip-tags <tags>', 'exclude all tests with the given tags', list, [])
 
 program.name = 'mocha';
 
@@ -255,6 +257,14 @@ if (program.grep) mocha.grep(new RegExp(program.grep));
 
 if (program.invert) mocha.invert();
 
+// --tags
+
+if (program.tags) mocha.tags(program.tags);
+
+// --skip-tags
+
+if (program.skipTags) mocha.skipTags(program.skipTags);
+
 // --check-leaks
 
 if (program.checkLeaks) mocha.checkLeaks();

lib/context.js

@@ -10,7 +10,9 @@ module.exports = Context;
  * @api private
  */
 
-function Context(){}
+function Context(){
+  this._tags = [];
+}
 
 /**
  * Set or get the context `Runnable` to `runnable`.

lib/filter.js

@@ -0,0 +1,36 @@
+var utils = require('./utils');
+
+module.exports = Filter;
+
+function Filter() {
+  this.grep = /.*/;
+  this.invertGrep = false;
+  this.tags = [];
+  this.skipTags = [];
+}
+
+Filter.prototype.count = function(suite) {
+  var self = this;
+  var total = 0;
+  suite.eachTest(function(test){
+    if (self.shouldRun(test)) total++;
+  });
+  return total;
+};
+
+Filter.prototype.shouldRun = function(test) {
+  // --grep
+  var grepMatch = this.grep.test(test.fullTitle());
+  if (this.invertGrep) grepMatch = !grepMatch;
+  // --tags --skip-tags
+  var include = (!this.tags.length) || matchTags(test.ctx._tags, this.tags);
+  var exclude = this.skipTags.length && matchTags(test.ctx._tags, this.skipTags);
+  // final decision
+  return grepMatch && include && !exclude;
+};
+
+function matchTags(actualTags, against) {
+  return utils.some(against, function(tag) {
+    return utils.indexOf(actualTags, tag) !== -1;
+  });
+}

lib/mocha.js

@@ -67,6 +67,8 @@ function image(name) {
  *   - `slow` milliseconds to wait before considering a test slow
  *   - `ignoreLeaks` ignore global leaks
  *   - `grep` string or regexp to filter tests with
+ *   - `tags` array of tags to be included when filtering
+ *   - `skipTags` array of tags to be excluded when filtering
  *
  * @param {Object} options
  * @api public
@@ -238,6 +240,26 @@ Mocha.prototype.invert = function(){
   return this;
 };
 
+/**
+ * Set a list of tags to include
+ * @returns {Mocha}
+ * @api public
+ */
+Mocha.prototype.tags = function(tags) {
+  this.options.tags = tags;
+  return this;
+};
+
+/**
+ * Set a list of tags to exclude
+ * @returns {Mocha}
+ * @api public
+ */
+Mocha.prototype.skipTags = function(tags) {
+  this.options.skipTags = tags;
+  return this;
+};
+
 /**
  * Ignore global leaks.
  *
@@ -399,6 +421,8 @@ Mocha.prototype.run = function(fn){
   runner.ignoreLeaks = false !== options.ignoreLeaks;
   runner.asyncOnly = options.asyncOnly;
   if (options.grep) runner.grep(options.grep, options.invert);
+  if (options.tags) runner.tags(options.tags);
+  if (options.skipTags) runner.skipTags(options.skipTags);
   if (options.globals) runner.globals(options.globals);
   if (options.growl) this._growl(runner, reporter);
   exports.reporters.Base.useColors = options.useColors;

lib/reporters/tap.js

@@ -29,8 +29,7 @@ function TAP(runner) {
     , failures = 0;
 
   runner.on('start', function(){
-    var total = runner.grepTotal(runner.suite);
-    console.log('%d..%d', 1, total);
+    console.log('%d..%d', 1, runner.total);
   });
 
   runner.on('test end', function(){

lib/runner.js

@@ -5,6 +5,7 @@
 var EventEmitter = require('events').EventEmitter
   , debug = require('debug')('mocha:runner')
   , Test = require('./test')
+  , Filter = require('./filter')
   , utils = require('./utils')
   , filter = utils.filter
   , keys = utils.keys;
@@ -54,12 +55,12 @@ function Runner(suite) {
   var self = this;
   this._globals = [];
   this._abort = false;
+  this._filter = new Filter();
   this.suite = suite;
   this.total = suite.total();
   this.failures = 0;
   this.on('test end', function(test){ self.checkGlobals(test); });
   this.on('hook end', function(hook){ self.checkGlobals(hook); });
-  this.grep(/.*/);
   this.globals(this.globalProps().concat(extraGlobals()));
 }
 
@@ -88,34 +89,42 @@ Runner.prototype.__proto__ = EventEmitter.prototype;
  * @api public
  */
 
-Runner.prototype.grep = function(re, invert){
-  debug('grep %s', re);
-  this._grep = re;
-  this._invert = invert;
-  this.total = this.grepTotal(this.suite);
+Runner.prototype.grep = function(re, invert) {
+  debug('grep %s (%s)', re, invert);
+  this._filter.grep = re;
+  this._filter.invertGrep = invert;
+  this.total = this._filter.count(this.suite);
   return this;
 };
 
 /**
- * Returns the number of tests matching the grep search for the
- * given suite.
+ * Only run tests matching the given tags
  *
- * @param {Suite} suite
- * @return {Number}
+ * @param {Array} tags
+ * @return {Runner} for chaining
  * @api public
  */
 
-Runner.prototype.grepTotal = function(suite) {
-  var self = this;
-  var total = 0;
+Runner.prototype.tags = function(tags){
+  debug('include tags: %s', tags);
+  this._filter.tags = tags;
+  this.total = this._filter.count(this.suite);
+  return this;
+};
 
-  suite.eachTest(function(test){
-    var match = self._grep.test(test.fullTitle());
-    if (self._invert) match = !match;
-    if (match) total++;
-  });
+/**
+ * Exclude tests matching the given tags
+ *
+ * @param {Array} tags
+ * @return {Runner} for chaining
+ * @api public
+ */
 
-  return total;
+Runner.prototype.skipTags = function(tags){
+  debug('skip tags: %s', tags);
+  this._filter.skipTags = tags;
+  this.total = this._filter.count(this.suite);
+  return this;
 };
 
 /**
@@ -430,10 +439,8 @@ Runner.prototype.runTests = function(suite, fn){
     // all done
     if (!test) return fn();
 
-    // grep
-    var match = self._grep.test(test.fullTitle());
-    if (self._invert) match = !match;
-    if (!match) return next();
+    // filter
+    if (!self._filter.shouldRun(test)) return next();
 
     // pending
     if (test.pending) {
@@ -480,7 +487,7 @@ Runner.prototype.runTests = function(suite, fn){
  */
 
 Runner.prototype.runSuite = function(suite, fn){
-  var total = this.grepTotal(suite)
+  var total = this._filter.count(suite)
     , self = this
     , i = 0;
 

lib/suite.js

@@ -151,6 +151,24 @@ Suite.prototype.bail = function(bail){
   return this;
 };
 
+/*
+ * Sets tags on the suite's context,
+ * inheriting any parent tags
+ *
+ * @param {String...} tags
+ * @return {Suite} for chaining
+ * @api private
+ */
+
+Suite.prototype.tag = function(tags) {
+  if (this.parent) {
+    this.ctx._tags = Array.prototype.concat.apply(this.parent.ctx._tags, arguments);
+  } else {
+    this.ctx._tags = Array.prototype.slice.apply(arguments);
+  }
+  return this;
+};
+
 /**
  * Run `fn(test[, done])` before running tests.
  *

lib/utils.js

@@ -117,6 +117,21 @@ exports.filter = function(arr, fn){
   return ret;
 };
 
+/**
+ * Array#some
+ *
+ * @param {Array} array
+ * @param {Function} fn
+ * @api private
+ */
+
+exports.some = function(arr, fn) {
+  for (var i = 0, l = arr.length; i < l; ++i) {
+    if (fn(arr[i], i, arr)) return true;
+  }
+  return false;
+};
+
 /**
  * Object.keys (<=IE8)
  *