Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document the done() contract #3134

Closed
boneskull opened this issue Dec 9, 2017 · 1 comment · Fixed by Urigo/tortilla#64
Closed

Document the done() contract #3134

boneskull opened this issue Dec 9, 2017 · 1 comment · Fixed by Urigo/tortilla#64
Labels
area: documentation anything involving docs or mochajs.org good first issue new contributors should look here! status: accepting prs Mocha can use your help with this one!

Comments

@boneskull
Copy link
Contributor

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

@boneskull boneskull added area: documentation anything involving docs or mochajs.org pr-please labels Dec 9, 2017
@boneskull boneskull added status: accepting prs Mocha can use your help with this one! good first issue new contributors should look here! and removed pr-please labels Dec 9, 2017
boneskull pushed a commit that referenced this issue Jan 9, 2018
* docs: Error/undefined params to the 'done' callback
sgilroy pushed a commit to TwineHealth/mocha that referenced this issue Feb 27, 2019
…s#3134

* docs: Error/undefined params to the 'done' callback
@ghost
Copy link

ghost commented Oct 10, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area: documentation anything involving docs or mochajs.org good first issue new contributors should look here! status: accepting prs Mocha can use your help with this one!
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant