busterjs/buster-docs — pull request #11 by meisl (2013-01-14 18:27:46+00:00)
Title: async tests: 'done' as callback vs 'done' as factory

added explanations in overview.rst. But *only there*, for now. Let's continue the [discussion on IRC](http://irclogger.com/.buster.js/2013-01-14) here.

To be discussed:

- maybe now too long for a section in overview?
- maybe use `makeDone` or similar as parameter name in "factory" example?
- the "factory" usage is most probably always superior, but why exactly?
- how big a pitfall is passing `done` as a callback itself?

re the last:
```javascript
"might work as expected": function (done) {
this.httpServer.on("close", done);
}
```
would just pass if "fail-on-no-assertions" is switched off.

In contrast,
```javascript
"will strangely fail": function (done) {
this.httpServer.on("connect", done);
// trigger connection to this.httpServer
}
```
will probably fail with an error from within `done`. Or it might just time out.
This is because `done` will be invoked in the wrong way, ie. with arguments - and thus will behave fundamentally different.

Q: is just discouraging such use enough? Or, as we're still in beta, should the "simple" use of `done` be thrown away altogether and *only* the "factory" use be supported? What's the cost of such a drastic step (eg. how many tests of buster itself to rewrite)?

Having only one way ("factory") is obviously advantageous, easier to explain, less error-prone etc. What I'm not sure of is whether it's affordable...

TODO:
- update https://github.com/meisl/buster-docs/blob/master/modules/buster-test/test-case.rst#asynchronous-tests
- update https://github.com/meisl/buster-docs/blob/master/modules/buster-test/spec.rst#asynchronous-specs
- anywhere else?