Basic macro support.

This adds basic macro support as discussed in #695.

It does not completely implement the spec outlined there, specifically:

- The macro can only specify the title using a function in `macroFn.title`. We discussed allowing `macroFn.title` to also be a string, and allowing some form of template language for extracting a title. However, using ES2015 string templates is already pretty easy, so we may just skip this.
- We discussed allowing groups of tests to be created using arrays.

Both the above proposals are found in [this comment](#695 (comment)). They both enhance the implementation found in this commit, and would not break the contract. So I don't think there is anything preventing us from shipping this now.

Author: jamestalmage

lib/runner.js

@@ -9,7 +9,6 @@ var TestCollection = require('./test-collection');
 function noop() {}
 
 var chainableMethods = {
-	spread: true,
 	defaults: {
 		type: 'test',
 		serial: false,
@@ -55,10 +54,19 @@ function Runner(options) {
 util.inherits(Runner, EventEmitter);
 module.exports = Runner;
 
-optionChain(chainableMethods, function (opts, title, fn) {
-	if (typeof title === 'function') {
-		fn = title;
+optionChain(chainableMethods, function (opts, args) {
+	var title;
+	var fn;
+	var macroArgIndex;
+
+	if (typeof args[0] === 'string') {
+		title = args[0];
+		fn = args[1];
+		macroArgIndex = 2;
+	} else {
+		fn = args[0];
 		title = null;
+		macroArgIndex = 1;
 	}
 
 	if (opts.todo) {
@@ -83,6 +91,20 @@ optionChain(chainableMethods, function (opts, title, fn) {
 		opts.exclusive = title !== null && matcher([title], this._match).length === 1;
 	}
 
+	if (args.length > macroArgIndex) {
+		args = args.slice(macroArgIndex);
+
+		if (!title && fn.title) {
+			title = fn.title(args);
+		}
+
+		var _fn = fn;
+
+		fn = function (t) {
+			return _fn.apply(this, [t, args]);
+		};
+	}
+
 	this.tests.add({
 		metadata: opts,
 		fn: fn,

readme.md

@@ -524,6 +524,33 @@ test.only.serial(...);
 
 This means you can temporarily add `.skip` or `.only` at the end of a test or hook definition without having to make any other changes.
 
+### Test macros
+
+Additional arguments after the test function will be passed as an array to the test function. This is useful for creating reusable test macros.
+
+```js
+function macro(t, [input, expected]) {
+  t.is(eval(input), expected);
+}
+
+test('2 + 2 === 4', macro, '2 + 2', 4);
+test('2 * 3 === 6', macro, '2 * 3', 6);
+```
+
+You can build the test title programatically by attaching a `title` function to the macro:
+
+ ```js
+ function macro(t, [input, expected]) {
+   t.is(eval(input), expected);
+ }
+
+ macro.title = ([input, expected]) => `${input} === ${expected}`;
+
+ test(macro, '2 + 2', 4);
+ test(macro, '2 * 3', 6);
+ ```
+
+
 ### Custom assertions
 
 You can use any assertion library instead of or in addition to the built-in one, provided it throws exceptions when the assertion fails.

test/runner.js

@@ -468,3 +468,56 @@ test('options.match overrides .only', function (t) {
 		t.end();
 	});
 });
+
+test('additional args will be passed as an array', function (t) {
+	t.plan(3);
+
+	var runner = new Runner();
+
+	runner.test('test1', function (avaT, args) {
+		t.deepEqual(args, ['foo', 'bar']);
+	}, 'foo', 'bar');
+
+	runner.run({}).then(function (stats) {
+		t.is(stats.passCount, 1);
+		t.is(stats.testCount, 1);
+		t.end();
+	});
+});
+
+test('macro functions can be named by attaching a custom function', function (t) {
+	t.plan(8);
+
+	var expectedTitles = [
+		'titleA',
+		'overridden',
+		'titleC'
+	];
+
+	var expectedArgs = [
+		['A'],
+		['B'],
+		['C']
+	];
+
+	function macroFn(avaT, args) {
+		t.is(avaT.title, expectedTitles.shift());
+		t.deepEqual(args, expectedArgs.shift());
+	}
+
+	macroFn.title = function (args) {
+		return 'title' + args[0];
+	};
+
+	var runner = new Runner();
+
+	runner.test(macroFn, 'A');
+	runner.test('overridden', macroFn, 'B');
+	runner.test(macroFn, 'C');
+
+	runner.run({}).then(function (stats) {
+		t.is(stats.passCount, 3);
+		t.is(stats.testCount, 3);
+		t.end();
+	});
+});