pivotal/jasmine — pull request #527 by gburghardt (2014-02-22 01:58:49+00:00)
Title: Added Data Driven Tests

Resolves Issue #480

Clean up your repetive Jasmine specs with data driven tests using an easy to read
syntax:

all("your base are belong to us", [ [2,3], [1,4] ], function(your, base) {
var longToUs = 5;

expect(your + base).toBe(longToUs);
});

Specify single arguments or multiple arguments:

all("specs can have one argument", [1, 2, 3, 4], function(x) {
expect(x > 0).toBe(true);
});

all("specs can have multiple arguments", [ [1,2], [3,4] ], function(x, y) {
expect(y > x).toBe(true);
});

Under the hood, data driven tests are expanded into multiple `it`'s, which are visible
in the Spec Runner:

all("numbers are greater than zero", [ [2,1], [4,3] ], function(a, b) {
expect(a - b > 0).toBe(true);
});

Becomes:

numbers are greater than zero (Variant #0 <2, 1>)
numbers are greater than zero (Variant #1 <4, 3>)

Since each argument group in the dataset becomes its own spec, you can easily run a
single variant by clicking on the spec name in the browser based spec runner.

Data driven tests can be marked as pending:

xall("these are pending", [1, 2, 3], function(x) { });

The `all` and `xall` functions return the array of specs that were created:

var specs = all("foo", [1, 2], function(x) { ... });

Asynchronous data driven tests are executed in the order they are declared, just
like regular async specs defined using `it`:

all("repetitive async tests are supported", [1, 2, 3, 4], function(x, done) {
setTimeout(function() {
expect(x > 0).toBe(true);

done();
}, 500);
});

Jasmine will assume your data driven test is asynchronous and provide a `done` callback if
your test function defines `n + 1` arguments, where `n` is the number of arguments in each
dataset argument group. So beware of:

all("foo", [1, 2], function(x, y) {
// "y" is a callback function!
});

The dataset is validated to ensure your test function doesn't exhibit wonky behavior, which
should prevent some hair pulling and head banging.

Consider the following test definition:

all("test description", [ [1,2], [5] ], function(x, y) {
...
});

The second argument group only has one argument. When the test is created, this error will
be thrown:

Jasmine.ArgumentCountMismatchError: Expected 2 argument(s). Found 1 at index 1 (test description)

Now consider:

all("test description", [ [1,2], [3,4] ], function(a, b, c, d) {
...
});

The dataset has two arguments in each group, but the test function itself is expecting 4
arguments. When the test is created, this error will be thrown:

Jasmine.ArgumentCountMismatchError: Expecting data driven spec to accept 2 arguments, but 4 arguments are specified in the dataset at index 0 (test description)

If you give an invalid or empty dataset:

all("test description", [], function(x) {
...
});

This error is thrown:

Jasmine.ArgumentsMissingError: No arguments for a data-driven test were provided (test description)