Requirements

• Filling out the template is required. Any pull request that does not include enough information to be reviewed in a timely manner may be closed at the maintainers' discretion.
• All new code requires tests to ensure against regressions.

Description of the Change

This is a documentation only change.

I couldn't find any reference to describe not supporting an async callback. It seems like a natural conclusion to draw, given mocha specializes in async tests, and given it and hook do.

I spent considerable time trying to figure out why an async test was failing in one of my modules before I discovered the reason deep in an issue discussion (#2975 (comment))!

Alternate Designs

Why should this be in core?

This is a documentation change.

Benefits

I hope that this helps others design their test suites (I saw a number of comments about spending 'lots of time' trying to figure this out).

Possible Drawbacks

Applicable issues

• Describe block with async function behaving weirdly #2975
• 🚀 Feature: Allow async function in describe (block) #2116
• Please allow describe can do async with done/promise #2085