jquery/qunit — pull request #434 by englercj (2013-03-28 21:06:47+00:00)
Title: Skip feature

### Why

I was missing a feature that would mark tests as "skipped" so that I can see tests that aren't implemented, or features lacking in that browser, or to temporarily skip a test with a reason so I could remember to come back to it.

### How

The general implementation is to make your final result a 3-state variable instead of 2-state. Right now there is `true` for passing and `false` for failing. This adds a thirds state of `null` for skipped. Calling `skip()` or `skipIf()` will mark that test as "skipped" which will color it yellow, and add to the "skipped" counter (note that `skipIf()` has a test param and will only assert "skipped" if that param is truthy).

### Use cases

##### Mocked Test

The most basic use case that I started with was me mocking out tests, and implementing random ones out of order. I didn't want to have "failing" tests for unimplemented, nor did I want to use `expect(0)` and have a passing test because I will forget to go back to it. So the most basic case was something like:

```js
module('Utils');

test('#utilFunction', function() {
skip();
});
```
which gives me output like:

![tests 1][1]

##### SkipIf based on Feature Detection

This was brought up in [#189][0] that it would be nice if we could detect a browser feature, and conditionally skip the assertions depending on if it had it or not. Something like:

```js
test("that the function will return the element passed by a selector", function() {
skipIf(!document.querySelectorAll, "Browser doesn't support querySelectorAll. Implement test for alternative interface if we're going to support this browser.", function () {
var result =document.querySelectorAll('#container a');
ok(result);
});
});
```
which on FF19 gives the result:

![tests 2][2]

but in IE7 gives the result:

![tests 3][3]

### Final Notes

Obviously there a many reasons that skipping a test is preferred to it failing. I may have implemented it in a way that is not ideal, and if so please let me know and I will try to fix it because this is a feature I would really like to see land. The final thing I want to note is that if you have failed assertions in a test with a `skip()` call as well, the test is still marked as failed:

![tests 4][4]

If you have tests you *know* will fail if some condition isn't met, then that is what `skipIf()` is for. You can do the test and only run code inside if you need to, otherwise you get a skip assertion.

[0]: https://github.com/jquery/qunit/pull/189#issuecomment-3718941
[1]: http://dl.dropbox.com/u/1810371/qunit/tests3.png
[2]: http://dl.dropbox.com/u/1810371/qunit/tests4.png
[3]: http://dl.dropbox.com/u/1810371/qunit/tests5.png
[4]: http://dl.dropbox.com/u/1810371/qunit/tests6.png