Core: Add test.each.

Gruntfile.js

@@ -102,6 +102,8 @@ module.exports = function( grunt ) {
 						"test/string-filter.html",
 						"test/module-skip.html",
 						"test/module-todo.html",
+						"test/each.html",
+						"test/only-each.html",
 
 						// ensure this is last - it has the potential to drool
 						// and omit subsequent tests during coverage runs

docs/QUnit/test.each.md

@@ -0,0 +1,73 @@
+---
+layout: default
+title: QUnit.test.each()
+excerpt: Add a parameterized test to run.
+categories:
+  - main
+version_added: "unreleased"
+---
+
+`QUnit.test.each( name, data, callback )`
+
+Add a parameterized test to run.
+
+| parameter | description |
+|-----------|-------------|
+| `name` (string) | Title of unit being tested |
+| `data` (Array) | Array of arrays of parameters to be passed as input to each test. This can also be specified as a 1D array of primitives |
+| `callback` (function) | Function to close over assertions |
+
+#### Callback parameters: `callback( assert, args )`:
+
+| parameter | description |
+|-----------|-------------|
+| `assert` (object) | A new instance object with the [assertion methods](../assert/index.md) |
+| `args` (any) | All input parameters. The original array is passed. Array destructuring can be used to unpack input values |
+
+### Description
+
+Add a parameterized test to run using `QUnit.test.each()`. `QUnit.test.each()` generates multiple calls to `QUnit.test()` so `then`-able behavior is maintained.
+
+
+The `assert` argument to the callback contains all of QUnit's [assertion methods](../assert/index.md). Use this argument to call your test assertions.
+`QUnit.test.only.each`, `QUnit.test.skip.each` and `QUnit.test.todo.each` are also available.
+
+See also:
+* [`QUnit.test.only()`](./test.only.md)
+* [`QUnit.test.skip()`](./test.skip.md)
+* [`QUnit.test.todo()`](./test.todo.md)
+
+
+### Examples
+
+A practical example, using the assert argument and no globals.
+
+```js
+function square( x ) {
+  return x * x;
+}
+
+function isEven( x ) {
+  return x % 2 === 0;
+}
+
+function isAsyncEven( x ) {
+  return new Promise( resolve => {
+    return resolve( isEven( x ) );
+  } );
+}
+
+QUnit.test.each( "square()", [ [ 2, 4 ], [ 3, 9 ] ], ( assert, [ value, expected ] ) => {
+  assert.equal( square( value ), expected, `square(${value})` );
+});
+
+QUnit.test.each( "isEven()", [ 2, 4 ], ( assert, value ) => {
+  assert.true( isEven( value ), `isEven(${value})` );
+});
+
+QUnit.test.each( "isAsyncEven()", [ 2, 4 ], ( assert, value ) => {
+  return isAsyncEven( value ).then( ( value ) => {
+    assert.true( isAsyncEven( value ), `isAsyncEven(${value})` );
+  } );
+});
+```

src/test.js

@@ -176,7 +176,7 @@ Test.prototype = {
 		}
 
 		function runTest( test ) {
-			const promise = test.callback.call( test.testEnvironment, test.assert );
+			const promise = test.callback.call( test.testEnvironment, test.assert, test.params );
 			test.resolvePromise( promise );
 
 			// If the test has a "lock" on it, but the timeout is 0, then we push a
@@ -674,66 +674,122 @@ function checkPollution() {
 	}
 }
 
+function addTestWithData( data ) {
+	if ( focused || config.currentModule.ignored ) {
+		return;
+	}
+
+	const newTest = new Test( data );
+
+	newTest.queue();
+}
+
 let focused = false; // indicates that the "only" filter was used
 
 // Will be exposed as QUnit.test
 export function test( testName, callback ) {
+	addTestWithData( {
+		testName: testName,
+		callback: callback
+	} );
+}
+
+function todo( testName, data, callback ) {
 	if ( focused || config.currentModule.ignored ) {
 		return;
 	}
 
 	const newTest = new Test( {
-		testName: testName,
-		callback: callback
+		testName,
+		callback,
+		todo: true,
+		params: data
 	} );
 
 	newTest.queue();
 }
 
-extend( test, {
-	todo: function todo( testName, callback ) {
-		if ( focused || config.currentModule.ignored ) {
-			return;
-		}
+function skip( testName ) {
+	if ( focused || config.currentModule.ignored ) {
+		return;
+	}
 
-		const newTest = new Test( {
-			testName,
-			callback,
-			todo: true
-		} );
+	const test = new Test( {
+		testName: testName,
+		skip: true
+	} );
 
-		newTest.queue();
-	},
-	skip: function skip( testName ) {
-		if ( focused || config.currentModule.ignored ) {
-			return;
-		}
+	test.queue();
+}
+function only( testName, data, callback ) {
+	if ( config.currentModule.ignored ) {
+		return;
+	}
+	if ( !focused ) {
+		config.queue.length = 0;
+		focused = true;
+	}
 
-		const test = new Test( {
-			testName: testName,
-			skip: true
-		} );
+	const newTest = new Test( {
+		testName: testName,
+		callback: callback,
+		params: data
+	} );
 
-		test.queue();
-	},
-	only: function only( testName, callback ) {
-		if ( config.currentModule.ignored ) {
-			return;
-		}
-		if ( !focused ) {
-			config.queue.length = 0;
-			focused = true;
-		}
+	newTest.queue();
+}
 
-		const newTest = new Test( {
-			testName: testName,
-			callback: callback
-		} );
+function makeEachTestName( testName, argument ) {
+	return `${testName} [${argument}]`;
+}
+
+function runEach( data, eachFn ) {
+	if ( Array.isArray( data ) ) {
+		data.forEach( eachFn );
+	} else {
+		throw new Error(
+			`test.each expects an array of arrays or an array of primitives as the expected input.
+${typeof data} was found instead.`
+		);
+	}
+}
 
-		newTest.queue();
+extend( test, {
+	todo: function( testName, callback ) {
+		todo( testName, undefined, callback );
+	},
+	skip,
+	only: function( testName, callback ) {
+		only( testName, undefined, callback );
+	},
+	each: function( testName, data, callback ) {
+		runEach( data, ( datum, i ) => {
+			addTestWithData( {
+				testName: makeEachTestName( testName, i ),
+				callback: callback,
+				params: datum
+			} );
+		} );
 	}
 } );
 
+test.todo.each = function( testName, data, callback ) {
+	runEach( data, ( datum, i ) => {
+		todo( makeEachTestName( testName, i ), datum, callback );
+	} );
+};
+test.skip.each = function( testName, data ) {
+	runEach( data, ( _, i ) => {
+		skip( makeEachTestName( testName, i ) );
+	} );
+};
+
+test.only.each = function( testName, data, callback ) {
+	runEach( data, ( datum, i ) => {
+		only( makeEachTestName( testName, i ), datum, callback );
+	} );
+};
+
 // Resets config.timeout with a new timeout duration.
 export function resetTestTimeout( timeoutDuration ) {
 	clearTimeout( config.timeout );

test/each.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+	<meta charset="UTF-8">
+	<title>QUnit.test.each Suite</title>
+	<link rel="stylesheet" href="../qunit/qunit.css">
+	<script src="../qunit/qunit.js"></script>
+	<script src="main/each.js"></script>
+</head>
+<body>
+	<div id="qunit"></div>
+	<div id="qunit-fixture">test markup</div>
+</body>
+</html>

test/main/each.js

@@ -0,0 +1,32 @@
+QUnit.module( "test.each", function() {
+	QUnit.test.each( "test.each", [ [ 1, 2, 3 ], [ 1, 1, 2 ] ], function( assert, data ) {
+		assert.strictEqual( data[ 0 ] + data[ 1 ], data[ 2 ] );
+	} );
+	QUnit.test.each( "test.each returning a Promise", [ [ 1, 2, 3 ], [ 1, 1, 2 ] ], function( assert, data ) {
+		function sum( a, b ) {
+			return new Promise( function( resolve ) {
+				resolve( a + b );
+			} );
+		}
+		return sum( data[ 0 ], data[ 1 ] ).then( function( result ) { assert.strictEqual( result, data[ 2 ] ); } );
+	} );
+	QUnit.test.each( "test.each 1D", [ 1, [], "some" ], function( assert, value ) {
+		assert.true( Boolean( value ) );
+	} );
+	QUnit.test.each( "test.each fails with non-array input", [ "something", 1, undefined, null, {} ], function( assert, value ) {
+		assert.throws( function() {
+			QUnit.test.each( "test.each 1D", value, function() { } );
+		} );
+	} );
+} );
+QUnit.module( "test.skip.each", function() {
+	QUnit.test( "do run", function( assert ) { assert.true( true ); } );
+	QUnit.test.skip.each( "test.skip.each", [ [ 1, 2, 3 ], [ 1, 1, 2 ] ], function( assert ) {
+		assert.true( false );
+	} );
+} );
+QUnit.module( "test.todo.each", function() {
+	QUnit.test.todo.each( "test.todo.each", [ [ 1, 2, 3 ], [ 1, 1, 2 ] ], function( assert ) {
+		assert.true( false );
+	} );
+} );

test/main/only-each.js

@@ -0,0 +1,9 @@
+QUnit.module.only( "test.each.only", function() {
+	QUnit.test( "don't run", function( assert ) { assert.true( false ); } );
+	QUnit.test.only.each( "test.each.only", [ [ 1, 2, 3 ], [ 1, 1, 2 ] ], function( assert, data ) {
+		assert.strictEqual( data[ 0 ] + data[ 1 ], data[ 2 ] );
+	} );
+	QUnit.test.only.each( "test.each.only 1D", [ 1, [], "some" ], function( assert, value ) {
+		assert.true( Boolean( value ) );
+	} );
+} );

test/only-each.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+	<meta charset="UTF-8">
+	<title>QUnit.test.each.only Suite</title>
+	<link rel="stylesheet" href="../qunit/qunit.css">
+	<script src="../qunit/qunit.js"></script>
+	<script src="main/only-each.js"></script>
+</head>
+<body>
+	<div id="qunit"></div>
+	<div id="qunit-fixture">test markup</div>
+</body>
+</html>