Skip to content

Commit

Permalink
docs: Add warning about async callback for describe (#5046)
Browse files Browse the repository at this point in the history
* docs: Add warning about async callback for describe

I couldn't find any reference to `describe` not supporting an async function. It seems like a natural idea given `it` and `before` do.

I spent considerable time trying to figure out why an async test was failing before I discovered the reason deep in an issue discussion (#2975 (comment)), so hope that this helps others design their test suites!

* Update docs/index.md

Co-authored-by: Josh Goldberg ✨ <git@joshuakgoldberg.com>

* Update docs/index.md

Co-authored-by: Josh Goldberg ✨ <git@joshuakgoldberg.com>

---------

Co-authored-by: Josh Goldberg ✨ <git@joshuakgoldberg.com>
  • Loading branch information
mcdurdin and JoshuaKGoldberg authored Jul 2, 2024
1 parent 177732f commit c43930c
Showing 1 changed file with 5 additions and 0 deletions.
5 changes: 5 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -298,6 +298,11 @@ describe('#find()', function () {
});
```

### Limitations of asynchronous callbacks

You can use all asynchronous callbacks (`done`, `Promise`, and `async`/`await`) in callbacks for `it()`, `before()`, `after()`, `beforeEach()`, `afterEach()`) but not `describe()` -- it must be synchronous.
See [#5046](https://github.com/mochajs/mocha/pull/5046) for more information.

## Synchronous Code

When testing synchronous code, omit the callback and Mocha will automatically continue on to the next test.
Expand Down

0 comments on commit c43930c

Please sign in to comment.