Add timeoutAfter method

[FredrikNoren]

To automatically timeout long running tests

[Raynos]

@FredrikNoren

do you want a per test timeout or a global timeout ?
Generally I find that tests that time out are obvious, they just hang.

You need external timeouts anyway, because anything can hang including resource leaks and infinite loops.

What's the use-case for this ?

[FredrikNoren]

@Raynos Per test preferably. The use case is any asynchronous code that might crash or fail to return for whatever reason. An example would be if you work with any kind of event driven or streaming code, and you want to test that: if you mess up but don't have timeouts the test will just stop at the particular example that doesn't work and never fail and continue to the other tests.

[Raynos]

@FredrikNoren the same holds for any other failures like thrown exceptions or infinite loops, it just halts your code.

[FredrikNoren]

@Raynos I guess it's probably a matter of taste but exceptions are handled as failures in mocha. Infinite loops are hard to get around if it's the same process though.

The reason it might be advantageous to fail the tests is that if you fail them the rest of the tests will still run, so if one of the tests fails early on you can still know that everything else works. The way it is now it will just halt and you don't know if it's just this one test that fails or if all your tests fails (which might be completely unrelated to that first test which fails).

[Raynos]

@FredrikNoren I think this feature is legit.

Do we have a preference between

test('foo', function (t) {
    t.timeoutAfter(5000);
    ...
});

And

test('foo', {
    timeout: 5000
}, function (t) {
    ...
});

I favor the later as we already use that for { skip: true }

[FredrikNoren]

@Raynos either is fine for me. I guess it would probably even be pretty easy to support both (i.e. if(opt.timeout) this.timeoutAfter(opt.timeout))

[FredrikNoren]

@Raynos added support for it to the PR

[Raynos]

I have a preference for not extending the public interface of t personally, but maybe I'm weird.

I have a seperate PR that is trying to make the public interface of t be exactly node assert + .end().

We can support both, but it is nice to only have one interface.

[Raynos]

@FredrikNoren

let's leave the method in place and document the { timeout: 5000 } option in the README then its good to go.

[FredrikNoren]

@Raynos Cool, I added opts to the documentation. From what I could tell skip was the only previously available one.

[Raynos]

@FredrikNoren sweet, thank you :)

[FredrikNoren]

@Raynos Thanks for the quick release!