Document the done() contract

[boneskull]

From @FagnerMartinsBrack on February 22, 2016 6:57

When I call done() passing a non Error instance (let's say an error Object Literal, for instance) I get the following message:

done() invoked with non-Error: [Object object]

If the contract is that you should pass an Error instance to the async done handler, then that should be documented. I couldn't find that when looking at the site, only looking at the internals (which, as we all know, should not be relied upon).

If you pass a String (done("it should not do this")), according to the source, it is supposed to be casted accordingly, but then the result will be something like:

done() invoked with non-Error: it should not do this

That is interpreted as a mistake, but then the docs should reflect what should be done to prevent that mistake.

Below is the relevant piece of code from source (2.4.5):

function callFnAsync(fn) {
  fn.call(ctx, function(err) {
    if (err instanceof Error || toString.call(err) === '[object Error]') {
      return done(err);
    }
    if (err) {
      if (Object.prototype.toString.call(err) === '[object Object]') {
        return done(new Error('done() invoked with non-Error: '
          + JSON.stringify(err)));
      }
     return done(new Error('done() invoked with non-Error: ' + err));
    }
    done();
  });
}

TL DR;

Document that done accepts either undefined or an Error object to reflect the current undocumented behavior.

Copied from original issue: mochajs/old-mochajs-site#24

[ghost]

Commenting here even though the issue is closed already: I think the docs are still unclear about the treating of Error instances:

This callback accepts both an Error instance (or subclass thereof) or a falsy value; anything else will cause a failed test.

To me this sounds like passing an Error instance to done() will cause the test to pass, but this is obviously not the case.